Important Update: Migrating from Okteto Stacks to Docker Compose

Help
1

In January 2021, we announced compatibility between Okteto Stacks and Docker Compose. Okteto Stacks is an application format inspired by Docker Compose to simplify application deployment on Kubernetes. Since the Docker Compose Spec was open-sourced, Okteto has been working on supporting the Docker Compose spec. This is in the spirit of joining forces and simplifying the learning curve to adopt Okteto for people using Docker Compose.

Why are we deprecating Okteto Stacks?

We are deprecating Okteto Stacks in favor of Docker Compose syntax. Docker Compose spec is now open source. This decision aims to streamline our code base and provide a more unified experience for our users. With Docker Compose syntax, users can now define the same behavior regardless of whether they’re using Docker Compose or Okteto Stacks.

How to Migrate

Before migrating your Okteto Stack files, make sure you are running Okteto CLI >= 2.27.0 and Okteto Chart >= 1.20.

Once you meet those requirements, here are the steps and samples to migrate from Okteto Stacks to Docker Compose:

  1. Force Docker Compose behavior: Okteto differentiates between Stacks and Docker Compose based on file names for legacy reasons. The file names: docker-compose.yml, okteto-compose.yml and compose.yml are considered Docker Compose files. You can set the environment variable OKTETO_SUPPORT_STACKS_ENABLED to false to force Okteto to consider the Docker Compose syntax for other file names.

  2. Rename the args field into command and the command field into entrypoint:

From

# okteto stack syntax
services:
  web:
    command: python
    args:
      - "app.py"

To

# compose syntax
services:
  web:
    entrypoint: python
    command:
      - "app.py"
  1. Rename annotations into labels and labels into annotations

From

# okteto stack syntax
services:
  web:
    annotations: 
    - "com.example.annotation"
    labels:
    - "com.example.label"

To

# compose syntax
services:
  web:
    labels: 
    - "com.example.annotation"
    annotations:
    - "com.example.label"
  1. Rename camel case fields such as capAdd, capDrop or envFile to cap_add, cap_drop, and env_file respectively:

From

# okteto stack syntax
services:
  web:
    capAdd:
      - "NET_ADMIN"
    capDrop:
      - "ALL"
    envFile:
      - "./env"

To

# compose syntax
services:
  web:
    cap_add:
      - "NET_ADMIN"
    cap_drop:
      - "ALL"
    env_file:
      - "./env"

We recommend migrating to Docker Compose syntax. Okteto Stack syntax will be deprecated in Okteto CLI 3.0. We understand that changes like these may require some adjustments to your workflows, and we’re here to support you every step of the way. If you have any questions or need assistance with transitioning to the new deployment method, please don’t hesitate to reach out to our support team.

Thank you for your understanding and continued support as we strive to enhance the Okteto experience for all users.

Best regards