Docker Compose Reference

Docker Compose are for developers who don't want to deal with the complexities of Kubernetes manifests. Okteto implements and extends the Compose Specification to make it easy to develop Docker Compose applications in Kubernetes.

Example

services:
  vote:
    build: vote
    scale: 2
    environment:
      - FLASK_ENV=development
    command: python app.py
    ports:
      - 8080:8080
    volumes:
      - ./vote:/src

  redis:
    image: redis
    ports:
      - 6379
    volumes:
      - redis:/data

volumes:
  redis:

The equivalent Kubernetes manifests would have more than 300 lines of yaml!

Schema reference

services ([object], optional)

Define the services that make up your Docker Compose application.

services:
  vote:
    build: vote
    scale: 2
    ports:
      - 8080:8080

  redis:
    image: redis
    ports:
      - 6379
    volumes:
      - redis:/data

Each service supports the fields in the Compose Specification. We summarize the most relevant ones below:

build ([string|object], optional)

Indicate how to build the image of this service when running okteto build or okteto deploy --build. The value is the path to the build context:

build: vote

It can also be an object with these fields:

• context: the build context. When the value supplied is a relative path, it is interpreted as relative to the location of the Docker Compose 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: prod
  args:
    - ENV1=prod
    - ENV2=$VALUE

okteto deploy builds a new docker image, pushes it to the registry and redeploys your containers.

cap_add ([string], optional)

Add container capabilities. See man 7 capabilities for a full list.

cap_add:
  - ALL

cap_drop ([string], optional)

Drop container capabilities. See man 7 capabilities for a full list.

cap_drop:
  - NET_ADMIN
  - SYS_ADMIN

command (string, optional)

Override the default command of the container image CMD.

command: --debug

command can also be a list of strings:

command: ["-p", "3000"]

depends_on ([string]|object, optional)

Specify the conditions that the declared services must meet in order for the service to start. The condition must be one of the following:

• service_started: Wait until the service is running.
• service_healthy: Wait for one of the ports of the dependent service to be available, or for its healthcheck test commands to complete successfully.
• service_completed_successfully: Wait until the dependent service has been successfully completed.

depends_on:
  app:
    condition: service_started
  db:
    condition: service_healthy
  initialization-svc:
    condition: service_completed_successfully

You can also express dependencies as a list of services. In this case it will be the same as setting the condition to service_started.

depends_on:
  - app
  - db
  - initialization-svc

info

💡 To enforce depends_on ordering during environment wake-up, enable the OKTETO_COMPOSE_DEPENDS_ON_ENABLED feature flag.

endpoint_mode (string, optional)

Specify the endpoint mode for the service.

• vip (default): Creates a virtual IP endpoint that maps to a standard Kubernetes ClusterIP service, providing load balancing across service replicas.
• dnsrr: Creates a DNS round-robin endpoint that maps to a Kubernetes headless service (ClusterIP: None), where DNS queries return all pod IPs directly without load balancing.

deploy:
  endpoint_mode: dnsrr

warning

When endpoint_mode is set to dnsrr, Okteto Divert will not work.

info

More information here: https://compose-spec.github.io/compose-spec/deploy.html#endpoint_mode

entrypoint (string, optional)

Override the default entrypoint of the container image ENTRYPOINT.

entrypoint: yarn start

The entrypoint can also be a list of strings:

entrypoint: ["yarn", "start"]

env_file (string, optional)

Add environment variables from a file to the containers of a service. Environment variables declared in the environment section override these values. This also holds true if those values are empty or undefined.

env_file: .env

env_file also accepts a list of files:

env_file:
  - .env.frontend
  - .env.api

environment ([string], optional)

Add environment variables:

environment:
  DEV_MODE: yes
  DB_HOST: postgres://${DB_HOST:-db}:${DB_PASSWORD}@postgres:5432/postgres

healthcheck (object, optional)

healthcheck declares a check that's run to determine whether or not containers for a service are "healthy".

