Okteto Manifest Reference

okteto.yaml is a manifest format for describing development environments.

The Okteto Manifest has four main sections: build, deploy, test and dev, to define how to build, deploy, test, and develop your development environment.

The open-source version of Okteto supports features within the dev section of the Okteto Manifest. For a complete comparison of features, refer to the open-source README.

Example

build:
  api:
    context: api
  frontend:
    context: frontend
deploy:
  - helm upgrade --install movies chart --set api.image=${OKTETO_BUILD_API_IMAGE} --set frontend.image=${OKTETO_BUILD_FRONTEND_IMAGE}
dev:
  api:
    command: ["bash"]
    forward:
      - 8080:8080
      - 9229:9229
    sync:
      - api:/usr/src/app
  frontend:
    command: yarn start
    sync:
      - frontend:/usr/src/app
test:
  unit:
    image: okteto/golang:1
    commands:
      - "go test ."

Schema reference

build (object, optional)

A list of images to build as part of your development environment.

build:
  base:
    context: .
  api:
    context: api
  frontend:
    context: frontend
    dockerfile: Dockerfile
    target: dev
    depends_on: base
    args:
      SOURCE_IMAGE: ${OKTETO_BUILD_BASE_IMAGE}
    secrets:
      npmrc: .npmrc

Each image supports the following fields:

• args: add build arguments, which are environment variables accessible only during the build process. Build arguments with a value containing a $ sign are resolved to the environment variable value on the machine Okteto is running on.
• context: the build context. Relative paths are relative to the location of the Okteto Manifest (default: .)
• depends_on: list of images that need to be built first.
• dockerfile: the path to the Dockerfile. It's a relative path to the build context (default: Dockerfile)
• image: the name of the image to build and push. In clusters that have Okteto installed, this is optional (if not specified, the Okteto Registry is used).
• secrets: list of secrets exposed to the build. The value of each secret refers to a file. Okteto will resolve references containing a $ sign in this file to environment variables on the machine Okteto is running on.
• target: build the specified stage as defined inside the Dockerfile. See the multi-stage official docs for details.

You can build all these images by running okteto build, or okteto build xxx to build a single one.

Follow this document for a list of environment variables available in your deploy commands to refer to the images built in the build section of your Okteto Manifest.

Okteto will automatically add all the build environment variables from all previous images in the dependency chain as build arguments. To refer to them, remember to add the ARG instruction on your Dockerfile.

dependencies ([string], optional)

A list of repositories you want to deploy as part of your development environment.

dependencies:
  - https://github.com/okteto/movies-frontend

tip

Use okteto deploy --dependencies to force the redeployment of your dependencies.

There is also an extended notation to configure how to deploy your dependencies:

dependencies:
  frontend:
    repository: https://github.com/okteto/movies-frontend
    manifest: okteto.yaml
    branch: main
    variables:
      ENVIRONMENT: development
      DEBUG: true
    wait: true
    timeout: 15m

When specifying the manifest path, the dependency deployment will use this path as the location of the Okteto Manifest in the Git repository.

deploy ([string], optional)

A list of commands to deploy your development environment.

It's usually a combination of helm, kubectl, and okteto commands.

Deploy with Commands

For example, deploy a Helm chart using a command to invoke the helm CLI:

deploy:
  - helm upgrade --install movies chart --set api.image=${OKTETO_BUILD_API_IMAGE} --set frontend.image=${OKTETO_BUILD_FRONTEND_IMAGE}

You can name your commands with the following syntax:

deploy:
  - name: Deploy Movies App with Helm
    command: helm upgrade --install movies chart --set api.image=${OKTETO_BUILD_API_IMAGE} --set frontend.image=${OKTETO_BUILD_FRONTEND_IMAGE}

You can share environment variables between steps by adding them to $OKTETO_ENV:

deploy:
  - name: Set env value
    command: echo "OKTETO_FOLDER=/app" >> $OKTETO_ENV
  - name: Get env value
    command: echo "$OKTETO_FOLDER" # Prints /app

Follow this document for a list of environment variables available in your deploy commands.

Deploy remotely (recommended)

If you define an image in your deploy section, okteto deploy will run in remote mode:

