Stacks Manifest Reference

Okteto Stacks are for developers who don't want to deal with the complexities of Kubernetes manifests. Okteto Stacks implement and extend the Compose Specification to make it easy to deploy containers in Kubernetes.

Example#

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

  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 Okteto Stack.

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 stack 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 Okteto Stack 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: prod
  args:
    - ENV1=prod
    - ENV2=$VALUE

okteto stack deploy --build builds a new docker image, pushes it to the registry and redeploys your containers. By default, it builds the images using the Okteto Build Service. Set the variable BUILDKIT_HOST if you want to use your own BuildKit instance.

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

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

image (string, optional)#

The container image of each service.

image: okteto/vote:stacks

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

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

In you need 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
Rethink	828015,29015
Solr	7574,8983
Golang debugger	2345
Node debugger	5858,9229
Java debugger	5005
Ruby debugger	1234
Python debugger	4444,5678

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

scale (int, optional)#

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

scale: 2

resources (object, optional)#

Configure resource requests and limits.

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

reservations translates to Kubernetes requests.

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.

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

working_dir (string, optional)#

Override the default working directory of the container image WORKDIR.

working_dir: "/app/code"

volumes ([object], optional)#

List of volumes created by the Okteto Stack. 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:

labels (string, optional)#

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

labels:
  app: redis

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

Environment variables#

There are multiple parts of Okteto Stacks 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 Okteto Stack:

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 Okteto Stack in an environment file named .env. The .env file is placed at the same folder than the Okteto Stack manifest.

For example:

$ cat .env
TAG=v1.5

$ cat okteto-stack.yml
services:
   web:
      image: "app:${TAG}"

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

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

You can also use your Okteto Secrets in your Okteto Stack.

For example, if your have an Okteto Secret named PASSWORD whose value is change-me!, the following Okteto Stack:

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 stack deploy.

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

Okteto Cloud makes Docker Compose even more powerful!#

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

name (string, optional)#

The name of the Okteto Stack. Used by the Okteto UI to group the resources created by this stack. Defaults to the name of the git repository. If the current path doesn't belong to a git repository, defaults to the name of the current folder.

name: voting-app

namespace (string, optional)#

The namespace where you want to deploy your Okteto Stack. If not specified, it uses the current Okteto namespace.

namespace: development

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 stack to generate a URL with the following format: https://STACK_NAME-NAMESPACE.cloud.okteto.net.

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.cloud.okteto.net and web-NAMESPACE.cloud.okteto.net 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