• start_period (duration): Time between the start of the container and the initiation of the healthcheck.
• interval (duration): Time between a healthcheck and a subsequent new try.
• timeout (duration): Number of seconds after which the healthcheck times out.
• retries (int): Number of retries before healthcheck fails.
• test (string): Defines the command that will be run to check the container's health. It can be either a string or a list. If it's a list, the first item must be either NONE, CMD or CMD-SHELL. If it's a string, it's equivalent to specifying CMD-SHELL followed by that string.
• http (object): Defines the path and port that has to be tested on the container to set the healthcheck as successful
• x-okteto-readiness (bool): Defines if the probe should be a readiness probe (default: true).
• x-okteto-liveness (bool): Defines if the probe should be a liveness probe (default: false).

healthcheck:
  interval: 10s
  timeout: 10m
  retries: 5
  start_period: 30s
  http:
    path: /
    port: 8080

Healthchecks can also test a command as follows:

healthcheck:
  interval: 10s
  timeout: 10m
  retries: 5
  start_period: 30s
  test: echo 'db.runCommand({serverStatus:1}).ok' | mongo admin -u $MONGO_INITDB_ROOT_USERNAME -p $MONGO_INITDB_ROOT_PASSWORD --quiet | grep 1

image (string, optional)

The container image of each service.

image: ghcr.io/okteto/vote:compose

If build is defined, image is optional. Otherwise, it's required.

labels ([string], optional)

Specify labels for the service. They translates to Kubernetes annotations.

labels:
  app: sample

You can set the update policy of a service by setting the label dev.okteto.com/update.

Depending on the kind of resource the acceptance values are different:

• rolling: Will deploy a service with zero downtime. Only allowed for deployments and stateful sets.
• recreate: Will wait until the current pod is deleted to start creating the new one. Only allowed on deployments.
• on-delete: Will wait until the current pod is deleted to start creating the new one. Only allowed on stateful sets.

services:
  deployment:
    image: python:alpine
    labels:
      "dev.okteto.com/update": rolling
    entrypoint: python -m http.server 8080
    ports:
      - 8080:8080
  sfs:
    image: python:alpine
    labels:
      "dev.okteto.com/update": on-delete
    entrypoint: python -m http.server 8080
    ports:
      - 8080:8080
    volumes:
    - /usr/src

info

Remember that Docker Compose labels are translated into Kubernetes annotations.

ports ([int], optional)

Ports exposed by each service. By default, they're only accessible from the cluster private network.

ports:
  - 8080

To make the port public, use the following notation:

ports:
  - 8080:8080

If you need to configure HTTPS routes, use endpoints instead of configuring an NGINX container in your Docker Compose file.

The following ports are never made public:

Protocol	Port
MySQL	3306
OracleDB	1521,1830
PostgreSQL	5432
SQL Server	1433,1434
MaxDB	7210
Neo4j	7473
ArangoDB	8529
Cassandra	7000,7001,9042
InfluxDB	8086
Elasticsearch	9200,9300
CouchDB	5984
MongoDB	27017,27018,27019,28017
Redis	6379
Riak	8087,8088
RethinkDB	828015,29015,28015
Solr	7574,8983
Golang debugger	2345
Node debugger	5858,9229
Java debugger	5005
Ruby debugger	1234
Python debugger	4444,5678

If you need make these ports public, you can use endpoints.

resources (object, optional)

Configure resource requests and limits.

resources:
  requests:
    cpu: 300m
    memory: 500Mi
  limits:
    cpu: 500m
    memory: 800Mi

Or with the docker-compose v3 configuration.

deploy:
  resources:
    reservations:
      cpus: 500m
      memory: 800Mi
    limits:
      cpus: 300m
      memory: 500Mi

restart (string, optional)

Defines the policy that the platform will apply on container termination.

• always/unless-stopped/any: The default restart policy. The policy always restarts the container until its removal.
• none/never/no: The policy does not restart a container under any circumstances.
• on-failure: The policy restarts a container if the exit code indicates an error.

deploy:
  restart_policy:
    condition: on-failure
    max_attempts: 3

If the restart policy is other than always, the service will be translated to a Kubernetes Job.

scale (int, optional)