deploy:
  image: okteto/pipeline-runner:1.0.0
  commands:
    - helm upgrade --install movies chart --set api.image=${OKTETO_BUILD_API_IMAGE} --set frontend.image=${OKTETO_BUILD_FRONTEND_IMAGE}

If you don't define an image, you can run in remote mode adding the remote field to your manifest:

deploy:
  remote: true
  commands:
    - helm upgrade --install movies chart --set api.image=${OKTETO_BUILD_API_IMAGE} --set frontend.image=${OKTETO_BUILD_FRONTEND_IMAGE}

Follow our docs to know more about remote execution and how it works.

Deploy with Compose

Deploy a Docker Compose file using the following notation:

deploy:
  compose: docker-compose.yml

note

Images specified in the build section of the Okteto Manifest overrides the image associated with services sharing the same name in your Docker Compose files.

There is an extended notation to deploy several Docker Compose files and endpoints:

deploy:
  compose:
    - file: docker-compose.yml
      services:
        - frontend
    - file: docker-compose.dev.yml
      services:
        - api
  endpoints:
    - path: /
      service: frontend
      port: 80
    - path: /api
      service: api
      port: 8080

The services field allows us to deploy only a subset of the services in the Docker compose file (default to all services). Only the volumes and endpoints of the services specified in the services field are deployed.

You can combine deploy commands with Docker Compose files:

deploy:
  commands:
    - helm upgrade --install movies chart --set api.image=${OKTETO_BUILD_API_IMAGE} --set frontend.image=${OKTETO_BUILD_FRONTEND_IMAGE}
  compose: docker-compose.yml

Your deploy commands will be executed before deploying your Docker Compose files.

Divert

Divert is useful when you have many services and you only want to deploy a subset of them in your development environment, while connecting these services with a shared environment that runs all your microservices.

When divert is enabled, Okteto adds the header baggage.okteto-divert to every request coming from the developer namespace. If the request reaches the shared namespace and matches a diverted virtual service, Okteto redirects the request back to the developer namespace.

To divert a virtual service as part of your development environment, use the following notation:

deploy:
  commands:
    - helm upgrade --install movies chart --set api.image=${OKTETO_BUILD_API_IMAGE} --set frontend.image=${OKTETO_BUILD_FRONTEND_IMAGE}
  divert:
    driver: istio
    virtualServices:
      - name: vs1
        namespace: staging
        routes:
          - route1
          - route2
    hosts:
      - virtualService: frontend
        namespace: staging

• driver: the backend for divert. Currently, the only supported driver is istio.
• virtualServices: a list of virtual services to divert. Each virtual service is defined with it's name, namespace, and an optional list of routes to be diverted. By default, all routes are diverted.
• hosts: the list of hosts you want to divert in the developer namespace. Requests to these virtual services will have the header baggage.okteto-divert injected.

destroy ([string], optional)

A list of commands to destroy external resources created by your development environment.

okteto destroy automatically takes care of destroying all the Kubernetes resources created by okteto deploy.

Use the destroy section if you create resources out of the scope of Kubernetes, like s3 buckets or RDS databases.

destroy:
  - helm uninstall movies

Follow this document for a list of variables available in your destroy commands.

Destroy remotely (recommended)

If you define an image in your destroy section, okteto destroy will run in remote mode:

destroy:
  image: okteto/tfenv-ci:1.4
  commands:
    - terraform destroy --auto-approve

If you don't define an image, you can run in remote mode adding the remote field to your manifest:

destroy:
  remote: true
  commands:
    - helm uninstall movies

Follow our docs to know more about remote execution and how it works.

dev (object, optional)

A list of development containers to define the behavior of okteto up and synchronize your code in your development environment.

dev:
  api:
    command: ["bash"]
    forward:
      - 8080:8080
      - 9229:9229
    sync:
      - api:/usr/src/app
  frontend:
    command: yarn start
    sync:
      - frontend:/usr/src/app

The name of each development container must match the name of the Kubernetes Deployment or Statefulset that you want to put on development mode. If the name of your Deployment or Statefulset is dynamically generated, use the selector field to match the Deployment or Statefulset by labels.

Each development container supports the following fields:

affinity (Affinity, optional)

Affinity allows you to constrain which nodes your development container is eligible to be scheduled on, based on labels on the node. More information about Kubernetes affinities is available here.

