Docs for multi-node support for polling tentacles

dictionary-octopus.txt

@@ -345,6 +345,7 @@ nlog
 nmap
 noconsolelogging
 nodir
+noeviction
 nologo
 nologs
 noninteractive

src/pages/docs/administration/high-availability/polling-tentacles-with-ha/index.mdx

@@ -0,0 +1,21 @@
+---
+layout: src/layouts/Default.astro
+pubDate: 2023-01-01
+modDate: 2026-10-06
+title: Polling Tentacles with HA
+navTitle: Overview
+navSection: Polling Tentacles with HA
+description: How to connect Polling Tentacles to an Octopus High Availability cluster, using multi-node support with Redis or by polling every node.
+navOrder: 50
+---
+
+Listening Tentacles require no special configuration for Octopus High Availability. Polling Tentacles and Kubernetes agents, however, poll a server at regular intervals to check if there are any tasks waiting for the Tentacle to perform. In a High Availability scenario, a Polling Tentacle needs to be able to collect work queued by any Octopus Server node in your configuration. To configure the Kubernetes agent with Octopus High Availability, see [Kubernetes agent HA Cluster Support](/docs/infrastructure/deployment-targets/kubernetes/kubernetes-agent/ha-cluster-support).
+
+## Connecting Polling Tentacles
+
+There are two ways to connect Polling Tentacles to an HA cluster:
+
+- **[Multi-node support for Polling Tentacles](/docs/administration/high-availability/polling-tentacles-with-ha/multi-node-polling-tentacles)** (recommended). The nodes share a queue of pending requests in Redis, so any node can hand work to any Tentacle. Each Polling Tentacle only needs to poll a single load-balanced address, and you do not need to update your Tentacles when you add or remove a node.
+- **[Polling every node](/docs/administration/high-availability/polling-tentacles-with-ha/poll-every-node)**. Each Polling Tentacle polls every node in your cluster, using a unique address or a unique port for each node. This does not need Redis, but you need to register every node with every Polling Tentacle, and update your Tentacles whenever you add or remove a node.
+
+We recommend multi-node support for Polling Tentacles. Poll every node only if you cannot run Redis, or your Octopus Server version does not support multi-node support for Polling Tentacles.

src/pages/docs/administration/high-availability/polling-tentacles-with-ha.mdx → src/pages/docs/administration/high-availability/polling-tentacles-with-ha/poll-every-node.md

@@ -1,26 +1,22 @@
 ---
 layout: src/layouts/Default.astro
 pubDate: 2023-01-01
-modDate: 2026-08-20
-title: Polling Tentacles with HA
-description: With Octopus High Availability, Polling Tentacles must poll all Octopus Server nodes in your configuration.
-navOrder: 50
+modDate: 2026-10-06
+title: Polling every node
+description: Connect Polling Tentacles to an Octopus High Availability cluster without Redis, by registering every node with every Polling Tentacle.
+navOrder: 20
 ---
 
-Listening Tentacles require no special configuration for Octopus High Availability. Polling Tentacles and Kubernetes agents, however, poll a server at regular intervals to check if there are any tasks waiting for the Tentacle to perform. In a High Availability scenario Polling Tentacles must poll all Octopus Server nodes in your configuration. To configure the Kubernetes agent with Octopus High Availability, see [Kubernetes agent HA Cluster Support](/docs/infrastructure/deployment-targets/kubernetes/kubernetes-agent/ha-cluster-support).
+If you cannot use [multi-node support for Polling Tentacles](/docs/administration/high-availability/polling-tentacles-with-ha/multi-node-polling-tentacles), configure each Polling Tentacle to poll every node in your Octopus High Availability (HA) cluster. Work for a Tentacle is queued in memory on the node that runs the task, and only that node can hand it to the Tentacle, so the Tentacle must be able to reach each node individually.
 
-## Connecting Polling Tentacles
-
-While a Tentacle could poll a load balancer in an Octopus High Availability cluster, there is a risk, depending on your load balancer configuration, that the Tentacle will not poll all servers in a timely manner.
-
-We recommend two options when configuring Polling Tentacles to connect to your Octopus High Availability cluster:
+There are two ways to do this:
 
 - Using a **unique address**, and the same listening port (`10943` by default) for each node.
 - Using the same address and a **unique port** for each node.
 
-These are discussed further in the next sections.
+With either option, you need to register every node with every Polling Tentacle, and update your Tentacles whenever you add or remove a node.
 
