Okteto Variables

Application configuration should be passed at deployment time, not hardcoded in your code.

Okteto variables help you save application configuration in Okteto and automatically inject it during deployment time.

There are a few different ways to leverage variables. In short:

• You can define variables manually in the manifest or in the Okteto UI
• There are some default variables built in to the Okteto platform
• All variables used in the Okteto manifest are automatically expanded
• All variables are injected as runtime environment variables in the execution of your deploy and destroy scripts

We will cover each of these behaviors in more detail below.

User-defined variables

Okteto supports manual definition of variables, offering significant flexibility in configuration. These user-defined variables are separate from Okteto's default, built-in variables. We recommend creating variables in the following order of preference:

• Local variables
• Deploy time variables
• Catalog variables
• User variables (in settings)
• Admin variables

note

Variables will be overridden by those above them in this list. For example, local variables will override admin variables.

Manage Okteto Variables from the Okteto dashboard

You can create and delete your Okteto Variables from the Variables section in the Settings view of the Okteto dashboard:

To create a new variable, click on the Add Variable button, and provide a name and a value. The value will be masked once the variable is created.

To delete an existing variable, click on the Delete button on the right. You'll have to confirm your choice before the variable is deleted. Deleted variables can't be recovered, so be careful when doing this.

Configuring dynamic endpoints

You can create dynamic endpoints for external resources within your Okteto environment using $OKTETO_ENV. You can define $variables, assign them to OKTETO_ENV, and make those variables available in other sections (e.g. deploy, destroy) of the Okteto manifest or to generate dynamic endpoints for external resources.

The example below demonstrates adding variables to $OKTETO_ENV in the deploy section and then accessing those variables in a sample destroy section:

deploy:
  hashicorp/terraform:1.4
  commands:
  - name: Create AWS infrastructure
    command: |
      set -e
      resourceName="${OKTETO_NAMESPACE}-oktacoshop"
      region=$AWS_REGION

      terraform apply -input=false -var "bucket_name=$resourceName" -var "queue_name=$resourceName" -var "region=$region" -auto-approve
      s3Dashboard="https://s3.console.aws.amazon.com/s3/buckets/${resourceName}"

      # ... shortened for brevity
    {
      echo "$resourceName"
      echo "$region"
      echo "OKTETO_EXTERNAL_S3_ENDPOINTS_BUCKET_URL=$s3Dashboard"
      echo "S3_BUCKET_NAME=$resourceName"
    } >> "$OKTETO_ENV"

destroy:
  image: hashicorp/terraform:1.4
  commands:
  - name: Delete the AWS infrastructure
    command: |
      set -e

      # omitted for brevity

      terraform apply -input=false -var "bucket_name=${S3_BUCKET_NAME}" -var "queue_name=$resourceName" -var "region=$region" -auto-approve --destroy

Default Environment Variables

These are automatically expanded and can be referenced in your Okteto manifest’s deploy/destroy sections either directly (within the manifest) or in external files (e.g. a Makefile):

• OKTETO_DOMAIN: The domain where Okteto exposes your application endpoints.
• OKTETO_NAMESPACE: The namespace where your application is installed.
• OKTETO_USERNAME: Your username in Okteto.
• OKTETO_REGISTRY_URL: The URL of the Okteto Registry.
• OKTETO_GIT_BRANCH: The name of the Git branch being deployed.
• OKTETO_GIT_COMMIT: The SHA1 hash of the last commit of the branch.
• OKTETO_IS_PREVIEW_ENVIRONMENT: Set to true when the environment is a preview environment.

Built-in Environment Variables for Images in Okteto Registry

Reference images defined in the build section of the Okteto manifest using the following environment variables:

• OKTETO_BUILD_(IMAGE)_IMAGE: Full image reference.
• OKTETO_BUILD_(IMAGE)_REGISTRY: Registry URL where the image was pushed.
• OKTETO_BUILD_(IMAGE)_REPOSITORY: Name of the image that was pushed.
• OKTETO_BUILD_(IMAGE)_SHA: Latest tag and SHA of the image.

For instance, with a build section like:

build:
  hello-world:
    context: .

Okteto will generate environment variables such as:

• OKTETO_BUILD_HELLO_WORLD_IMAGE: registry.okteto.example.com/cindy/hello-world@sha256:xxx
• OKTETO_BUILD_HELLO_WORLD_REGISTRY: registry.okteto.example.com
• OKTETO_BUILD_HELLO_WORLD_REPOSITORY: cindy/hello-world
• OKTETO_BUILD_HELLO_WORLD_SHA: f56119a37b@sha256:xxx

note

If an image name includes '-', it will be replaced by '_' in the corresponding environment variables.

Built-in Environment Variables for Dependencies:

Reference variables defined by your dependencies using the following pattern:

• OKTETO_DEPENDENCY_<dependency>_VARIABLE_<variable>: The value of a variable of a dependency.

For example, if you have a dependency in your Okteto Manifest:

dependencies:
  database:
    repository: https://github.com/okteto/my-database
    variables:
      USERNAME: okteto
    wait: true

And the repository has this Okteto Manifest:

deploy:
  - echo "PASSWORD=1234" >> $OKTETO_ENV

Reference the variables in your Okteto Manifest deploy section like this:

dependencies:
  database:
    repository: https://github.com/okteto/my-database
    variables:
      USERNAME: okteto
    wait: true

deploy:
  - echo ${OKTETO_DEPENDENCY_DATABASE_VARIABLE_USERNAME}
  - echo ${OKTETO_DEPENDENCY_DATABASE_VARIABLE_PASSWORD}

note

USERNAME has a static value, and PASSWORD is dynamically generated.

Feature flag variables

Okteto provides a list of variables that serve as feature flags for some of the features we release in our product. Below is a list of those variables that you can use to leverage these newer and experimental features:

• OKTETO_SMART_BUILDS_ENABLED: enables the "smart builds" feature that uses a hash of the build context to determine if an image needs to be rebuilt or can be pulled from the registry. This can accelerate build times.
• OKTETO_COMPOSE_VOLUME_AFFINITY_ENABLED: Compose services mounting the same volume will be placed on the same node using Kubernetes's pod affinity. (Defaults to true)
• OKTETO_KUBERNETES_TIMEOUT: specifies the timeout while deploying. (defaults to 0)
• OKTETO_FORCE_REMOTE: if true, the CLI will run deploy and destroy commands on the cluster instead of running them locally
• OKTETO_FOLDER: defines the path where the okteto folder is located (defaults to $OKTETO_HOME/.okteto)
• OKTETO_LOCAL_REGISTRY_STORE_ENABLED: enables the local registry credentials over the credentials stored in the cluster. (Defaults to true)
• OKTETO_USE_STATIC_KUBETOKEN: use a fixed token rather than a dynamic token for interactions with the Kubernetes API. (Defaults to false)
• OKTETO_AUTOGENERATE_STIGNORE: if true, generates the .stignore file when running okteto up. (Defaults to false)
• OKTETO_AUTODEPLOY: if set, forces the deployment of the development environment on okteto up (Defaults to false)
• OKTETO_COMPOSE_UPDATE_STRATEGY: defines the update strategy that the compose must translate (it can be one of: rolling/recreate/on-delete)
• OKTETO_DISABLE_SPINNER: if set disables the spinner rotation (defaults to false)
• OKTETO_SYNCTHING_VERSION: specifies the syncthing version the CLI must use

Accessing Okteto variables at deploy time

Okteto Variables are automatically injected in your Okteto CLI commands as environment variables.

Follow this tutorial for a sample using Okteto Variables when deploying your application.