Skip to main content
Version: okteto.com (1.2)

Okteto Manifest

okteto.yml 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.

Note: This doc contains the reference to the latest version of the Okteto manifest. For older versions, the supported manifest reference can be found here.

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 develoment environment.

build:
base:
context: .
api:
context: api
frontend:
context: frontend
dockerfile: Dockerfile
target: dev
depends_on: base
build_args:
SOURCE_IMAGE: ${OKTETO_BUILD_BASE_IMAGE}

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

In order to refer to these images from anywhere in your Okteto Manifest, you can use the following environment variables:

  • ${OKTETO_BUILD_<service>_IMAGE}: the full image reference
  • ${OKTETO_BUILD_<service>_REGISTRY}: the registry URL where the image was pushed
  • ${OKTETO_BUILD_<service>_REPOSITORY}: the name of the image that was pushed
  • ${OKTETO_BUILD_<service>_SHA}: the latest tag and the SHA of the image

For example, for the image registry.cloud.okteto.net/cindy/hello-world:okteto, you would have the following values:

  • OKTETO_BUILD_HELLO_WORLD_IMAGE: registry.cloud.okteto.net/cindy/hello-world@sha256:xxx
  • OKTETO_BUILD_HELLO_WORLD_REGISTRY: registry.cloud.okteto.net
  • OKTETO_BUILD_HELLO_WORLD_REPOSITORY: cindy/hello-world
  • OKTETO_BUILD_HELLO_WORLD_SHA: okteto@sha256:xxx

if a <service> name includes the symbol -, in the corresponding OKTETO_BUILD_<service> environment variables, the symbol - will be replaced by _. For example, if <service> is name-with-hyphen, the environment variable names will start with $OKTETO_BUILD_NAME_WITH_HYPHEN_.

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

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.yml
branch: main
variables:
ENVIRONMENT: development
DEBUG: true
wait: true

Or:

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

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 a Docker Compose file:

If you are planning to develop with your docker-compose only, you should check out our Getting Started guide!

You can also create an okteto.yml manifest to get even more out of okteto (e.g. to customize the folders that get synchronized, add extra environment variables, etc...). If you do that, you'll need to update the deploy section as follows:

deploy:
compose: docker-compose.yml

Deploy a helm chart:

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}

Advanced deploy:

There is an extended notation to deploy Docker compose files and endpoints as part of your development environment:

The services field allows us to deploy only a subset of the services in the Docker compose file. Only the volumes and endpoints of the services specified in the services field are deployed.

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

You can even merge 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

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:
- terraform destroy --auto-approve

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

  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"

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

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

You can use secrets if you need to synchronize a single file instead of a folder

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.

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 environmen in the Okteto Dashboard (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.

The .env file

You can set default values for any environment variables referenced in the okteto manifest 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
...
image: "node:${TAG}"
...

When you any Okteto CLI command, image will be node:v1.5.

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