affinity:
  podAffinity:
    requiredDuringSchedulingIgnoredDuringExecution:
      - labelSelector:
          matchExpressions:
            - key: role
              operator: In
              values:
                - web-server
        topologyKey: kubernetes.io/hostname

autocreate (bool, optional)

If set to true, okteto up creates a deployment if name doesn't match any existing deployment in the current namespace (default: false).

command (string, optional)

Sets the command of your development container. If empty, it defaults to sh:

command: bundle exec thin -p 3000

The command can also be a list:

command: ["bundle", "exec", "thin", "-p", "3000"]

container (string, optional)

The name of the container in your deployment you want to put on development mode. By default, it takes the first one.

environment ([string], optional)

Add environment variables to your development container. If a variable already exists on your deployment, it will be overridden with the value specified on the manifest.

Environment variables with only a key, or with a value with a $ sign resolve to their values on the machine Okteto is running on, which can be helpful for secret or machine-specific values.

environment:
  environment: development
  name: user-${USER:peter} ## will be replaced by the value of $USER or by "peter" if the variable USER does not exist
  DBPASSWORD: ## will be given the value of $DBPASSWORD if it exists

envFiles

Add environment variables to your development container from a file.

envFiles:
  - .env1
  - .env2

Environment variables declared in the environment section override these values.

externalVolumes ([string], optional)

A list of persistent volume claims (not managed by Okteto) that you want to mount in your development container. This is useful to share cache information between different development containers. For example, to share the go cache between different development containers, you could define:

externalVolumes:
  - go-cache:/root/.cache/go-build/

on different Okteto Manifests. You can also mount a relative subpath of a given persistent volume claim:

externalVolumes:
  - pvc-name:subpath:/var/lib/mysql

forward ([string], optional)

A list of ports to forward from your development container. The list should follow the localPort:remotePort notation and each element should be unique.

You can also access other services running in your namespace by using the notation localPort:remoteService:remotePort.

forward:
  - 8080:80
  - 5432:postgres:5432

You can also use the extended notation below to configure the service to be exposed using a label selector or its name.

forward:
  - localPort: 8080
    remotePort: 80
    name: app
  - localPort: 5432
    remotePort: 5432
    labels:
      app: db

Once your development container is up and running, you will be able to access the port directly by using localhost:localPort.

Common uses of port forwarding are:

1. Access a service via localhost instead of via an ingress
2. Remote debugging
3. Connect to a hot reloader via a websocket

If Okteto can't forward a port (typically because they are already taken), the okteto up command will fail with an error.

initContainer (object, optional)

Allows you to override the okteto init container configuration of your development container.

initContainer:
  image: okteto/bin:1.2.22
  resources:
    requests:
      cpu: 30m
      memory: 30Mi
    limits:
      cpu: 30m
      memory: 30Mi

interface (string, optional)

Port forwards and reverse tunnels will be bound to this address. Defaults to localhost.

interface: 0.0.0.0

image (string, optional)

Sets the docker image of your development container. Defaults to the image specified in your deployment.

More information on development images here

You can use an environment variable to replace the image, or any part of it:

image: okteto/dev:$USER

More information on how to use private images for your development container is available here.

imagePullPolicy (string, optional)

The image pull policy of your development environment (default: Always)

lifecycle (boolean, optional)

Configures lifecycle hooks for your development container. Lifecycle hooks allow you to execute commands when your container starts or stops, enabling you to automate setup or cleanup tasks.

If set to true, both postStart and preStop lifecycle events are enabled when running okteto up inheriting the lifecycle from the original container (default: false).

For more information about Kubernetes lifecycle hooks, see the official Kubernetes documentation.

lifecycle: true

This enables both postStart and preStop events to use the default commands defined in your Kubernetes deployment.

For more granular control, you can enable or disable specific lifecycle events and define custom commands to run during those events.

lifecycle:
  postStart:
    enabled: true
    command: "echo 'Container has started'"
  preStop:
    enabled: true
    command: "echo 'Container is stopping'"

• postStart:
  • enabled (boolean): Set to true to enable the postStart event (default: false).
  • command (string): The command to execute when the container starts.
• preStop:
  • enabled (boolean): Set to true to enable the preStop event (default: false).
  • command (string): The command to execute just before the container stops.

metadata (object, optional)

The metadata field allows to inject labels and annotations into your development container.