-### Using a unique address
+## Using a unique address
 
 In this scenario, no load balancer is required. Instead, each Octopus node would be configured to listen on the same port (`10943` by default) for inbound traffic. In addition, each node would be able to be reached directly by your Polling Tentacle on a unique address for the node.
 
@@ -41,7 +37,7 @@ A Polling Tentacle will connect to the Octopus Rest API over ports 80 or 443 whe
 It's important to ensure that any firewalls also allow port 80 or 443 for the initial Tentacle registration.
 :::
 
-### Using a unique port
+## Using a unique port
 
 In this scenario, a type of [Network Address Translation (NAT)](https://en.wikipedia.org/wiki/Network_address_translation) is leveraged by using the same address and **unique ports**, usually routed through a load balancer or other network device. Each Octopus node would be configured to listen on a different port (starting at `10943` by default) for inbound traffic.
 

src/pages/docs/administration/octopus.server.exe-command-line/configure.md

@@ -1,7 +1,7 @@
 ---
 layout: src/layouts/Default.astro
 pubDate: 2023-01-01
-modDate: 2023-01-01
+modDate: 2026-09-29
 title: Configure
 description: Configure this Octopus instance
 navOrder: 31
@@ -56,6 +56,15 @@ Where [<options>] is any of:
                                'https://+:443/OctopusComms'); set to blank to
                                disable websockets. Refer to https://o-
                                c.to/WebSocketComms.
+      --multiNodePollingTentaclesRedisConnectionString=VALUE
+                             Sets the Redis connection string used by
+                               multi-node support for polling tentacles,
+                               which allows polling tentacles to connect to
+                               any node in cluster (e.g. via a load
+                               balancer). Setting a value enables the
+                               feature; set to blank to disable it. Every
+                               node in the cluster must be configured with
+                               the same value.
       --webListenPrefixes=VALUE
                              Comma-separated list of HTTP.sys listen prefixes
                                (e.g., 'http://localhost/octopus')

src/pages/docs/administration/octopus.server.exe-command-line/path.md

@@ -1,7 +1,7 @@
 ---
 layout: src/layouts/Default.astro
 pubDate: 2023-01-01
-modDate: 2023-01-01
+modDate: 2026-09-29
 title: Path
 description: Set the file paths that Octopus will use for storage
 navOrder: 160
@@ -29,7 +29,39 @@ Where [<options>] is any of:
                                is not running. This directory should not be
                                shared between nodes.
       --clusterShared=VALUE  Set the root path where shared files will be
-                               stored for Octopus clusters
+                               stored for Octopus clusters. Set to blank to
+                               clear it, so that relative paths resolve under
+                               the Home directory again.
+      --executionsClusterShared=VALUE
+                             Set the root path where transient execution
+                               files will be stored for Octopus clusters.
+
+                               When configured, Octopus stores transient
+                               execution data (DataStreams, PackageCache, and
+                               DataBus) here instead of in the Cluster Shared
+                               directory. This data is generated during tasks
+                               like deployments and runbooks and is not long-
+                               lived. As with Cluster Shared, this path must
+                               be on a shared volume accessible to all nodes
+                               in the cluster.
+
+                               Configuration is typically not required, as
+                               Octopus automatically falls back to the
+                               Cluster Shared directory or the Home directory
+                               if no path is specified.
+
+                               Note: Before changing this setting, ensure
+                               that no tasks are running on the Octopus
+                               Servers. Additionally, the previously used
+                               directories (DataBus, DataStreams,
+                               PackageCache) in the ClusterShared directory or
+                               the Home directory will no longer be used and
+                               can be manually deleted since they will not be
+                               cleaned up automatically.
+
+                               Set to blank to clear it, so that transient
+                               execution data falls back to the Cluster
+                               Shared or Home directory.
       --nugetRepository=VALUE
                              Set the package path for the built-in package
                                repository
