Okteto Manifest Reference

okteto.yml is a manifest format for describing development environments. It declares the deployment target, the dev container, the working directory and other information required to activate your development environment with Okteto.

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
environment:
  - name=$USER
  - environment=development
secrets:
  - $HOME/.token:/root/.token:400
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 environment.

...
annotations:
  fluxcd.io/ignore: "true"
...

build (object, optional)

Allows you to configure how to build your dev image when running okteto up --build:

  • 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.
...
build:
  context: .
  dockerfile: Dockerfile
  target: dev
  args:
    - ENV1=dev
    - ENV2=$VALUE
...

command (string, optional)

Sets the command of your development environment. 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 transform into a development environment. By default, it takes the first one.

environment ([string], optional)

A list of environment variables that will be injected into your development environment. 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 that starts 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 environment. This is useful to share cache information between different development environments. For example, to share the go cache between different development environments, 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 environment. 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 environment 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), an error will be logged in the console.

healthchecks (bool, optional)

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

image (string, optional)

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

More information on how to create your own development environment 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 environment is available here.

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 transform into a development environment. They must identify a single Kubernetes deployment.

mountpath (string, optional)

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

Use the .stignore file to avoid synchronizing build artifacts, dependencies or git metadata. More information here

name (string, required)

The name of your development environment. If labels is not defined, it is also the name of the kubernetes deployment you want to transform into a development environment.

namespace (string, optional)

The namespace of the deployment you want to transform into a development environment. By default, it takes the current kube config namespace.

persistentVolume (object, optional)

Allows you to configure the okteto persistent volume:

  • enabled: enable/disable the use of persistent volumes (default: false)
  • storageClass: the storage class of the volume (default: the default storage class)
  • size: the size of the okteto persistent volume (default: 10Gi)
...
persistentVolume:
  enabled: true
  storageClass: standard
  size: 30Gi
...

persistentVolume.enabled must be true if you use services.

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 environment. It follows the same syntax used in Kubernetes. By default, requests and limits are unset.

remote (integer, optional)

Enables the remote mode for your development environment.

...
name: dev
remote: 2222
...

When remote mode is activated, the following happens:

  • An SSH server is injected into your development environment.
  • A port forward is created from the selected local port to port 22 of the development environment.
  • A host entry is added to your local .ssh/config file with the following values:
Host MANIFEST_NAME.okteto
  HostName localhost
  Port PORT
  StrictHostKeyChecking no
  UserKnownHostsFile /dev/null

Once the development environment is up and running, you can SSH into it with the command below:

ssh -P 2222 localhost

You can also ssh using the host entry added to your local SSH config:

ssh MANIFEST_NAME.okteto

When you run okteto up the first time, Okteto will create a SSH key pair for you and save it at $HOME/.okteto/id_rsa_okteto and $HOME/.okteto/id_rsa_okteto.pub. The SSH server launched in your development environment will be automatically configured to use these keys for authentication.

The remote mode is useful for integrating with IDEs that support remote development, such as VS Code, PHPStorm or PyCharm.

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

reverse ([string], optional)

A list of ports to reverse forward from your development environment 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 environment is up and running, any requests to 0.0.0.0:remotePort in the remote development environment will be directed to localhost:localPort

Common uses of reverse forwarding are:

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

Enabling this feature will automatically enable remote mode as well if it's not already enabled. If your manifest doesn't include the remote key, a random port will be selected.

If Okteto can't reverse forward a port (typically because they are already taken), an error will be logged in the console.

secrets ([string], optional)

A list of secrets that will be injected into your development environment. 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 environment.

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 one) that you want to put in developer mode. The difference with the main container and the ones defined in this section is that the main container is transformed into 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 folder in a particular path.

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

name: web
workdir: /app
command: ["python", "manage.py", "runserver", "0.0.0.0:8080"]
services:
  - name: worker
    workdir: /app
    command: ["celery", "worker", "-A", "myproject.celeryconf", "-Q", "default", "-n", "[email protected]%h"]

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. mountpath
  8. name
  9. namespace
  10. resources
  11. subpath
  12. tolerations
  13. 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).

subpath (string, optional)

Sets a relative subpath of your local folder to mount in your development environment, 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 environment.

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

volumes ([string], optional)

A list of paths in your development environment 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 environment. If mountpath is not specified, workdir also specifies the mount path of your local folder in your development environment.

Use the .stignore file to avoid synchronizing build artifacts, dependencies or git metadata. More information here.