Docs for multi-node support for polling tentacles - #3481
sburmanoctopus wants to merge 7 commits into
Conversation
|
Pull request environment is available at https://stoctodocspr3481.z22.web.core.windows.net/. You can view the ephemeral environment status in Octopus Deploy. This environment will be automatically deprovisioned when the pull request is closed, or after 7 days of inactivity. |
| Multi-node support for Polling Tentacles removes that restriction. The nodes share a pending request queue stored in Redis, so a request queued by any node can be collected by whichever node the Tentacle is connected to. Each Tentacle only needs to poll a single address, which a load balancer spreads across all the nodes. | ||
|
|
||
| :::div{.hint} | ||
| Multi-node support for Polling Tentacles is available from Octopus Server [VERIFY: 2026.4 — needs: the first release that ships the `multiNodePollingTentaclesRedisConnectionString` setting]. |
There was a problem hiding this comment.
Fill in when the branch for this merges to main
gb-8
left a comment
gb-8
left a comment
There was a problem hiding this comment.
✅ Pre-approved, with a bunch of minor comments.
Note that I have reviewed for clarity and readability.
I've also made sure that it seemed correct to me, but haven't exhaustively checked for correctness.
| ## 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. | ||
| 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. To poll through a load balancer, turn on [multi-node support for Polling Tentacles](/docs/administration/high-availability/multi-node-polling-tentacles). |
There was a problem hiding this comment.
Probably can remove the first sentence, since just randomly polling a load balancer and hoping is worth mentioning.
We should update this whole section to make it clear that using Redis is the recommended way, and these other ways are fallback options if you can't/won't use Redis.
| |**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 aren't 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 isn't 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.| |
There was a problem hiding this comment.
We document why you would want to do this below, so maybe say "see Cluster shared configuration below"?
Otherwise a reader is left wondering why they'd want to do this.
| Octopus stores transient execution data, which is only needed while tasks run, in these folders in the cluster shared directory: | ||
|
|
||
| - `DataStreams`, for data streams sent to Polling Tentacles | ||
| - `DataBus` |
There was a problem hiding this comment.
DataBus is the only one whose purpose is not explained. It's an internal detail, so we don't have to say much, but should probably say something.
| - `DataBus` | |
| - `DataBus`, used internally by Octopus Server |
| - If the Redis connection string is set and `CLUSTER_SHARED_CONFIG` is `SEPARATE_VOLUMES`, the container stops with an error. | ||
| - If the Redis connection string is set and `CLUSTER_SHARED_CONFIG` isn't set, the container logs a warning. Octopus Server then fails to start unless a cluster shared or executions cluster shared directory was already configured. | ||
|
|
||
| These checks only look at the `OCTOPUS_MULTI_NODE_POLLING_TENTACLES_REDIS_CONNECTION_STRING` environment variable. |
There was a problem hiding this comment.
This line is a bit confusing, since the checks are comparing multiple things, not just checking one thing.
I assume it is calling out that it is not checking if the setting is used directly (rather than env var)?
In which case, it's better to just be explicit about this in the lines above.
E.g.
- If the `OCTOPUS_MULTI_NODE_POLLING_TENTACLES_REDIS_CONNECTION_STRING` is set and `CLUSTER_SHARED_CONFIG` isn't set, the container logs a warning. Octopus Server then fails to start unless a cluster shared or executions cluster shared directory was already configured.
Also, prefer ...is not set... to isn't set.
|
|
||
| ## Turn on multi-node support for Polling Tentacles | ||
|
|
||
| Multi-node support for Polling Tentacles is turned on when a Redis connection string is configured, and turned off when it isn't. Configure **every node** in the cluster with the same connection string. |
There was a problem hiding this comment.
I find the use of isn't here (and elsewhere in the docs) jarring.
I think "is not" is more readable in documentation.
3 participants
We are releasing the multi-node support for polling tentacles feature. To use this feature, you need to configure certain settings and directories.
This PR are all the docs regarding what you need to configure in order to use the multi-node support for polling tentacles feature.
Fixes LEV-1982