Deployment Rings
Deployment rings implement phased rollouts for update policies. Instead of deploying patches to your entire fleet at once, rings let you gradually expand coverage while monitoring for issues at each stage.
Ring concept
A deployment ring is a staged rollout strategy. Instead of deploying patches to every endpoint simultaneously, you define a sequence of rollout phases that gradually expand coverage. Updates flow through each phase in order, and if problems surface at any stage, you can halt the rollout before it reaches the rest of your fleet.
This approach reduces risk. A patch that causes application compatibility issues or performance degradation is caught early, where the impact is limited to a small number of non-critical endpoints.
Rollout phases
Each deployment ring has a customizable set of rollout phases. You define how many phases the ring uses, what percentage of agents each phase targets, and how the rollout advances between them. There is no fixed number of phases: a simple ring might use two phases, while a cautious enterprise rollout might use five or more.
A typical ring configuration might look like this:
But you can define any number of phases with any target percentages. The only requirement is that the final phase must target 100%.
Presets
To help you get started, TridentStack Control provides built-in presets that populate a ring with a recommended set of phases:
| Preset | Description |
|---|---|
| Conservative | Multiple phases with longer wait times and higher success thresholds. Best for production-critical environments |
| Moderate | Balanced phase count and wait times. Good for most environments |
| Aggressive | Fewer phases with shorter wait times. For environments that need rapid patching |
| Immediate | Single phase at 100%. Deploys to all agents at once with no staging |
| Custom | Start from scratch and define your own phases |
Selecting a preset populates the ring's phases automatically. You can then customize individual phases or add and remove phases as needed. When you modify any phase after applying a preset, the ring switches to Custom mode.
Phase configuration
Each phase in a deployment ring has the following settings:
| Setting | Description |
|---|---|
| Name | A label for the phase (for example, "Canary", "Early Adopters", "Full Fleet") |
| Target percentage | The cumulative percentage of agents this phase covers. The final phase must be 100% |
| Minimum agents | The minimum number of agents that must be targeted before this phase can execute |
| Advancement type | Automatic (advances after wait time and success conditions are met) or Manual (requires an administrator to click Advance) |
| Wait time | Hours to wait after the phase completes before advancing to the next phase. Gives you time to observe results. Not shown for the final 100% phase since there is nothing to advance to. |
| Success rate | The minimum percentage of successful installations required before the rollout can advance (automatic mode only) |
| Max failures | The maximum number of failures allowed before the rollout auto-halts (automatic mode only) |
Additionally, the ring itself has a Window-aware phase advancement toggle that controls whether phase transitions respect deployment windows. See Window-aware phase advancement for details.
Targeting modes
Each phase can target agents in one of three ways:
- Percentage-based (default) - TridentStack Control automatically selects a percentage of agents from the policy's target groups. Simple to set up but gives you less control over exactly which endpoints are in each phase.
- Tag-based - Target agents that have specific tags (for example, "Canary Ring" or "Early Adopters"). This is the recommended approach for maintaining consistent phase membership over time.
- Specific agents - Individually select which agents are included in the phase. Useful for small canary groups where you want precise control.
Deployment windows
Deployment windows control when updates are allowed to install. Each ring can have its own schedule independent of the update policy's maintenance window.
- Timezone - Set the timezone for all schedule rules in this ring
- Schedule rules - Define time-of-day and day-of-week restrictions using criteria groups with AND/OR logic (for example, "weekdays between 2:00 AM and 6:00 AM")
- Exclusion dates - Block specific date ranges from deployments (for example, company-wide code freezes, holidays, or change blackout windows). Each exclusion includes a reason for documentation
If no deployment windows are configured, updates are allowed at any time.
What happens during and outside windows
TridentStack Control only performs disruptive actions during active deployment windows:
- Application update deployment - only dispatched when the window is open
- System update deployment - only dispatched when the window is open
- Scheduled reboots - only executed when the window is open
If an application deployment finishes and the system update phase is ready, but the deployment window has closed, the system updates will wait until the next window opens. Similarly, if a scheduled reboot time arrives but the window is closed, the reboot will wait.
Non-disruptive actions (settle timer countdown, timeout cleanup, failure marking) continue regardless of window state. These are housekeeping operations that do not affect the endpoint.
Window lifecycle states
Each deployment ring tracks its window lifecycle to provide clear visibility into what the ring is doing at any given time:
| State | Meaning |
|---|---|
| Scheduled | The deployment window is closed. No deployments are occurring. The ring is waiting for the next window to open. |
| Active | The deployment window is open and the ring is actively deploying updates to agents. |
| Idle | The deployment window is open, but the ring has no remaining actions to perform. All eligible agents have been deployed, and there are no pending system update dispatches or reboots. |
How transitions work:
When a deployment window opens, the ring enters the Active state. As agents receive their updates and no more work remains, the ring transitions to Idle. If a new agent comes online or becomes eligible during the window, the ring moves back to Active. When the window closes, the ring returns to Scheduled regardless of its current state.
The Idle state does not mean the rollout is complete. It means the ring has done everything it can during this window. Agents that were offline, in cooldown, or not yet eligible may receive updates in the next window.
Window-aware phase advancement
By default, phase advancement (moving from one phase to the next) happens as soon as the wait time expires and success criteria are met, regardless of whether a deployment window is currently open. This means a phase transition can occur at any time, even outside your scheduled maintenance windows.
If your organization requires strict change-window compliance, enable Window-aware phase advancement on the deployment ring. When enabled:
- Phases only advance to the next stage during an active deployment window
- Wait times are still measured in wall-clock hours. For example, a 24-hour wait always means 24 real hours.
- Once the wait time expires and success criteria are met, the phase waits for the next open deployment window before advancing
- This applies to both automatic advancement and manual approval. For manual approval, the administrator approves the advancement, and the actual transition occurs at the next open window.
Example: A canary phase completes at 11 PM with a 24-hour wait. The wait expires at 11 PM the next day. If the deployment window is 9 AM to 5 PM, the phase advances at 9 AM the following morning when the window opens.
This setting is off by default for all new rings. Enable it in the Rollout Phases section of the ring configuration.
Enable this when your change management process requires that all deployment activity, including phase transitions, occurs only during approved maintenance windows. Leave it off when you want phases to advance as quickly as possible and rely on deployment windows only to control when agents receive updates.
Safety controls
Each ring includes configurable safety mechanisms to automatically halt a rollout if something goes wrong:
- Auto-halt by failure count - Halt the rollout if the number of failures exceeds a defined limit
- Auto-halt by failure rate - Halt the rollout if the failure percentage exceeds a defined threshold
- Manual override - Allow or block administrators from manually overriding an auto-halt to continue the rollout
Failed agent cooldown
When an agent fails during a deployment, it enters a per-window cooldown. The agent is excluded from further deployment attempts for the remainder of the current deployment window. When the next window opens, the agent gets a fresh start and is eligible for deployment again.
This prevents the scheduler from repeatedly retrying a failing agent every five minutes within the same window, while ensuring the agent is not permanently blocked. If the underlying issue is resolved (for example, a bug fix is deployed to the server), the agent will succeed on its next window.
If you need to retry a failed agent immediately within the same window, use the Re-deploy button on the Rollout Status tab to reset the ring's phase state and restart the deployment cycle.
Additional ring settings
Pre-staging
When pre-staging is enabled, agents download update files in advance during a separate download window, before the deployment window opens. This ensures updates are ready to install immediately when the deployment window starts, reducing the time agents spend in the maintenance window.
Pre-staging settings include download windows, retry attempts, bandwidth limits, and file retention period.
Auto-restart
Configure whether agents automatically restart after installing updates. Settings include a prompt timeout (how long to wait for user acknowledgement before restarting), maximum postpone time, and reprompt interval.
Calendar view
The Deployment Rings page includes a calendar view that shows all scheduled deployment windows across your rings in a monthly grid.
Each deployment window appears as an event on the calendar with a color-coded status indicator:
| Status | Description |
|---|---|
| Scheduled | The window is upcoming and has not started yet |
| In Progress | The window is currently active and deployments are running |
| Completed | The window finished and all deployments in that window are done |
| Awaiting Approval | The rollout reached a manual-advance phase and is waiting for administrator approval |
| Paused | The rollout was paused by an administrator |
| Halted | The rollout was automatically halted due to safety controls |
| Failed | The deployment window encountered errors |
| Skipped | The window was manually skipped by an administrator |
| Unassigned | The ring is not applied to any endpoints (shown with a gray dashed border). Check that the ring's target tags match active agents |
Click any event on the calendar to see details including the ring name, current phase, time window, execution breakdown (completed, in-progress, pending, and failed counts), and phase advancement type.
From the event detail view, you can:
- Skip a scheduled window to exclude it from the rollout
- Restore a previously skipped window
The calendar refreshes automatically to reflect the latest rollout status.
Notifications
Deployment ring lifecycle events can trigger notifications to your team via Email, Slack, Microsoft Teams, Discord, or custom webhooks. Events include deployment started, phase advanced, approval pending, deployment completed, emergency halt, and phase failure. Configure which events trigger alerts and who receives them in Settings > Notifications. See Notifications for full setup instructions.
Enable notifications for Approval Pending and Emergency Halt at minimum. These are the two ring events most likely to require immediate action.
Monitoring ring progression
The deployment rings list view shows each ring's status at a glance, including the current phase, success and failure counts, success rate, and time remaining before the next phase advancement.
Rollout completion and automatic restart
When a ring reaches its final phase and all targeted agents have been deployed, the ring checks whether any agents still have pending updates. If pending updates remain (for example, an agent was offline during the rollout or new updates became applicable), the ring stays active and continues deploying. It only marks itself as complete when no pending updates remain for any agent in the ring.
Once a rollout completes, the ring does not stop permanently. If new applicable updates arrive for agents in the ring while a deployment window is active, the ring automatically starts a new rollout cycle. This means rings with broad deployment windows (such as daily or continuous schedules) behave as perpetual rollout engines: any time a new patch is approved or a new update becomes applicable, the ring picks it up and deploys it through the configured phases without manual intervention.
For rings with narrower windows (for example, a weekly Wednesday 2:00 AM - 6:00 AM window), the ring waits in a completed state until the next window opens. If agents have new pending updates at that time, the rollout restarts automatically.
If you need to restart a completed rollout immediately without waiting for new updates to arrive, click the Re-deploy button on the Rollout Status tab. This resets the ring's phase state and begins a fresh rollout cycle on the next scheduler evaluation.
Controlling a rollout
Halting
If issues are detected at any phase, you can halt the rollout. Halting:
- Prevents advancement to the next phase
- Stops any pending installations on agents that have not yet started
- Does not roll back updates that have already been installed
- Keeps the rollout in a halted state until you take action
Rollouts can also halt automatically when safety controls are triggered (for example, when the failure count or failure rate exceeds the configured threshold). When an auto-halt occurs, a banner displays the halt reason on the ring's detail view.
Rollback is not automatic. If a rollout is halted, updates that were already installed on earlier phases remain in place. If a patch needs to be removed, create a separate remediation plan for the affected endpoints.
Un-halting
To resume a halted rollout, click Un-halt from the ring's action menu or the table row. A dialog appears showing the halt reason and two options:
| Option | Behavior |
|---|---|
| Continue deploying, skip failed agents | Failed agents are left in their current state. Deployment resumes with the remaining agents only |
| Retry failed agents and continue deploying | Failed agents are re-queued for another attempt. Recommended when the original failure was transient (for example, a network timeout that has since been resolved) |
The dialog shows the count of failed agents in each option label so you can assess the scope before choosing.
An optional notes field lets you document what corrective action was taken. These notes are recorded for audit purposes.
If the ring is also paused, you must resume it separately after un-halting. The un-halt dialog displays a warning when this applies.
Pausing vs halting
| Pause | Halt | |
|---|---|---|
| Trigger | Manual (administrator clicks Pause) | Automatic (safety controls) or manual |
| Resume | Click Resume at any time | Requires un-halt with a decision about failed agents |
| Pending installs | Stopped | Stopped |
| Completed installs | Not rolled back | Not rolled back |
Use Pause for temporary stops (planned maintenance, investigation). Use Halt when failures need to be addressed before continuing.
Assign your least critical endpoints to the earliest phases. Development machines, test servers, and lab systems are ideal candidates. If a patch causes issues, the impact is minimal and you catch the problem before it reaches production.
Cancelling pending executions
To stop a rollout entirely, you can cancel all pending executions. Right-click the ring and select Cancel Pending. A confirmation dialog warns that this action cannot be undone.
Cancelling immediately removes all agents in "pending" status from the rollout. Installations that are already in progress complete normally. Use this when you need an emergency stop, when a configuration error is discovered, or when you want to prevent remaining agents from being updated.
Viewing agent details
To see per-agent execution status for a rollout, right-click the ring and select View Agent Details, or expand the ring and click View Agent Details.
A modal opens with a searchable table of all agents in the ring:
| Column | Description |
|---|---|
| Hostname | The agent's system name |
| Phase | Which deployment phase the agent belongs to |
| Status | Current execution state (completed, failed, pending, in progress, or cancelled) |
| Error | Failure details, if applicable |
| Duration | How long the installation took |
Use the status tabs at the top of the modal to filter by state (All, Completed, Failed, Pending, In Progress, Cancelled). Type in the hostname search field to find a specific endpoint. The table is paginated for rings targeting large numbers of agents.
Scheduled column indicators
The Scheduled column on the agent detail page shows the agent's current deployment ring status:
| Indicator | Meaning |
|---|---|
| Active (green pulsing dot) | Deployment window is open and the ring is actively deploying |
| Idle (gray badge) | Deployment window is open but no actions are pending for this ring |
| Cooldown (amber badge) | This agent failed during the current window and will retry in the next window |
| Completed (green check) | The ring's rollout has finished |
| Halted (red badge) | The ring has been halted due to excessive failures |
| Paused (amber badge) | The ring has been manually paused |
| Next window time (blue clock) | The deployment window is closed; shows when the next window opens |
| Manual (gray badge) | No deployment ring is assigned; updates are deployed manually |
Managing rings
From the deployment rings list page you can:
- Duplicate a ring to create a copy with all settings (starts inactive)
- Export a ring as JSON for backup or sharing
- Import a ring from a JSON file (creates an inactive copy)
- Delete a ring that is not assigned to any policies