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, ensure you are running Okteto CLI >= 2.27.0 and Okteto Chart >= 1.20.

Okteto identifies Okteto Stack files by the following filenames: okteto-stack.yml, okteto-stack.yaml, stack.yml or stack.yaml. If your file does not have one of these names, you do not need to make any changes — it is already using the Docker Compose syntax.

If your stack file uses one of these names, follow the steps below to migrate from Okteto Stacks to Docker Compose syntax:

  1. Create an Okteto Admin Variable OKTETO_SUPPORT_STACKS_ENABLED and set it to true. This ensures your Okteto Stack syntax continues to work, which is particularly important if you are upgrading to Okteto CLI version 3.0. By default, Okteto CLI 3.0 treats OKTETO_SUPPORT_STACKS_ENABLED as false.

  2. Rename your Okteto Stack file: To force Okteto to use the Docker Compose syntax, rename your Okteto Stack file. For example, change it to okteto-compose.yaml. By renaming the file to something other than the default stack filenames, Okteto will interpret it using the Docker Compose syntax.

  3. In your stack file, rename the args field to command and the command field to entrypoint to match Docker Compose syntax.:

From

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

To

# compose syntax
services:
  web:
    entrypoint: python
    command:
      - "app.py"
  1. In your stack file, rename the annotations field to labels and the labels field to annotations to match Docker Compose syntax:

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"
  1. Run okteto deploy to deploy your application and ensure that it works correctly with the updated Docker Compose syntax.

After you have successfully migrated all your Okteto Stack files to Docker Compose syntax, you can remove the OKTETO_SUPPORT_STACKS_ENABLED Okteto Admin Variables. This is because your files no longer rely on the Okteto Stack syntax.

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