Okteto Manifest Reference

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

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

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

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:

• 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).
• context: the build context. Relative paths are relative to the location of the Okteto Manifest (default: .)
• dockerfile: the path to the Dockerfile. It's a relative path to the build context (default: Dockerfile)
• target: build the specified stage as defined inside the Dockerfile. See the multi-stage official docs for details.
• 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.
• 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.
• export_cache: image tag for exported cache when build.
• cache_from: list of images to import cache from.
• depends_on: list of images that need to be built first.

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.

context (string, optional)

The okteto context when the development environment is deployed. By default, it uses the current okteto context.

For example, to force that your development environment is always created on your minikube context, you can define:

context: minikube

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

context: $DEV_CONTEXT

dependencies ([string], optional)

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

dependencies is only supported in clusters that have Okteto installed.

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

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

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

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

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

Or:

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 where the manifest is defined as the context.

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 custom command invoking 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.

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

More information about affinity is available here.

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 the variable USER doe 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)

If set to true, postStart and postStop lifecycle events are enabled when running okteto up (default: false). More information about lifecycle events is available here.

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

lifecycle:
  postStart: false
  postStop: true

• postStart: specifies if the postStart event is enabled when running okteto up (default: false).
• postStop: specifies if postStop event is enabled when running okteto up (default: false).

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.

nodeSelector:
  disktype: ssd

More information about nodeSelector is available here.

persistentVolume (object, optional)

Allows you to configure the okteto persistent volume:

• enabled: enable/disable the use of persistent volumes (default: true)
• storageClass: the storage class of the volume (default: the default storage class)
• size: the size of the okteto persistent volume (default: 2Gi)

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 while developing an app.

probes (boolean, optional)

If set to true, liveness, readiness, and start probes are enabled when running okteto up (default: false).

More information about 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. namespace
9. resources
10. sync
11. tolerations
12. workdir
13. 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.

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.

namespace (string, optional)

The namespace where the development environment is deployed. By default, it takes the current okteto context namespace.

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

namespace: $DEV_NAMESPACE

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.