From a2e796163c0cfff19b90ad7e4b4830584a08b37e Mon Sep 17 00:00:00 2001 From: Vadym Popov Date: Tue, 7 Jan 2025 10:02:51 -0800 Subject: [PATCH 1/9] Add client tools auto-update docs --- .../upgrading/client-tools-autoupdate.mdx | 137 ++++++++++++++++++ 1 file changed, 137 insertions(+) create mode 100644 docs/pages/upgrading/client-tools-autoupdate.mdx diff --git a/docs/pages/upgrading/client-tools-autoupdate.mdx b/docs/pages/upgrading/client-tools-autoupdate.mdx new file mode 100644 index 0000000000000..ff978a493f98b --- /dev/null +++ b/docs/pages/upgrading/client-tools-autoupdate.mdx @@ -0,0 +1,137 @@ +--- +title: Teleport Client Tools Automatic Updates +description: Explains how to use Teleport client tools (`tsh` and `tctl`) auto-updates. +--- + +## Overview + +This documentation explains how to keep Teleport client tools like `tsh` and `tctl` up-to-date. +Updates can be automatic or self-managed, ensuring tools are secure, free from bugs, +and compatible with your Teleport cluster. + +## Why Keep Client Tools Updated? + +- **Security**: Updates deliver patches for known vulnerabilities. +- **Bug Fixes**: Resolved issues are pushed to endpoints. +- **Compatibility**: Avoid manual understanding of [Teleport component compatibility rules](https://goteleport.com/docs/upgrading/overview/#component-compatibility). + +--- + +## Automatic Updates + +### How It Works + +When you run `tsh login`, the tool will check if updates are enabled for your cluster. +If your client version differs from the cluster's required version, it will: + +1. Download the updated version. +2. Store it in `~/.tsh/bin`. +3. Validate the binary with a checksum. +4. Re-execute using the updated version (with the same environment variables). + +### Key Features + +- **Binary Management**: Original binaries are preserved, and updates are stored separately. + +Updates are installed in the `$TELEPORT_HOME/.tsh/bin/` folder. 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. + +- **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, +platform, and edition. The edition must be identified by the original client tools binary. +The URL pattern is as follows: +- `https://cdn.teleport.dev/teleport-{ent-}vX.Y.Z-{linux,darwin,windows}-{amd64,arm64,arm,386}-{fips-}bin.tar.gz` +- `https://cdn.teleport.dev/teleport-{ent-}vX.Y.Z-{linux,darwin,windows}-{amd64,arm64,arm,386}-{fips-}bin.tar.gz.sha256` + +- **Concurrency**: Tools use a locking mechanism to enable smooth operation during updates. + +Only one process can acquire the lock to update client tools, while other processes wait for the lock to be released. +If the first process cancels the update, the next process in line will initiate the update. + +### User Experience + +Updates are displayed with a progress bar: +```bash +$ tsh login --proxy=proxy.example.com +Client tools are out of date, updating to vX.Y.Z. +Update progress: [▒▒▒▒▒▒ ] (Ctrl-C to cancel update) +``` +Cancel updates with Ctrl-C if needed due to bandwidth constraints or urgency. After cancellation command must +be executed with current version. + +### Environment Variable: TELEPORT_TOOLS_VERSION +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, +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 +only version environment variable will be overridden to `TELEPORT_TOOLS_VERSION=off`. + +Example of self-managed auto-update by setting the version with environment variable: +```bash +$ TELEPORT_TOOLS_VERSION=17.0.5 ./build/tctl version +Update progress: [▒▒▒▒▒▒▒▒▒▒] (Ctrl-C to cancel update) +Teleport v17.0.5 git:v17.0.5-0-g7cc4c2a go1.23.4 +```` + +### Cluster auto-update configuration details + +To enable client tools automatic updates in cluster, first create a file named `autoupdate_config.yaml` with the following content: + +```yaml +kind: autoupdate_config +metadata: + name: autoupdate-config + revision: 3a43b44a-201e-4d7f-aef1-ae2f6d9811ed +spec: + tools: + mode: enabled +version: v1 +``` + +And write resource data to the cluster `tctl create -f autoupdate_config.yaml`, after that any new `tsh` login must +check the target version and initiate downloading desired version to install in Teleport home folder. + +The next resource is responsible for setting target version `autoupdate_version.yaml`. + +```yaml +kind: autoupdate_version +metadata: + name: autoupdate-version + revision: 3a43b44a-201e-4d7f-aef1-ae2f6d9811ed +spec: + tools: + target_version: X.Y.Z +``` + +Create the resource using `tctl create -f autoupdate_version.yaml`. +If the `autoupdate_version` resource hasn't been created yet, the cluster version will be used as the default target version. + + + - For self-hosted clusters, automatic updates are disabled by default but can be enabled. + - Cloud clusters are automatically enrolled in updates, managed by the Teleport Cloud team. + - For clusters with multiple root versions, use self-managed updates to avoid frequent version switching. + + +### Cluster auto-update API endpoint + +To determine the version required to operate with the cluster, during the login process, `tsh` queries from the +unauthenticated proxy discovery `/v1/webapi/find` endpoint. If `.auto_update.tools_auto_update` is enabled, the +client tools must initiate the installation of the version specified in `.auto_update.tools_version`. + +For manual updates, when scheduling updates at specific times or using custom CDN mirrors or with self-build packages, +you can disable auto-update via configuration. In this case, you can monitor the tools version separately +or pair it with the `TELEPORT_TOOLS_VERSION=off` environment variable. + +```bash +$ curl https://proxy.example.com/v1/webapi/find | jq .auto_update +{ + "tools_auto_update": true, + "tools_version": "X.Y.Z", +} +``` From d18cc107d272b85e28fad9fdb0c9e1738c243cdb Mon Sep 17 00:00:00 2001 From: Vadym Popov Date: Tue, 7 Jan 2025 10:40:47 -0800 Subject: [PATCH 2/9] Add reference to index page --- docs/pages/upgrading/upgrading.mdx | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/pages/upgrading/upgrading.mdx b/docs/pages/upgrading/upgrading.mdx index 9657cdfc3e1da..a0cc335475a02 100644 --- a/docs/pages/upgrading/upgrading.mdx +++ b/docs/pages/upgrading/upgrading.mdx @@ -19,5 +19,8 @@ Enterprise cluster. For more information about upgrading, for example, to upgrade manually, read the [Upgrading Reference](upgrading-reference.mdx). +For more information about client tools auto-update, read the +[Teleport Client Tools Automatic Updates](client-tools-autoupdate.mdx). + You can find more information regarding the automatic updates architecture in the [Agent Update Management](../reference/architecture/agent-update-management.mdx) page. From 08c313ff7fc53f8ee09a9ec11869fa88250bd841 Mon Sep 17 00:00:00 2001 From: Vadym Popov Date: Tue, 7 Jan 2025 11:13:25 -0800 Subject: [PATCH 3/9] Fix linter prose style --- docs/pages/upgrading/client-tools-autoupdate.mdx | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/pages/upgrading/client-tools-autoupdate.mdx b/docs/pages/upgrading/client-tools-autoupdate.mdx index ff978a493f98b..2964440261cb4 100644 --- a/docs/pages/upgrading/client-tools-autoupdate.mdx +++ b/docs/pages/upgrading/client-tools-autoupdate.mdx @@ -3,8 +3,6 @@ title: Teleport Client Tools Automatic Updates description: Explains how to use Teleport client tools (`tsh` and `tctl`) auto-updates. --- -## Overview - This documentation explains how to keep Teleport client tools like `tsh` and `tctl` up-to-date. Updates can be automatic or self-managed, ensuring tools are secure, free from bugs, and compatible with your Teleport cluster. From 2ba8a9f0a2ae049cdaef07265a0c03258c6af29e Mon Sep 17 00:00:00 2001 From: Vadym Popov Date: Thu, 9 Jan 2025 16:08:10 -0800 Subject: [PATCH 4/9] Add section with tctl commands Code review changes --- .../upgrading/client-tools-autoupdate.mdx | 73 ++++++++++++++----- 1 file changed, 56 insertions(+), 17 deletions(-) diff --git a/docs/pages/upgrading/client-tools-autoupdate.mdx b/docs/pages/upgrading/client-tools-autoupdate.mdx index 2964440261cb4..eed013a6de4f7 100644 --- a/docs/pages/upgrading/client-tools-autoupdate.mdx +++ b/docs/pages/upgrading/client-tools-autoupdate.mdx @@ -5,21 +5,17 @@ description: Explains how to use Teleport client tools (`tsh` and `tctl`) auto-u This documentation explains how to keep Teleport client tools like `tsh` and `tctl` up-to-date. Updates can be automatic or self-managed, ensuring tools are secure, free from bugs, -and compatible with your Teleport cluster. +and compatible with your Teleport cluster. Available in versions: 17.0.1, 16.4.10, and 15.4.24. -## Why Keep Client Tools Updated? +Why keep client tools updated? - **Security**: Updates deliver patches for known vulnerabilities. - **Bug Fixes**: Resolved issues are pushed to endpoints. - **Compatibility**: Avoid manual understanding of [Teleport component compatibility rules](https://goteleport.com/docs/upgrading/overview/#component-compatibility). ---- - -## Automatic Updates - -### How It Works +### How it works -When you run `tsh login`, the tool will check if updates are enabled for your cluster. +When you run `tsh login`, the tsh tool will check if updates are enabled for your cluster. If your client version differs from the cluster's required version, it will: 1. Download the updated version. @@ -27,13 +23,14 @@ If your client version differs from the cluster's required version, it will: 3. Validate the binary with a checksum. 4. Re-execute using the updated version (with the same environment variables). -### Key Features +#### Key features: - **Binary Management**: Original binaries are preserved, and updates are stored separately. -Updates are installed in the `$TELEPORT_HOME/.tsh/bin/` folder. 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. +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. - **Validation**: Downloaded packages are verified with a hash sum to ensure integrity. @@ -48,7 +45,7 @@ The URL pattern is as follows: Only one process can acquire the lock to update client tools, while other processes wait for the lock to be released. If the first process cancels the update, the next process in line will initiate the update. -### User Experience +### User experience Updates are displayed with a progress bar: ```bash @@ -59,7 +56,7 @@ Update progress: [▒▒▒▒▒▒ ] (Ctrl-C to cancel update) Cancel updates with Ctrl-C if needed due to bandwidth constraints or urgency. After cancellation command must be executed with current version. -### Environment Variable: TELEPORT_TOOLS_VERSION +### Environment variable: TELEPORT_TOOLS_VERSION Values: - `X.Y.Z`: Use a specific version. - `off`: Disable updates. @@ -72,20 +69,63 @@ only version environment variable will be overridden to `TELEPORT_TOOLS_VERSION= Example of self-managed auto-update by setting the version with environment variable: ```bash -$ TELEPORT_TOOLS_VERSION=17.0.5 ./build/tctl version +$ TELEPORT_TOOLS_VERSION=17.0.5 tctl version Update progress: [▒▒▒▒▒▒▒▒▒▒] (Ctrl-C to cancel update) Teleport v17.0.5 git:v17.0.5-0-g7cc4c2a go1.23.4 ```` ### Cluster auto-update configuration details +#### Configuration by `tctl autoupdate` commands + +To enable or disable client tools automatic updates in the cluster, use the following command: + +```code +$ tctl autoupdate client-tools enable +client tools auto update mode has been changed + +$ tctl autoupdate client-tools disable +client tools auto update mode has been changed +``` + +To set or remove the target version for automatic updates for all client tools: + +```code +$ tctl autoupdate client-tools target X.Y.Z +client tools auto update target version has been set + +tctl autoupdate client-tools target --clear +client tools auto update target version has been cleared +``` + +If the target version is cleared, the cluster version will be used automatically, eliminating the need for manual +updates each time the cluster version is upgraded." + +The `status` command retrieves the target version and mode configured for the logged-in cluster. +To use an unauthenticated endpoint for this configuration, include the `--proxy` flag. + +```code +$ tctl autoupdate client-tools status --format json +{ + "mode": "enabled", + "target_version": "X.Y.Z" +} + +$ tctl autoupdate client-tools status --proxy proxy.example.com --format json +{ + "mode": "enabled", + "target_version": "X.Y.Z" +} +``` + +#### Configuration using resource definitions + To enable client tools automatic updates in cluster, first create a file named `autoupdate_config.yaml` with the following content: ```yaml kind: autoupdate_config metadata: name: autoupdate-config - revision: 3a43b44a-201e-4d7f-aef1-ae2f6d9811ed spec: tools: mode: enabled @@ -101,7 +141,6 @@ The next resource is responsible for setting target version `autoupdate_version. kind: autoupdate_version metadata: name: autoupdate-version - revision: 3a43b44a-201e-4d7f-aef1-ae2f6d9811ed spec: tools: target_version: X.Y.Z From 9e7f18006ed16a0459cbae2ea9c67f8ebdb5ac13 Mon Sep 17 00:00:00 2001 From: Vadym Popov Date: Mon, 13 Jan 2025 12:37:59 -0800 Subject: [PATCH 5/9] Reorganize sections Add documentation to navigation config Code review changes --- docs/config.json | 6 ++- .../upgrading/client-tools-autoupdate.mdx | 43 ++++++------------- 2 files changed, 19 insertions(+), 30 deletions(-) diff --git a/docs/config.json b/docs/config.json index f5ce95aca7d60..c25c6039ab314 100644 --- a/docs/config.json +++ b/docs/config.json @@ -35,7 +35,11 @@ { "title": "Upgrading Reference", "slug": "/upgrading/upgrading-reference/" - } + }, + { + "title": "Client Tools Automatic Updates", + "slug": "/upgrading/client-tools-autoupdate/" + } ] }, { diff --git a/docs/pages/upgrading/client-tools-autoupdate.mdx b/docs/pages/upgrading/client-tools-autoupdate.mdx index eed013a6de4f7..ae19554d3b97e 100644 --- a/docs/pages/upgrading/client-tools-autoupdate.mdx +++ b/docs/pages/upgrading/client-tools-autoupdate.mdx @@ -13,7 +13,7 @@ Why keep client tools updated? - **Bug Fixes**: Resolved issues are pushed to endpoints. - **Compatibility**: Avoid manual understanding of [Teleport component compatibility rules](https://goteleport.com/docs/upgrading/overview/#component-compatibility). -### How it works +## How it works When you run `tsh login`, the tsh tool will check if updates are enabled for your cluster. If your client version differs from the cluster's required version, it will: @@ -23,40 +23,28 @@ If your client version differs from the cluster's required version, it will: 3. Validate the binary with a checksum. 4. Re-execute using the updated version (with the same environment variables). -#### Key features: - -- **Binary Management**: Original binaries are preserved, and updates are stored separately. +### Key features: +**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. -- **Validation**: Downloaded packages are verified with a hash sum to ensure integrity. - +**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, platform, and edition. The edition must be identified by the original client tools binary. The URL pattern is as follows: -- `https://cdn.teleport.dev/teleport-{ent-}vX.Y.Z-{linux,darwin,windows}-{amd64,arm64,arm,386}-{fips-}bin.tar.gz` -- `https://cdn.teleport.dev/teleport-{ent-}vX.Y.Z-{linux,darwin,windows}-{amd64,arm64,arm,386}-{fips-}bin.tar.gz.sha256` - -- **Concurrency**: Tools use a locking mechanism to enable smooth operation during updates. +- `https://cdn.teleport.dev/teleport-{ent-}vX.Y.Z-{linux,darwin,windows}-{amd64,arm64,arm,386}-{fips-}bin.{tar.gz,pkg,zip}` +- `https://cdn.teleport.dev/teleport-{ent-}vX.Y.Z-{linux,darwin,windows}-{amd64,arm64,arm,386}-{fips-}bin.{tar.gz,pkg,zip}.sha256` +**Concurrency**: Tools use a locking mechanism to enable smooth operation during updates. Only one process can acquire the lock to update client tools, while other processes wait for the lock to be released. If the first process cancels the update, the next process in line will initiate the update. -### User experience +## Configuring client tool automatic updates -Updates are displayed with a progress bar: -```bash -$ tsh login --proxy=proxy.example.com -Client tools are out of date, updating to vX.Y.Z. -Update progress: [▒▒▒▒▒▒ ] (Ctrl-C to cancel update) -``` -Cancel updates with Ctrl-C if needed due to bandwidth constraints or urgency. After cancellation command must -be executed with current version. - -### Environment variable: TELEPORT_TOOLS_VERSION +### Using environment variables Values: - `X.Y.Z`: Use a specific version. - `off`: Disable updates. @@ -74,9 +62,7 @@ Update progress: [▒▒▒▒▒▒▒▒▒▒] (Ctrl-C to cancel update) Teleport v17.0.5 git:v17.0.5-0-g7cc4c2a go1.23.4 ```` -### Cluster auto-update configuration details - -#### Configuration by `tctl autoupdate` commands +### Using `tctl` To enable or disable client tools automatic updates in the cluster, use the following command: @@ -94,7 +80,7 @@ To set or remove the target version for automatic updates for all client tools: $ tctl autoupdate client-tools target X.Y.Z client tools auto update target version has been set -tctl autoupdate client-tools target --clear +$ tctl autoupdate client-tools target --clear client tools auto update target version has been cleared ``` @@ -118,7 +104,7 @@ $ tctl autoupdate client-tools status --proxy proxy.example.com --format json } ``` -#### Configuration using resource definitions +### Using resource definitions To enable client tools automatic updates in cluster, first create a file named `autoupdate_config.yaml` with the following content: @@ -129,7 +115,6 @@ metadata: spec: tools: mode: enabled -version: v1 ``` And write resource data to the cluster `tctl create -f autoupdate_config.yaml`, after that any new `tsh` login must @@ -155,14 +140,14 @@ If the `autoupdate_version` resource hasn't been created yet, the cluster versio - For clusters with multiple root versions, use self-managed updates to avoid frequent version switching. -### Cluster auto-update API endpoint +## Determining a client tool version To determine the version required to operate with the cluster, during the login process, `tsh` queries from the unauthenticated proxy discovery `/v1/webapi/find` endpoint. If `.auto_update.tools_auto_update` is enabled, the client tools must initiate the installation of the version specified in `.auto_update.tools_version`. For manual updates, when scheduling updates at specific times or using custom CDN mirrors or with self-build packages, -you can disable auto-update via configuration. In this case, you can monitor the tools version separately +you can disable auto-update via configuration. In this case, you can monitor the tool's version separately or pair it with the `TELEPORT_TOOLS_VERSION=off` environment variable. ```bash From 208b2388744e462526e555e54908c9a6aa50bcb2 Mon Sep 17 00:00:00 2001 From: Vadym Popov Date: Mon, 13 Jan 2025 14:51:53 -0800 Subject: [PATCH 6/9] Add `autoupdate` from command to cspell --- docs/cspell.json | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/cspell.json b/docs/cspell.json index 08c89c4305a08..74ddd3b98778f 100644 --- a/docs/cspell.json +++ b/docs/cspell.json @@ -307,6 +307,7 @@ "automations", "automount", "autoscale", + "autoupdate", "awly", "awsapp", "awsathena", From 46ae04ed14f84c2dde42e9568fb84c72b9f9ef69 Mon Sep 17 00:00:00 2001 From: Vadym Popov Date: Mon, 13 Jan 2025 15:11:14 -0800 Subject: [PATCH 7/9] Fix linter warning with relative link --- docs/pages/upgrading/client-tools-autoupdate.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/pages/upgrading/client-tools-autoupdate.mdx b/docs/pages/upgrading/client-tools-autoupdate.mdx index ae19554d3b97e..c80e67f986a8c 100644 --- a/docs/pages/upgrading/client-tools-autoupdate.mdx +++ b/docs/pages/upgrading/client-tools-autoupdate.mdx @@ -11,7 +11,7 @@ Why keep client tools updated? - **Security**: Updates deliver patches for known vulnerabilities. - **Bug Fixes**: Resolved issues are pushed to endpoints. -- **Compatibility**: Avoid manual understanding of [Teleport component compatibility rules](https://goteleport.com/docs/upgrading/overview/#component-compatibility). +- **Compatibility**: Avoid manual understanding of [Teleport component compatibility rules](overview.mdx#component-compatibility). ## How it works @@ -23,7 +23,7 @@ If your client version differs from the cluster's required version, it will: 3. Validate the binary with a checksum. 4. Re-execute using the updated version (with the same environment variables). -### Key features: +### Key features **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). From d93c380cc943382ba00d2f8bf455583143ad270f Mon Sep 17 00:00:00 2001 From: Vadym Popov Date: Tue, 14 Jan 2025 10:59:23 -0800 Subject: [PATCH 8/9] Update docs/config.json Co-authored-by: Paul Gottschling --- docs/config.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/config.json b/docs/config.json index c25c6039ab314..ac71c2753af3f 100644 --- a/docs/config.json +++ b/docs/config.json @@ -37,7 +37,7 @@ "slug": "/upgrading/upgrading-reference/" }, { - "title": "Client Tools Automatic Updates", + "title": "Client Tool Automatic Updates", "slug": "/upgrading/client-tools-autoupdate/" } ] From b3acc1a7496eb1e9f5fe921f5a1d59a2459e0493 Mon Sep 17 00:00:00 2001 From: Vadym Popov Date: Tue, 14 Jan 2025 10:59:33 -0800 Subject: [PATCH 9/9] Update docs/pages/upgrading/client-tools-autoupdate.mdx Co-authored-by: Paul Gottschling --- docs/pages/upgrading/client-tools-autoupdate.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/pages/upgrading/client-tools-autoupdate.mdx b/docs/pages/upgrading/client-tools-autoupdate.mdx index c80e67f986a8c..0d414ae131c36 100644 --- a/docs/pages/upgrading/client-tools-autoupdate.mdx +++ b/docs/pages/upgrading/client-tools-autoupdate.mdx @@ -1,5 +1,5 @@ --- -title: Teleport Client Tools Automatic Updates +title: Teleport Client Tool Automatic Updates description: Explains how to use Teleport client tools (`tsh` and `tctl`) auto-updates. ---