diff --git a/docs/pages/reference/cli/tctl.mdx b/docs/pages/reference/cli/tctl.mdx index 23b004abcea13..94408c4f5b539 100644 --- 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 [] +``` + +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 [] +``` + +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 + +- `` - 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 index d3a1a27bc13fb..a824acd861a7d 100644 --- 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` - - `tctl autoupdate` commands are available in versions: >=17.2.0 - - 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 index 11593a3ab24bc..fa38c574a180b 100644 --- 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.")