From 1e98872cf59ae3fa0eba8b726d014feb9230e911 Mon Sep 17 00:00:00 2001 From: Andy Yu Date: Fri, 9 Oct 2026 12:08:47 +1300 Subject: [PATCH 1/3] Recommend the multi-platform worker-tools tag for Windows --- .../workers/worker-tools-versioning-and-caching.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/pages/docs/infrastructure/workers/worker-tools-versioning-and-caching.md b/src/pages/docs/infrastructure/workers/worker-tools-versioning-and-caching.md index fcab57bb66..5305287d76 100644 --- a/src/pages/docs/infrastructure/workers/worker-tools-versioning-and-caching.md +++ b/src/pages/docs/infrastructure/workers/worker-tools-versioning-and-caching.md @@ -1,7 +1,7 @@ --- layout: src/layouts/Default.astro pubDate: 2023-01-01 -modDate: 2026-06-04 +modDate: 2026-10-09 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 @@ -11,7 +11,7 @@ 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 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.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. 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 @@ -42,11 +42,11 @@ Patch update - Update of a pinned tools Patch version - Any new release, the latest tools will be updated automatically -In short, we recommend using the full `octopusdeploy/worker-tools:Major.Minor.Patch-Distro` tag format. Depending on your use case, the latest releases, `octopusdeploy/worker-tools:ubuntu.24.04` and `octopusdeploy/worker-tools:windows.ltsc2025` respectively or `octopusdeploy/worker-tools:Major-distro`, `octopusdeploy/worker-tools:Major.Minor-Distro` may be suitable for you. +In short, we recommend using the full version. On Ubuntu, use the `octopusdeploy/worker-tools:Major.Minor.Patch-Distro` tag format (e.g. `octopusdeploy/worker-tools:6.6.5-ubuntu.24.04`). On Windows, use the plain `octopusdeploy/worker-tools:Major.Minor.Patch` tag (e.g. `octopusdeploy/worker-tools:6.6.5`). It contains both the Windows 2022 and Windows 2025 images, and Docker pulls the one that matches the worker's version of Windows. Depending on your use case, the latest releases, `octopusdeploy/worker-tools:ubuntu.24.04` and `octopusdeploy/worker-tools:windows.ltsc2025` respectively or `octopusdeploy/worker-tools:Major-distro`, `octopusdeploy/worker-tools:Major.Minor-Distro` may be suitable for you. ## 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. +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. 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). From 9d4f2c40141a181be34e65a12c6f46f76994a439 Mon Sep 17 00:00:00 2001 From: Andy Yu Date: Fri, 9 Oct 2026 14:16:57 +1300 Subject: [PATCH 2/3] simplify --- .../workers/worker-tools-versioning-and-caching.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pages/docs/infrastructure/workers/worker-tools-versioning-and-caching.md b/src/pages/docs/infrastructure/workers/worker-tools-versioning-and-caching.md index 5305287d76..a7d34bdc0c 100644 --- a/src/pages/docs/infrastructure/workers/worker-tools-versioning-and-caching.md +++ b/src/pages/docs/infrastructure/workers/worker-tools-versioning-and-caching.md @@ -42,7 +42,7 @@ Patch update - Update of a pinned tools Patch version - Any new release, the latest tools will be updated automatically -In short, we recommend using the full version. On Ubuntu, use the `octopusdeploy/worker-tools:Major.Minor.Patch-Distro` tag format (e.g. `octopusdeploy/worker-tools:6.6.5-ubuntu.24.04`). On Windows, use the plain `octopusdeploy/worker-tools:Major.Minor.Patch` tag (e.g. `octopusdeploy/worker-tools:6.6.5`). It contains both the Windows 2022 and Windows 2025 images, and Docker pulls the one that matches the worker's version of Windows. Depending on your use case, the latest releases, `octopusdeploy/worker-tools:ubuntu.24.04` and `octopusdeploy/worker-tools:windows.ltsc2025` respectively or `octopusdeploy/worker-tools:Major-distro`, `octopusdeploy/worker-tools:Major.Minor-Distro` may be suitable for you. +In short, we recommend the following. On Ubuntu, use the `octopusdeploy/worker-tools:Major.Minor.Patch-Distro` tag format. On Windows, use the plain `octopusdeploy/worker-tools:Major.Minor.Patch` tag. It contains both the Windows 2022 and Windows 2025 images, and Docker pulls the one that matches the worker's version of Windows. ## Caching Worker Tools From 9a13bbfd795c1c8ca3d336145c7f33770db08fa7 Mon Sep 17 00:00:00 2001 From: Andy Yu Date: Fri, 9 Oct 2026 14:21:01 +1300 Subject: [PATCH 3/3] lint --- .../workers/worker-tools-versioning-and-caching.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pages/docs/infrastructure/workers/worker-tools-versioning-and-caching.md b/src/pages/docs/infrastructure/workers/worker-tools-versioning-and-caching.md index a7d34bdc0c..ee72b98ec0 100644 --- a/src/pages/docs/infrastructure/workers/worker-tools-versioning-and-caching.md +++ b/src/pages/docs/infrastructure/workers/worker-tools-versioning-and-caching.md @@ -42,7 +42,7 @@ Patch update - Update of a pinned tools Patch version - Any new release, the latest tools will be updated automatically -In short, we recommend the following. On Ubuntu, use the `octopusdeploy/worker-tools:Major.Minor.Patch-Distro` tag format. On Windows, use the plain `octopusdeploy/worker-tools:Major.Minor.Patch` tag. It contains both the Windows 2022 and Windows 2025 images, and Docker pulls the one that matches the worker's version of Windows. +In short, we recommend the following. On Ubuntu, use the `octopusdeploy/worker-tools:Major.Minor.Patch-Distro` tag format. On Windows, use the plain `octopusdeploy/worker-tools:Major.Minor.Patch` tag. It contains both the Windows 2022 and Windows 2025 images, and Docker pulls the one that matches the worker's version of Windows. ## Caching Worker Tools