Okteto Manifest Reference

okteto.yml is a manifest format for describing development containers. It declares the deployment target, the dev container, the folders to be synchronized, and other information required to activate your development container.

Example#

name: vote
labels:
  app.kubernetes.io/part-of: vote
  app.kubernetes.io/component: api
image: python:3
command: ["python", "app.py"]
workdir: /usr/src/app
sync:
 - .:/usr/src/app
environment:
  - name=$USER
  - environment=development
resources:
  requests:
    memory: "64Mi"
    cpu: "250m"
  limits:
    memory: "128Mi"
    cpu: "500m"
forward:
  - 8080:80
  - 5432:postgres:5432
reverse:
  - 9000:9001
securityContext:
  runAsUser: 1000
  runAsGroup: 2000
  fsGroup: 3000
  capabilities:
    add:
    - SYS_PTRACE

Schema reference#

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.

annotations (map[string]string, optional)#

A list of annotations that will be injected into your development container.

annotations:
  fluxcd.io/ignore: "true"

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.

context (string, optional)#

The kubeconfig context of the deployment you want to put on development mode. By default, it uses the current kubeconfig context.

You can also use the OKTETO_CONTEXT environment variable to set the kubeconfig context for all your okteto commands. The context defined in the okteto manifest will take priority over the OKTETO_CONTEXT environment variable.

For example, to force that okteto up always run 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

divert (object, optional)#

Adding divert to your manifest modifies how development mode is enabled. Development mode, without a divert configured, always replaces the target deployment with a development container. Development mode, with a divert configured, will duplicate the target deployment, ingress, service, and port used by the deployment. HTTP traffic will then be diverted to the duplicated deployment when the new ingress is used.

The divert option has the benefit of allowing you to use both the original application and the actively developed application side-by-side, depending on which ingress is used.

divert:
  ingress: api
  service: api
  port: 8080

ingress: the name of the Kubernetes ingress to be duplicated for the development deployment
service: the name of the Kubernetes service to be duplicated for the development deployment
port: optionally defines the service port used when there are multiple ports

Code changes must also be made to your application in order to make use of a divert. The divert functionality relies on the use of HTTP headers. In particular the x-okteto-dvrt header, added by the duplicate ingress, must be propagated by each application. This is similar to the stratagy use for tracing and a library for Go can be found here.

docker (object, optional)#

Allows you to automatically inject a Docker in Docker (DinD) sidecar in your development environment. This feature is only supported in Okteto Enterprise.

docker:
  enabled: true
  image: docker:20-dind
  resources:
    requests:
      cpu: 30m
      memory: 30Mi
    limits:
      cpu: 30m
      memory: 30Mi

enabled: set to true to inject the DinD sidecar in your development environment (default: false)
context: the image of the DinD sidecar container (default: docker:20-dind)
resources: resources configuration of the Did sidecar container

When DinD is enabled, the okteto persistent volume must be enabled too. The DinD container uses the okteto persistent volume to persist /var/lib/docker, the folder used by Docker to store image cache layers.

Your Okteto Registry credentials are injected automatically into your development environment allowing you to pull and push docker images from the Okteto registry.

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

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 peristent 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:
Access a service via localhost instead of via an ingress
Remote debugging
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

healthchecks (bool, optional)#

This field is deprecated in favor of probes and will be removed in future versions.

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

More information about health checks is available here.

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.

Use the extended notation to configure how to build your dev image when running okteto up --build:

image:
  name: okteto/golang:1
  context: .
  dockerfile: Dockerfile
  target: dev
  args:
    - ENV1=dev
    - ENV2=$VALUE

name: the container image of your development container. The same as the image single notation.
context: the build context sent to BuildKit. When the value supplied is a relative path, it's relative to the location of the okteto manifest file (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 build Docker 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, which can be helpful for secret or machine-specific values.

imagePullPolicy (string, optional)#

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

labels (map[string]string, optional)#

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

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).

name (string, required)#

The name of your development container. If labels is not defined, it's also the name of the kubernetes deployment you want to put on development mode.

namespace (string, optional)#

