From 07d431e09b2d582f8ca169dbab979a65c24f4ccd Mon Sep 17 00:00:00 2001 From: Stephen Levine Date: Tue, 28 Jan 2025 18:59:03 -0500 Subject: [PATCH 01/11] docs wip --- docs/config.json | 14 +- ...dates.mdx => agent-managed-updates-v1.mdx} | 55 +- .../pages/upgrading/agent-managed-updates.mdx | 487 ++++++++++++++++++ 3 files changed, 532 insertions(+), 24 deletions(-) rename docs/pages/upgrading/{automatic-agent-updates.mdx => agent-managed-updates-v1.mdx} (86%) create mode 100644 docs/pages/upgrading/agent-managed-updates.mdx diff --git a/docs/config.json b/docs/config.json index c30f72cee000f..16b6e809e2dea 100644 --- a/docs/config.json +++ b/docs/config.json @@ -29,13 +29,17 @@ "slug": "/upgrading/overview/" }, { - "title": "Set up Automatic Agent Updates", - "slug": "/upgrading/automatic-agent-updates/" + "title": "Cluster Upgrading Reference", + "slug": "/upgrading/upgrading-reference/" }, { - "title": "Upgrading Reference", - "slug": "/upgrading/upgrading-reference/" - }, + "title": "Managed Updates for Agent (v1)", + "slug": "/upgrading/agent-managed-updates-v1/" + }, + { + "title": "Managed Updates for Agents (v2)", + "slug": "/upgrading/agent-managed-updates/" + }, { "title": "Client Tool Automatic Updates", "slug": "/upgrading/client-tools-autoupdate/" diff --git a/docs/pages/upgrading/automatic-agent-updates.mdx b/docs/pages/upgrading/agent-managed-updates-v1.mdx similarity index 86% rename from docs/pages/upgrading/automatic-agent-updates.mdx rename to docs/pages/upgrading/agent-managed-updates-v1.mdx index 00bb8e7ac5328..d0521973dc563 100644 --- a/docs/pages/upgrading/automatic-agent-updates.mdx +++ b/docs/pages/upgrading/agent-managed-updates-v1.mdx @@ -1,9 +1,26 @@ --- -title: Set up Automatic Agent Updates -description: Describes how to set up automatic agent updates. +title: Managed Agent Updates (v1) +description: Describes how to set up managed agent updates using the original updater. --- -On cloud-hosted Teleport Enterprise accounts, users must set up automatic agent + +This document describes the original (v1) Teleport Agent updater, which is +currently supported but will eventually be deprecated. + +The original updater uses the `teleport-ent-updater` package and +`cluster_maintenance_config` resource described in this document, while the +next-generation updater is included in the `teleport` package and uses the +`autoupdate_config` and `autoupdate_version` resources. + +Please consider using the next-generation updater, which is distributed with +all versions of Teleport and provides a simpler, more flexible, and more reliable +update experience compared to the original updater. + +For details about the next-generation updater, see +[Managed Updates for Agents (v2)](./agent-managed-updates.mdx). + + +On cloud-hosted Teleport Enterprise accounts, users must set up managed agent updates to ensure that the version of Teleport running on agents remains compatible with the version running on the Auth Service and Proxy Service. If an agent does not maintain [version compatibility](./overview.mdx) with your @@ -14,17 +31,17 @@ updates are performed every 4 months. You can monitor and subscribe to the [Teleport Status](https://status.teleport.sh/) page to be notified of scheduled updates. -Teleport supports automatic agent updates for systemd-based Linux distributions +Teleport supports managed agent updates for SystemD-based Linux distributions using `apt`, `yum`, and `zypper` package managers, as well as Kubernetes clusters. -This guide explains how to enable automatic updates for Teleport agents on +This guide explains how to enable managed updates for Teleport agents on Teleport Enterprise clusters, including both self-hosted and cloud-hosted clusters. ## How it works -When automatic updates are enabled, a Teleport updater is installed alongside +When managed updates are enabled, a Teleport updater is installed alongside each Teleport agent. The updater communicates with the Teleport Proxy Service to determine when an update is available. When an update is available, the updater will update the Teleport agent during the next maintenance window. However, if a @@ -38,22 +55,22 @@ regular maintenance window. Reference](upgrading-reference.mdx) to read about manual updates. - Familiarity with the [Upgrading Compatibility Overview](./overview.mdx) guide, which describes the sequence in which to upgrade components in your cluster. -- Teleport agents that are not yet enrolled in automatic updates. +- Teleport agents that are not yet enrolled in managed updates. - (!docs/pages/includes/tctl-tsh-prerequisite.mdx!) - (!docs/pages/includes/tctl.mdx!) -## Step 1/4. Enable automatic agent upgrades +## Step 1/4. Enable managed agent upgrades If you are running a cloud-hosted Teleport Enterprise cluster, skip to [Step 2](#step-24-find-agents-to-enroll-in-automatic-updates). -Before enabling automatic upgrades in your self-hosted Teleport cluster, you +Before enabling managed upgrades in your self-hosted Teleport cluster, you must enable a **version server**. This section shows you how to enable a version server in your cluster. ### Configure a maintenance schedule -To enable automatic upgrades in your cluster, you must create a cluster +To enable managed upgrades in your cluster, you must create a cluster maintenance configuration. This configures a maintenance schedule for the Teleport cluster that agents use to determine when to check for upgrades. @@ -137,10 +154,10 @@ $ curl "https:///v1/webapi/automaticupgra (=teleport.version=) ``` -## Step 2/4. Find agents to enroll in automatic updates +## Step 2/4. Find agents to enroll in managed updates Use the `tctl inventory ls` command to list connected agents along with their current -version. Use the `--upgrader=none` flag to list agents that are not enrolled in automatic +version. Use the `--upgrader=none` flag to list agents that are not enrolled in managed updates. ```code @@ -151,7 +168,7 @@ Server ID Hostname Services Version Upgrader ... ``` -## Step 3/4. Enroll agents on Linux servers in automatic updates +## Step 3/4. Enroll agents on Linux servers in managed updates 1. For each agent ID returned by the `tctl inventory ls` command, copy the ID and run the following `tctl` command to access the host via `tsh`: @@ -177,7 +194,7 @@ Server ID Hostname Services Version Upgrader 1. Ensure that the Teleport repository is properly configured to use the channel, and install the `teleport-ent-updater` package. You must install `teleport-ent-updater` on each agent you would like - to enroll into automatic updates: + to enroll into managed updates: @@ -246,7 +263,7 @@ $ sudo chown /etc/teleport-upgrade.d/schedule schedule. This is expected immediately after install as the maintenance schedule might not be exported yet. -## Step 4/4. Enroll Kubernetes agents in automatic updates +## Step 4/4. Enroll Kubernetes agents in managed updates This section assumes that the name of your `teleport-kube-agent` release is `teleport-agent`, and that you have installed it in the `teleport` namespace. @@ -334,7 +351,7 @@ can consult the updater logs to help troubleshoot the problem: $ journalctl -u teleport-upgrade ``` -### Troubleshooting automatic agent upgrades on Kubernetes +### Troubleshooting managed agent upgrades on Kubernetes The updater is a controller that periodically reconciles expected Kubernetes resources with those in the cluster. The updater executes a reconciliation loop @@ -348,12 +365,12 @@ until the next reconciliation, you can trigger an event. $ kubectl -n annotate statefulset/ 'debug.teleport.dev/trigger-event=1' ``` -1. To suspend automatic updates for an agent, annotate the agent deployment +1. To suspend managed updates for an agent, annotate the agent deployment with `teleport.dev/skipreconcile: "true"`, either by setting the `annotations.deployment` value in Helm, or by patching the deployment directly with `kubectl`. -### Troubleshooting automatic agent upgrades on Linux +### Troubleshooting managed agent upgrades on Linux 1. If an agent is not automatically upgraded, you can invoke the upgrader manually and look at its logs: @@ -362,7 +379,7 @@ until the next reconciliation, you can trigger an event. $ sudo teleport-upgrade run ``` -1. To suspend automatic updates, disable the systemd timer: +1. To suspend managed updates, disable the systemd timer: ```code $ sudo systemctl disable --now teleport-upgrade.timer diff --git a/docs/pages/upgrading/agent-managed-updates.mdx b/docs/pages/upgrading/agent-managed-updates.mdx new file mode 100644 index 0000000000000..a32d44e7fbad6 --- /dev/null +++ b/docs/pages/upgrading/agent-managed-updates.mdx @@ -0,0 +1,487 @@ +--- +title: Managed Agent Updates (v2) +description: Describes how to set up managed agent updates using the next-generation updater. +--- + + +This document describes the next-generation (v2) Teleport Agent updater, which +is currently in beta. + +The original updater uses the `teleport-ent-updater` package and +`cluster_maintenance_config` resource, while the next-generation updater is +included in the `teleport` package and uses the `autoupdate_version` and +`autoupdate_config` resources described in this document. + +Please consider using the next-generation updater, which is distributed with +all versions of Teleport and provides a simpler, more flexible, and more reliable +update experience compared to the original updater. + +For details about the original updater, see +[Managed Updates for Agents (v1)](./agent-managed-updates-v1.mdx). + + +On cloud-hosted Teleport Enterprise accounts, users must set up managed agent +updates to ensure that the version of Teleport running on agents remains +compatible with the version running on the Auth Service and Proxy Service. If an +agent does not maintain [version compatibility](./overview.mdx) with your +Teleport cluster, connections to those agents will become degraded or lost. + +Cloud-hosted Teleport clusters are updated on a weekly basis. Major version +updates are performed every 4 months. You can monitor and subscribe to the +[Teleport Status](https://status.teleport.sh/) page to be notified of scheduled +updates. + +Teleport supports managed agent updates for SystemD-based Linux distributions +as well as Kubernetes clusters. + +This guide explains how to enable managed updates for Teleport agents on +Teleport Enterprise clusters, including both self-hosted and cloud-hosted +clusters. + +## How it works + +When managed updates are enabled, a Teleport updater runs alongside +each Teleport agent. The updater communicates with the Teleport Proxy Service to +determine when an update is available. When an update is available, the updater +will update the Teleport agent. Each agent belongs to an update group, and the +time each group is updated can be configured using `tctl`. + +For Linux server-based installations, `teleport-update` command configures +managed updates. + +For Kubernetes-based installations, the `teleport-kube-agent` Helm chart +is configured to automatically update the Teleport container. + +## Prerequisites + +- A Teleport Enterprise cluster. If you do not have one, [sign + up](https://goteleport.com/signup) for a free trial or consult the [Update + Reference](upgrading-reference.mdx) to read about manual updates. +- Familiarity with the [Upgrading Compatibility Overview](./overview.mdx) guide, + which describes the sequence in which to upgrade components in your cluster. +- Teleport agents that are not yet enrolled in managed updates. +- (!docs/pages/includes/tctl-tsh-prerequisite.mdx!) +- (!docs/pages/includes/tctl.mdx!) + +## Quick Setup for Linux Servers + +Users of cloud-hosted Teleport Enterprise can enable managed updates +on Linux servers with a single command: + +```code +$ sudo teleport-update enable --proxy=[cluster-name].teleport.sh +``` + +This command will disable the original (v1) updater if present. +No other action is necessary. + +If everything is working, the deprecated updater can be removed: + +```code +$ sudo apt remove teleport-ent-updater +``` + +If the new updater does not work, your installation can be reverted +back to manual updates or the original updater (if it has not been removed): + +```code +$ sudo teleport-update uninstall +``` + +For cloud-hosted Teleport Enterprise, updates will roll out automatically +during the first chosen maintenance window that is at least 36 hours after +the cluster version is updated. Keep reading to learn how to customize this. + +## Step 1/4. Enable managed agent updates + +For cloud-hosted Teleport Enterprise, managed updates are enabled by default. +The `autoupdate_version` resource is managed for you, and cannot be edited. + +For self-hosted Teleport Enterprise, the `autoupdate_version` resource must be +created to enabled managed updates. + +Create a file called `autoupdate_version.yaml` containing: + +```yaml +kind: autoupdate_version +spec: + agents: + start_version: v17.2.0 + target_version: v17.2.1 + schedule: regular + strategy: time-based + mode: enabled +``` + +- `start_version` is the version used to install new agents before their update window. +- `target_version` is the version that agents will be updated to during their update window, as well + as the version used to install new agents during and after their update windows. +- `schedule` is `regular` or `immediate`, where `immediate` forces an immediate update for all agents. +- `strategy` is `time-based` or `halt-on-error`. `halt-on-error` will ensure groups listed first + in `autoupdate_config` are updated before groups listed later in `autoupdate_config`. Note that + client-side errors are not detected automatically. Set `mode` to `suspended` to stop the rollout. +- `mode` is `enabled`, `disabled`, or `suspended`. + +Run the following command: + +```code +$ tctl create autoupdate_version.yaml +``` + +For both cloud-hosted and self-hosted editions of Teleport, an update schedule +may be set with the + + +See below for how + + + + + + +```yaml +kind: autoupdate_config +spec: + agents: + schedules: + regular: + - name: default + days: ["Mon", "Tue", "Wed", "Thu"] + start_hour: 4 +``` + + + + +If you are running a cloud-hosted Teleport Enterprise cluster, the +`autoupdate_version` is managed for you and cannot be edited. + + + +Before enabling managed upgrades in your self-hosted Teleport cluster, you +must enable a **version server**. This section shows you how to enable a version +server in your cluster. + +### Configure a maintenance schedule + +To enable managed upgrades in your cluster, you must create a cluster +maintenance configuration. This configures a maintenance schedule for the +Teleport cluster that agents use to determine when to check for upgrades. + +1. Create a Teleport role that can manage cluster maintenance configurations + through the `cluster_maintenance_config` dynamic resource. No preset Teleport + roles provide this ability, so you will need to create one. + + Create a file called `cmc-editor.yaml` with the following content: + + ```yaml + kind: role + version: v7 + metadata: + name: cmc-editor + spec: + allow: + rules: + - resources: ['cluster_maintenance_config'] + verbs: ['create', 'read', 'update', 'delete'] + ``` + + Create the role resource: + + ```code + $ tctl create cmc-editor.yaml + ``` + + (!docs/pages/includes/create-role-using-web.mdx!) + +1. Add the role to your Teleport user: + +(!docs/pages/includes/add-role-to-user.mdx role="cmc-editor"!) + +1. Create a cluster maintenance config in a file called `cmc.yaml`. The + following example allows maintenance on Monday, Wednesday and Friday between + 02:00 and 03:00 UTC: + + (!docs/pages/includes/cluster-maintenance-config-spec.mdx!) + +1. Apply the manifest using `tctl`: + + ```code + $ tctl create cmc.yaml + maintenance window has been updated + ``` + +### [Optional] Assign the version served by the version server + +By default, the version server has a single `default` channel, serving the +version of the Teleport Proxy Service. If you want to override the default +version or add other channels you can use the `automatic_upgrades_channels` +field in the Proxy Service configuration file: + +```yaml +proxy_service: + enabled: "yes" + automatic_upgrades_channels: + # Override the default version channel reachable at + # https:///v1/webapi/automaticupgrades/channel/default/version + default: + static_version: v14.2.1 + # Define a new version channel with a static version reachable at + # https:///v1/webapi/automaticupgrades/channel/m-static-channel/version + my-static-channel: + static_version: v14.2.0 + # Define a new version channel forwarding requests to an upstream version server + my-remote-channel: + forward_url: https://updates.releases.teleport.dev/v1/stable/cloud +``` + +You must ensure that all Proxy Service instances share the same +`automatic_upgrades_channels` configuration. If some Proxy Service instances are +configured differently, you will experience agents flickering between versions +as the version served is not consistent across instances. + +If your Proxy Service public address is , +you can query the version server with the following command: + +```code +$ curl "https:///v1/webapi/automaticupgrades/channel/default/version" +(=teleport.version=) +``` + +## Step 2/4. Find agents to enroll in managed updates + +Use the `tctl inventory ls` command to list connected agents along with their current +version. Use the `--upgrader=none` flag to list agents that are not enrolled in managed +updates. + +```code +$ tctl inventory ls --upgrader=none +Server ID Hostname Services Version Upgrader +------------------------------------ ------------- -------- ------- -------- +00000000-0000-0000-0000-000000000000 ip-10-1-6-130 Node v14.4.5 none +... +``` + +## Step 3/4. Enroll agents on Linux servers in managed updates + +1. For each agent ID returned by the `tctl inventory ls` command, copy the ID + and run the following `tctl` command to access the host via `tsh`: + + ```code + $ HOST=00000000-0000-0000-0000-000000000000 + $ USER=root + $ tsh ssh "${USER?}@${HOST?}" + ``` + +1. Determine the Teleport version to install by querying the Teleport Proxy + Service. This way, the Teleport installation has the same major version as + the automatic updater. + + Replace with the name of your automatic update + channel. For cloud-hosted Teleport Enterprise accounts, this is always + `stable/cloud`: + + ```code + $ TELEPORT_VERSION="$(curl https:///v1/webapi/automaticupgrades/channel//version | sed 's/v//')" + ``` + +1. Ensure that the Teleport repository is properly configured to use the + channel, and install the `teleport-ent-updater` + package. You must install `teleport-ent-updater` on each agent you would like + to enroll into managed updates: + + + + + ```code + $ curl (=teleport.teleport_install_script_url=) | bash -s ${TELEPORT_VERSION?} cloud + ``` + + + + + 1. Follow the instructions in the Teleport [installation + guide](../installation.mdx#package-repositories) to install the `teleport` + binary on your Linux server for your package manager. + + 1. Using your package manager, install `teleport-ent-updater` on the + server where you installed `teleport`. For example: + + ```code + $ apt-get install -y teleport-ent-updater + ``` + + + + + The installation script detects the package manager on your Linux server and + uses it to install Teleport binaries. To customize your installation, learn + about the Teleport package repositories in the [installation + guide](../installation.mdx#linux). + +1. Confirm that the version of the `teleport` binary is the one you expect: + + ```code + $ teleport version + ``` + +
+ +If you changed the agent user to run as non-root, create +`/etc/teleport-upgrade.d/schedule` and grant ownership to your Teleport user: + +```code +$ sudo mkdir -p /etc/teleport-upgrade.d/ +$ sudo touch /etc/teleport-upgrade.d/schedule +$ sudo chown /etc/teleport-upgrade.d/schedule +``` + +
+ +1. Verify that the upgrader can see your version endpoint by checking for + upgrades: + + ```code + $ sudo teleport-upgrade dry-run + ``` + +1. You should see one of the following messages, depending on the target version + you are currently serving: + + ```text + no upgrades available (1.2.3 == 1.2.3) + an upgrade is available (1.2.3 -> 2.3.4) + ``` + + `teleport-upgrade` may display warnings about not having a valid upgrade + schedule. This is expected immediately after install as the maintenance + schedule might not be exported yet. + +## Step 4/4. Enroll Kubernetes agents in managed updates + +This section assumes that the name of your `teleport-kube-agent` release is +`teleport-agent`, and that you have installed it in the `teleport` namespace. + +1. Confirm that you are using the Teleport Enterprise edition of the + `teleport-kube-agent` chart. You should see the following when you query your + `teleport-kube-agent` release: + + ```code + $ helm -n `teleport` get values `teleport-agent` -o json | jq '.enterprise' + true + ``` + + If another value such as `null` is returned, update your existing agent + `values.yaml` to use the Enterprise version: + + ```yaml + enterprise: true + ``` + +1. Add the following chart values to the values file for the + `teleport-kube-agent` chart: + + ```yaml + updater: + enabled: true + ``` + +1. Update the Teleport Helm repository to include any new versions of the + `teleport-kube-agent` chart: + + ```code + $ helm repo update teleport + ``` + +1. Update the Helm chart release with the new values: + + + + + ```code + $ helm -n upgrade teleport/teleport-kube-agent \ + --values=values.yaml \ + --version="(=cloud.version=)" + ``` + + + + ```code + $ helm -n upgrade teleport/teleport-kube-agent \ + --values=values.yaml \ + --version="(=teleport.version=)" + ``` + + + +1. You can validate the updater is running properly by checking if its pod is + ready: + + ```code + $ kubectl -n teleport-agent get pods + NAME READY STATUS RESTARTS AGE + -0 1/1 Running 0 14m + -1 1/1 Running 0 14m + -2 1/1 Running 0 14m + -updater-d9f97f5dd-v57g9 1/1 Running 0 16m + ``` + +1. Check for any deployment issues by checking the updater logs: + + ```code + $ kubectl -n logs deployment/-updater + 2023-04-28T13:13:30Z INFO StatefulSet is already up-to-date, not updating. {"controller": "statefulset", "controllerGroup": "apps", "controllerKind": "StatefulSet", "StatefulSet": {"name":"my-agent","namespace":"agent"}, "namespace": "agent", "name": "my-agent", "reconcileID": "10419f20-a4c9-45d4-a16f-406866b7fc05", "namespacedname": "agent/my-agent", "kind": "StatefulSet", "err": "no new version (current: \"v12.2.3\", next: \"v12.2.3\")"} + ``` + +## Troubleshooting + +Teleport agents are not updated immediately when a new version of Teleport is +released, and agent updates can lag behind the cluster by a few days. + +If the Teleport agent has not been automatically updating for several weeks, you +can consult the updater logs to help troubleshoot the problem: + +```code +$ journalctl -u teleport-upgrade +``` + +### Troubleshooting managed agent upgrades on Kubernetes + +The updater is a controller that periodically reconciles expected Kubernetes +resources with those in the cluster. The updater executes a reconciliation loop +every 30 minutes or in response to a Kubernetes event. If you don't want to wait +until the next reconciliation, you can trigger an event. + +1. Any deployment update will send an event, so you can trigger the upgrader by + annotating the resource: + + ```code + $ kubectl -n annotate statefulset/ 'debug.teleport.dev/trigger-event=1' + ``` + +1. To suspend managed updates for an agent, annotate the agent deployment + with `teleport.dev/skipreconcile: "true"`, either by setting the + `annotations.deployment` value in Helm, or by patching the deployment + directly with `kubectl`. + +### Troubleshooting managed agent upgrades on Linux + +1. If an agent is not automatically upgraded, you can invoke the upgrader + manually and look at its logs: + + ```code + $ sudo teleport-upgrade run + ``` + +1. To suspend managed updates, disable the systemd timer: + + ```code + $ sudo systemctl disable --now teleport-upgrade.timer + ``` + +1. To enable and start the systemd timer after suspending: + + ```code + $ sudo systemctl enable --now teleport-upgrade.timer + ``` + From 3d21f004b30d08bcfa1991e4470ad3517792a659 Mon Sep 17 00:00:00 2001 From: Stephen Levine Date: Sun, 2 Feb 2025 14:09:57 -0500 Subject: [PATCH 02/11] wip 2 --- .../upgrading/agent-managed-updates-v1.mdx | 5 +- .../pages/upgrading/agent-managed-updates.mdx | 124 +++++++++++++----- 2 files changed, 96 insertions(+), 33 deletions(-) diff --git a/docs/pages/upgrading/agent-managed-updates-v1.mdx b/docs/pages/upgrading/agent-managed-updates-v1.mdx index d0521973dc563..d60b54e575e61 100644 --- a/docs/pages/upgrading/agent-managed-updates-v1.mdx +++ b/docs/pages/upgrading/agent-managed-updates-v1.mdx @@ -9,8 +9,9 @@ currently supported but will eventually be deprecated. The original updater uses the `teleport-ent-updater` package and `cluster_maintenance_config` resource described in this document, while the -next-generation updater is included in the `teleport` package and uses the -`autoupdate_config` and `autoupdate_version` resources. +next-generation updater is a binary called `teleport-update` that is included +in the `teleport` package and configured by the `autoupdate_version` and +`autoupdate_config` resources described in this document. Please consider using the next-generation updater, which is distributed with all versions of Teleport and provides a simpler, more flexible, and more reliable diff --git a/docs/pages/upgrading/agent-managed-updates.mdx b/docs/pages/upgrading/agent-managed-updates.mdx index a32d44e7fbad6..749eecae4b19d 100644 --- a/docs/pages/upgrading/agent-managed-updates.mdx +++ b/docs/pages/upgrading/agent-managed-updates.mdx @@ -9,8 +9,9 @@ is currently in beta. The original updater uses the `teleport-ent-updater` package and `cluster_maintenance_config` resource, while the next-generation updater is -included in the `teleport` package and uses the `autoupdate_version` and -`autoupdate_config` resources described in this document. +a binary called `teleport-update` that is included in the `teleport` package and +configured by the `autoupdate_version` and `autoupdate_config` resources +described in this document. Please consider using the next-generation updater, which is distributed with all versions of Teleport and provides a simpler, more flexible, and more reliable @@ -47,7 +48,7 @@ will update the Teleport agent. Each agent belongs to an update group, and the time each group is updated can be configured using `tctl`. For Linux server-based installations, `teleport-update` command configures -managed updates. +managed updates locally on the server. For Kubernetes-based installations, the `teleport-kube-agent` Helm chart is configured to automatically update the Teleport container. @@ -63,13 +64,13 @@ is configured to automatically update the Teleport container. - (!docs/pages/includes/tctl-tsh-prerequisite.mdx!) - (!docs/pages/includes/tctl.mdx!) -## Quick Setup for Linux Servers +## Quick Setup for Connected Linux Servers Users of cloud-hosted Teleport Enterprise can enable managed updates -on Linux servers with a single command: +on Linux servers that are already connected with a single command: ```code -$ sudo teleport-update enable --proxy=[cluster-name].teleport.sh +$ sudo teleport-update enable ``` This command will disable the original (v1) updater if present. @@ -90,7 +91,32 @@ $ sudo teleport-update uninstall For cloud-hosted Teleport Enterprise, updates will roll out automatically during the first chosen maintenance window that is at least 36 hours after -the cluster version is updated. Keep reading to learn how to customize this. +the cluster version is updated. Keep reading to learn how to customize the time. + +## Quick Setup for New Linux Servers + +The [Install Script] is the fastest way to onboard new Linux servers with +a single command. However, it is also easy use `teleport-update` to setup +a Teleport agent manually. + +Users of cloud-hosted Teleport Enterprise can install a fresh copy of Teleport +with managed updates already enabled using a single command. First, download a +copy of the [Teleport tarball] from the downloads page. Next, invoke +`teleport-update` to install the correct version for your cluster. + +```code +$ tar xf teleport-[version].tgz +$ cd teleport-[version] +$ sudo ./teleport-update enable --proxy example.teleport.sh +``` + +After Teleport is installed, you can create `/etc/teleport.yaml`, either manually +or using `teleport configure`. After, the Teleport agent can be enabled and +started via the `systemctl` command: + +```code +$ sudo systemctl enable teleport --now +``` ## Step 1/4. Enable managed agent updates @@ -109,7 +135,7 @@ spec: start_version: v17.2.0 target_version: v17.2.1 schedule: regular - strategy: time-based + strategy: halt-on-error mode: enabled ``` @@ -129,15 +155,25 @@ $ tctl create autoupdate_version.yaml ``` For both cloud-hosted and self-hosted editions of Teleport, an update schedule -may be set with the - - -See below for how - - +may be set with the `autoupdate_config` resource. The default resource looks +like this: +```yaml +kind: autoupdate_config +spec: + agents: + schedules: + regular: + - name: default + days: [ "Mon", "Tue", "Wed", "Thu" ] + start_hour: 16 +``` +For cloud-hosted Teleport Enterprise, the `days` are not configurable for most +customers, and the `start_hour` is defaulted to your selected maintenance window. +For example, a user of cloud-hosted Teleport with a staging environment and a +production environment might create a schedule that looks like this: ```yaml kind: autoupdate_config @@ -145,22 +181,48 @@ spec: agents: schedules: regular: - - name: default - days: ["Mon", "Tue", "Wed", "Thu"] - start_hour: 4 + - name: staging + start_hour: 4 + wait_hours: 24 + - name: production + start_hour: 5 ``` +This schedule would update agents in the `staging` group at 4 UTC, and then update +the `production` group at 5 UTC the next day. The `production` group will not execute +update until the staging group has updated. + +While failed installations will revert automatically on the client-side, +server-side healthchecks are still in development. To prevent the `production` +group above from updating after `staging` has failed, you must manually suspend +the schedule by setting the `spec.agents.mode` to `suspended`. + +You may wish to schedule groups of agents to update without any dependence between +them. For example, groups may represent geographic areas and not environments. +To accomplish this, you can change the default `halt-on-error` strategy to the +`time-based` strategy: -If you are running a cloud-hosted Teleport Enterprise cluster, the -`autoupdate_version` is managed for you and cannot be edited. - +```yaml +kind: autoupdate_config +spec: + agents: + strategy: time-based + schedules: + regular: + - name: nyc + start_hour: 4 + - name: sjc + start_hour: 20 +``` +With this strategy, updates to `sjc` may occur before `nyc`, depending on when +new versions become available. -Before enabling managed upgrades in your self-hosted Teleport cluster, you -must enable a **version server**. This section shows you how to enable a version -server in your cluster. +To add agents to groups, run `teleport-update enable --group group-name`. +You may execute `teleport-update enable` repeatedly to change the group +(or other managed update settings). ### Configure a maintenance schedule @@ -300,16 +362,16 @@ Server ID Hostname Services Version Upgrader - 1. Follow the instructions in the Teleport [installation - guide](../installation.mdx#package-repositories) to install the `teleport` - binary on your Linux server for your package manager. + 1. Follow the instructions in the Teleport [installation + guide](../installation.mdx#package-repositories) to install the `teleport` + binary on your Linux server for your package manager. - 1. Using your package manager, install `teleport-ent-updater` on the - server where you installed `teleport`. For example: + 1. Using your package manager, install `teleport-ent-updater` on the + server where you installed `teleport`. For example: - ```code - $ apt-get install -y teleport-ent-updater - ``` + ```code + $ apt-get install -y teleport-ent-updater + ``` From b7e0b686735415d886c1a72050d48181dd5dea26 Mon Sep 17 00:00:00 2001 From: Stephen Levine Date: Mon, 3 Feb 2025 12:52:20 -0500 Subject: [PATCH 03/11] wip 3 --- .../pages/upgrading/agent-managed-updates.mdx | 295 +++++++----------- 1 file changed, 106 insertions(+), 189 deletions(-) diff --git a/docs/pages/upgrading/agent-managed-updates.mdx b/docs/pages/upgrading/agent-managed-updates.mdx index 749eecae4b19d..ac501a6d959b4 100644 --- a/docs/pages/upgrading/agent-managed-updates.mdx +++ b/docs/pages/upgrading/agent-managed-updates.mdx @@ -73,8 +73,13 @@ on Linux servers that are already connected with a single command: $ sudo teleport-update enable ``` -This command will disable the original (v1) updater if present. -No other action is necessary. + +If this command is not available, update the `teleport` package +to the latest version that is supported by your cluster. + + +The `teleport-update enable` command will disable the original (v1) +updater if present. No other action is necessary. If everything is working, the deprecated updater can be removed: @@ -96,13 +101,13 @@ the cluster version is updated. Keep reading to learn how to customize the time. ## Quick Setup for New Linux Servers The [Install Script] is the fastest way to onboard new Linux servers with -a single command. However, it is also easy use `teleport-update` to setup +a single command. However, you may also use `teleport-update` to setup a Teleport agent manually. -Users of cloud-hosted Teleport Enterprise can install a fresh copy of Teleport -with managed updates already enabled using a single command. First, download a -copy of the [Teleport tarball] from the downloads page. Next, invoke -`teleport-update` to install the correct version for your cluster. +Users of cloud-hosted Teleport Enterprise can create a new installation of +Teleport using any version of the `teleport-update` binary. +First, copy of the [Teleport tarball] from the downloads page. +Next, invoke `teleport-update` to install the correct version for your cluster. ```code $ tar xf teleport-[version].tgz @@ -118,41 +123,43 @@ started via the `systemctl` command: $ sudo systemctl enable teleport --now ``` -## Step 1/4. Enable managed agent updates +## Configuring managed agent updates -For cloud-hosted Teleport Enterprise, managed updates are enabled by default. -The `autoupdate_version` resource is managed for you, and cannot be edited. +### Configuring roles -For self-hosted Teleport Enterprise, the `autoupdate_version` resource must be -created to enabled managed updates. +To configure managed updates in your cluster, you must have access to +the `autoupdate_config` and `autoupdate_version` resources. -Create a file called `autoupdate_version.yaml` containing: +1. Create a Teleport role that can manage these resources. No preset Teleport + roles provide this ability, so you will need to create one. -```yaml -kind: autoupdate_version -spec: - agents: - start_version: v17.2.0 - target_version: v17.2.1 - schedule: regular - strategy: halt-on-error - mode: enabled -``` + Create a file called `autoupdate-editor.yaml` with the following content: -- `start_version` is the version used to install new agents before their update window. -- `target_version` is the version that agents will be updated to during their update window, as well - as the version used to install new agents during and after their update windows. -- `schedule` is `regular` or `immediate`, where `immediate` forces an immediate update for all agents. -- `strategy` is `time-based` or `halt-on-error`. `halt-on-error` will ensure groups listed first - in `autoupdate_config` are updated before groups listed later in `autoupdate_config`. Note that - client-side errors are not detected automatically. Set `mode` to `suspended` to stop the rollout. -- `mode` is `enabled`, `disabled`, or `suspended`. + ```yaml + kind: role + version: v7 + metadata: + name: autoupdate-editor + spec: + allow: + rules: + - resources: ['autoupdate_config', 'autoupdate_version'] + verbs: ['create', 'read', 'update', 'delete'] + ``` -Run the following command: + Create the role resource: -```code -$ tctl create autoupdate_version.yaml -``` + ```code + $ tctl create autoupdate-editor.yaml + ``` + + (!docs/pages/includes/create-role-using-web.mdx!) + +1. Add the role to your Teleport user: + +(!docs/pages/includes/add-role-to-user.mdx role="autoupdate-editor"!) + +### Configuring the schedule For both cloud-hosted and self-hosted editions of Teleport, an update schedule may be set with the `autoupdate_config` resource. The default resource looks @@ -173,7 +180,7 @@ For cloud-hosted Teleport Enterprise, the `days` are not configurable for most customers, and the `start_hour` is defaulted to your selected maintenance window. For example, a user of cloud-hosted Teleport with a staging environment and a -production environment might create a schedule that looks like this: +production environment might create a custom schedule that looks like this: ```yaml kind: autoupdate_config @@ -183,14 +190,16 @@ spec: regular: - name: staging start_hour: 4 - wait_hours: 24 - name: production start_hour: 5 + wait_hours: 24 ``` This schedule would update agents in the `staging` group at 4 UTC, and then update the `production` group at 5 UTC the next day. The `production` group will not execute -update until the staging group has updated. +update until the staging group has updated. The `wait_hours` field sets a minimum +duration between groups, ensuring that `production` happens the day after `staging`, +and not one hour after. While failed installations will revert automatically on the client-side, @@ -209,6 +218,7 @@ kind: autoupdate_config spec: agents: strategy: time-based + maintenance_window_duration: 1h schedules: regular: - name: nyc @@ -218,99 +228,56 @@ spec: ``` With this strategy, updates to `sjc` may occur before `nyc`, depending on when -new versions become available. +new versions become available. The `maintenance_window_duration` restricts +updates to the specified duration after the `start_hour`. This ensures that +disruptions do not occur outside a known window. + +The time-based strategy does not support the `wait_days` option. To add agents to groups, run `teleport-update enable --group group-name`. You may execute `teleport-update enable` repeatedly to change the group (or other managed update settings). -### Configure a maintenance schedule - -To enable managed upgrades in your cluster, you must create a cluster -maintenance configuration. This configures a maintenance schedule for the -Teleport cluster that agents use to determine when to check for upgrades. - -1. Create a Teleport role that can manage cluster maintenance configurations - through the `cluster_maintenance_config` dynamic resource. No preset Teleport - roles provide this ability, so you will need to create one. - - Create a file called `cmc-editor.yaml` with the following content: - - ```yaml - kind: role - version: v7 - metadata: - name: cmc-editor - spec: - allow: - rules: - - resources: ['cluster_maintenance_config'] - verbs: ['create', 'read', 'update', 'delete'] - ``` - - Create the role resource: - - ```code - $ tctl create cmc-editor.yaml - ``` - - (!docs/pages/includes/create-role-using-web.mdx!) - -1. Add the role to your Teleport user: +### Setting the version -(!docs/pages/includes/add-role-to-user.mdx role="cmc-editor"!) - -1. Create a cluster maintenance config in a file called `cmc.yaml`. The - following example allows maintenance on Monday, Wednesday and Friday between - 02:00 and 03:00 UTC: - - (!docs/pages/includes/cluster-maintenance-config-spec.mdx!) - -1. Apply the manifest using `tctl`: - - ```code - $ tctl create cmc.yaml - maintenance window has been updated - ``` +For cloud-hosted Teleport Enterprise, managed updates are enabled by default. +The `autoupdate_version` resource is managed for you, and cannot be edited. -### [Optional] Assign the version served by the version server +For self-hosted Teleport Enterprise, the `autoupdate_version` resource must be +created and edited to enabled managed updates. -By default, the version server has a single `default` channel, serving the -version of the Teleport Proxy Service. If you want to override the default -version or add other channels you can use the `automatic_upgrades_channels` -field in the Proxy Service configuration file: +Create a file called `autoupdate_version.yaml` containing: ```yaml -proxy_service: - enabled: "yes" - automatic_upgrades_channels: - # Override the default version channel reachable at - # https:///v1/webapi/automaticupgrades/channel/default/version - default: - static_version: v14.2.1 - # Define a new version channel with a static version reachable at - # https:///v1/webapi/automaticupgrades/channel/m-static-channel/version - my-static-channel: - static_version: v14.2.0 - # Define a new version channel forwarding requests to an upstream version server - my-remote-channel: - forward_url: https://updates.releases.teleport.dev/v1/stable/cloud +kind: autoupdate_version +spec: + agents: + start_version: v17.2.0 + target_version: v17.2.1 + schedule: regular + mode: enabled ``` -You must ensure that all Proxy Service instances share the same -`automatic_upgrades_channels` configuration. If some Proxy Service instances are -configured differently, you will experience agents flickering between versions -as the version served is not consistent across instances. +This resource is used to deploy new versions of Teleport to your agents. +The `start_version` is the version used to install new agents before their +scheduled update time, while `target_version` is the version that agents +will be updated to according to the configured schedule. + +The `schedule` may be changed from `regular` to `immediate` to force all +agents to update to the `target_version` immediately. -If your Proxy Service public address is , -you can query the version server with the following command: +The `mode` is used to enable, disable, or suspend managed updates. +The `mode` may be set in both `autoupdate_version` or `autoupdate_config`, +such that `disabled` overrides `suspended`, which overrides `enabled` on either side. + +Run the following command to create or update the resource: ```code -$ curl "https:///v1/webapi/automaticupgrades/channel/default/version" -(=teleport.version=) +$ tctl create autoupdate_version.yaml ``` +## Migrating agents on Linux servers to managed updates -## Step 2/4. Find agents to enroll in managed updates +### Finding unmanaged agents Use the `tctl inventory ls` command to list connected agents along with their current version. Use the `--upgrader=none` flag to list agents that are not enrolled in managed @@ -324,7 +291,18 @@ Server ID Hostname Services Version Upgrader ... ``` -## Step 3/4. Enroll agents on Linux servers in managed updates +Use the `--upgrader=unit` flag to list agents that are enrolled in the outdated +updater and need to be configured to the next-generation updater: + +```code +$ tctl inventory ls --upgrader=unit +Server ID Hostname Services Version Upgrader +------------------------------------ ------------- -------- ------- -------- +00000000-0000-0000-0000-000000000000 ip-10-1-6-131 Node v14.4.5 unit +... +``` + +### Enrolling unmanaged agents 1. For each agent ID returned by the `tctl inventory ls` command, copy the ID and run the following `tctl` command to access the host via `tsh`: @@ -335,56 +313,23 @@ Server ID Hostname Services Version Upgrader $ tsh ssh "${USER?}@${HOST?}" ``` -1. Determine the Teleport version to install by querying the Teleport Proxy - Service. This way, the Teleport installation has the same major version as - the automatic updater. - - Replace with the name of your automatic update - channel. For cloud-hosted Teleport Enterprise accounts, this is always - `stable/cloud`: +1. Run `teleport-update enable` on each agent you would like + to enroll into managed updates: ```code - $ TELEPORT_VERSION="$(curl https:///v1/webapi/automaticupgrades/channel//version | sed 's/v//')" + $ sudo teleport-update enable ``` -1. Ensure that the Teleport repository is properly configured to use the - channel, and install the `teleport-ent-updater` - package. You must install `teleport-ent-updater` on each agent you would like - to enroll into managed updates: - - - +1. Confirm that the version of the `teleport` binary is the one you expect: ```code - $ curl (=teleport.teleport_install_script_url=) | bash -s ${TELEPORT_VERSION?} cloud + $ teleport version ``` - - - - 1. Follow the instructions in the Teleport [installation - guide](../installation.mdx#package-repositories) to install the `teleport` - binary on your Linux server for your package manager. - - 1. Using your package manager, install `teleport-ent-updater` on the - server where you installed `teleport`. For example: - - ```code - $ apt-get install -y teleport-ent-updater - ``` - - - - - The installation script detects the package manager on your Linux server and - uses it to install Teleport binaries. To customize your installation, learn - about the Teleport package repositories in the [installation - guide](../installation.mdx#linux). - -1. Confirm that the version of the `teleport` binary is the one you expect: +1. Remove the last-generation updater if present: ```code - $ teleport version + $ sudo apt remove teleport-ent-updater ```
@@ -398,26 +343,10 @@ $ sudo touch /etc/teleport-upgrade.d/schedule $ sudo chown /etc/teleport-upgrade.d/schedule ``` -
- -1. Verify that the upgrader can see your version endpoint by checking for - upgrades: +While `teleport-update` does not read this file, `teleport` will warn if it +cannot disable the last-generation updater using this file. - ```code - $ sudo teleport-upgrade dry-run - ``` - -1. You should see one of the following messages, depending on the target version - you are currently serving: - - ```text - no upgrades available (1.2.3 == 1.2.3) - an upgrade is available (1.2.3 -> 2.3.4) - ``` - - `teleport-upgrade` may display warnings about not having a valid upgrade - schedule. This is expected immediately after install as the maintenance - schedule might not be exported yet. + ## Step 4/4. Enroll Kubernetes agents in managed updates @@ -504,7 +433,7 @@ If the Teleport agent has not been automatically updating for several weeks, you can consult the updater logs to help troubleshoot the problem: ```code -$ journalctl -u teleport-upgrade +$ journalctl -u teleport-update ``` ### Troubleshooting managed agent upgrades on Kubernetes @@ -528,22 +457,10 @@ until the next reconciliation, you can trigger an event. ### Troubleshooting managed agent upgrades on Linux -1. If an agent is not automatically upgraded, you can invoke the upgrader +1. If an agent is not automatically updated, you can invoke the updater manually and look at its logs: ```code - $ sudo teleport-upgrade run - ``` - -1. To suspend managed updates, disable the systemd timer: - - ```code - $ sudo systemctl disable --now teleport-upgrade.timer - ``` - -1. To enable and start the systemd timer after suspending: - - ```code - $ sudo systemctl enable --now teleport-upgrade.timer + $ sudo teleport-update update --now ``` From 4007c90fa9110f3f097f0ad16b772d96cec553c2 Mon Sep 17 00:00:00 2001 From: Stephen Levine Date: Mon, 3 Feb 2025 14:28:43 -0500 Subject: [PATCH 04/11] remove roles --- .../pages/upgrading/agent-managed-updates.mdx | 37 ++----------------- 1 file changed, 4 insertions(+), 33 deletions(-) diff --git a/docs/pages/upgrading/agent-managed-updates.mdx b/docs/pages/upgrading/agent-managed-updates.mdx index ac501a6d959b4..3eebd4a0ed883 100644 --- a/docs/pages/upgrading/agent-managed-updates.mdx +++ b/docs/pages/upgrading/agent-managed-updates.mdx @@ -125,39 +125,10 @@ $ sudo systemctl enable teleport --now ## Configuring managed agent updates -### Configuring roles - To configure managed updates in your cluster, you must have access to -the `autoupdate_config` and `autoupdate_version` resources. - -1. Create a Teleport role that can manage these resources. No preset Teleport - roles provide this ability, so you will need to create one. - - Create a file called `autoupdate-editor.yaml` with the following content: - - ```yaml - kind: role - version: v7 - metadata: - name: autoupdate-editor - spec: - allow: - rules: - - resources: ['autoupdate_config', 'autoupdate_version'] - verbs: ['create', 'read', 'update', 'delete'] - ``` - - Create the role resource: - - ```code - $ tctl create autoupdate-editor.yaml - ``` - - (!docs/pages/includes/create-role-using-web.mdx!) - -1. Add the role to your Teleport user: - -(!docs/pages/includes/add-role-to-user.mdx role="autoupdate-editor"!) +the `autoupdate_config` and `autoupdate_version` resources. By default, +the `editor` role can modify both resources (self-hosted) or just +`autoupdate_config` (cloud-hosted). ### Configuring the schedule @@ -348,7 +319,7 @@ cannot disable the last-generation updater using this file. -## Step 4/4. Enroll Kubernetes agents in managed updates +## Enroll Kubernetes agents in managed updates This section assumes that the name of your `teleport-kube-agent` release is `teleport-agent`, and that you have installed it in the `teleport` namespace. From 61de3c2fad4477b682b8ca6546df86fcdaf3f96f Mon Sep 17 00:00:00 2001 From: Stephen Levine Date: Fri, 7 Feb 2025 14:14:30 -0500 Subject: [PATCH 05/11] wip --- docs/pages/upgrading/agent-managed-updates-v1.mdx | 2 +- docs/pages/upgrading/agent-managed-updates.mdx | 12 +++++++++--- 2 files changed, 10 insertions(+), 4 deletions(-) diff --git a/docs/pages/upgrading/agent-managed-updates-v1.mdx b/docs/pages/upgrading/agent-managed-updates-v1.mdx index d60b54e575e61..4994b07bd873f 100644 --- a/docs/pages/upgrading/agent-managed-updates-v1.mdx +++ b/docs/pages/upgrading/agent-managed-updates-v1.mdx @@ -9,7 +9,7 @@ currently supported but will eventually be deprecated. The original updater uses the `teleport-ent-updater` package and `cluster_maintenance_config` resource described in this document, while the -next-generation updater is a binary called `teleport-update` that is included +next-generation updater uses a binary called `teleport-update` that is included in the `teleport` package and configured by the `autoupdate_version` and `autoupdate_config` resources described in this document. diff --git a/docs/pages/upgrading/agent-managed-updates.mdx b/docs/pages/upgrading/agent-managed-updates.mdx index 3eebd4a0ed883..3f8e780d6e864 100644 --- a/docs/pages/upgrading/agent-managed-updates.mdx +++ b/docs/pages/upgrading/agent-managed-updates.mdx @@ -8,7 +8,7 @@ This document describes the next-generation (v2) Teleport Agent updater, which is currently in beta. The original updater uses the `teleport-ent-updater` package and -`cluster_maintenance_config` resource, while the next-generation updater is +`cluster_maintenance_config` resource, while the next-generation updater uses a binary called `teleport-update` that is included in the `teleport` package and configured by the `autoupdate_version` and `autoupdate_config` resources described in this document. @@ -64,7 +64,7 @@ is configured to automatically update the Teleport container. - (!docs/pages/includes/tctl-tsh-prerequisite.mdx!) - (!docs/pages/includes/tctl.mdx!) -## Quick Setup for Connected Linux Servers +## Quick setup for existing connected Linux servers Users of cloud-hosted Teleport Enterprise can enable managed updates on Linux servers that are already connected with a single command: @@ -94,11 +94,17 @@ back to manual updates or the original updater (if it has not been removed): $ sudo teleport-update uninstall ``` +If Teleport was installed via the apt/yum package, this will revert the +running version of Teleport back to the version provided by the package. +If Teleport was installed using `teleport-update` without the package, +**this command will remove Teleport entirely, leaving the system disconnected.** +Do not run `uninstall` without verifying your installation type. + For cloud-hosted Teleport Enterprise, updates will roll out automatically during the first chosen maintenance window that is at least 36 hours after the cluster version is updated. Keep reading to learn how to customize the time. -## Quick Setup for New Linux Servers +## Quick setup for new Linux servers The [Install Script] is the fastest way to onboard new Linux servers with a single command. However, you may also use `teleport-update` to setup From fe686bcbd76090dc6585822b04dcb5952c0d75df Mon Sep 17 00:00:00 2001 From: Stephen Levine Date: Sun, 9 Feb 2025 23:19:44 -0500 Subject: [PATCH 06/11] wip 4 --- docs/pages/installation.mdx | 1 + docs/pages/reference/cli/teleport-update.mdx | 571 ++++++++++++++++++ docs/pages/reference/resources.mdx | 220 ++++++- .../upgrading/agent-managed-updates-v1.mdx | 6 +- .../pages/upgrading/agent-managed-updates.mdx | 7 +- 5 files changed, 789 insertions(+), 16 deletions(-) create mode 100644 docs/pages/reference/cli/teleport-update.mdx diff --git a/docs/pages/installation.mdx b/docs/pages/installation.mdx index 502c8e01aac74..7e40fd145a397 100644 --- a/docs/pages/installation.mdx +++ b/docs/pages/installation.mdx @@ -9,6 +9,7 @@ tocDepth: 3 This guide shows you how to install Teleport binaries on your platform, including: - `teleport` +- `teleport-update` - `tsh` - `tctl` - `tbot` diff --git a/docs/pages/reference/cli/teleport-update.mdx b/docs/pages/reference/cli/teleport-update.mdx new file mode 100644 index 0000000000000..6ce8ebcb69ec3 --- /dev/null +++ b/docs/pages/reference/cli/teleport-update.mdx @@ -0,0 +1,571 @@ +--- +title: teleport-update CLI reference +description: Comprehensive reference of subcommands, flags, and arguments for the teleport-update CLI tool. +--- + +`tbot` is a CLI tool used with **Machine ID** that programatically issues and renews +short-lived certificates to any service account (e.g, a CI/CD server). + +The primary commands for `tbot` are as follows: + +| Command | Description | +| - | - | +| `tbot help` | Outputs guidance for using commands with `tbot`. | +| `tbot version` | Outputs the current version of the `tbot` binary. | +| `tbot configure` | Outputs a basic Machine ID client configuration file to be adjusted as needed. | +| `tbot start` | Starts the Machine ID client `tbot`, fetching and writing certificates to disk at a set interval. | +| `tbot init` | Initialize a certificate destination directory for writes from a separate bot user, configuring either file or POSIX ACL permissions. | +| `tbot db` | Connects to databases using native clients and queries database information. Functions as a wrapper for `tsh`, and requires `tsh` installation. | +| `tbot proxy` | Allows for access to Teleport resources on a cluster using TLS Routing. Functions as a wrapper for `tsh`, and requires `tsh` installation. | +| `tbot tpm identify` | Output identifying information related to the TPM (Trusted Platform Module) detected on the system. | + +## tbot db + +Connects to databases using native clients and queries database information. This is best used for testing and validation purposes; +most users will likely prefer to connect their own databases to a local proxy using `tbot proxy db`. + +Note that `tsh` must be installed to make use of this command. + +### Flags + +| Flag | Description | +|---------------------|----------------------------------------------------------------------------------------------------------| +| `-d/--debug` | Enable verbose logging to stderr. | +| `-c/--config` | Path to a Machine ID configuration file. Required if not using other required configuration flags. | +| `--destination-dir` | Path to the Machine ID destination dir that should be used for authentication. Required. | +| `--proxy-server` | The `host:port` of the Teleport Proxy Service to use to access resources. Required. | +| `--cluster` | The name of the cluster on which resources should be accessed. Extracted from the bot identity if unset. | + +All other flags and arguments are passed directly to `tsh db ...`, along +with authentication parameters to use the Machine ID identity to skip `tsh`'s +login steps. + +Note that certain CLI parameters, for example `--help`, may be captured by +`tbot` even if intended to be passed to the wrapped `tsh`. A `--` argument can +be used to ensure all following arguments are passed to `tsh` and ignored by +`tbot`. + +Additionally, be aware of the following limitations of `tbot db`: + - `tbot db connect` requires a `tbot db login` for certain database types, + like MySQL, so that additional connection parameters can be written to a + local configuration file. + - `tbot db env` is not fully supported. + +## tbot init + +Initializes a certificate destination directory for access from a separate bot +user. Allows for certificates to be written to disks other than a Machine ID +client, configuring either file or POSIX ACL permissions. + +Note that most use cases should instead use tbot's runtime ACL management by +specifying allowed reader users and groups in the +[destination configuration](../machine-id/configuration.mdx#directory). + +### Flags + +| Flag | Description | +|---------------------|--------------------------------------------------------------------------------------------------------------------| +| `-d/--debug` | Enable verbose logging to stderr. | +| `-c/--config` | Path to a Machine ID configuration file. | +| `--destination-dir` | Directory to write short-lived machine certificates to. | +| `--owner` | Defines the Linux `user:group` owner of `--destination-dir`. Defaults to the Linux user running `tbot` if unspecified. | +| `--bot-user` | Enables POSIX ACLs and defines the Linux user that can read/write short-lived certificates to `--destination-dir`. | +| `--reader-user` | Enables POSIX ACLs and defines the Linux user that will read short-lived certificates from `--destination-dir`. | +| `--init-dir` | If using a config file and multiple destinations are configured, controls which destination dir to configure. | +| `--clean` | If set, remove unexpected files and directories from the destination. | +| `--log-format` | Controls the format of output logs. Can be `json` or `text`. Defaults to `text`. | + +### Examples + +**Example using file permissions.** + +The following command highlights how to set permissions with `tbot` through Linux groups, using the user and group `jenkins:jenkins`. +If running `tbot` as the Linux user `root`, use the following invocation of +`tbot init` to initialize the short-lived certificate directory +`/opt/machine-id` with owner `jenkins:jenkins`. + +```code +$ tbot init \ + --destination-dir=/opt/machine-id \ + --owner=jenkins:jenkins +``` + +**Example using POSIX ACLs.** + +If running `tbot` as the Linux user `teleport`, use the following invocation of +`tbot init` to initialize the short-lived certificate directory +`/opt/machine-id` with owner `teleport:teleport` but allow `jenkins` to read +from `/opt/machine-id`. + +```code +$ tbot init \ + --destination-dir=/opt/machine-id \ + --bot-user=teleport \ + --reader-user=jenkins +``` + +## tbot proxy + +Allows for access to Teleport resources via a local TLS proxy in TLS Routing mode. +The `tbot proxy` command acts as a wrapper for `tsh proxy` to provide local proxy functionality for various protocols. + +Note that `tsh` must be installed to make use of this command. + +Consider using one of the following dedicated tunnel modes where possible: +- [`tbot start application-tunnel`](#tbot-start-application-tunnel) +- [`tbot start database-tunnel`](#tbot-start-database-tunnel) + +### Flags + +| Flag | Description | +|---------------------|----------------------------------------------------------------------------------------------------------| +| `-d/--debug` | Enable verbose logging to stderr. | +| `-c/--config` | Path to a Machine ID configuration file. Required if not using other required configuration flags. | +| `--destination-dir` | Path to the Machine ID destination dir that should be used for authentication. Required. | +| `--proxy-server` | The `host:port` of the Teleport Proxy Service through which resources will be accessed. Required. | +| `--cluster` | The name of the cluster on which resources should be accessed. Extracted from the bot identity if unset. | + +All other flags and arguments are passed directly to `tsh proxy ...`, along +with authentication parameters to use the Machine ID identity to skip `tsh`'s +login step. + +Additionally, the following should be noted: + +- Certain CLI parameters, for example `--help`, may be captured by + `tbot` even if intended to be passed to the wrapped `tsh`. A `--` argument can + be used to ensure all following arguments are passed to `tsh` and ignored by + `tbot` +- If no configuration file is provided, `tbot` will apply a sample configuration based on provided CLI flags. + For this reason, it is recommended that settings are explicitly applied to a configuration file in production. + +### Examples + +**Example using OpenSSH** + +The following command forwards standard input and output over a proxy suitable for use as an OpenSSH `ProxyCommand` for SSH access: + +```code +$ tbot proxy --destination-dir=./tbot-user --proxy-server=proxy.example.com:3080 ssh alice@node:3022 +``` + + In this case: + - `alice` is the remote username + - `node` is the Teleport Node name + - `3022` is the remote SSH port, which is `3022` for Nodes running the Teleport + SSH service. + +**Example using a Teleport-protected database** + +The following example opens a local proxy server to the given database. Your database client +must still be configured with client TLS certificates: + +```code +$ tbot proxy --destination-dir=./tbot-user --proxy-server=proxy.example.com:3080 db --port=1234 example +``` + +In this case: + - `example` is the name of the database server as it exists in Teleport + - `1234` is an arbitrary port on which to run the proxy + +Though not recommended, to avoid the need for additional client authentication, +the `--tunnel` flag may be used to perform authentication at the local proxy +rather than within your client: + +```code +$ tbot proxy --destination-dir=./tbot-user --proxy-server=proxy.example.com:3080 db --tunnel --port=1234 example +``` + +Note that this decreases security: + - It allows any user on the system to access the database via `localhost`. + - Your connection to the database will be unencrypted until it reaches the + `tbot` proxy running on `localhost`. + +Refer to the [database guide](../../enroll-resources/machine-id/access-guides/databases.mdx) for more information on +using database proxies. + +### Flags + +| Flag | Description | +|----------------------|------------------------------------------------------------------------------------------------| +| `-d/--debug` | Enable verbose logging to stderr. | +| `-c/--config` | Path to a configuration file. | +| `-a/--auth-server` | Address of the Teleport Auth Service. Prefer using --proxy-server where possible | +| `--proxy-server` | Address of the Teleport Proxy Server. | +| `--token` | A bot join token, if attempting to onboard a new bot; used on first connect. Can also be an absolute path to a file containing the token. | +| `--ca-pin` | CA pin to validate the Teleport Auth Service; used on first connect. | +| `--data-dir` | Directory to store internal bot data. In production environments access to this directory should be limited only to an isolated linux user as an owner with `0600` permissions. | +| `--destination-dir` | Directory to write short-lived machine certificates. | +| `--certificate-ttl` | TTL of short-lived machine certificates. | +| `--renewal-interval` | Interval at which short-lived certificates are renewed; must be less than the certificate TTL. | +| `--join-method` | Method to use to join the cluster. Can be `token` or `iam`. | +| `--oneshot` | If set, quit after the first renewal. | + +## tbot configure + +The `tbot configure` command is used to convert a `tbot start` CLI call into a +YAML configuration file. It supports all the same subcommands and flags as +[`tbot start`](#tbot-start), but prints an equivalent configuration instead of +starting a bot. + +For example, consider this `tbot start identity` CLI call: +```code +$ tbot start identity \ + --destination=./example \ + --join-method=token \ + --token=foo \ + --proxy-server=teleport.example.com:443 +``` + +To convert this CLI command into a configuration file, replace `tbot start` with +`tbot configure`: +```code +$ tbot configure identity \ + --destination=./example \ + --join-method=token \ + --token=foo \ + --proxy-server=teleport.example.com:443 +``` + +An equivalent YAML configuration will be printed, which can be written to a +file. The client can then be started using this configuration file: + +```code +$ tbot configure identity \ + --destination=./example \ + --join-method=token \ + --token=foo \ + --proxy-server=teleport.example.com:443 > tbot.yaml +$ tbot start -c tbot.yaml +``` + +### Flags + +This subcommand supports one additional flag beyond its `tbot start` equivalent: + +| Flag | Description | +|---------------|-------------| +| `-o/--output` | If set, writes the generated configuration to the given file path instead of stdout. | + +## tbot start + +The `tbot start` family of commands starts the Machine ID client in various +modes, depending on the type of resources to be accessed: + +- [`tbot start legacy`](#tbot-start-legacy): Starts with a YAML configuration file or in legacy output mode +- [`tbot start identity`](#tbot-start-identity): Starts with an identity output for SSH and Teleport API access +- [`tbot start database`](#tbot-start-database): Starts with a database credential output +- [`tbot start kubernetes`](#tbot-start-kubernetes): Starts with a Kubernetes output +- [`tbot start application`](#tbot-start-application): Starts with an application TLS credential output +- [`tbot start application-tunnel`](#tbot-start-application-tunnel): Starts a local application tunnel +- [`tbot start database-tunnel`](#tbot-start-database-tunnel): Starts a local database tunnel +- [`tbot start spiffe-svid`](#tbot-start-spiffe-svid): Starts a Workload ID SPIFFE SVID output + +If only `tbot start` is specified, `tbot start legacy` will be inferred by +default; this is the correct mode for use with a YAML configuration file. + +### Common Start Flags + +These flags are available to all `tbot start` commands. Note that +`tbot start legacy` supports slightly different options, so refer to its +specific section for details when using a YAML config file or legacy output. + +| Flag | Description | +|----------------------|-------------| +| `-d/--debug` | Enable verbose logging to stderr. | +| `--[no-]fips` | Whether to run tbot in FIPS compliance mode. This requires the FIPS `tbot` binary. | +| `--log-format` | Controls the format of output logs. Can be `json` or `text`. Defaults to `text`. | +| `-a/--auth-server` | Address of the Teleport Auth Service. Prefer using `--proxy-server` where possible. | +| `--proxy-server` | Address of the Teleport Proxy Server. | +| `--token` | A bot join token or path to file with token value, if attempting to onboard a new bot; used on first connect. | +| `--ca-pin` | CA pin to validate the Teleport Auth Service; used on first connect. | +| `--certificate-ttl` | TTL of short-lived machine certificates. | +| `--renewal-interval` | Interval at which short-lived certificates are renewed; must be less than the certificate TTL. | +| `--join-method` | Method to use to join the cluster. One of: `azure`, `circleci`, `gcp`, `github`, `gitlab`, `iam`, `kubernetes`, `spacelift`, `token`, `tpm`, `terraform_cloud` | +| `--[no-]oneshot` | If set, quit after the first renewal. | +| `--diag-addr` | If set and the bot is in debug mode, a diagnostics service will listen on specified address. | +| `--storage` | A destination URI for tbot's internal storage, e.g. `file:///foo/bar`. See [Destination URIs](#destination-uris) for more info. | + +## tbot start legacy + +Starts the Machine ID client `tbot`, fetching and writing certificates to disk +at a set interval. This command either starts from a configuration file if `-c` +is specified, or starts with a default, legacy-compatible identity output. + +This is the default `tbot start` subcommand if no other command is specified. +Unless using a configuration file, consider using `tbot start identity` or +another dedicated mode instead. + +### Flags + +| Flag | Description | +|----------------------|------------------------------------------------------------------------------------------------| +| `-d/--debug` | Enable verbose logging to stderr. | +| `-c/--config` | Path to a Machine ID configuration file. | +| `--[no-]fips` | Whether to run tbot in FIPS compliance mode. This requires the FIPS `tbot` binary. | +| `-a/--auth-server` | Address of the Teleport Auth Service. Prefer using --proxy-server where possible | +| `--proxy-server` | Address of the Teleport Proxy Server. | +| `--token` | A bot join token, if attempting to onboard a new bot; used on first connect. Can also be an absolute path to a file containing the token. | +| `--ca-pin` | CA pin to validate the Teleport Auth Service; used on first connect. | +| `--data-dir` | Directory to store internal bot data. In production environments access to this directory should be limited only to an isolated linux user as an owner with `0600` permissions. | +| `--destination-dir` | Directory to write short-lived machine certificates. | +| `--certificate-ttl` | TTL of short-lived machine certificates. | +| `--renewal-interval` | Interval at which short-lived certificates are renewed; must be less than the certificate TTL. | +| `--join-method` | Method to use to join the cluster. Can be `token`, `azure`, `circleci`, `gcp`, `github`, `gitlab` or `iam`. | +| `--oneshot` | If set, quit after the first renewal. | +| `--log-format` | Controls the format of output logs. Can be `json` or `text`. Defaults to `text`. | + +### Examples + + + +```code +$ tbot start \ + --data-dir=/var/lib/teleport/bot \ + --destination-dir=/opt/machine-id \ + --token=00000000000000000000000000000000 \ + --join-method=token \ + --ca-pin=sha256:1111111111111111111111111111111111111111111111111111111111111111 \ + --proxy-server=example.teleport.sh:443 +``` + + + + +```code +$ tbot start \ + --data-dir=/var/lib/teleport/bot \ + --destination-dir=/opt/machine-id \ + --token=00000000000000000000000000000000 \ + --join-method=token \ + --ca-pin=sha256:1111111111111111111111111111111111111111111111111111111111111111 \ + --proxy-server=teleport.example.com:443 +``` + + + + +## tbot start identity + +Starts the Machine ID client `tbot` with an identity output, fetching and +writing certificates at a regular interval to the output specified with +`--destination`. + +```code +$ tbot start identity --destination=DESTINATION [] +``` + +### Flags + +In addition to the [common `tbot start` flags](#common-start-flags), this +command supports these additional flags: + +| Flag | Description | +|----------------------|-------------| +| `--destination` | A destination URI, such as file:///foo/bar. See [Destination URIs](#destination-uris) for more info. Required. | +| `--reader-user` | An additional user name or UID that should be allowed by ACLs to read this destination. Only valid for file destinations on Linux. | +| `--reader-group` | An additional group name or GID that should be allowed by ACLs to read this destination. Only valid for file destinations on Linux. | +| `--cluster` | The name of a specific cluster for which to issue an identity if using a leaf cluster | + +### Examples + +To start a bot with a one-time-use join token: + +```code +$ tbot start identity \ + --proxy-server=example.teleport.sh:443 \ + --join-type=token \ + --token=TOKEN \ + --destination=./tbot-user \ + --storage=./tbot-data +``` + +## tbot start database + +Starts the Machine ID client `tbot` with a database output, fetching and writing +database certificates at a regular interval to the output specified with +`--destination`. + +```code +$ tbot start database --destination=DESTINATION --service=SERVICE --username=USERNAME --database=DATABASE [] +``` + +### Flags + +In addition to the [common `tbot start` flags](#common-start-flags), this +command supports these additional flags: + +| Flag | Description | +|----------------------|-------------| +| `--destination` | A destination URI, such as file:///foo/bar. See [Destination URIs](#destination-uris) for more info. Required. | +| `--reader-user` | An additional user name or UID that should be allowed by ACLs to read this destination. Only valid for file destinations on Linux. | +| `--reader-group` | An additional group name or GID that should be allowed by ACLs to read this destination. Only valid for file destinations on Linux. | +| `--format` | The database output format if necessary | +| `--service` | The service name of the database as it appears in Teleport and `tsh db ls`. Required. | +| `--username` | The database user name. The bot user must have permission to connect as this user. Required. | +| `--database` | The name of the database available in the requested service. Required. | + +## tbot start kubernetes + +Starts the Machine ID client `tbot` with a Kubernetes output, fetching and +writing Kubernetes credentials and a `kubeconfig.yaml` at a regular interval to +the output specified with `--destination`. + +```code +$ tbot start kubernetes --destination=DESTINATION --kubernetes-cluster=KUBERNETES-CLUSTER [] +``` + +### Flags + +In addition to the [common `tbot start` flags](#common-start-flags), this +command supports these additional flags: + +| Flag | Description | +|------------------------|-------------| +| `--destination` | A destination URI, such as file:///foo/bar. See [Destination URIs](#destination-uris) for more info. Required. | +| `--reader-user` | An additional user name or UID that should be allowed by ACLs to read this destination. Only valid for file destinations on Linux. | +| `--reader-group` | An additional group name or GID that should be allowed by ACLs to read this destination. Only valid for file destinations on Linux. | +| `--kubernetes-cluster` | The name of the Kubernetes cluster in Teleport for which to fetch credentials | + +## tbot start application + +Starts the Machine ID client `tbot` with an application output, fetching and +writing application TLS credentials at a regular interval to the output +specified with `--destination`. + +```code +$ tbot start application --destination=DESTINATION --app=APP [] +``` + +### Flags + +In addition to the [common `tbot start` flags](#common-start-flags), this +command supports these additional flags: + +| Flag | Description | +|----------------------|-------------| +| `--destination` | A destination URI, such as file:///foo/bar. See [Destination URIs](#destination-uris) for more info. Required. | +| `--reader-user` | An additional user name or UID that should be allowed by ACLs to read this destination. Only valid for file destinations on Linux. | +| `--reader-group` | An additional group name or GID that should be allowed by ACLs to read this destination. Only valid for file destinations on Linux. | +| `--app` | The name of the app in Teleport | + +## tbot start application-tunnel + +Starts the Machine ID client with a local tunnel to a particular application. +This tunnel will run continuously and automatically refresh its certificates. + +Note that this tunnel will be unencrypted. Be wary of the selected listen +address, and prefer to use `localhost` or an equivalent loopback interface +address when possible. Additionally, note that all users on the local system +will be able to access this socket. + +If you wish to tunnel multiple apps from one bot instance, use +`tbot configure application-tunnel ...` to generate a configuration file and +repeat the generated block under `services:` as desired. + +This tunneling method is preferred over the legacy [`tbot proxy app`](#tbot-proxy). + +```code +$ tbot start application-tunnel --listen=LISTEN --app=APP [] +``` + +### Flags + +| Flag | Description | +|------------|-------------| +| `--listen` | A socket URI to listen on, e.g. `tcp://localhost:1234`. Required. | +| `--app` | The name of the app in Teleport | + +## tbot start database-tunnel + +Starts the Machine ID client with a local tunnel to a particular database. +This tunnel will run continuously and automatically refresh its certificates. + +Note that this tunnel will be unencrypted. Be wary of the selected listen +address, and prefer to use `localhost` or an equivalent loopback interface +address when possible. Additionally, note that all users on the local system +will be able to access this socket. + +If you wish to tunnel multiple databases from one bot instance, use +`tbot configure database-tunnel ...` to generate a configuration file and repeat +the generated block under `services:` as desired. + +This tunneling method is preferred over the legacy +[`tbot proxy db`](#tbot-proxy), and is roughly equivalent to +`tbot proxy db --tunnel`. + +```code +$ tbot start database-tunnel --listen=LISTEN --service=SERVICE --username=USERNAME --database=DATABASE [] +``` + +### Flags + +In addition to the [common `tbot start` flags](#common-start-flags), this +command supports these additional flags: + +| Flag | Description | +|--------------|-------------| +| `--listen` | A socket URI to listen on, e.g. `tcp://localhost:1234`. Required. | +| `--service` | The service name of the database as it appears in Teleport and `tsh db ls`. Required. | +| `--username` | The database user name. The bot user must have permission to connect as this user. Required. | +| `--database` | The name of the database available in the requested service. Required. | + +## tbot start spiffe-svid + +### Flags + +In addition to the [common `tbot start` flags](#common-start-flags), this +command supports these additional flags: + +| Flag | Description | +|----------------------|-------------| +| `--destination` | A destination URI, such as file:///foo/bar. See [Destination URIs](#destination-uris) for more info. Required. | +| `--reader-user` | An additional user name or UID that should be allowed by ACLs to read this destination. Only valid for file destinations on Linux. | +| `--reader-group` | An additional group name or GID that should be allowed by ACLs to read this destination. Only valid for file destinations on Linux. | +| `--[no-]include-federated-trust-bundles` | If set, include federated trust bundles in the output | +| `--svid-path` | A SPIFFE ID to request, prefixed with '/'. Required. | +| `--svid-hint` | An optional hint for consumers of the SVID to aid in identification | +| `--dns-san` | A DNS name that should be included in the SVID. Repeatable. | +| `--ip-san` | An IP address that should be included in the SVID. Repeatable. | + +## tbot install systemd + +Generates and installs a systemd unit file for a specific tbot configuration. + +### Flags + +| Flag | Description | +|-----------------------|----------------------------------------------------------------------------------------------------------------------------------| +| `-d/--debug` | Enable verbose logging to stderr. | +| `-c/--config` | Path to a configuration file. | +| `--write ` | Write the systemd unit file. If not specified, this command runs in a dry-run mode that outputs the generated content to stdout. | +| `--systemd-directory` | Path to the directory that the systemd unit file should be written. Defaults to '/etc/systemd/system'. | +| `--force` | Overwrite existing systemd unit file if present. | +| `--name` | Name for the systemd unit. Defaults to 'tbot'. | +| `--user` | The user that the service should run as. Defaults to 'teleport'. | +| `--group` | The group that the service should run as. Defaults to 'teleport'. | + +### Examples + +```code +$ tbot install systemd \ + --config=/etc/tbot.yaml \ + --write +``` + +## Destination URIs + +Many `tbot start` subcommands accept destination URIs via the `--storage` and +`--destination` flags. + +| Protocol | Description | +|------------------------|-------------| +| `file://` | A local directory destination, such as `file:///foo/bar/` | +| `memory://` | An in-memory destination. Useful for internal bot storage if no persistence is required. | +| `kubernetes-secret://` | A Kubernetes secret destination, such as `kubernetes-secret:///my-secret` | + +Plain file paths are also be accepted with no `file://` prefix; these will be +treated as directory outputs. + +Note that `tbot start legacy` only supports directory output destinations via +the `--destination-dir` flag, though it does support URIs for `--storage`. All +other `tbot start` subcommands accept these URIs where relevant. diff --git a/docs/pages/reference/resources.mdx b/docs/pages/reference/resources.mdx index 8dc55641b2202..3aa0a33c080e8 100644 --- a/docs/pages/reference/resources.mdx +++ b/docs/pages/reference/resources.mdx @@ -212,7 +212,14 @@ spec: ## Cluster maintenance config -Global configuration options for the agents enrolled into automatic updates. +Global configuration options for the agents enrolled into automatic updates (v1). + + +`cluster_maintenance_config` configures the original (v1) Teleport Agent updater, +which is currently supported but will eventually be deprecated. +The `autoupdate_config` and `autoupdate_version` resources below configure the +next-generation (v2) Teleport updater. + (!docs/pages/includes/cluster-maintenance-config-spec.mdx!) @@ -331,34 +338,231 @@ Find out more on the ## Auto-update config -Configuration options for managed updates for Teleport client tools. +Configuration options for Teleport agent and client tools Managed Updates (v2). + + +The `autoupdate_config` and `autoupdate_version` resources configure the both the +next-generation (v2) Teleport updater and original (v1) Teleport Agent updater. +`cluster_maintenance_config` above configures the original (v1) Teleport Agent updater, +which is currently supported but will eventually be deprecated. + ```yaml kind: autoupdate_config metadata: name: autoupdate-config spec: + agents: + # mode allows users to enable, disable, or suspend agent updates at the + # cluster level. Disable agent automatic updates only if self-managed + # updates are in place. This value may also be set in autoupdate_version. + # If set in both places, disabled overrides suspended, which overrides enabled. + # Possible values: "enabled", "disabled", "suspended" + # Default: "disabled" (unless specified in autoupdate_version) + mode: enabled + + # strategy used to roll out updates to agents. + # The halt-on-error strategy ensures that groups earlier in the schedule are + # given the opportunity to update to the target_version before groups that are + # later in the schedule. (Currently, the schedule must be stopped manually by + # setting the mode to "suspended" or "disabled". In the future, errors will be + # detected automatically). + # The time-based strategy ensure that each group updates within a defined + # time window, with no dependence between groups. + # Possible values: "halt-on-error" or "time-based" + # Default: "halt-on-error" + strategy: halt-on-error + + # maintenance_window_duration configures the duration after the start_hour + # when updates may occur. Only valid for the time-based strategy. + # maintenance_window_duration: 1h + + # schedules define groups of agents with different update times. + # Currently, only the regular schedule is configurable. + schedules: + regular: + + # name of each group, configured locally via "teleport-update enable --group" + - name: staging + + # start_hour of the update, in UTC + start_hour: 4 + + # days that the update may occur on + # Days are not configurable for most Enterprise cloud-hosted users. + # Possible values: "Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun", and "*" + # Default: [ "Mon", "Tue", "Wed", "Thu" ] + days: [ "Mon", "Tue", "Wed", "Thu" ] + + - name: production + start_hour: 5 + + # wait_hours ensures that the group executes at least a specific number of hours + # after the previous group. Only valid for the halt-on-error schedule. + # Default: 0 + wait_hours: 24 + tools: - # tools mode allows users to enable or disable client tool updates at the + # mode allows users to enable or disable client tool updates at the # cluster level. Disable client tool automatic updates only if self-managed # updates are in place. - mode: enabled|disabled + # Possible values: "enabled" or "disabled" + # Default: "disabled" + mode: enabled ``` -See [Teleport Client Tool Automatic Updates](../upgrading/client-tools-autoupdate.mdx) for more details. +See [Teleport Client Tool Managed Updates](../upgrading/client-tools-autoupdate.mdx) and +[Teleport Agent Managed Updates](../upgrading/agent-managed-updates.mdx) for more details. ## Auto-update version -Allows cluster administrators to manage the version of client tools that must be installed after logging into the cluster. +Allows cluster administrators to manage versions used for agent and client tools Managed Updates. + + +The `autoupdate_config` and `autoupdate_version` resources configure the +next-generation (v2) Teleport updater. +`cluster_maintenance_config` above configures the original (v1) Teleport Agent updater, +which is currently supported but will eventually be deprecated. + + +This resource is not editable for cloud-managed Teleport Enterprise to ensure that all of +your clients receive security patches and remain compatible with your cluster. ```yaml kind: autoupdate_version metadata: name: autoupdate-version spec: + agents: + # start_version is the version used to install new agents before their + # group's scheduled update time. Agents never update to the start_version + # automatically, but may be required to via "teleport-update update --now". + start_version: v17.2.0 + + # target_version is the version that agents update to during their group's + # scheduled update time. New agents also use this version after their group's + # scheduled update time. + target_version: v17.2.1 + + # schedule used to roll out updates. + # The regular schedule is defined in the autoupdate_config resource. + # The immediate schedule updates all agents to target_version immediately. + # Possible values: "regular" or "immediate" + # Default: "regular" + schedule: regular + + # mode allows users to enable, disable, or suspend agent updates at the + # cluster level. Disable agent automatic updates only if self-managed + # updates are in place. This value may also be set in autoupdate_config. + # If set in both places, disabled overrides suspended, which overrides enabled. + # Possible values: "enabled", "disabled", "suspended" + # Default: "disabled" (unless specified in autoupdate_config) + mode: enabled + tools: # target_version is the semver version of client tools the cluster will advertise. - target_version: X.Y.Z + # Client tools such as tsh and tctl will update to this version at login if the + # mode set in autoupdate_config is set to enabled. + # Default: cluster version + target_version: v17.2.1 +``` + +See [Teleport Client Tool Managed Updates](../upgrading/client-tools-autoupdate.mdx) and +[Teleport Agent Managed Updates](../upgrading/agent-managed-updates.mdx) for more details. + +## Auto-update agent rollout + +Allows cluster administrators to view the current agent rollout for Teleport Agent Managed Updates (v2). + +This resource should not be edited by humans. + +```yaml +kind: autoupdate_agent_rollout +metadata: + name: autoupdate-agent-rollout +spec: + # start_version is the version used to install new agents before their + # group's scheduled update time. Agents never update to the start_version + # automatically, but may be required to via "teleport-update update --now". + start_version: v17.2.0 + + # target_version is the version that agents update to during their group's + # scheduled update time. New agents also use this version after their group's + # scheduled update time. + target_version: v17.2.1 + + # schedule used to roll out updates. + # The regular schedule is defined in the autoupdate_config resource. + # The immediate schedule updates all agents to target_version immediately. + # Possible values: "regular" or "immediate" + schedule: regular + + # autoupdate_mode allows users to enable, disable, or suspend agent updates at the + # cluster level. Disable agent automatic updates only if self-managed + # updates are in place. This value may also be set in autoupdate_config. + # If set in both places, disabled overrides suspended, which overrides enabled. + # Possible values: "enabled", "disabled", "suspended" + autoupdate_mode: enabled + + # strategy used to roll out updates to agents. + # The halt-on-error strategy ensures that groups earlier in the schedule are + # given the opportunity to update to the target_version before groups that are + # later in the schedule. (Currently, the schedule must be stopped manually by + # setting the mode to "suspended" or "disabled". In the future, errors will be + # detected automatically). + # The time-based strategy ensure that each group updates within a defined + # time window, with no dependence between groups. + # Possible values: "halt-on-error" or "time-based" + # Default: "halt-on-error" + strategy: halt-on-error + + # maintenance_window_duration configures the duration after the start_hour + # when updates may occur. Only valid for the time-based strategy. + # maintenance_window_duration: 1h + +status: + + # groups contains the status for each group in the currently executing schedule. + groups: + + # name of each group, configured locally via "teleport-update enable --group" + - name: staging + + # start_time of the group + start_time: 0001-01-01T00:00:00Z + + # state of the group + # Possible values: unstarted, active, done, rolledback + state: active + + # last_update_time of this group's status + last_update_time: 0001-01-01T00:00:00Z + + # last_update_reason of this group's status + last_update_reason: "new version" + + # days that the update may occur on, from autoupdate_config + # Possible values: "Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun", and "*" + config_days: [ "Mon", "Tue", "Wed", "Thu" ] + + # start_hour of the update, in UTC, from autoupdate_config + config_start_hour: 4 + + - name: production + + # ... + + # config_wait_hours is specific number of hours after the previous group that this + # group may execute after, from autoupdate_config. + config_wait_hours: 24 + + # start_time of the rollout + start_time: 0001-01-01T00:00:00Z + + # state of the entire rollout + # Possible values: unstarted, active, done, rolledback + state: active + ``` -See [Teleport Client Tool Automatic Updates](../upgrading/client-tools-autoupdate.mdx) for more details. \ No newline at end of file +See [Teleport Agent Managed Updates](../upgrading/agent-managed-updates.mdx) for more details. diff --git a/docs/pages/upgrading/agent-managed-updates-v1.mdx b/docs/pages/upgrading/agent-managed-updates-v1.mdx index 4994b07bd873f..90c8db2dca77b 100644 --- a/docs/pages/upgrading/agent-managed-updates-v1.mdx +++ b/docs/pages/upgrading/agent-managed-updates-v1.mdx @@ -1,17 +1,18 @@ --- -title: Managed Agent Updates (v1) +title: Teleport Managed Agent Updates (v1) description: Describes how to set up managed agent updates using the original updater. --- This document describes the original (v1) Teleport Agent updater, which is currently supported but will eventually be deprecated. + The original updater uses the `teleport-ent-updater` package and `cluster_maintenance_config` resource described in this document, while the next-generation updater uses a binary called `teleport-update` that is included in the `teleport` package and configured by the `autoupdate_version` and -`autoupdate_config` resources described in this document. +`autoupdate_config` resources. Please consider using the next-generation updater, which is distributed with all versions of Teleport and provides a simpler, more flexible, and more reliable @@ -19,7 +20,6 @@ update experience compared to the original updater. For details about the next-generation updater, see [Managed Updates for Agents (v2)](./agent-managed-updates.mdx). - On cloud-hosted Teleport Enterprise accounts, users must set up managed agent updates to ensure that the version of Teleport running on agents remains diff --git a/docs/pages/upgrading/agent-managed-updates.mdx b/docs/pages/upgrading/agent-managed-updates.mdx index 3f8e780d6e864..30eff6680147c 100644 --- a/docs/pages/upgrading/agent-managed-updates.mdx +++ b/docs/pages/upgrading/agent-managed-updates.mdx @@ -1,11 +1,12 @@ --- -title: Managed Agent Updates (v2) +title: Teleport Managed Agent Updates (v2) description: Describes how to set up managed agent updates using the next-generation updater. --- This document describes the next-generation (v2) Teleport Agent updater, which is currently in beta. + The original updater uses the `teleport-ent-updater` package and `cluster_maintenance_config` resource, while the next-generation updater uses @@ -19,7 +20,6 @@ update experience compared to the original updater. For details about the original updater, see [Managed Updates for Agents (v1)](./agent-managed-updates-v1.mdx). - On cloud-hosted Teleport Enterprise accounts, users must set up managed agent updates to ensure that the version of Teleport running on agents remains @@ -96,9 +96,6 @@ $ sudo teleport-update uninstall If Teleport was installed via the apt/yum package, this will revert the running version of Teleport back to the version provided by the package. -If Teleport was installed using `teleport-update` without the package, -**this command will remove Teleport entirely, leaving the system disconnected.** -Do not run `uninstall` without verifying your installation type. For cloud-hosted Teleport Enterprise, updates will roll out automatically during the first chosen maintenance window that is at least 36 hours after From b078d49c6d41c39ca0d7cf8ee7dce77993241d1c Mon Sep 17 00:00:00 2001 From: Stephen Levine Date: Mon, 10 Feb 2025 20:57:53 -0500 Subject: [PATCH 07/11] wip 5 --- docs/pages/installation.mdx | 21 ++++---- .../upgrading/agent-managed-updates-v1.mdx | 27 ++++++---- .../pages/upgrading/agent-managed-updates.mdx | 50 +++++++++++-------- 3 files changed, 60 insertions(+), 38 deletions(-) diff --git a/docs/pages/installation.mdx b/docs/pages/installation.mdx index 7e40fd145a397..92a1eaac20ddf 100644 --- a/docs/pages/installation.mdx +++ b/docs/pages/installation.mdx @@ -58,7 +58,7 @@ Teleport maintains DEB and RPM package repositories for different operating systems, platforms, and Teleport versions. A server that installs Teleport from a DEB or RPM package must have systemd installed. You can also download TAR archives containing Teleport binaries. All installations include `teleport`, -`tsh`, `tctl`, `fdpass-teleport` and `tbot`. +`teleport-update`, `tsh`, `tctl`, `fdpass-teleport` and `tbot`. ### Recommended installation steps @@ -320,17 +320,16 @@ repositories. -### Downloading packages and TAR archives (self-hosted only) +### Downloading packages and TAR archives Teleport maintains TAR archives as well as DEB and RPM packages for Linux-compatible binaries at `https://cdn.teleport.dev`. This section explains how to install Teleport by manually downloading a release. -It is not possible to install the automatic agent updater using this method, so -using packages and TAR archives is only available for users who self-hosted -Teleport. Teleport Cloud customers must use the [one-line installation -script](#one-line-installation-script) or manually install Teleport from a -[package repository](#package-repositories) in order to install the updater. +The original (v1) Teleport updater is not compatible with this method. +If you use cloud-hosted Teleport, you must use `teleport-update` to manage +your Teleport installation. We recommend using the [one-line installation +script](#one-line-installation-script). 1. In your terminal, assign environment variables that you will use to download your intended archive. @@ -376,7 +375,7 @@ script](#one-line-installation-script) or manually install Teleport from a $ shasum --check -a 256 ${TELEPORT_PKG?}-v${TELEPORT_VERSION?}-linux-${SYSTEM_ARCH?}-bin.tar.gz $ tar -xvf ${TELEPORT_PKG?}-v${TELEPORT_VERSION?}-linux-${SYSTEM_ARCH?}-bin.tar.gz $ cd ${TELEPORT_PKG?} - $ sudo ./install + $ sudo ./teleport-update enable --proxy example.teleport.sh # or sudo ./install for static installation ``` @@ -387,6 +386,7 @@ script](#one-line-installation-script) or manually install Teleport from a $ curl -O https://cdn.teleport.dev/${TELEPORT_PKG?}_${TELEPORT_VERSION?}_${SYSTEM_ARCH?}.deb $ shasum --check -a 256 ${TELEPORT_PKG?}_${TELEPORT_VERSION?}_${SYSTEM_ARCH?}.deb $ sudo dpkg -i ${TELEPORT_PKG?}_${TELEPORT_VERSION?}_${SYSTEM_ARCH?}.deb + $ sudo teleport-update enable --proxy example.teleport.sh # enable managed updates ``` @@ -399,6 +399,7 @@ script](#one-line-installation-script) or manually install Teleport from a $ shasum --check -a 256 https://cdn.teleport.dev/${TELEPORT_PKG?}-${TELEPORT_VERSION?}-1.${SYSTEM_ARCH?}.rpm # Or use yum localinstall, dnf localinstall etc. $ sudo rpm -i https://cdn.teleport.dev/${TELEPORT_PKG?}-${TELEPORT_VERSION?}-1.${SYSTEM_ARCH?}.rpm + $ sudo teleport-update enable --proxy example.teleport.sh # enable managed updates ``` @@ -417,7 +418,7 @@ script](#one-line-installation-script) or manually install Teleport from a $ shasum --check -a 256 teleport-ent-v${TELEPORT_VERSION?}-linux-${SYSTEM_ARCH?}-fips-bin.tar.gz $ tar -xvf teleport-ent-v${TELEPORT_VERSION?}-linux-${SYSTEM_ARCH?}-fips-bin.tar.gz $ cd teleport-ent - $ sudo ./install + $ sudo ./teleport-update enable --proxy example.teleport.sh # or sudo ./install for static installation ``` @@ -431,6 +432,7 @@ script](#one-line-installation-script) or manually install Teleport from a $ curl -O https://cdn.teleport.dev/teleport-ent_${TELEPORT_VERSION}-fips_${SYSTEM_ARCH}.deb $ shasum --check -a 256 teleport-ent_${TELEPORT_VERSION}-fips_${SYSTEM_ARCH}.deb $ sudo dpkg -i teleport-ent_${TELEPORT_VERSION}-fips_${SYSTEM_ARCH}.deb + $ sudo teleport-update enable --proxy example.teleport.sh # enable managed updates ``` @@ -446,6 +448,7 @@ script](#one-line-installation-script) or manually install Teleport from a $ shasum --check -a 256 https://cdn.teleport.dev/teleport-ent-${TELEPORT_VERSION?}-1-fips.${SYSTEM_ARCH?}.rpm # Or use yum localinstall, dnf localinstall etc. $ sudo rpm -i https://cdn.teleport.dev/teleport-ent-${TELEPORT_VERSION?}-1-fips.${SYSTEM_ARCH?}.rpm + $ sudo teleport-update enable --proxy example.teleport.sh # enable managed updates ``` diff --git a/docs/pages/upgrading/agent-managed-updates-v1.mdx b/docs/pages/upgrading/agent-managed-updates-v1.mdx index 90c8db2dca77b..ef83cbc76ee90 100644 --- a/docs/pages/upgrading/agent-managed-updates-v1.mdx +++ b/docs/pages/upgrading/agent-managed-updates-v1.mdx @@ -5,20 +5,29 @@ description: Describes how to set up managed agent updates using the original up This document describes the original (v1) Teleport Agent updater, which is -currently supported but will eventually be deprecated. +currently supported but will be deprecated after the new (v2) updater is released. -The original updater uses the `teleport-ent-updater` package and -`cluster_maintenance_config` resource described in this document, while the -next-generation updater uses a binary called `teleport-update` that is included -in the `teleport` package and configured by the `autoupdate_version` and -`autoupdate_config` resources. +The original updater uses a script called `teleport-upgrade` that is provided by +the `teleport-ent-updater` package and configured by the `cluster_maintenance_config` +Teleport resource. The new updater uses a binary called `teleport-update` that is +provided by the `teleport` package and configured by the `autoupdate_version` and +`autoupdate_config`. The original updater and resource are described in this document. -Please consider using the next-generation updater, which is distributed with -all versions of Teleport and provides a simpler, more flexible, and more reliable +Please consider using the new updater, which will be distributed with +all versions of Teleport and provides a safer, simpler, more flexible, and more reliable update experience compared to the original updater. -For details about the next-generation updater, see +The new `teleport-update` updater is backwards compatible with the +`cluster_maintenance_config` resource, and the old `teleport-upgrade` script +is forwards compatible with the `autoupdate_` resources. +Agents connected to the same cluster may use either resource. +If the `autoupdate_ ` resources are present, `cluster_maintenance_config` is ignored. +This allows for a safe, non-breaking, incremental migration to the new update system. +Users of cloud-hosted Teleport Enterprise will be migrated to the new set of resources +in the first half of 2025 and should plan to migrate their agents to `teleport-update`. + +For details about the new updater, see [Managed Updates for Agents (v2)](./agent-managed-updates.mdx). On cloud-hosted Teleport Enterprise accounts, users must set up managed agent diff --git a/docs/pages/upgrading/agent-managed-updates.mdx b/docs/pages/upgrading/agent-managed-updates.mdx index 30eff6680147c..9e608b41361fe 100644 --- a/docs/pages/upgrading/agent-managed-updates.mdx +++ b/docs/pages/upgrading/agent-managed-updates.mdx @@ -4,20 +4,29 @@ description: Describes how to set up managed agent updates using the next-genera --- -This document describes the next-generation (v2) Teleport Agent updater, which -is currently in beta. +This document describes the new (v2) Teleport Agent updater, which is currently +in beta. -The original updater uses the `teleport-ent-updater` package and -`cluster_maintenance_config` resource, while the next-generation updater uses -a binary called `teleport-update` that is included in the `teleport` package and -configured by the `autoupdate_version` and `autoupdate_config` resources -described in this document. +The original updater uses a script called `teleport-upgrade` that is provided by +the `teleport-ent-updater` package and configured by the `cluster_maintenance_config` +Teleport resource. The new updater uses a binary called `teleport-update` that is +provided by the `teleport` package and configured by the `autoupdate_version` and +`autoupdate_config`. The new updater and resources are described in this document. -Please consider using the next-generation updater, which is distributed with -all versions of Teleport and provides a simpler, more flexible, and more reliable +Please consider using the new updater, which will be distributed with +all versions of Teleport and provides a safer, simpler, more flexible, and more reliable update experience compared to the original updater. +The new `teleport-update` updater is backwards compatible with the +`cluster_maintenance_config` resource, and the old `teleport-upgrade` script +is forwards compatible with the `autoupdate_` resources. +Agents connected to the same cluster may use either resource. +If the `autoupdate_ ` resources are present, `cluster_maintenance_config` is ignored. +This allows for a safe, non-breaking, incremental migration to the new update system. +Users of cloud-hosted Teleport Enterprise will be migrated to the new set of resources +in the first half of 2025 and should plan to migrate their agents to `teleport-update`. + For details about the original updater, see [Managed Updates for Agents (v1)](./agent-managed-updates-v1.mdx). @@ -78,8 +87,8 @@ If this command is not available, update the `teleport` package to the latest version that is supported by your cluster. -The `teleport-update enable` command will disable the original (v1) -updater if present. No other action is necessary. +The `teleport-update enable` command will disable (but not remove) +the original (v1) updater if present. No other action is necessary. If everything is working, the deprecated updater can be removed: @@ -94,23 +103,24 @@ back to manual updates or the original updater (if it has not been removed): $ sudo teleport-update uninstall ``` -If Teleport was installed via the apt/yum package, this will revert the +If Teleport was installed via the apt or yum package, this will revert the running version of Teleport back to the version provided by the package. For cloud-hosted Teleport Enterprise, updates will roll out automatically during the first chosen maintenance window that is at least 36 hours after -the cluster version is updated. Keep reading to learn how to customize the time. +the cluster version is updated. Keep reading to learn how to customize the +schedule. ## Quick setup for new Linux servers -The [Install Script] is the fastest way to onboard new Linux servers with -a single command. However, you may also use `teleport-update` to setup -a Teleport agent manually. +The [Install Script](installation.mdx#one-line-installation-script) is the +fastest way to onboard new Linux servers. However, you may also use +`teleport-update` by itself to setup a Teleport agent manually. -Users of cloud-hosted Teleport Enterprise can create a new installation of -Teleport using any version of the `teleport-update` binary. -First, copy of the [Teleport tarball] from the downloads page. -Next, invoke `teleport-update` to install the correct version for your cluster. +Users can create a new installation of Teleport using any version of the +`teleport-update` binary. First, download copy of the [Teleport tarball] from +the downloads page. Next, invoke `teleport-update` to install the correct version +for your cluster. ```code $ tar xf teleport-[version].tgz From 66962f1a23013b8102a4357eece9b0d4e7e4306f Mon Sep 17 00:00:00 2001 From: Stephen Levine Date: Mon, 10 Feb 2025 21:31:58 -0500 Subject: [PATCH 08/11] wip 6 --- docs/pages/reference/cli/teleport-update.mdx | 7 +++--- docs/pages/reference/resources.mdx | 16 ++++++------ .../pages/upgrading/agent-managed-updates.mdx | 25 +++++++++++++++---- 3 files changed, 32 insertions(+), 16 deletions(-) diff --git a/docs/pages/reference/cli/teleport-update.mdx b/docs/pages/reference/cli/teleport-update.mdx index 6ce8ebcb69ec3..4d58149c06ca1 100644 --- a/docs/pages/reference/cli/teleport-update.mdx +++ b/docs/pages/reference/cli/teleport-update.mdx @@ -3,10 +3,11 @@ title: teleport-update CLI reference description: Comprehensive reference of subcommands, flags, and arguments for the teleport-update CLI tool. --- -`tbot` is a CLI tool used with **Machine ID** that programatically issues and renews -short-lived certificates to any service account (e.g, a CI/CD server). +`teleport-update` is a CLI tool that is used to update Teleport agents installed on Linux servers. -The primary commands for `tbot` are as follows: +See [Teleport Agent Managed Updates](../upgrading/agent-managed-updates.mdx) for more details. + +The primary commands for `teleport-update` are as follows: | Command | Description | | - | - | diff --git a/docs/pages/reference/resources.mdx b/docs/pages/reference/resources.mdx index 3aa0a33c080e8..921073708cb79 100644 --- a/docs/pages/reference/resources.mdx +++ b/docs/pages/reference/resources.mdx @@ -216,9 +216,9 @@ Global configuration options for the agents enrolled into automatic updates (v1) `cluster_maintenance_config` configures the original (v1) Teleport Agent updater, -which is currently supported but will eventually be deprecated. -The `autoupdate_config` and `autoupdate_version` resources below configure the -next-generation (v2) Teleport updater. +which is currently supported but will be deprecated after the new updater is released. +The `autoupdate_config` and `autoupdate_version` resources further down configure the +new (v2) Teleport updater. (!docs/pages/includes/cluster-maintenance-config-spec.mdx!) @@ -342,9 +342,9 @@ Configuration options for Teleport agent and client tools Managed Updates (v2). The `autoupdate_config` and `autoupdate_version` resources configure the both the -next-generation (v2) Teleport updater and original (v1) Teleport Agent updater. +new (v2) Teleport Agent updater and original (v1) Teleport Agent updater. `cluster_maintenance_config` above configures the original (v1) Teleport Agent updater, -which is currently supported but will eventually be deprecated. +which is currently supported but will be deprecated after the new updater is released. ```yaml @@ -419,10 +419,10 @@ See [Teleport Client Tool Managed Updates](../upgrading/client-tools-autoupdate. Allows cluster administrators to manage versions used for agent and client tools Managed Updates. -The `autoupdate_config` and `autoupdate_version` resources configure the -next-generation (v2) Teleport updater. +The `autoupdate_config` and `autoupdate_version` resources configure the both the +new (v2) Teleport Agent updater and original (v1) Teleport Agent updater. `cluster_maintenance_config` above configures the original (v1) Teleport Agent updater, -which is currently supported but will eventually be deprecated. +which is currently supported but will be deprecated after the new updater is released. This resource is not editable for cloud-managed Teleport Enterprise to ensure that all of diff --git a/docs/pages/upgrading/agent-managed-updates.mdx b/docs/pages/upgrading/agent-managed-updates.mdx index 9e608b41361fe..1ae06ea7fbde5 100644 --- a/docs/pages/upgrading/agent-managed-updates.mdx +++ b/docs/pages/upgrading/agent-managed-updates.mdx @@ -225,7 +225,7 @@ You may execute `teleport-update enable` repeatedly to change the group ### Setting the version For cloud-hosted Teleport Enterprise, managed updates are enabled by default. -The `autoupdate_version` resource is managed for you, and cannot be edited. +The `autoupdate_version` resource is managed for you and cannot be edited. For self-hosted Teleport Enterprise, the `autoupdate_version` resource must be created and edited to enabled managed updates. @@ -275,8 +275,8 @@ Server ID Hostname Services Version Upgrader ... ``` -Use the `--upgrader=unit` flag to list agents that are enrolled in the outdated -updater and need to be configured to the next-generation updater: +Use the `--upgrader=unit` flag to list agents that are enrolled in the original +updater and need to be configured to the new updater (`teleport-update`): ```code $ tctl inventory ls --upgrader=unit @@ -286,6 +286,8 @@ Server ID Hostname Services Version Upgrader ... ``` +Agents using the new updater can be queried with the `--upgrader=binary` flag. + ### Enrolling unmanaged agents 1. For each agent ID returned by the `tctl inventory ls` command, copy the ID @@ -310,12 +312,25 @@ Server ID Hostname Services Version Upgrader $ teleport version ``` -1. Remove the last-generation updater if present: +1. Remove the original updater if present: + + + ```code $ sudo apt remove teleport-ent-updater ``` + + + + ```code + $ sudo yum remove teleport-ent-updater + ``` + + + +
If you changed the agent user to run as non-root, create @@ -328,7 +343,7 @@ $ sudo chown /etc/teleport-upgrade.d/schedule ``` While `teleport-update` does not read this file, `teleport` will warn if it -cannot disable the last-generation updater using this file. +cannot disable the original updater using this file.
From 262917a299450b16f02c1a4c5e7573500eff5a86 Mon Sep 17 00:00:00 2001 From: Stephen Levine Date: Mon, 10 Feb 2025 22:52:59 -0500 Subject: [PATCH 09/11] cli 1 --- docs/pages/reference/cli/teleport-update.mdx | 547 +------------------ 1 file changed, 27 insertions(+), 520 deletions(-) diff --git a/docs/pages/reference/cli/teleport-update.mdx b/docs/pages/reference/cli/teleport-update.mdx index 4d58149c06ca1..4ddc9bfaf63e6 100644 --- a/docs/pages/reference/cli/teleport-update.mdx +++ b/docs/pages/reference/cli/teleport-update.mdx @@ -9,50 +9,21 @@ See [Teleport Agent Managed Updates](../upgrading/agent-managed-updates.mdx) for The primary commands for `teleport-update` are as follows: -| Command | Description | -| - | - | -| `tbot help` | Outputs guidance for using commands with `tbot`. | -| `tbot version` | Outputs the current version of the `tbot` binary. | -| `tbot configure` | Outputs a basic Machine ID client configuration file to be adjusted as needed. | -| `tbot start` | Starts the Machine ID client `tbot`, fetching and writing certificates to disk at a set interval. | -| `tbot init` | Initialize a certificate destination directory for writes from a separate bot user, configuring either file or POSIX ACL permissions. | -| `tbot db` | Connects to databases using native clients and queries database information. Functions as a wrapper for `tsh`, and requires `tsh` installation. | -| `tbot proxy` | Allows for access to Teleport resources on a cluster using TLS Routing. Functions as a wrapper for `tsh`, and requires `tsh` installation. | -| `tbot tpm identify` | Output identifying information related to the TPM (Trusted Platform Module) detected on the system. | - -## tbot db - -Connects to databases using native clients and queries database information. This is best used for testing and validation purposes; -most users will likely prefer to connect their own databases to a local proxy using `tbot proxy db`. - -Note that `tsh` must be installed to make use of this command. - -### Flags - -| Flag | Description | -|---------------------|----------------------------------------------------------------------------------------------------------| -| `-d/--debug` | Enable verbose logging to stderr. | -| `-c/--config` | Path to a Machine ID configuration file. Required if not using other required configuration flags. | -| `--destination-dir` | Path to the Machine ID destination dir that should be used for authentication. Required. | -| `--proxy-server` | The `host:port` of the Teleport Proxy Service to use to access resources. Required. | -| `--cluster` | The name of the cluster on which resources should be accessed. Extracted from the bot identity if unset. | - -All other flags and arguments are passed directly to `tsh db ...`, along -with authentication parameters to use the Machine ID identity to skip `tsh`'s -login steps. - -Note that certain CLI parameters, for example `--help`, may be captured by -`tbot` even if intended to be passed to the wrapped `tsh`. A `--` argument can -be used to ensure all following arguments are passed to `tsh` and ignored by -`tbot`. - -Additionally, be aware of the following limitations of `tbot db`: - - `tbot db connect` requires a `tbot db login` for certain database types, - like MySQL, so that additional connection parameters can be written to a - local configuration file. - - `tbot db env` is not fully supported. - -## tbot init +| Command | Description | +|----------------------------------|----------------------------------------------------------------------------------------| +| `teleport-update help` | Output guidance for using commands with `teleport-update`. | +| `teleport-update version` | Output the current version of the `teleport-update` binary. | +| `teleport-update enable` | Install the version of Teleport advertised by the cluster and enable managed updates. | +| `teleport-update pin` | Install the version of Teleport advertised by the cluster and stay on that version. | +| `teleport-update disable` | Disable auto-updates without removing Teleport. Disables all requests. | +| `teleport-update unpin` | Allow the installed version of Teleport to be updated, if managed updates are enabled. | | +| `teleport-update update` | Update Teleport to the version advertised by the cluster. | | +| `teleport-update link-package` | Restore the system-packaged (apt/yum) version of Teleport to /usr/local/bin. | | +| `teleport-update unlink-package` | Remove the system-packaged (apt/yum) version of Teleport from /usr/local/bin. | | +| `teleport-update status` | Output the status of the installed version of Teleport. | | +| `teleport-update uninstall` | Remove both Teleport and the updater. | | + +## teleport-update enable Initializes a certificate destination directory for access from a separate bot user. Allows for certificates to be written to disks other than a Machine ID @@ -64,23 +35,24 @@ specifying allowed reader users and groups in the ### Flags -| Flag | Description | -|---------------------|--------------------------------------------------------------------------------------------------------------------| -| `-d/--debug` | Enable verbose logging to stderr. | -| `-c/--config` | Path to a Machine ID configuration file. | -| `--destination-dir` | Directory to write short-lived machine certificates to. | +| Flag | Description | +|---------------------|------------------------------------------------------------------------------------------------------------------------| +| `-d/--debug` | Enable verbose logging to stderr. | +| `-c/--config` | Path to a Machine ID configuration file. | +| `--destination-dir` | Directory to write short-lived machine certificates to. | | `--owner` | Defines the Linux `user:group` owner of `--destination-dir`. Defaults to the Linux user running `tbot` if unspecified. | -| `--bot-user` | Enables POSIX ACLs and defines the Linux user that can read/write short-lived certificates to `--destination-dir`. | -| `--reader-user` | Enables POSIX ACLs and defines the Linux user that will read short-lived certificates from `--destination-dir`. | -| `--init-dir` | If using a config file and multiple destinations are configured, controls which destination dir to configure. | -| `--clean` | If set, remove unexpected files and directories from the destination. | -| `--log-format` | Controls the format of output logs. Can be `json` or `text`. Defaults to `text`. | +| `--bot-user` | Enables POSIX ACLs and defines the Linux user that can read/write short-lived certificates to `--destination-dir`. | +| `--reader-user` | Enables POSIX ACLs and defines the Linux user that will read short-lived certificates from `--destination-dir`. | +| `--init-dir` | If using a config file and multiple destinations are configured, controls which destination dir to configure. | +| `--clean` | If set, remove unexpected files and directories from the destination. | +| `--log-format` | Controls the format of output logs. Can be `json` or `text`. Defaults to `text`. | ### Examples **Example using file permissions.** -The following command highlights how to set permissions with `tbot` through Linux groups, using the user and group `jenkins:jenkins`. +The following command highlights how to set permissions with `tbot` through Linux groups, using the user and group +`jenkins:jenkins`. If running `tbot` as the Linux user `root`, use the following invocation of `tbot init` to initialize the short-lived certificate directory `/opt/machine-id` with owner `jenkins:jenkins`. @@ -105,468 +77,3 @@ $ tbot init \ --reader-user=jenkins ``` -## tbot proxy - -Allows for access to Teleport resources via a local TLS proxy in TLS Routing mode. -The `tbot proxy` command acts as a wrapper for `tsh proxy` to provide local proxy functionality for various protocols. - -Note that `tsh` must be installed to make use of this command. - -Consider using one of the following dedicated tunnel modes where possible: -- [`tbot start application-tunnel`](#tbot-start-application-tunnel) -- [`tbot start database-tunnel`](#tbot-start-database-tunnel) - -### Flags - -| Flag | Description | -|---------------------|----------------------------------------------------------------------------------------------------------| -| `-d/--debug` | Enable verbose logging to stderr. | -| `-c/--config` | Path to a Machine ID configuration file. Required if not using other required configuration flags. | -| `--destination-dir` | Path to the Machine ID destination dir that should be used for authentication. Required. | -| `--proxy-server` | The `host:port` of the Teleport Proxy Service through which resources will be accessed. Required. | -| `--cluster` | The name of the cluster on which resources should be accessed. Extracted from the bot identity if unset. | - -All other flags and arguments are passed directly to `tsh proxy ...`, along -with authentication parameters to use the Machine ID identity to skip `tsh`'s -login step. - -Additionally, the following should be noted: - -- Certain CLI parameters, for example `--help`, may be captured by - `tbot` even if intended to be passed to the wrapped `tsh`. A `--` argument can - be used to ensure all following arguments are passed to `tsh` and ignored by - `tbot` -- If no configuration file is provided, `tbot` will apply a sample configuration based on provided CLI flags. - For this reason, it is recommended that settings are explicitly applied to a configuration file in production. - -### Examples - -**Example using OpenSSH** - -The following command forwards standard input and output over a proxy suitable for use as an OpenSSH `ProxyCommand` for SSH access: - -```code -$ tbot proxy --destination-dir=./tbot-user --proxy-server=proxy.example.com:3080 ssh alice@node:3022 -``` - - In this case: - - `alice` is the remote username - - `node` is the Teleport Node name - - `3022` is the remote SSH port, which is `3022` for Nodes running the Teleport - SSH service. - -**Example using a Teleport-protected database** - -The following example opens a local proxy server to the given database. Your database client -must still be configured with client TLS certificates: - -```code -$ tbot proxy --destination-dir=./tbot-user --proxy-server=proxy.example.com:3080 db --port=1234 example -``` - -In this case: - - `example` is the name of the database server as it exists in Teleport - - `1234` is an arbitrary port on which to run the proxy - -Though not recommended, to avoid the need for additional client authentication, -the `--tunnel` flag may be used to perform authentication at the local proxy -rather than within your client: - -```code -$ tbot proxy --destination-dir=./tbot-user --proxy-server=proxy.example.com:3080 db --tunnel --port=1234 example -``` - -Note that this decreases security: - - It allows any user on the system to access the database via `localhost`. - - Your connection to the database will be unencrypted until it reaches the - `tbot` proxy running on `localhost`. - -Refer to the [database guide](../../enroll-resources/machine-id/access-guides/databases.mdx) for more information on -using database proxies. - -### Flags - -| Flag | Description | -|----------------------|------------------------------------------------------------------------------------------------| -| `-d/--debug` | Enable verbose logging to stderr. | -| `-c/--config` | Path to a configuration file. | -| `-a/--auth-server` | Address of the Teleport Auth Service. Prefer using --proxy-server where possible | -| `--proxy-server` | Address of the Teleport Proxy Server. | -| `--token` | A bot join token, if attempting to onboard a new bot; used on first connect. Can also be an absolute path to a file containing the token. | -| `--ca-pin` | CA pin to validate the Teleport Auth Service; used on first connect. | -| `--data-dir` | Directory to store internal bot data. In production environments access to this directory should be limited only to an isolated linux user as an owner with `0600` permissions. | -| `--destination-dir` | Directory to write short-lived machine certificates. | -| `--certificate-ttl` | TTL of short-lived machine certificates. | -| `--renewal-interval` | Interval at which short-lived certificates are renewed; must be less than the certificate TTL. | -| `--join-method` | Method to use to join the cluster. Can be `token` or `iam`. | -| `--oneshot` | If set, quit after the first renewal. | - -## tbot configure - -The `tbot configure` command is used to convert a `tbot start` CLI call into a -YAML configuration file. It supports all the same subcommands and flags as -[`tbot start`](#tbot-start), but prints an equivalent configuration instead of -starting a bot. - -For example, consider this `tbot start identity` CLI call: -```code -$ tbot start identity \ - --destination=./example \ - --join-method=token \ - --token=foo \ - --proxy-server=teleport.example.com:443 -``` - -To convert this CLI command into a configuration file, replace `tbot start` with -`tbot configure`: -```code -$ tbot configure identity \ - --destination=./example \ - --join-method=token \ - --token=foo \ - --proxy-server=teleport.example.com:443 -``` - -An equivalent YAML configuration will be printed, which can be written to a -file. The client can then be started using this configuration file: - -```code -$ tbot configure identity \ - --destination=./example \ - --join-method=token \ - --token=foo \ - --proxy-server=teleport.example.com:443 > tbot.yaml -$ tbot start -c tbot.yaml -``` - -### Flags - -This subcommand supports one additional flag beyond its `tbot start` equivalent: - -| Flag | Description | -|---------------|-------------| -| `-o/--output` | If set, writes the generated configuration to the given file path instead of stdout. | - -## tbot start - -The `tbot start` family of commands starts the Machine ID client in various -modes, depending on the type of resources to be accessed: - -- [`tbot start legacy`](#tbot-start-legacy): Starts with a YAML configuration file or in legacy output mode -- [`tbot start identity`](#tbot-start-identity): Starts with an identity output for SSH and Teleport API access -- [`tbot start database`](#tbot-start-database): Starts with a database credential output -- [`tbot start kubernetes`](#tbot-start-kubernetes): Starts with a Kubernetes output -- [`tbot start application`](#tbot-start-application): Starts with an application TLS credential output -- [`tbot start application-tunnel`](#tbot-start-application-tunnel): Starts a local application tunnel -- [`tbot start database-tunnel`](#tbot-start-database-tunnel): Starts a local database tunnel -- [`tbot start spiffe-svid`](#tbot-start-spiffe-svid): Starts a Workload ID SPIFFE SVID output - -If only `tbot start` is specified, `tbot start legacy` will be inferred by -default; this is the correct mode for use with a YAML configuration file. - -### Common Start Flags - -These flags are available to all `tbot start` commands. Note that -`tbot start legacy` supports slightly different options, so refer to its -specific section for details when using a YAML config file or legacy output. - -| Flag | Description | -|----------------------|-------------| -| `-d/--debug` | Enable verbose logging to stderr. | -| `--[no-]fips` | Whether to run tbot in FIPS compliance mode. This requires the FIPS `tbot` binary. | -| `--log-format` | Controls the format of output logs. Can be `json` or `text`. Defaults to `text`. | -| `-a/--auth-server` | Address of the Teleport Auth Service. Prefer using `--proxy-server` where possible. | -| `--proxy-server` | Address of the Teleport Proxy Server. | -| `--token` | A bot join token or path to file with token value, if attempting to onboard a new bot; used on first connect. | -| `--ca-pin` | CA pin to validate the Teleport Auth Service; used on first connect. | -| `--certificate-ttl` | TTL of short-lived machine certificates. | -| `--renewal-interval` | Interval at which short-lived certificates are renewed; must be less than the certificate TTL. | -| `--join-method` | Method to use to join the cluster. One of: `azure`, `circleci`, `gcp`, `github`, `gitlab`, `iam`, `kubernetes`, `spacelift`, `token`, `tpm`, `terraform_cloud` | -| `--[no-]oneshot` | If set, quit after the first renewal. | -| `--diag-addr` | If set and the bot is in debug mode, a diagnostics service will listen on specified address. | -| `--storage` | A destination URI for tbot's internal storage, e.g. `file:///foo/bar`. See [Destination URIs](#destination-uris) for more info. | - -## tbot start legacy - -Starts the Machine ID client `tbot`, fetching and writing certificates to disk -at a set interval. This command either starts from a configuration file if `-c` -is specified, or starts with a default, legacy-compatible identity output. - -This is the default `tbot start` subcommand if no other command is specified. -Unless using a configuration file, consider using `tbot start identity` or -another dedicated mode instead. - -### Flags - -| Flag | Description | -|----------------------|------------------------------------------------------------------------------------------------| -| `-d/--debug` | Enable verbose logging to stderr. | -| `-c/--config` | Path to a Machine ID configuration file. | -| `--[no-]fips` | Whether to run tbot in FIPS compliance mode. This requires the FIPS `tbot` binary. | -| `-a/--auth-server` | Address of the Teleport Auth Service. Prefer using --proxy-server where possible | -| `--proxy-server` | Address of the Teleport Proxy Server. | -| `--token` | A bot join token, if attempting to onboard a new bot; used on first connect. Can also be an absolute path to a file containing the token. | -| `--ca-pin` | CA pin to validate the Teleport Auth Service; used on first connect. | -| `--data-dir` | Directory to store internal bot data. In production environments access to this directory should be limited only to an isolated linux user as an owner with `0600` permissions. | -| `--destination-dir` | Directory to write short-lived machine certificates. | -| `--certificate-ttl` | TTL of short-lived machine certificates. | -| `--renewal-interval` | Interval at which short-lived certificates are renewed; must be less than the certificate TTL. | -| `--join-method` | Method to use to join the cluster. Can be `token`, `azure`, `circleci`, `gcp`, `github`, `gitlab` or `iam`. | -| `--oneshot` | If set, quit after the first renewal. | -| `--log-format` | Controls the format of output logs. Can be `json` or `text`. Defaults to `text`. | - -### Examples - - - -```code -$ tbot start \ - --data-dir=/var/lib/teleport/bot \ - --destination-dir=/opt/machine-id \ - --token=00000000000000000000000000000000 \ - --join-method=token \ - --ca-pin=sha256:1111111111111111111111111111111111111111111111111111111111111111 \ - --proxy-server=example.teleport.sh:443 -``` - - - - -```code -$ tbot start \ - --data-dir=/var/lib/teleport/bot \ - --destination-dir=/opt/machine-id \ - --token=00000000000000000000000000000000 \ - --join-method=token \ - --ca-pin=sha256:1111111111111111111111111111111111111111111111111111111111111111 \ - --proxy-server=teleport.example.com:443 -``` - - - - -## tbot start identity - -Starts the Machine ID client `tbot` with an identity output, fetching and -writing certificates at a regular interval to the output specified with -`--destination`. - -```code -$ tbot start identity --destination=DESTINATION [] -``` - -### Flags - -In addition to the [common `tbot start` flags](#common-start-flags), this -command supports these additional flags: - -| Flag | Description | -|----------------------|-------------| -| `--destination` | A destination URI, such as file:///foo/bar. See [Destination URIs](#destination-uris) for more info. Required. | -| `--reader-user` | An additional user name or UID that should be allowed by ACLs to read this destination. Only valid for file destinations on Linux. | -| `--reader-group` | An additional group name or GID that should be allowed by ACLs to read this destination. Only valid for file destinations on Linux. | -| `--cluster` | The name of a specific cluster for which to issue an identity if using a leaf cluster | - -### Examples - -To start a bot with a one-time-use join token: - -```code -$ tbot start identity \ - --proxy-server=example.teleport.sh:443 \ - --join-type=token \ - --token=TOKEN \ - --destination=./tbot-user \ - --storage=./tbot-data -``` - -## tbot start database - -Starts the Machine ID client `tbot` with a database output, fetching and writing -database certificates at a regular interval to the output specified with -`--destination`. - -```code -$ tbot start database --destination=DESTINATION --service=SERVICE --username=USERNAME --database=DATABASE [] -``` - -### Flags - -In addition to the [common `tbot start` flags](#common-start-flags), this -command supports these additional flags: - -| Flag | Description | -|----------------------|-------------| -| `--destination` | A destination URI, such as file:///foo/bar. See [Destination URIs](#destination-uris) for more info. Required. | -| `--reader-user` | An additional user name or UID that should be allowed by ACLs to read this destination. Only valid for file destinations on Linux. | -| `--reader-group` | An additional group name or GID that should be allowed by ACLs to read this destination. Only valid for file destinations on Linux. | -| `--format` | The database output format if necessary | -| `--service` | The service name of the database as it appears in Teleport and `tsh db ls`. Required. | -| `--username` | The database user name. The bot user must have permission to connect as this user. Required. | -| `--database` | The name of the database available in the requested service. Required. | - -## tbot start kubernetes - -Starts the Machine ID client `tbot` with a Kubernetes output, fetching and -writing Kubernetes credentials and a `kubeconfig.yaml` at a regular interval to -the output specified with `--destination`. - -```code -$ tbot start kubernetes --destination=DESTINATION --kubernetes-cluster=KUBERNETES-CLUSTER [] -``` - -### Flags - -In addition to the [common `tbot start` flags](#common-start-flags), this -command supports these additional flags: - -| Flag | Description | -|------------------------|-------------| -| `--destination` | A destination URI, such as file:///foo/bar. See [Destination URIs](#destination-uris) for more info. Required. | -| `--reader-user` | An additional user name or UID that should be allowed by ACLs to read this destination. Only valid for file destinations on Linux. | -| `--reader-group` | An additional group name or GID that should be allowed by ACLs to read this destination. Only valid for file destinations on Linux. | -| `--kubernetes-cluster` | The name of the Kubernetes cluster in Teleport for which to fetch credentials | - -## tbot start application - -Starts the Machine ID client `tbot` with an application output, fetching and -writing application TLS credentials at a regular interval to the output -specified with `--destination`. - -```code -$ tbot start application --destination=DESTINATION --app=APP [] -``` - -### Flags - -In addition to the [common `tbot start` flags](#common-start-flags), this -command supports these additional flags: - -| Flag | Description | -|----------------------|-------------| -| `--destination` | A destination URI, such as file:///foo/bar. See [Destination URIs](#destination-uris) for more info. Required. | -| `--reader-user` | An additional user name or UID that should be allowed by ACLs to read this destination. Only valid for file destinations on Linux. | -| `--reader-group` | An additional group name or GID that should be allowed by ACLs to read this destination. Only valid for file destinations on Linux. | -| `--app` | The name of the app in Teleport | - -## tbot start application-tunnel - -Starts the Machine ID client with a local tunnel to a particular application. -This tunnel will run continuously and automatically refresh its certificates. - -Note that this tunnel will be unencrypted. Be wary of the selected listen -address, and prefer to use `localhost` or an equivalent loopback interface -address when possible. Additionally, note that all users on the local system -will be able to access this socket. - -If you wish to tunnel multiple apps from one bot instance, use -`tbot configure application-tunnel ...` to generate a configuration file and -repeat the generated block under `services:` as desired. - -This tunneling method is preferred over the legacy [`tbot proxy app`](#tbot-proxy). - -```code -$ tbot start application-tunnel --listen=LISTEN --app=APP [] -``` - -### Flags - -| Flag | Description | -|------------|-------------| -| `--listen` | A socket URI to listen on, e.g. `tcp://localhost:1234`. Required. | -| `--app` | The name of the app in Teleport | - -## tbot start database-tunnel - -Starts the Machine ID client with a local tunnel to a particular database. -This tunnel will run continuously and automatically refresh its certificates. - -Note that this tunnel will be unencrypted. Be wary of the selected listen -address, and prefer to use `localhost` or an equivalent loopback interface -address when possible. Additionally, note that all users on the local system -will be able to access this socket. - -If you wish to tunnel multiple databases from one bot instance, use -`tbot configure database-tunnel ...` to generate a configuration file and repeat -the generated block under `services:` as desired. - -This tunneling method is preferred over the legacy -[`tbot proxy db`](#tbot-proxy), and is roughly equivalent to -`tbot proxy db --tunnel`. - -```code -$ tbot start database-tunnel --listen=LISTEN --service=SERVICE --username=USERNAME --database=DATABASE [] -``` - -### Flags - -In addition to the [common `tbot start` flags](#common-start-flags), this -command supports these additional flags: - -| Flag | Description | -|--------------|-------------| -| `--listen` | A socket URI to listen on, e.g. `tcp://localhost:1234`. Required. | -| `--service` | The service name of the database as it appears in Teleport and `tsh db ls`. Required. | -| `--username` | The database user name. The bot user must have permission to connect as this user. Required. | -| `--database` | The name of the database available in the requested service. Required. | - -## tbot start spiffe-svid - -### Flags - -In addition to the [common `tbot start` flags](#common-start-flags), this -command supports these additional flags: - -| Flag | Description | -|----------------------|-------------| -| `--destination` | A destination URI, such as file:///foo/bar. See [Destination URIs](#destination-uris) for more info. Required. | -| `--reader-user` | An additional user name or UID that should be allowed by ACLs to read this destination. Only valid for file destinations on Linux. | -| `--reader-group` | An additional group name or GID that should be allowed by ACLs to read this destination. Only valid for file destinations on Linux. | -| `--[no-]include-federated-trust-bundles` | If set, include federated trust bundles in the output | -| `--svid-path` | A SPIFFE ID to request, prefixed with '/'. Required. | -| `--svid-hint` | An optional hint for consumers of the SVID to aid in identification | -| `--dns-san` | A DNS name that should be included in the SVID. Repeatable. | -| `--ip-san` | An IP address that should be included in the SVID. Repeatable. | - -## tbot install systemd - -Generates and installs a systemd unit file for a specific tbot configuration. - -### Flags - -| Flag | Description | -|-----------------------|----------------------------------------------------------------------------------------------------------------------------------| -| `-d/--debug` | Enable verbose logging to stderr. | -| `-c/--config` | Path to a configuration file. | -| `--write ` | Write the systemd unit file. If not specified, this command runs in a dry-run mode that outputs the generated content to stdout. | -| `--systemd-directory` | Path to the directory that the systemd unit file should be written. Defaults to '/etc/systemd/system'. | -| `--force` | Overwrite existing systemd unit file if present. | -| `--name` | Name for the systemd unit. Defaults to 'tbot'. | -| `--user` | The user that the service should run as. Defaults to 'teleport'. | -| `--group` | The group that the service should run as. Defaults to 'teleport'. | - -### Examples - -```code -$ tbot install systemd \ - --config=/etc/tbot.yaml \ - --write -``` - -## Destination URIs - -Many `tbot start` subcommands accept destination URIs via the `--storage` and -`--destination` flags. - -| Protocol | Description | -|------------------------|-------------| -| `file://` | A local directory destination, such as `file:///foo/bar/` | -| `memory://` | An in-memory destination. Useful for internal bot storage if no persistence is required. | -| `kubernetes-secret://` | A Kubernetes secret destination, such as `kubernetes-secret:///my-secret` | - -Plain file paths are also be accepted with no `file://` prefix; these will be -treated as directory outputs. - -Note that `tbot start legacy` only supports directory output destinations via -the `--destination-dir` flag, though it does support URIs for `--storage`. All -other `tbot start` subcommands accept these URIs where relevant. From f76a8b3593323c71678649975c4f0b9eb9a50c7c Mon Sep 17 00:00:00 2001 From: Stephen Levine Date: Mon, 10 Feb 2025 23:09:50 -0500 Subject: [PATCH 10/11] next --- docs/pages/reference/cli/teleport-update.mdx | 34 ++++++++++---------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/docs/pages/reference/cli/teleport-update.mdx b/docs/pages/reference/cli/teleport-update.mdx index 4ddc9bfaf63e6..1c8b70eb2c029 100644 --- a/docs/pages/reference/cli/teleport-update.mdx +++ b/docs/pages/reference/cli/teleport-update.mdx @@ -25,27 +25,27 @@ The primary commands for `teleport-update` are as follows: ## teleport-update enable -Initializes a certificate destination directory for access from a separate bot -user. Allows for certificates to be written to disks other than a Machine ID -client, configuring either file or POSIX ACL permissions. +Enables agent auto-updates and performs an initial installation of the Teleport agent. +This command also creates a systemd timer that periodically runs the update subcommand. -Note that most use cases should instead use tbot's runtime ACL management by -specifying allowed reader users and groups in the -[destination configuration](../machine-id/configuration.mdx#directory). +If Teleport is already installed, `enable` will update to the cluster-advertised version +and ensure managed updates are enabled. + +Most flags passed to `enable` are persisted for `update`. +To change these flags, run `enable` again with the new flags. ### Flags -| Flag | Description | -|---------------------|------------------------------------------------------------------------------------------------------------------------| -| `-d/--debug` | Enable verbose logging to stderr. | -| `-c/--config` | Path to a Machine ID configuration file. | -| `--destination-dir` | Directory to write short-lived machine certificates to. | -| `--owner` | Defines the Linux `user:group` owner of `--destination-dir`. Defaults to the Linux user running `tbot` if unspecified. | -| `--bot-user` | Enables POSIX ACLs and defines the Linux user that can read/write short-lived certificates to `--destination-dir`. | -| `--reader-user` | Enables POSIX ACLs and defines the Linux user that will read short-lived certificates from `--destination-dir`. | -| `--init-dir` | If using a config file and multiple destinations are configured, controls which destination dir to configure. | -| `--clean` | If set, remove unexpected files and directories from the destination. | -| `--log-format` | Controls the format of output logs. Can be `json` or `text`. Defaults to `text`. | +| Flag | Description | +|----------------------|------------------------------------------------------------------------------------------------------------------------| +| -d, --[no-]debug | Verbose logging to stdout. | +| --data-dir | Teleport data directory. Access to this directory should be limited. | +| --log-format | Controls the format of output logs. Can be `json` or `text`. Defaults to `text`. | +| -i, --install-suffix | Suffix for creating an agent installation outside of the default $PATH. Note: this changes the default data directory. | +| -p, --proxy | Address of the Teleport Proxy. | +| -g, --group | Update group for this agent installation. | +| -b, --base-url | Base URL used to override the Teleport download URL. | +| -o, --[no-]overwrite | Allow existing installed Teleport binaries to be overwritten. | ### Examples From 5212077340b0aaedfec5e6870881b5c06c997b6b Mon Sep 17 00:00:00 2001 From: Stephen Levine Date: Fri, 21 Feb 2025 16:23:01 -0500 Subject: [PATCH 11/11] cli ref --- docs/pages/reference/cli/teleport-update.mdx | 246 +++++++++++++++++-- 1 file changed, 225 insertions(+), 21 deletions(-) diff --git a/docs/pages/reference/cli/teleport-update.mdx b/docs/pages/reference/cli/teleport-update.mdx index 1c8b70eb2c029..f6a0db52c259c 100644 --- a/docs/pages/reference/cli/teleport-update.mdx +++ b/docs/pages/reference/cli/teleport-update.mdx @@ -14,8 +14,8 @@ The primary commands for `teleport-update` are as follows: | `teleport-update help` | Output guidance for using commands with `teleport-update`. | | `teleport-update version` | Output the current version of the `teleport-update` binary. | | `teleport-update enable` | Install the version of Teleport advertised by the cluster and enable managed updates. | -| `teleport-update pin` | Install the version of Teleport advertised by the cluster and stay on that version. | | `teleport-update disable` | Disable auto-updates without removing Teleport. Disables all requests. | +| `teleport-update pin` | Install the version of Teleport advertised by the cluster and stay on that version. | | `teleport-update unpin` | Allow the installed version of Teleport to be updated, if managed updates are enabled. | | | `teleport-update update` | Update Teleport to the version advertised by the cluster. | | | `teleport-update link-package` | Restore the system-packaged (apt/yum) version of Teleport to /usr/local/bin. | | @@ -25,12 +25,25 @@ The primary commands for `teleport-update` are as follows: ## teleport-update enable -Enables agent auto-updates and performs an initial installation of the Teleport agent. +Enables agent managed updates and performs an initial installation of the Teleport agent. This command also creates a systemd timer that periodically runs the update subcommand. If Teleport is already installed, `enable` will update to the cluster-advertised version and ensure managed updates are enabled. +Existing package-based installations will be converted to managed updates automatically. +Existing tarball-based, static installations may require `--overwrite`. +(A clear error will let you know if this is the case.) + +Files are installed to the following paths (with the default `install-suffix`): + +- `/usr/local/bin/{teleport,tsh,...}` - Symbolic links into `/opt/teleport/default/versions/X.Y.Z/bin/` +- `/lib/systemd/system/teleport.service` - Teleport SystemD service +- `/opt/teleport/default` - Storage for Teleport versions and updater configuration +- `/etc/systemd/system/teleport-update.{service,timer}` - Updater SystemD timer and service +- `/etc/systemd/system/teleport.service.d/teleport-update.conf` - Environment variables that configure Teleport +- `/etc/needrestart/conf.d/teleport-update.conf` - Needrestart defaults for Teleport + Most flags passed to `enable` are persisted for `update`. To change these flags, run `enable` again with the new flags. @@ -39,9 +52,9 @@ To change these flags, run `enable` again with the new flags. | Flag | Description | |----------------------|------------------------------------------------------------------------------------------------------------------------| | -d, --[no-]debug | Verbose logging to stdout. | -| --data-dir | Teleport data directory. Access to this directory should be limited. | | --log-format | Controls the format of output logs. Can be `json` or `text`. Defaults to `text`. | | -i, --install-suffix | Suffix for creating an agent installation outside of the default $PATH. Note: this changes the default data directory. | +| --[no-]insecure | Insecure mode disables certificate verification. Do not use in production. | | -p, --proxy | Address of the Teleport Proxy. | | -g, --group | Update group for this agent installation. | | -b, --base-url | Base URL used to override the Teleport download URL. | @@ -49,31 +62,222 @@ To change these flags, run `enable` again with the new flags. ### Examples -**Example using file permissions.** +**Example for a new installation.** -The following command highlights how to set permissions with `tbot` through Linux groups, using the user and group -`jenkins:jenkins`. -If running `tbot` as the Linux user `root`, use the following invocation of -`tbot init` to initialize the short-lived certificate directory -`/opt/machine-id` with owner `jenkins:jenkins`. +Install Teleport with managed updates enabled on a fresh system. ```code -$ tbot init \ - --destination-dir=/opt/machine-id \ - --owner=jenkins:jenkins +# create /etc/teleport.yaml +$ sudo teleport-update enable +$ sudo systemctl enable teleport --now ``` -**Example using POSIX ACLs.** +**Example for an existing installation.** -If running `tbot` as the Linux user `teleport`, use the following invocation of -`tbot init` to initialize the short-lived certificate directory -`/opt/machine-id` with owner `teleport:teleport` but allow `jenkins` to read -from `/opt/machine-id`. +Install Teleport with managed updates enabled on a system with a running Teleport version. +Package-based installations will be converted to managed updates automatically. ```code -$ tbot init \ - --destination-dir=/opt/machine-id \ - --bot-user=teleport \ - --reader-user=jenkins +$ teleport-update enable ``` +**Example with a custom installation suffix.** + +Install Teleport with managed updates enabled to an isolated path. +This will not interfere with package-based installations. +Multiple installations with separate suffixes may operate individually and independently against separate clusters. + +```code +# create /etc/teleport_mycluster.yaml +$ sudo teleport-update --install-suffix mycluster enable +$ sudo systemctl enable teleport_mycluster --now +$ export PATH=/opt/teleport/mycluster/bin:$PATH +``` + +## teleport-update disable + +Disable managed updates for the installed agent. +This command does not remove or change the active installation of Teleport. + +Unlike `pin`, this command will not touch the current installation, and version lookup requests will stop entirely. + +### Flags + +| Flag | Description | +|----------------------|------------------------------------------------------------------------------------------------------------------------| +| -d, --[no-]debug | Verbose logging to stdout. | +| --log-format | Controls the format of output logs. Can be `json` or `text`. Defaults to `text`. | +| -i, --install-suffix | Suffix for creating an agent installation outside of the default $PATH. Note: this changes the default data directory. | +| --[no-]insecure | Insecure mode disables certificate verification. Do not use in production. | + +### Examples + +**Example for disabling managed updates.** + +Disable managed updates for the current agent. + +```code +$ sudo teleport-update disable +``` + +## teleport-update pin + +Pin the installed agent to a specific version of Teleport. +This command updates Teleport to latest version (or a version specified with `--force-version`), and ensures the local +installation of Teleport remains at that version. +New versions will continue to be reported in SystemD `teleport-update.service` logs, they but will not be installed. + +`pin` is similar to `enable`, but the resulting version will not change until `unpin` is run. + +### Flags + +| Flag | Description | +|----------------------|------------------------------------------------------------------------------------------------------------------------| +| -d, --[no-]debug | Verbose logging to stdout. | +| --log-format | Controls the format of output logs. Can be `json` or `text`. Defaults to `text`. | +| -i, --install-suffix | Suffix for creating an agent installation outside of the default $PATH. Note: this changes the default data directory. | +| --[no-]insecure | Insecure mode disables certificate verification. Do not use in production. | +| -p, --proxy | Address of the Teleport Proxy. | +| -g, --group | Update group for this agent installation. | +| -b, --base-url | Base URL used to override the Teleport download URL. | +| -o, --[no-]overwrite | Allow existing installed Teleport binaries to be overwritten. | +| -f, --force-version | Force the provided version instead of using the version provided by the Teleport cluster. | | + +### Examples + +**Example for a new installation at the cluster-advertised version.** + +Install the cluster-advertised Teleport version on a fresh system, but lock the version in-place. + +```code +# create /etc/teleport.yaml +$ sudo teleport-update pin +$ sudo systemctl enable teleport --now +``` + +**Example for a new installation at a custom version.** + +Install the specified Teleport version on a fresh system, but lock the version in-place. + +```code +# create /etc/teleport.yaml +$ sudo teleport-update pin --force-version v17.1.2 +$ sudo systemctl enable teleport --now +``` + +**Example for an existing installation.** + +Install the cluster-advertised Teleport version on a system with a running Teleport agent, but lock the version +in-place. +Package-based installations will be converted to managed updates automatically. + +```code +$ sudo teleport-update pin +``` + +## teleport-update unpin + +Unpin the version of Teleport, so that the cluster-advertised version will be installed on the next update. +This command does not immediately remove or change the active installation of Teleport. + +### Flags + +| Flag | Description | +|----------------------|------------------------------------------------------------------------------------------------------------------------| +| -d, --[no-]debug | Verbose logging to stdout. | +| --log-format | Controls the format of output logs. Can be `json` or `text`. Defaults to `text`. | +| -i, --install-suffix | Suffix for creating an agent installation outside of the default $PATH. Note: this changes the default data directory. | +| --[no-]insecure | Insecure mode disables certificate verification. Do not use in production. | + +### Examples + +**Example for unpinning managed updates to allow the cluster-advertised version to be installed.** + +Unpin managed updates for the current agent. + +```code +$ sudo teleport-update unpin +$ sudo teleport-update update --now # force immediate update, if desired +``` + +## teleport-update update + +Update the version of Teleport to either the pinned version, or the version advertised by the cluster. + +If `--now` is not specified, `update` will only update if the current time is in the update window for the agent's group. + +This command is used by the `teleport-update` SystemD service/timer, and does not need to be manually executed. + +### Flags + +| Flag | Description | +|----------------------|------------------------------------------------------------------------------------------------------------------------| +| -d, --[no-]debug | Verbose logging to stdout. | +| --log-format | Controls the format of output logs. Can be `json` or `text`. Defaults to `text`. | +| -i, --install-suffix | Suffix for creating an agent installation outside of the default $PATH. Note: this changes the default data directory. | +| --[no-]insecure | Insecure mode disables certificate verification. Do not use in production. | +| -n, --[no-]now | Force immediate update even if update window is not active. | + +### Examples + +**Example for updating immediately.** + +Force update outside of update window with `--now`. + +```code +$ sudo teleport-update update --now +``` + +## teleport-update link-package + +Link the system installation of Teleport from the Teleport package, if managed updates is disabled. + +This command is used to link the system package installation by: +- Creating symbolic links from `/opt/teleport/system/bin/*` into `/usr/local/bin/`. +- Copying the Teleport systemd service file from `/opt/teleport/system/lib/systemd/system/teleport.service` into `/ib/systemd/system/teleport.service`. + +This command is executed automatically when the Teleport package is installed, and does not need to be manually executed. + +Managed updates must be disabled, and the active version of Teleport must be removed, for this command to work. +Note that `uninstall` will automatically remove the active version of Teleport and link the system package if the package is installed. + +### Flags + +| Flag | Description | +|----------------------|------------------------------------------------------------------------------------------------------------------------| +| -d, --[no-]debug | Verbose logging to stdout. | +| --log-format | Controls the format of output logs. Can be `json` or `text`. Defaults to `text`. | +| -i, --install-suffix | Suffix for creating an agent installation outside of the default $PATH. Note: this changes the default data directory. | +| --[no-]insecure | Insecure mode disables certificate verification. Do not use in production. | + +### Examples + +**Example for restoring the system package installation of Teleport.** + +Re-link Teleport apt/yum package. + +```code +$ sudo teleport-update link-package +``` + +## teleport-update unlink-package + +Unlink the system installation of Teleport from the Teleport package. + +This command is used to unlink the system package installation by: +- Removing symbolic links from `/opt/teleport/system/bin/*` into `/usr/local/bin/`. +- Removing the Teleport systemd service file from `/ib/systemd/system/teleport.service` (if symlinks are removed). + +This command is executed automatically when the Teleport package is removed, and should not be manually executed. + +**Note that this command will unlink a running version of Teleport, potentially causing loss of access to the system via Teleport.** + +### Flags + +| Flag | Description | +|----------------------|------------------------------------------------------------------------------------------------------------------------| +| -d, --[no-]debug | Verbose logging to stdout. | +| --log-format | Controls the format of output logs. Can be `json` or `text`. Defaults to `text`. | +| -i, --install-suffix | Suffix for creating an agent installation outside of the default $PATH. Note: this changes the default data directory. | +| --[no-]insecure | Insecure mode disables certificate verification. Do not use in production. | +