[v17] Update tctl reference docs with autoupdate commands (#52630)

* Update `tctl` reference docs with autoupdate commands * Documentation feedback --------- Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com> * Update docs/pages/reference/cli/tctl.mdx Co-authored-by: Zac Bergquist <zac.bergquist@goteleport.com> --------- Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com> Co-authored-by: Zac Bergquist <zac.bergquist@goteleport.com>
gravitational · Feb 28, 2025 · 9c8b103 · 9c8b103
1 parent a3dc4de
commit 9c8b103
Show file tree

Hide file tree

Showing 3 changed files with 110 additions and 8 deletions.
diff --git a/docs/pages/reference/cli/tctl.mdx b/docs/pages/reference/cli/tctl.mdx
@@ -1914,6 +1914,113 @@ $ tctl users update priya --set-azure-identities \
  `/subscriptions/${SUBSCRIPTION_ID?}/resourceGroups/${MY_RESOURCE_GROUP?}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/dba
 ```
 
+## tctl autoupdate client-tools status
+
+```code
+$ tctl autoupdate client-tools status [<flags>]
+```
+
+Requests the current status of client tool managed updates, indicating whether managed updates are enabled and displaying the target version for the update.
+If the `--proxy` flag is defined, tctl sends a request to an unauthenticated endpoint to retrieve the data.
+
+### Flags
+
+| Name | Default Value(s) | Allowed Value(s) | Description |
+| - | - | - | - |
+| `--proxy` | none | none | Address of the Teleport Proxy Service. When defined this address will be used to retrieve client tool auto update configuration. |
+| `--format` | yaml | `json`, `yaml` | Output format: 'yaml' or 'json'. |
+
+### Examples
+
+```code
+$ tctl autoupdate client-tools status
+mode: enabled
+target_version: 17.2.7
+
+$ tctl autoupdate client-tools status --format json
+{
+    "mode": "enabled",
+    "target_version": "17.2.7"
+}
+
+# Request to an unauthenticated endpoint.
+$ tctl autoupdate client-tools status --proxy proxy.example.com
+mode: enabled
+target_version: 17.2.7
+```
+
+## tctl autoupdate client-tools enable
+
+Enables managed updates for client tools in the cluster. If the target version is not set, the proxy version will be advertised.
+
+### Examples
+
+```code
+$ tctl autoupdate client-tools enable
+client tools auto update mode has been changed
+```
+
+## tctl autoupdate client-tools disable
+
+Disables managed updates for client tools in the cluster.
+
+### Examples
+
+```code
+$ tctl autoupdate client-tools disable
+client tools auto update mode has been changed
+```
+
+## tctl autoupdate client-tools target
+
+```code
+$ tctl autoupdate client-tools target [<flags>] <target-version>
+```
+
+Sets the target version for client tools in the cluster. After login, client tools will be advertised to this version and initiate the update process.
+
+### Arguments
+
+- `<target-version>` - Client tools target version. Clients will be told to update to this version.
+
+### Flags
+
+| Name | Default Value(s) | Allowed Value(s) | Description |
+| - | - | - | - |
+| `--clear` | none | none | Removes the target version, Teleport will default to its current proxy version. |
+
+### Examples
+
+```code
+$ tctl autoupdate client-tools target 17.2.7
+client tools auto update target version has been set
+
+$ tctl autoupdate client-tools target --clear
+client tools auto update target version has been cleared
+```
+
+## tctl autoupdate agents status
+
+Prints the status of automatic updates for Teleport Agents.
+
+### Examples
+
+```code
+$ tctl autoupdate agents status
+Agent autoupdate mode: enabled
+Rollout creation date: 2025-01-14 16:17:36
+Start version: 17.0.1
+Target version: 17.1.5
+Rollout state: Done
+
+Group Name State Start Time          State Reason
+---------- ----- ------------------- --------------
+dev        Done  2025-01-15 12:00:08 outside_window
+stage      Done  2025-01-15 16:17:45 outside_window
+prod       Done  2025-01-15 18:00:12 outside_window
+backup     Done  2025-01-14 20:00:31 outside_window
+```
+
 ## tctl version
 
 Print the version of your `tctl` binary:

diff --git a/docs/pages/upgrading/client-tools-autoupdate.mdx b/docs/pages/upgrading/client-tools-autoupdate.mdx
@@ -28,8 +28,7 @@ If your client version differs from the cluster's required version, it will:
 **Binary Management**: Original binaries are preserved, and updates are stored separately.
 Updates are installed in the `$TELEPORT_HOME/.tsh/bin/` folder (if `TELEPORT_HOME` is not defined, the home folder is used).
 When client tools (`tctl` or `tsh`) are executed from any other path, they consistently check for binaries in the update
-folder and re-execute them if found. After logging out from the cluster, the update folder is cleaned up, as each
-cluster might require its own version.
+folder and re-execute them if found.
 
 **Validation**: Downloaded packages are verified with a hash sum to ensure integrity.
 Package downloads are directed to the `cdn.teleport.dev` endpoint and depend on the operating system,
@@ -49,7 +48,7 @@ Values:
 - `X.Y.Z`: Use a specific version.
 - `off`: Disable updates.
 
-An environment variable `TELEPORT_TOOLS_VERSION` can be used as a emergency workaround for a known issue,
+An environment variable `TELEPORT_TOOLS_VERSION` can be used as an emergency workaround for a known issue,
 pinning to a specific version in CI/CD, for debugging, or for manual updates.
 
 During re-execution, child process will inherit all environment variables and flags. To prevent infinite loops
@@ -64,10 +63,6 @@ Teleport v17.0.5 git:v17.0.5-0-g7cc4c2a go1.23.4
 
 ### Using `tctl`
 
-<Admonition type="note">
-    `tctl autoupdate` commands are available in versions: >=17.2.0
-</Admonition>
-
 To enable or disable client tools automatic updates in the cluster, use the following command:
 
 ```code

diff --git a/tool/tctl/common/autoupdate_command.go b/tool/tctl/common/autoupdate_command.go
@@ -83,7 +83,7 @@ func (c *AutoUpdateCommand) Initialize(app *kingpin.Application, ccf *tctlcfg.Gl
 
 	c.toolsTargetCmd = clientToolsCmd.Command("target", "Sets the client tools target version. This command is not supported on Teleport Cloud.")
 	c.toolsTargetCmd.Arg("version", "Client tools target version. Clients will be told to update to this version.").StringVar(&c.toolsTargetVersion)
-	c.toolsTargetCmd.Flag("clear", "removes the target version, Teleport will default to its current proxy version.").BoolVar(&c.clear)
+	c.toolsTargetCmd.Flag("clear", "Removes the target version, Teleport will default to its current proxy version.").BoolVar(&c.clear)
 
 	agentsCmd := autoUpdateCmd.Command("agents", "Manage agents auto update configuration.")
 	c.agentsStatusCmd = agentsCmd.Command("status", "Prints agents auto update status.")