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

annotations (map[string]string, optional)

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

annotations:
  fluxcd.io/ignore: "true"

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 takes the current kube config context.

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

environment ([string], optional)

A list of environment variables that will be injected into 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 are resolved 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 container, 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

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.

healthchecks (bool, optional)

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

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 that is sent to BuildKit. When the value supplied is a relative path, it is interpreted as relative to the location of the okteto manifest file (default: .)
dockerfile: the path to the Dockerfile. It is 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 ennvionemnt (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.

mountpath (string, optional)

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

Sets the mount path of your local folder in your development container (default: /okteto).

name (string, required)

The name of your development container. If labels is not defined, it is 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

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.

push (object, optional)

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

context: the build context that is sent to BuildKit. When the value supplied is a relative path, it is interpreted as relative to the location of the okteto manifest file (default: .)
dockerfile: the path to the Dockerfile. It is 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 are 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 are 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 are 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
mountpath
name
namespace
resources
sync
subpath
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.

subpath (string, optional)

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

Sets a relative subpath of your local folder to mount in your development container, instead of mounting the root of your local folder. It is only supported for services.

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

Example#

Schema reference#

annotations (map[string]string, optional)#

command (string, optional)#

container (string, optional)#

context (string, optional)#

environment ([string], optional)#

externalVolumes ([string], optional)#

forward ([string], optional)#

healthchecks (bool, optional)#

interface (string, optional)#

image (string, optional)#

imagePullPolicy (string, optional)#

labels (map[string]string, optional)#

mountpath (string, optional)#

name (string, required)#

namespace (string, optional)#

persistentVolume (object, optional)#

push (object, optional)#

resources (object, optional)#

remote (integer, optional)#

reverse ([string], optional)#

secrets ([string], optional)#

securityContext (object, optional)#

services ([object], optional)#

sync ([string], required)#

subpath (string, optional)#

tolerations ([object], optional)#

volumes ([string], optional)#

workdir (string, optional)#