metadata:
  annotations:
    fluxcd.io/ignore: "true"
  labels:
    custom.label/dev: "true"

mode (string, optional)

The development mode used for a development environment. There are two options available for this field:

• sync: the standard and default mode. This mode will synchronize your code with the remote development container
• hybrid: use this mode if you want to run your service locally but run the rest of your application components in the cluster

More information about development modes is available here.

nodeSelector (map[string]string, optional)

List of labels that the node must have to include the development container on it. More information about Kubernetes node selectors is available here.

nodeSelector:
  disktype: ssd

persistentVolume (object, optional)

Allows you to configure the okteto persistent volume:

• enabled: enable/disable the use of persistent volumes (default: true)
• accessMode: the Okteto persistent volume access mode (default: ReadWriteOnce)
• annotations: add annotations to the Okteto persistent volume
• labels: add labels to the Okteto persistent volume
• size: the size of the Okteto persistent volume (default: 5Gi)
• storageClass: the storage class of the Okteto persistent volume (default: the default storage class in your cluster)
• volumeMode: the Okteto persistent volume mode (default: Filesystem)

persistentVolume:
  enabled: true
  storageClass: standard
  size: 30Gi

Note the following limitations:

• persistentVolume.enabled must be true if you use services.
• persistentVolume.enabled must be true if you use volumes.
• persistentVolume.enabled must be true if you want to share command history across development containers between different okteto up sessions.

priorityClassName (string, optional)

This field allows you to optionally override the priorityClassName of your development container. By default, this is not set, but you can specify a custom value as shown below:

priorityClassName: okteto

This value will also apply to the priorityClassName of the pods defined in your services.

probes (boolean, optional)

If set to true, liveness, readiness, and start probes are enabled when running okteto up (default: false). More information about Kubernetes probes is available here.

Use the extended notation below to have more control over which probes to enable/disable:

probes:
  liveness: true
  readiness: true
  startup: true

• liveness: specifies if liveness probes are enabled when running okteto up (default: false).
• readiness: specifies if readiness probes are enabled when running okteto up (default: false).
• startup: specifies if startup probes are enabled when running okteto up (default: false).

resources (object, optional)

Allows you to override the resources configuration of your development container. It follows the same syntax used in Kubernetes. By default, requests, limits and ephemeral-storage are unset.

resources:
  requests:
    cpu: "250m"
    memory: "64Mi"
    ephemeral-storage: "64Mi"
  limits:
    cpu: "500m"
    memory: "1Gi"
    ephemeral-storage: "1Gi"

remote (integer, optional)

The local port to use for SSH communication with your development environment. Defaults to a random value.

remote: 2222

Setting this value in the manifest is equivalent to starting your development container with the okteto up --remote=2222 command.

reverse ([string], optional)

A list of ports to reverse forward from your development container to your local machine. The list should follow the remotePort:localPort notation and each element should be unique.

reverse:
  - 9000:9001
  - 8080:8080

Once your development container is up and running, any requests to 0.0.0.0:remotePort in the development container will be directed to localhost:localPort

Common uses of reverse forwarding are:

1. Remote debugging
2. Send events or logs to your local machine

If Okteto can't reverse forward a port (typically because they're already taken), the okteto up command will fail with an error.

secrets ([string], optional)

A list of secrets that will be injected into your development container. The format of a secret is LOCAL_PATH:REMOTE_PATH:MODE. LOCAL_PATH must exist, REMOTE_PATH must be an absolute path, and MODE is the remote file permissions in Base-8 (optional: defaults to 644).

secrets:
  - $HOME/.token:/root/.token:400

securityContext (object, optional)

Allows you to override the pod security context of your development container.

Okteto supports overriding the fsGroup, runAsUser, runAsGroup and capabilities values. They're not set by default, and they follow the same syntax used in Kubernetes.

securityContext:
  runAsUser: 1000
  runAsGroup: 2000
  fsGroup: 3000
  capabilities:
    add:
      - SYS_PTRACE

Non-root Containers:

If you're using a non-root container, and the runAsUser and runAsGroup values are not specified in your Kubernetes manifest, you need to set these values in your Okteto manifest. Remember to use the numeric ID in all cases, not the human readable name.

selector (map[string]string, optional)