@@ -69,3 +101,15 @@ octopus.server path --imports \\Octoshared\OctopusData\Imports
 octopus.server path --eventExports \\Octoshared\OctopusData\EventExports
 octopus.server path --telemetry \\Octoshared\OctopusData\Telemetry
 ```
+
+This example stores transient execution data, such as data streams for [multi-node support for Polling Tentacles](/docs/administration/high-availability/polling-tentacles-with-ha/multi-node-polling-tentacles), on separate shared storage:
+
+```text
+octopus.server path --executionsClusterShared \\OctoFastShared\OctopusExecutions
+```
+
+This example clears the executions cluster shared directory, so transient execution data is stored in the cluster shared directory again:
+
+```text
+octopus.server path --executionsClusterShared=
+```

src/pages/docs/installation/octopus-server-linux-container/index.mdx

@@ -1,7 +1,7 @@
 ---
 layout: src/layouts/Default.astro
 pubDate: 2023-01-01
-modDate: 2024-07-15
+modDate: 2026-09-29
 title: Octopus Server Linux Container
 description: Run Octopus Deploy in the official Docker Linux container. Pull the image, configure environment variables, connect a SQL Server database, and get started.
 navOrder: 8
@@ -82,6 +82,9 @@ Read the Docker [docs](https://docs.docker.com/engine/reference/commandline/run/
 |**ADMIN_EMAIL**|The email associated with the admin user account|
 |**TASK_CAP**|Sets the task cap for this node. If not specified, the default is 5.|
 |**DISABLE_DIND**|The Linux image will by default attempt to run Docker-in-Docker to support [execution containers for workers](/docs/projects/steps/execution-containers-for-workers). This requires the image to be launched with [privileged permissions](https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities). Setting `DISABLE_DIND` to `Y` prevents Docker-in-Docker from being run when the container is booted.|
+|**CLUSTER_SHARED_CONFIG**|Sets how Octopus stores the files that every node in a cluster needs to share. Valid values are `CLUSTER_SHARED`, `SEPARATE_VOLUMES_WITH_CLUSTER_SHARED`, and `SEPARATE_VOLUMES`, and they are not case-sensitive. Any other value stops the container with an error. If not set, a new installation uses the `/repository`, `/artifacts`, `/taskLogs`, and `/eventExports` volumes, and an existing installation keeps its current paths. See [cluster shared configuration](#cluster-shared-configuration).|
+|**USE_EXECUTIONS_CLUSTER_SHARED**|Set to `True` to store transient execution data (the `SharedPackageCache`, `DataBus`, and `DataStreams` folders) in the `/executionsClusterShared` volume instead of in `/clusterShared`. The value is not case-sensitive. Only valid when `CLUSTER_SHARED_CONFIG` is `SEPARATE_VOLUMES_WITH_CLUSTER_SHARED` or `CLUSTER_SHARED`. With any other `CLUSTER_SHARED_CONFIG` value, including not set, the container stops with an error. See [cluster shared configuration](#cluster-shared-configuration) for why you might use this.|
+|**OCTOPUS_MULTI_NODE_POLLING_TENTACLES_REDIS_CONNECTION_STRING**|The Redis connection string that turns on [multi-node support for Polling Tentacles](/docs/administration/high-availability/polling-tentacles-with-ha/multi-node-polling-tentacles). Requires `CLUSTER_SHARED_CONFIG` to be `SEPARATE_VOLUMES_WITH_CLUSTER_SHARED` or `CLUSTER_SHARED`.|
 
 ### Exposed container ports
 
@@ -106,11 +109,34 @@ Read the Docker [docs](https://docs.docker.com/engine/reference/commandline/run/
 | **/taskLogs** | Path where task logs are stored | Shared storage |
 | **/eventExports** | Path where event audit logs are exported | Shared storage |
 | **/cache** | Path where cached files e.g., signature and delta files (used for package acquisition), are stored | Host filesystem or container |
+| **/clusterShared** | Cluster shared directory. Used when `CLUSTER_SHARED_CONFIG` is `SEPARATE_VOLUMES_WITH_CLUSTER_SHARED` or `CLUSTER_SHARED` | Shared storage |
+| **/executionsClusterShared** | Transient execution data, in the `SharedPackageCache`, `DataBus`, and `DataStreams` folders. Used when `USE_EXECUTIONS_CLUSTER_SHARED` is `True` | Shared storage |
 
 :::div{.hint}
 **Note:** We recommend using shared storage when mounting the volumes for files that must be shared between multiple octopus container nodes, e.g., artifacts, packages, task logs, and event exports.
 :::
 
+### Cluster shared configuration \{#cluster-shared-configuration}
+
+The `CLUSTER_SHARED_CONFIG` environment variable sets which volumes Octopus uses for the files that every node needs to share. When it is set, the container applies it each time it starts, not only on first start, so you can change it on an existing installation.
+
+The values are not case-sensitive.
+
+| Value | When to use it | Volumes used |
+| --- | --- | --- |
+| `CLUSTER_SHARED` | Recommended for new installations. | A single `/clusterShared` volume: packages in `/clusterShared/Packages`, artifacts in `/clusterShared/Artifacts`, task logs in `/clusterShared/TaskLogs`, event exports in `/clusterShared/EventExports`, imports in `/clusterShared/Imports`, telemetry in `/clusterShared/Telemetry`, and transient execution data in `/clusterShared/SharedPackageCache`, `/clusterShared/DataBus`, and `/clusterShared/DataStreams`. The `/repository`, `/artifacts`, `/taskLogs`, and `/eventExports` volumes are not used. |
+| `SEPARATE_VOLUMES_WITH_CLUSTER_SHARED` | Recommended if you are moving an existing installation to multiple nodes and want to keep your existing volumes, rather than moving their contents into a single volume. | `/repository`, `/artifacts`, `/taskLogs`, and `/eventExports`, plus `/clusterShared`. Octopus stores transient execution data in `/clusterShared` instead of in `/cache` and the Octopus home directory: the package cache in `/clusterShared/SharedPackageCache`, DataBus in `/clusterShared/DataBus`, and DataStreams in `/clusterShared/DataStreams`. Imports and telemetry are also stored in `/clusterShared/Imports` and `/clusterShared/Telemetry`. |
+| `SEPARATE_VOLUMES` | To go back to the layout without a cluster shared directory, for example if you tried one of the other values and want to undo it. | `/repository`, `/artifacts`, `/taskLogs`, and `/eventExports`, with no cluster shared directory. Any cluster shared or executions cluster shared directory configured previously is removed. Multi-node support for Polling Tentacles cannot be used with this value. |
+| Not set | To keep the current configuration. | On a new installation, `/repository`, `/artifacts`, `/taskLogs`, and `/eventExports`. On an existing installation, the container does not change any paths, so whatever was configured previously, including any cluster shared directory, is kept. For example, if you used `CLUSTER_SHARED` and then remove the variable, Octopus keeps using `/clusterShared`. |
+
+In every mode, `/cache` is still used as the node's own cache directory.
+
+Switching an existing installation to `CLUSTER_SHARED` does not move existing packages, artifacts, or logs into `/clusterShared`, so Octopus stops finding them unless you move them yourself. To add a cluster shared directory to an existing installation, use `SEPARATE_VOLUMES_WITH_CLUSTER_SHARED`.
+
+To keep transient execution data on different storage, such as faster storage that does not need to be backed up, set `USE_EXECUTIONS_CLUSTER_SHARED` to `True` and mount `/executionsClusterShared` on storage every node can read and write. Octopus then uses the same `SharedPackageCache`, `DataBus`, and `DataStreams` folders in `/executionsClusterShared`.
+
+[Multi-node support for Polling Tentacles](/docs/administration/high-availability/polling-tentacles-with-ha/multi-node-polling-tentacles) needs a cluster shared directory. If `OCTOPUS_MULTI_NODE_POLLING_TENTACLES_REDIS_CONNECTION_STRING` is set and `CLUSTER_SHARED_CONFIG` is `SEPARATE_VOLUMES`, the container stops with an error. The container only checks the environment variable, not a connection string set with the `configure` command.
+
 ## Upgrading
 
 When the volumes are externally mounted to the host filesystem, upgrades between Octopus versions are much easier. We can picture the upgrade process with a container as being similar to [moving a standard Octopus Server](/docs/administration/managing-infrastructure/moving-your-octopus/move-the-database-and-server) since containers, being immutable, don't themselves get updated.

src/pages/docs/installation/octopus-server-linux-container/octopus-in-kubernetes.mdx

@@ -1,7 +1,7 @@
 ---
 layout: src/layouts/Default.astro
 pubDate: 2023-01-01
-modDate: 2024-04-23
+modDate: 2026-09-29
 title: Run Octopus Server in Kubernetes
 description: Install Octopus Server into a Kubernetes cluster using the official Linux container. Choose a single-node setup or High Availability across multiple pods.
 navOrder: 40
@@ -150,6 +150,10 @@ spec:
 
 Unlike the Octopus Web Portal, Polling Tentacles must be able to connect to each Octopus node individually to pick up new tasks. Our Octopus HA cluster assumes two nodes, therefore a load balancer is required for each node to allow direct access.
 
+:::div{.hint}
+If you turn on [multi-node support for Polling Tentacles](/docs/administration/high-availability/polling-tentacles-with-ha/multi-node-polling-tentacles), Polling Tentacles can connect to any node through a single TCP load balancer instead, so you do not need to add each node to each Polling Tentacle. The [Helm chart](#helm-chart) can create this load balancer for you.
+:::
+
 The following YAML creates load balancers with separate public IPs for each node. They direct web traffic to each node on port `80`, Polling Tentacle traffic on port `10943`, and gRPC traffic on port `8443`.
 
 The `octopus-0` load balancer: