Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
55 changes: 5 additions & 50 deletions src/pages/docs/infrastructure/workers/dynamic-worker-pools.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
layout: src/layouts/Default.astro
pubDate: 2023-01-01
modDate: 2026-07-02
modDate: 2026-10-21
title: Dynamic Worker pools
description: Dynamic Worker pools are used in our cloud product to dynamically create and assign workers to running tasks. This page describes how dynamic worker pools work.
navOrder: 50
Expand Down Expand Up @@ -36,12 +36,12 @@ Each dynamic worker pool uses a specific worker image. This is a VM image which

When you sign up to [Octopus Cloud](/docs/octopus-cloud) (or create a new [space](/docs/administration/spaces)), you automatically receive a worker pool for the `Ubuntu (default)` image, and a worker pool for the `Windows (default)` image.

The full list of available worker images includes both specific operating system versions (e.g., `Ubuntu Linux 22.04`), and also generic "default" options such as `Ubuntu (default)`. Choosing the default option means that your worker will use the latest stable worker image when it is released.
The full list of available worker images includes both specific operating system versions (e.g., `Ubuntu Linux 24.04`), and also generic "default" options such as `Ubuntu (default)`. Choosing the default option means that your worker will use the latest stable worker image when it is released.

The current default images are:

- `Ubuntu (default)` ➜ `Ubuntu Linux 22.04`
- `Windows (default)` ➜ `Windows Server Core 2022`
- `Ubuntu (default)` ➜ `Ubuntu Linux 24.04`
- `Windows (default)` ➜ `Windows Server Core 2025`

### Choosing an Image

Expand All @@ -57,7 +57,7 @@ Alternatively, you can choose a specific worker image, instead of the "default"
| Type | Pros | Cons |
|--------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Default (eg `Ubuntu (default)`) | Automatically uses the latest image. Deployments will continue to work even when a worker image is marked as deprecated or decommissioned. | The versions of dependencies (e.g. Helm) are not fixed; deployments that rely on specific versions of dependencies or operating system‑specific features may break during upgrades. |
| Specific (e.g., `Ubuntu Linux 22.04`)| The version of the operating system and dependencies are fixed and can be relied upon. | When a worker image is marked as deprecated, warnings will start to appear in your deployment logs; when it is decommissioned, you will need to update your worker pool or deployments will fail. |
| Specific (e.g., `Ubuntu Linux 24.04`)| The version of the operating system and dependencies are fixed and can be relied upon. | When a worker image is marked as deprecated, warnings will start to appear in your deployment logs; when it is decommissioned, you will need to update your worker pool or deployments will fail. |

### Deprecation

Expand All @@ -81,22 +81,6 @@ Click the overflow menu (`...`) and click **Edit**. You can then select a new wo

Worker images are rebuilt on a regular basis, so that the operating system is up to date with the latest security patches.

### Ubuntu 22.04

This is the default for the Ubuntu operating system, referenced as `Ubuntu (default)`.

Each `Ubuntu Server 22.04` worker is provisioned with a baseline of tools including (but not limited to):

- .NET (8.0, 6.0)
- Docker (latest)
- PowerShell Core (latest)
- Python 3 (latest)
- GCloud CLI (550.0.0)

:::div{.hint}
Ubuntu workers are designed to use [execution worker containers](https://octopus.com/blog/execution-containers) for tooling like `kubectl` and `helm`. This makes it much easier to choose the appropriate runtime environment with the tools you need for your use case.
:::

### Ubuntu 24.04

Each `Ubuntu Server 24.04` worker is provisioned with a baseline of tools including (but not limited to):
Expand All @@ -111,35 +95,6 @@ Each `Ubuntu Server 24.04` worker is provisioned with a baseline of tools includ
Ubuntu workers are designed to use [execution worker containers](https://octopus.com/blog/execution-containers) for tooling like `kubectl` and `helm`. This makes it much easier to choose the appropriate runtime environment with the tools you need for your use case.
:::

### Windows Server Core 2022

This is the default for the Windows operating system, referenced as `Windows (default)`.

Each `Windows Server Core 2022` worker is provisioned with a baseline of tools including (but not limited to):

- .NET (8.0, 6.0)
- .NET Framework 3.5
- .NET Framework 4.8
- AWS IAM Authenticator (0.7.10)
- Chocolatey (latest)
- Docker (latest)
- Helm (3.19.4)
- Kubectl (1.35.1, 1.34.4, 1.33.8, 1.32.12)
- Microsoft Service Fabric (10.1.2338.9590)
- Microsoft Service Fabric SDK (7.1.2338)
- Nuget CLI (latest)
- Octopus Client (latest)
- Pip (latest)
- PowerShell Core (latest)
- Python (3.14)
- GCloud CLI (550.0.0)

Windows 2022 workers are capable of running [execution worker containers](/docs/projects/steps/execution-containers-for-workers).

:::div{.hint}
We recommend execution containers as the preferred option for steps requiring external tools. This allows you to control which version of the tools will be used as your scripts will rely on a specific version that they are compatible with to function correctly.
:::

### Windows Server Core 2025

Each `Windows Server Core 2025` worker is provisioned with a baseline of tools including (but not limited to):
Expand Down
Original file line number Diff line number Diff line change
@@ -1,14 +1,18 @@
---
layout: src/layouts/Default.astro
pubDate: 2026-06-18
modDate: 2026-06-18
modDate: 2026-10-21
title: Ubuntu 22.04 End-of-life
description: Describing the deprecation process of Ubuntu 22.04 Dynamic Workers.
navOrder: 50
hideInThisSection: true
hideInThisSectionHeader: true
---

:::div{.warning}
Ubuntu 22.04 images are no longer available as of 13 October 2026. The details below are provided for historical reference.
:::

Our Ubuntu Dynamic Workers are being upgraded to use Ubuntu 24.04. This may result in breaking changes for users of community steps or custom scripts.

## What is changing?
Expand Down
Original file line number Diff line number Diff line change
@@ -1,13 +1,16 @@
---
layout: src/layouts/Default.astro
pubDate: 2026-07-14
modDate: 2026-07-14
modDate: 2026-10-21
title: Windows 2022 End-of-life
description: Describing the deprecation process of Windows 2022 Dynamic Workers.
navOrder: 50
hideInThisSection: true
hideInThisSectionHeader: true
---
:::div{.warning}
Windows Server 2022 images are no longer available as of 13 October 2026. The details below are provided for historical reference.
:::

Our Windows Server 2022 Dynamic Workers are being upgraded to use Windows Server 2025, this may result in breaking changes for users of community steps or custom scripts.

Expand Down

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I wasn't sure if we need to change the worker tools to remove the old images as well (didn't appear in the reference PR)

Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
layout: src/layouts/Default.astro
pubDate: 2023-01-01
modDate: 2026-10-16
modDate: 2026-10-23
title: Worker Tools, Versioning and Caching
description: How Octopus creates, versions, caches, and releases the worker-tools Docker images for use with the execution containers for workers feature.
navOrder: 50
Expand All @@ -11,13 +11,11 @@ Worker Tools are a set of Docker images used as [execution containers for worker

## Versioning Worker Tools

Worker Tool images follow a semantic versioning (SemVer) approach of `Major.Minor.Patch-Distro` for their tag format. When we release a new version of Worker Tools to the [Worker Tools Docker Hub repository](https://hub.docker.com/r/octopusdeploy/worker-tools/tags), we also add the following image tags, distribution (`ubuntu.22.04` or `windows.ltsc2022`), `Major-Distro` (e.g. `3-Distro`) and `Major.Minor-Distro` (`3.3-Distro`). We also publish multi-platform tags without a distribution, `Major.Minor.Patch`, `Major.Minor`, `Major` and `latest`, which contain the images for every distribution. We recommend using the fully qualified SemVer as patch updates of Worker Tools could result in an updated tool dependency introducing a breaking change.
Worker Tool images follow a semantic versioning (SemVer) approach of `Major.Minor.Patch-Distro` for their tag format. When we release a new version of Worker Tools to the [Worker Tools Docker Hub repository](https://hub.docker.com/r/octopusdeploy/worker-tools/tags), we also add the following image tags, distribution (`ubuntu.24.04` or `windows.ltsc2025`), `Major-Distro` (e.g. `3-Distro`) and `Major.Minor-Distro` (`3.3-Distro`). We also publish multi-platform tags without a distribution, `Major.Minor.Patch`, `Major.Minor`, `Major` and `latest`, which contain the images for every distribution. We recommend using the fully qualified SemVer as patch updates of Worker Tools could result in an updated tool dependency introducing a breaking change.

The Worker Tools Dockerfiles use a combination of tools pinned to specific versions, such as CLI tools and Frameworks, while other tools pull their latest available release. For Ubuntu, these are pulled with apt-get, and for Windows, chocolatey. You can find the full details of these tools in the Docker files for

- [Windows 2022](https://github.com/OctopusDeploy/WorkerTools/blob/main/windows.ltsc2022/Dockerfile)
- [Windows 2025](https://github.com/OctopusDeploy/WorkerTools/blob/main/windows.ltsc2025/Dockerfile)
- [Ubuntu 22.04](https://github.com/OctopusDeploy/WorkerTools/blob/main/ubuntu.22.04/Dockerfile)
- [Ubuntu 24.04](https://github.com/OctopusDeploy/WorkerTools/blob/main/ubuntu.24.04/Dockerfile)

The tools pulling their latest releases for Ubuntu include `wget`, `python3-pip`, `groff`, `unzip`, `apt-utils`, `curl`, `software-properties-common`, `jq`, `yq`, `openssh-client`, `rsync`, `git`, `augeas-tools`, `maven`, `gradle`, `Node 14`, `istioctl`, `linkerd`, `umoci`.
Expand Down Expand Up @@ -46,7 +44,7 @@ In short, we recommend the following. On Ubuntu, use the `octopusdeploy/worker-t

## Caching Worker Tools

Worker Tools are cached on dynamic workers to help improve the performance of deployments. Windows workers cache the latest two sets of Worker Tools while Ubuntu workers cache the latest three. Each worker only caches the images for its own operating system, so a `windows.ltsc2022` image on a Windows 2025 worker is always downloaded in full.
Worker Tools are cached on dynamic workers to help improve the performance of deployments. Windows workers cache the latest two sets of Worker Tools while Ubuntu workers cache the latest three. Each worker only caches the images for its own operating system version. For example, a `windows.ltsc2022` image on a Windows 2025 worker is always downloaded in full.

To understand this cache, it's important to understand a worker's life cycle. Workers are acquired from a dynamic worker pool and leased to a single cloud instance. They are allocated in a round robin fashion to individual deployment steps, storing packages, Docker images, and other data on disk. Workers are destroyed after either the worker has been idle for 60 minutes or has existed for 72 hours (3 days).

Expand Down

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I wasn't sure if we need to change the execution containers as well (didn't appear in the reference PR)

Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
layout: src/layouts/Default.astro
pubDate: 2023-01-01
modDate: 2023-01-01
modDate: 2026-10-21
title: Execution containers for workers
description: How to set a step in your deployment/runbook process to run inside a container.
navOrder: 30
Expand Down Expand Up @@ -34,7 +34,7 @@ You need Docker installed and running on the [worker](/docs/infrastructure/worke
- Set the **Execution Location** for your step to **Run on a worker**.
- In **Container Image** select **Run inside a container on a worker** and then **Pull container from a registry**.
- Choose the previously added container registry.
- Enter the name of the image (execution container) you want your step to run in. (e.g. `octopusdeploy/worker-tools:ubuntu.22.04`).
- Enter the name of the image (execution container) you want your step to run in. (e.g. `octopusdeploy/worker-tools:ubuntu.24.04`).
- Click **Save**.
- Click **Create release & deploy**.

Expand Down Expand Up @@ -75,8 +75,8 @@ We recommend using our `worker-tools` image as a starting point for your own cus

The canonical source for what is contained in the `octopusdeploy/worker-tools` images is the `Dockerfile`'s in the [GitHub repo](https://github.com/OctopusDeploy/WorkerTools). For example:

- The [Ubuntu 22.04 Dockerfile](https://github.com/OctopusDeploy/WorkerTools/blob/master/ubuntu.22.04/Dockerfile)
- The [Windows 2022 Dockerfile](https://github.com/OctopusDeploy/WorkerTools/blob/master/windows.ltsc2022/Dockerfile)
- The [Ubuntu 24.04 Dockerfile](https://github.com/OctopusDeploy/WorkerTools/blob/main/ubuntu.24.04/Dockerfile)
- The [Windows 2025 Dockerfile](https://github.com/OctopusDeploy/WorkerTools/blob/main/windows.ltsc2025/Dockerfile)

Some of the tools included are:

Expand All @@ -98,10 +98,10 @@ It can be beneficial to build your own custom Docker image when using execution

#### Supported Windows base images

For Windows images, we recommend using a base image no older than the `ltsc2022` image. Octopus does not support images that are older than `ltsc2022`, and while containers based on these images can still run steps, you may run into unexpected issues.
For Windows images, we recommend using a base image no older than the `ltsc2025` image. Octopus does not support images that are older than `ltsc2025`, and while containers based on these images can still run steps, you may run into unexpected issues.

:::div{.hint}
If your containers are based on an earlier image of Windows, we strongly recommend upgrading your workers to Windows 2022 and rebasing your Docker containers to use a 2022 base image.
If your containers are based on an earlier image of Windows, we strongly recommend upgrading your workers to Windows 2025 and rebasing your Docker containers to use a 2025 base image.
:::

#### Supported Linux distributions
Expand All @@ -118,10 +118,10 @@ You can usually find the base operating system of a Linux Docker image by runnin
docker run --entrypoint='' [image name] /bin/cat /etc/os-release.
```

For example for the `octopusdeploy/worker-tools:5.0.0-ubuntu.22.04` image, you'd run:
For example for the `octopusdeploy/worker-tools:6.6.5-ubuntu.24.04` image, you'd run:

```bash
docker run --entrypoint='' octopusdeploy/worker-tools:5.0.0-ubuntu.22.04 /bin/cat /etc/os-release.
docker run --entrypoint='' octopusdeploy/worker-tools:6.6.5-ubuntu.24.04 /bin/cat /etc/os-release.
```

#### Required OS dependencies
Expand Down
Loading