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: votelabels: app.kubernetes.io/part-of: vote app.kubernetes.io/component: apiimage: python:3command: ["python", "app.py"]workdir: /usr/src/appsync: - .:/usr/src/appenvironment: - name=$USER - environment=developmentresources: requests: memory: "64Mi" cpu: "250m" limits: memory: "128Mi" cpu: "500m"forward: - 8080:80 - 5432:postgres:5432reverse: - 9000:9001securityContext: 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"
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 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 theimage
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: thedefault
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 betrue
if you use services.persistentVolume.enabled
must betrue
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: webcommand: ["python", "manage.py", "runserver", "0.0.0.0:8080"]sync: - .:/appservices: - 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
.
There is also an extendend sync
notation to fine tune the file synchronization service:
sync: folders: - .:/code compression: true rescanInterval: 100
folders
: list of local folders that must be synchronized to the development container.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
).
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: /oktetosync: - .:/okteto
This behavior is deprecated and will be removed in future versions. Define your synchronized folders using the sync field of your okteto manifest.