From ff43746c0e56228bac5eb4d06c041e723acf2ead Mon Sep 17 00:00:00 2001 From: AlexRothwell <7465195+AlexRothwell@users.noreply.github.com> Date: Wed, 14 Jan 2026 11:29:47 +1100 Subject: [PATCH 1/3] Update number of cached worker-tool versions on Ubuntu DWs --- .../workers/worker-tools-versioning-and-caching.md | 4 ++-- 1 file changed, 2 insertions(+), 2 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 6acbc3b406..a50f80dda4 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 @@ -37,7 +37,7 @@ In short, we recommend using the full `octopusdeploy/worker-tools:Major.Minor.Pa ## 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 five. +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. 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). @@ -52,7 +52,7 @@ To update to the latest set of Worker Tools select the "Use latest Distro-based ## Currently Cached Worker Tools **Octopus worker-tools cached on Dynamic Workers** -The `octopusdeploy/worker-tools` images provided for the execution containers feature cache the five latest Ubuntu and two latest Windows images on a Dynamic Worker when it's created. This makes them an excellent choice over installing additional software on a Dynamic Worker. +The `octopusdeploy/worker-tools` images provided for the execution containers feature cache the three latest Ubuntu and two latest Windows images on a Dynamic Worker when it's created. This makes them an excellent choice over installing additional software on a Dynamic Worker. [View the latest versions of worker tools on DockerHub](https://hub.docker.com/r/octopusdeploy/worker-tools). From 27cd6b3ebeb44467ed30654c1487b72d510e9d81 Mon Sep 17 00:00:00 2001 From: AlexRothwell <7465195+AlexRothwell@users.noreply.github.com> Date: Wed, 14 Jan 2026 12:01:43 +1100 Subject: [PATCH 2/3] Fix linting --- .../worker-tools-versioning-and-caching.md | 26 +++++++++++-------- 1 file changed, 15 insertions(+), 11 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 a50f80dda4..8d6b0a31c3 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 @@ -10,28 +10,32 @@ navOrder: 50 Worker Tools are a set of Docker images used as [execution containers for workers](https://octopus.com/docs/projects/steps/execution-containers-for-workers) to run deployment processes. Worker Tools include a wide range of software tools to support most deployment scenarios out of the box. This page focuses on how we create these Worker Tool images, version, cache on workers, and release them. ## 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. 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](https://github.com/OctopusDeploy/WorkerTools/blob/master/windows.ltsc2022/Dockerfile) and [Ubuntu](https://github.com/OctopusDeploy/WorkerTools/blob/master/ubuntu.22.04/Dockerfile) Worker Tools. -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`. +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`. For Windows these include `chocolatey` and `dotnet 6.0.*`. If your steps depend on any of these packages, we recommend you target the fully qualified SemVer of Worker Tools. Otherwise, our additional Worker Tools tags may be suitable for your use case. We version our releases as follows: Major update -* Update of a pinned tools major version -* Any update of a pinned tool with a 0 Major version i.e. `0.*.*` -* Removal of a tool + +- Update of a pinned tools major version +- Any update of a pinned tool with a 0 Major version i.e. `0.*.*` +- Removal of a tool Minor Update -* Update of a pinned tools minor version -* Addition of a new tool + +- Update of a pinned tools minor version +- Addition of a new tool Patch update -* Update of a pinned tools Patch version -* Any new release, the latest tools will be updated automatically + +- 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.22.04` and `octopusdeploy/worker-tools:windows.ltsc2022` respectively or `octopusdeploy/worker-tools:Major-distro`, `octopusdeploy/worker-tools:Major.Minor-Distro` may be suitable for you. @@ -39,14 +43,14 @@ In short, we recommend using the full `octopusdeploy/worker-tools:Major.Minor.Pa 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. -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). +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). When a new worker is acquired, if a new set of Worker Tools has been released, the worker will no longer have the oldest version of Worker Tools, and any other images pulled on the old worker. This is important for the performance of deployments as pull times for uncached Worker Tools are ~1.5 minutes for Ubuntu and ~20 minutes for Windows. We recommend updating to the latest set of Worker Tools available to avoid these pull times. By Caching multiple versions of Worker Tools when using the latest version, any new release of Worker Tools will not result in degraded deployment performance. -To update to the latest set of Worker Tools select the "Use latest Distro-based image" +To update to the latest set of Worker Tools select the "Use latest Distro-based image" :::figure -![](/docs/img/infrastructure/workers/images/container-selector.png) +![The container image settings](/docs/img/infrastructure/workers/images/container-selector.png) ::: ## Currently Cached Worker Tools From 5738b1715f2961eceb86f44b4b0a5066444d83dd Mon Sep 17 00:00:00 2001 From: AlexRothwell <7465195+AlexRothwell@users.noreply.github.com> Date: Wed, 14 Jan 2026 12:07:06 +1100 Subject: [PATCH 3/3] Update modDate --- .../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 8d6b0a31c3..87fcee957c 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: 2023-01-01 +modDate: 2026-01-14 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