Octopus Deploy Documentation

Execution containers for workers

Last updated

For a step running on a worker or on the Octopus Server, you can select a Docker image to execute the step inside of.

When an execution container is configured for a step, Octopus will still connect to the worker machine via a Tentacle or SSH. The difference is that the specified image will be run as a container and the step will be executed inside the container.

See the blog post announcing this feature for some added context.


You need Docker installed and running on the worker/Octopus Server (built-in worker), in order to use execution containers for workers

Octopus cloud dynamic worker pools

Octopus Cloud dynamic workers have Docker pre-installed and support execution containers, with the exception of Windows 2016 pools. Dynamic worker pools with a VM type of Windows Server Core 2016 do not have Docker installed, and they cannot be used to run execution containers.

How to use execution containers for workers

  • Configure a feed in Octopus Deploy for a Docker registry.
  • Add a project and define a deployment process (or add a runbook).
  • Set the Execution Location for your step to Run on a worker.
  • In Container Image select Runs on a worker inside a container.
  • Choose the previously added container registry.
  • Enter the name of the image (aka execution container) you want your step to run in. (e.g. octopusdeploy/worker-tools:2.0.1-windows.ltsc2019).
  • Click Save.
  • Click Create release & deploy.

First deployment on a docker container

Pre-pulling your chosen image will save you time during deployments.

When you choose to run one or more of your deployment steps in a container, your deployment process will docker pull the image you provide at the start of each deployment during package acquisition.

For your first deployment this may take a while since your docker image won't be cached. You can pre-pull the desired docker image on your worker before your first deployment to avoid any delays.

Which Docker images can I use?

The easiest way to get started is to use the worker-tools images built by Octopus Deploy.

When a step is configured to use an execution container, Calamari (the Octopus deployment utility) is executed inside the specified container. Calamari is a .NET Core self-contained executable, and the Docker image will need to include the dependencies required to execute a .NET self-contained executable. These dependencies can be found in the .NET docs. Microsoft provides base images which include these dependencies.

Images based on Alpine Linux (or any distro using musl instead of glibc) can not currently be used as execution containers.

The octopusdeploy/worker-tools Docker images

For convenience, we provide some images on Docker Hub octopusdeploy/worker-tools which include common tools used in deployments.

We recommend using our worker-tools image as a starting point for your own custom image to run on a worker

The canonical source for what is contained in the octopusdeploy/worker-tools images is the Dockerfile's in the GitHub repo. For example:

Some of the tools included are:

  • Octopus Deploy CLI and .NET client library
  • .NET Core
  • Java (JDK)
  • NodeJS
  • Azure CLI
  • Google Cloud CLI
  • kubectl
  • Helm
  • Terraform
  • Python

Need support? We're here to help.