diff --git a/docs/pages/reference/cli/tctl.mdx b/docs/pages/reference/cli/tctl.mdx index c052a459d8bde..136c5f4c80ce6 100644 --- a/docs/pages/reference/cli/tctl.mdx +++ b/docs/pages/reference/cli/tctl.mdx @@ -2071,6 +2071,83 @@ prod Done 2025-01-15 18:00:12 outside_window backup Done 2025-01-14 20:00:31 outside_window ``` +## tctl autoupdate agents report + +Aggregates the agent autoupdate reports and displays agent count per version and per update group. + +## tctl autoupdate agents start-update + +```code +$ tctl autoupdate agents start-update [--force] [...] +``` + +Manually initiates an update for the specified groups. + +### Arguments + +- `` - Groups to update. If not specified, all groups will be started. +- `--force` - Skips progressive deployment mechanism such as canaries or backpressure. + +### Examples + +Manually trigger staging and production updates: +```code +$ tctl autoupdate agents start-update stage prod +Started updating agents groups: [stage prod]. +New agent rollout status: + +Group Name State Start Time State Reason +---------- --------- ------------------- -------------- +dev Unstarted cannot_start +stage Active 2025-03-10 15:04:16 manual_trigger +prod Active 2025-03-10 15:04:16 manual_trigger +``` +## tctl autoupdate agents mark-done + +```code +$ tctl autoupdate agents mark-done [...] +``` + +Manually marks an agent update group as successfully updated. + +### Arguments + +- `` - Groups to mark as updated. If not specified, all groups will be marked. + +### Examples + +Manually mark the staging group as updated: +```code +$ tctl autoupdate agents mark-done stage +Successfully marked agent groups as completed: [stage]. +New agent rollout status: + +Group Name State Start Time State Reason +---------- --------- ------------------- ------------------ +dev Unstarted cannot_start +stage Done 2025-03-10 15:04:16 manual_forced_done +prod Active 2025-03-10 15:04:16 manual_trigger +``` + +## tctl autoupdate agents rollback + +```code +$ tctl autoupdate agents rollback [...] +``` + +Initiates an immediate rollback of Teleport agents from the target version to the start version. + +### Arguments + +- `` - Groups to rollback. If not specified, all groups not in the `unstarted` state will be rolled back. + +### Examples + +Rollback all agents immediately: +```code +$ tctl autoupdate agents rollback +``` + ## tctl plugins install awsic Install the AWS Identity Center integration. diff --git a/docs/pages/upgrading/agent-managed-updates/agent-managed-updates.mdx b/docs/pages/upgrading/agent-managed-updates/agent-managed-updates.mdx index a356f405f22b0..fff047929fe83 100644 --- a/docs/pages/upgrading/agent-managed-updates/agent-managed-updates.mdx +++ b/docs/pages/upgrading/agent-managed-updates/agent-managed-updates.mdx @@ -370,6 +370,38 @@ progress to further groups. Similarly, tbot installations are only considered candidates for canary installations if they are deployed alongside a running Teleport Agent. +## Managing Rollouts + +Managed Update groups are automatically progressed as configured by the `autoupdate_config` resource. +However, it is possible to manually trigger or rollback updates for a selection of groups using `tctl autoupdate agents` commands: + +```code +Commands: + autoupdate agents status Prints agents auto update status. + autoupdate agents report Aggregates the agent autoupdate reports and displays agent count per version and per update group. + autoupdate agents start-update Starts updating one or many groups. + autoupdate agents mark-done Marks one or many groups as done updating. + autoupdate agents rollback Rolls back one or many groups. +``` + +For example, if an earlier group cannot be started, the other groups can be triggered manually: +```code +$ tctl autoupdate agents start-update stage prod +Started updating agents groups: [stage prod]. +New agent rollout status: + +Group Name State Start Time State Reason +---------- --------- ------------------- -------------- +dev Unstarted cannot_start +stage Active 2025-03-10 15:04:16 manual_trigger +prod Active 2025-03-10 15:04:16 manual_trigger +``` + +While individual agents will automatically and immediately rollback if they fail health checks during the update, +regressions or breaking changes in new versions could make it desirable to rollback an agent update to an earlier version. +The `tctl autoupdate agents rollback` command can be used to rollback one or more groups to the cluster's `start_version`. +Rollbacks are immediate and do not wait for canaries to complete. + ## Migrating agents on Linux servers to Managed Updates ### Finding unmanaged agents diff --git a/tool/tctl/common/autoupdate_command.go b/tool/tctl/common/autoupdate_command.go index d515d6c4419bc..8ba4e77ab3417 100644 --- a/tool/tctl/common/autoupdate_command.go +++ b/tool/tctl/common/autoupdate_command.go @@ -485,9 +485,9 @@ func (c *AutoUpdateCommand) agentsMarkDoneCommand(ctx context.Context, client au } if len(c.groups) == 0 { - fmt.Fprintln(c.stdout, "Successfully rolledback every started agent group.") + fmt.Fprintln(c.stdout, "Successfully marked every started agent group as completed.") } else { - fmt.Fprintf(c.stdout, "Successfully rolledback agents groups: %v.\n", groups) + fmt.Fprintf(c.stdout, "Successfully marked agent groups as completed: %v.\n", groups) } fmt.Fprint(c.stdout, "New agent rollout status:\n\n")