The namespace of the deployment you want to put on development mode. By default, it takes the current kube config namespace.

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

namespace: $DEV_NAMESPACE

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.

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).

push (object, optional)#

Allows you to configure how to build your image when running okteto push:

context: the build context sent to BuildKit. When the value supplied is a relative path, it's relative to the location of the okteto manifest file (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 build Docker 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, which can be helpful for secret or machine-specific values.

push:
  context: .
  dockerfile: Dockerfile
  target: prod
  args:
    - ENV1=prod
    - ENV2=$VALUE

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 and limits are unset.

resources:
  requests:
    cpu: "250m"
    memory: "64Mi"
  limits:
    cpu: "500m"
    memory: "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:
Remote debugging
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.

services ([object], optional)#

A list of other containers (other than the main development container) that you want to put on developer mode. The difference with the main development container and the ones defined in this section is that the main development container gives you an interactive session, where you can, for example, execute a shell. The containers defined in this section run in detached mode, but they can also mount your local folders in a particular path.

For example, to put a Django application on developer mode you could use the following manifest:

name: web
command: ["python", "manage.py", "runserver", "0.0.0.0:8080"]
sync:
  - .:/app
services:
  - name: worker
    command: ["celery", "worker", "-A", "myproject.celeryconf", "-Q", "default", "-n", "[email protected]%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:

annotations
command
container
environment
image
labels
name
namespace
resources
sync
tolerations
workdir

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).

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/id_rsa:/root/.ssh/id_rsa

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, rememeber to set the field securityContext.runAsUser if your development container User ID is not root.

There is also an extendend 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.

If the sync field is not specified, workdir automatically adds a sync section to your okteto manifest. For example:

workdir: /okteto

is equivalent to:

workdir: /okteto
sync:
  - .:/okteto

This behavior is deprecated and will be removed in future versions. Define your synchronized folders using the sync field of your okteto manifest.

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 file:

image: "node:${TAG}"

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

The .env file#

You can set default values for any environment variables referenced in the Okteto Manifest file in an environment file named .env. The .env file is placed at the same folder than the Okteto Manifest.

For example:

$ cat .env
TAG=v1.5

$ cat okteto.yml
name: app
image: "node:${TAG}"

When you run okteto up the app container uses the image node:v1.5.

Values in the shell take precedence over those specified in the .env file.

Advanced Scenarios#

Prevent okteto from interacting with sensitive namespaces#

If you add the dev.okteto.com/not-allowed=true label to a namespace, okteto up will automatically fail. You can use this to prevent you or your team from deploying a development environment into a sensitive namespace, like staging or production.

$ kubectl label namespace staging dev.okteto.com/not-allowed=true

$ kubectl get namespace staging -oyaml
apiVersion: v1
kind: Namespace
metadata:
  annotations:
    dev.okteto.com/not-allowed: "true"
  name: staging
spec:
  finalizers:
  - kubernetes

User-level overrides#

User-level overrides can be used to modify or augment the okteto manifest included in your project's repository. You can use this to synchronize extra files, set a different context, change the command, add new environment variables, etc... In order to override the values of an existing manifest, you'll need to create a file named .okteto/okteto.yaml in your home directory. Any values specified in this fill will overwrite or merge with the values specified in your repository's okteto manifest file.

annotations#

Overwrites project file annotations if they are defined or adds them if they are not defined.

command#

Overwrites project file command

context#

Overwrites project file context

docker#

Overwrites project file docker

environment#

Overwrites project file environment variables if they are defined or adds them if they are not defined.

forward#

Overwrites project file forward ports if they are defined or adds them if they are not defined.

initContainer#

Overwrites project file initContainer

labels#

Overwrites project file labels if they are defined or adds them if they are not defined.

namespace#

Overwrites project file namespace

persistentVolume#

Overwrites project file persistent volume information

resources#

Overwrites project file resources

reverse#

Overwrites project file reverse ports if they are defined or adds them if they are not defined.

secrets#

Overwrites project file secrets

sync#

Overwrites project file sync folders

timeout#

Overwrites project file timeout