Specify the number of containers running for each service (default: 1).

scale: 2

stop_grace_period (duration|int, optional)

Specify how long to wait when attempting to stop a container before sending SIGKILL. If no unit of time is given, the system will interpret the number in seconds.

stop_grace_period translates to the terminationGracePeriod setting in the pod.

stop_grace_period: 10s

volumes ([string], optional)

Define volumes accessible by the containers of a service at a given path.

volumes:
  - redis:/data

The volume redis must be defined in the volumes section.

The following notation is also accepted:

volumes:
  - /data

Finally, host volumes are also supported:

volumes:
  - .:/usr/app/src

Host volumes are ignored at deployment time if the service defines a build section. Otherwise, they are added to the content of the image defined by the service.

okteto up uses host volumes to infer the sync paths between your local filesystem and your remote development container.

By default, services mounting the same volume will be placed on the same node using Kubernetes's pod affinity. If you wish to disable this behavior, set the environment variable OKTETO_COMPOSE_VOLUME_AFFINITY_ENABLED to false when deploying. You can also optionally configure this variable from the Okteto UI to make it available to all development environments in your namespace.

working_dir (string, optional)

Override the default working directory of the container image WORKDIR.

working_dir: "/app/code"

x-node-selector (map[string]string, optional)

List of labels that the node must have to include the service containers on it.

x-node-selector:
  disktype: ssd

More information about Kubernetes node selectors is available here.

volumes ([object], optional)

List of volumes created by the Docker Compose file. Volumes are mounted on the containers of a given service by referring the volume from the volumes field of the service.

volumes:
  redis:
    driver_opts:
      size: 1Gi

Each volume has the following properties:

driver_opts.class (string, optional)

Specify the storage class of the volume.

driver_opts:
  class: standard

driver_opts.size (string, optional)

Specify the size of the volume. Defaults to 1Gi.

driver_opts:
  size: 1Gi

labels (string, optional)

Specify labels for the volume. They will translate to Kubernetes annotations.

labels:
  app: redis

Environment variables

There are multiple parts of Docker Compose files that deal with environment variables in one sense or another. This section should help you find the information you need.

Environment variable substitution

It’s possible to use environment variables in your shell to populate values inside your Docker Compose file:

services:
  web:
    image: "app:${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 your Docker Compose file in an environment file named .env. The .env file is placed at the same folder than the Docker Compose file.

For example:

$ cat .env
TAG=v1.5

$ cat docker-compose.yml
services:
   web:
      image: "app:${TAG}"

When you run okteto deploy the web container uses the image app:v1.5.

note

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

extensions (object, optional)

Specifies a configuration that can be used in other services using anchors. Every top-level field starting with the prefix 'x-' will be interpreted as an extension.

x-function: &environment
  environment:
    DEV_MODE: yes
    DB_HOST: postgres://${DB_HOST:-db}:${DB_PASSWORD}@postgres:5432/postgres
services:
  app:
    <<: *environment
    image: okteto.dev/example

Okteto Variables

You can also use your Okteto Variables in your Docker Compose file.

For example, if your have an Okteto Variable named PASSWORD whose value is change-me!, the following Docker Compose file:

services:
  mysql:
    image: mysql
    environment:
      - MYSQL_ROOT_PASSWORD=${PASSWORD}

will use change-me! for the value of the MYSQL_ROOT_PASSWORD environment variable of the mysql service when you run okteto deploy.

note

Values in the shell and/or the .env file take precedence over those specified as Okteto Variables.

Okteto makes Docker Compose even more powerful!

Okteto extends the Compose Specification to make it even easier for you and your team to build cloud-native applications.

endpoints ([object], optional)

Endpoints expose HTTPS routes from outside the cluster to services within the cluster. Use this instead of having to run a NGINX proxy in your Docker Compose file.

endpoints:
  - path: /
    service: frontend
    port: 80
  - path: /api
    service: api
    port: 8080

The endpoint uses the name of the development environment to generate a URL with the following format: https://NAME-NAMESPACE.okteto.example.com.

