Okteto Manifest Reference

okteto.yml is a manifest format for describing development containers. It declares the deployment target, the dev container, the working directory and other information required to activate your development container 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
sync:
- .:/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 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 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 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:

  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 container. Defaults to the image specified in your deployment.

More information on how to create your own development container 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.

remote (integer, optional)

Enables the remote mode for your development container.

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

When remote mode is activated, the following happens:

  • An SSH server is injected into your development container.
  • A port forward is created from the selected local port to port 22 of the development container.
  • 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 container 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 container 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 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 remote 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.

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

  1. annotations
  2. command
  3. container
  4. environment
  5. image
  6. labels
  7. mountpath
  8. name
  9. namespace
  10. resources
  11. sync
  12. subpath
  13. tolerations
  14. 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.