The labels of the Kubernetes deployment/statefulset you want to put on development mode. They must identify a single Kubernetes deployment/statefulset.

selector:
  app.kubernetes.io/name: vote

serviceAccount (string, optional)

Allows you to override the serviceAccount of your development container.

serviceAccount: default

services ([object], optional)

A list of services that you want to put on developer mode along your development container. The services work just like the development container, with one exception: they won't be able to start an interactive session.

For example, imagine that you have a python-based application with an API and a Worker service. If you define the manifest as shown below, running okteto up would give you a remote terminal into the web development container, while synchronizing your changes with both web and worker.

dev:
  web:
    command: ["python", "manage.py", "runserver", "0.0.0.0:8080"]
    sync:
      - .:/app
    services:
      - name: worker
        replicas: 2
        command: ["celery", "worker", "-A", "myproject.celeryconf", "-Q", "default", "-n", "default@%h"]
        sync:
          - .:/app

and both deployments, web and worker will mount your local folder . into the path /app.

The supported keys for containers defined in this section are:

1. annotations
2. command
3. container
4. environment
5. image
6. labels
7. name
8. resources
9. sync
10. tolerations
11. workdir
12. replicas

They work the same as for the main container, except for the command and name keys. For services, command defaults to the command specified in your deployment, instead of sh. labels and name are mutually exclusive (for the main container, name is mandatory). replicas specifies the number of replicas for service dev containers. If replicas is not specified, it defaults to the original deployment replicas.

sync ([string], required)

Specifies local folders that must be synchronized to the development container.

sync:
  - .:/code

sync supports relative paths and environment variable expansion:

sync:
  - .:/code
  - config:/etc/config
  - $HOME/.ssh:/root/.ssh

Use the .stignore file on each local folder to avoid synchronizing build artifacts, dependencies, or git metadata. More information is available here

File sync can only update files that can be modified by your development container User ID. If you are using Okteto with persistent volumes, remember to set the field securityContext.runAsUser if your development container User ID is not root.

You can use secrets to synchronize a single file instead of a folder

There is also an extended sync notation to fine tune the file synchronization service:

sync:
  folders:
    - .:/code
  verbose: false
  compression: true
  rescanInterval: 100

• folders: list of local folders that must be synchronized to the development container
• verbose: enable verbose logging for syncthing (default: true)
• compression: compress files before synchronizing them (default: false)
• rescanInterval: the synchronization service rescan internal in seconds. It can be set to zero to disable rescans (default: 300)

timeout (time, optional)

Maximum time to be waiting for creating a development container until an error is returned.

timeout: 5m

You can also use the extended notation below to specify max time to be waiting for resources.

timeout:
  default: 3m
  resources: 5m

tolerations ([object], optional)

A list of tolerations that will be injected into your development container. More information about Kubernetes tolerations is available here.

tolerations:
  - key: nvidia.com/gpu
    operator: Exists

volumes ([string], optional)

A list of paths in your development container that you want to associate to persistent volumes. This is useful to persist information between okteto up executions, like downloaded libraries or cache information. For example, to speed your go builds up, you could define:

volumes:
  - /go/pkg/
  - /root/.cache/go-build/

You can also mount a relative subpath of your local folder:

volumes:
  - data:/var/lib/mysql

workdir (string, optional)

Sets the working directory of your development container.

external (object, optional)

A list of external resources that are part of your development environment. Use this section for resources that are deployed outside of the Okteto cluster, like Cloud resources or dashboards.

external:
  db:
    notes: docs/database.md
    icon: database
    endpoints:
    - name: db
      url: https://localhost:3306
  functions:
    notes: docs/lambdas.md
    icon: function
    endpoints:
    - name: data-aggregator
      url: https://fake-id.lambda-url.us-east-1.on.aws.aggregator
    - name: data-processor
      url: https://fake-id.lambda-url.us-east-1.on.aws.processor

endpoints ([object], required)

Endpoints contain information on how to access the external resource.

name (string, required)

The name of the endpoint.

url (string, optional)

The url of the endpoint.

Use dynamic endpoints for an external URL

The url value related to an external resource can be set during deployment stage by sharing $OKTETO_EXTERNAL_{EXTERNAL_NAME}_ENDPOINTS_{ENDPOINT_NAME}_URL. This allows a value to be generated dynamically at deployment time.