Each endpoint has the following properties:

path (string, required)

The request path that will handle this route.

service (string, required)

The service that will receive the request.

port (int, required)

The port that will receive the request.

If more than one endpoint is needed, you can declare multiple endpoints by using a map with the name of the endpoint and its specification:

endpoints:
  landing:
    - path: /
      service: nginx
      port: 80
  web:
    - path: /
      service: frontend
      port: 80
    - path: /api
      service: api
      port: 8080

In this case, the URLs landing-NAMESPACE.okteto.example.com and web-NAMESPACE.okteto.example.com are created.

endpoints also accepts an extended notation to specify labels for each endpoint:

endpoints:
  labels:
    kubernetes.io/ingress.class: nginx
  rules:
    - path: /
      service: frontend
      port: 3000
    - path: /api
      service: backend
      port: 8080

Compatibility Guide

Okteto supports a large subset of the Docker Compose specification and introduces a few useful extensions to simplify Kubernetes development. The table below outlines the compatibility between standard Compose keys and Okteto's implementation, helping you understand which features are fully supported, partially supported with warnings, silently ignored, or unique to Okteto.

Legend

Emoji	Meaning
✅	Fully supported by Okteto – it is unmarshalled into a regular Go type
⚠️	Recognized but unsupported – Okteto will recognize it but will throw a warning
⛔️	The key is missing from Okteto’s structs, therefore silently ignored
🆕	Key exists in Okteto but is not part of the Compose Spec (Okteto-specific)

---

Top-level Keys

Key	Compose Spec	Okteto	Notes
name	yes	✅
services	yes	✅
volumes	yes	✅
networks	yes	⚠️	Warning shown to the user
configs	yes	⚠️	Warning shown to the user
secrets	yes	⚠️	Warning shown to the user
version (obsolete)	yes	✅	Kept for back-compatibility
profiles	yes	⛔️	Ignored
x-* extension keys	yes	⛔️	Ignored but we ignore them consciously
endpoints	—	🆕	Okteto-specific syntax

Service Spec

✅ Supported

annotations
build.context / dockerfile / args
cap_add / cap_drop
command
depends_on
deploy.replicas
deploy.resources.{limits|reservations}
deploy.restart_policy.max_attempts
deploy.endpoint_mode
entrypoint
env_file
environment
healthcheck
image
labels
mem_limit
mem_reservation
cpu_count / cpus
ports / expose
restart
stop_grace_period
user
volumes
volumes.sub_path
working_dir
scale (short syntax)

⚠️ Recognized but Unsupported (Warning Shown)

blkio_config
cgroup_parent
configs
container_name
cpu_percent
cpu_period
cpu_quota
cpu_rt_period
cpu_rt_runtime
cpu_shares
cpuset
credential_spec
device_cgroup_rules
devices
dns
dns_opt
dns_search
domainname
driver_opts
extends
external_links
extra_hosts
group_add
hostname
init
ipc
isolation
links
logging
mac_address
mem_swappiness
memswap_limit
network_mode
networks
oom_kill_disable
oom_score_adj
pid
pids_limit
platform
privileged
profiles
pull_policy
read_only
runtime
secrets
security_opt
shm_size
stdin_open
stop_signal
storage_opts
sysctls
tmpfs
tty
ulimits
userns_mode
volumes_from

⛔️ Silently Ignored

attach
cgroup
develop
gpus
interface_name
label_file
link_local_ips
post_start
pre_stop
provider.*
uts

---

🆕 Okteto-Specific Extras

Key	Purpose
public: true	Auto-generate a Kubernetes Ingress
x-node-selector	Pod scheduling hint
resources	Set CPU / Memory
scale	Compose-style replica shorthand (alias for deploy.replicas)

---

Volume Section

Attribute	Compose Spec	Okteto	Notes
labels	yes	✅
driver, driver_opts, external	yes	⚠️	Warning then ignored
size, class	—	🆕	PVC size & storage-class helpers

---

Networks, Configs & Secrets Blocks

All three blocks are parsed only to raise a warning; every sub-field therefore falls under ⚠️.