deploy:
  - name: Set endpoint URL dynamically
    command: echo "OKTETO_EXTERNAL_DB_ENDPOINTS_DB_URL=$(aws deploy db --name foo)" >> $OKTETO_ENV
  - name: Use dynamic value
    command: echo ${OKTETO_EXTERNAL_DB_ENDPOINTS_DB_URL}
external:
  db:
    notes: docs/database.md
    icon: database
    endpoints:
    - name: db
    # url: is not set because it is dynamically generated in the deploy section.

If the url value is declared in both places, the one declared in the deploy section will prevail.

icon (string, optional)

Sets the icon that will be shown in the Okteto UI. The supported values for icons are listed below. If empty, it will default to default.

aws	container	dashboard	database	default	function
gcp	graph	launchdarkly	mongodb	okteto	storage

notes (string, optional)

A relative path to a markdown file. The contents of the file will be displayed in the Okteto UI. You can use this to describe the resource or share instructions on how to use it.

GitHub Flavored Markdown (GFM) is supported, which adds the following to standard Markdown:

• Autolink literals (www.x.com)
• Footnotes ([^1])
• Strikethrough (~~stuff~~)
• Tables (| cell |…)
• Tasklists (* [x])

Images are allowed, as long as they are referenced by https://. Images from unsupported protocol sources or relative paths will not render and will be replaced with a warning message pointing to this document.

Inline HTML markup will be escaped and render as text.

forward ([string], optional)

When declaring a global forward, Okteto will automatically handle port collision when two or more okteto up sessions are running simultaneously. If the okteto up session detects that the port is already in use, and said port is defined as global forward, okteto up will ignore the port collision and continue the up sequence. If the port is later available, okteto up session will automatically connect to it without interrupting the session.

Global forward uses the same format than forward:

forward:
  - 5432:postgres:5432
  - localPort: 8080
    remotePort: 80
    name: app

You can also indicate the service to expose using a label selector.

forward:
  - localPort: 5432
    remotePort: 5432
    labels:
      app: db

icon (string, optional)

The icon associated to your development environment in the Okteto UI (optional).

name (string, optional)

The name of your development environment. It defaults to the name of your git repository.

test (object, optional)

A dictionary of Test Containers to run tests using Remote Execution.

test:
  unit:
    image: okteto/golang:1
    artifacts:
      - coverage.out
    caches:
      - /go
      - /root/.cache
    commands:
      - "go test . -v"

  integration:
    depends_on:
      - unit
    image: okteto/golang:1
    context: integration
    commands:
      - make tests
    hosts:
      - "localhost:127.0.0.1"

Each key is the name of your Test Container, and it has the following fields:

artifacts ([string], optional)

A list of files and/or folder to be exported after the execution of the tests. They will be added relative to root context of the tests. If you want to export coverage reports and test results this is where they should go.

caches ([string], optional)

A list of cache mounts to be used as part of running the tests. This is used to speed up recurrent test executions where, for example, dependencies will not be reinstalled and will instead be mounted from the cache.

commands ([string], required)

Provide a list of commands to run the tests. For the tests to be considered successful, each command must exit with a zero exit code. If any command returns a non-zero exit code, the Test Container will be marked as failed.

context (string, optional)

The folder to use as the root for running the tests. If this is empty, the location of the Okteto Manifest will be used (usually the root of the project).

info

If context is used, the .oktetoignore file must be place in the context folder

depends_on ([string], optional)

A list of Test Containers this test depends on. When a Test Container is executed, all its dependencies are executed first. The Test Containers defined in depends_on must exist in the current Okteto Manifest.

hosts ([string], optional)

A list of hostnames and ips. For each pair, an entry is created in /etc/hosts during the test execution. The following extended notation is also supported:

hosts:
  - hostname: localhost
    ip: 127.0.0.1

image (string, optional)

The base image used to run your test.

If it is not defined, Okteto uses the pipeline-runner image unless an Okteto Cluster admin has specifically changed it here with a custom installer image

Environment variables

There are multiple parts of the Okteto Manifest that deal with environment variables in one sense or another. This section should help you find the information you need.

Substitute environment variables

It’s possible to use environment variables in your shell to populate values inside an Okteto Manifest:

image: "node:${TAG}"

If you have multiple environment variables, you can substitute them by adding them to a file named .env.