From 52c0363cbeee58bde66245e34680f252fbe162bb Mon Sep 17 00:00:00 2001 From: fheinecke <23390735+fheinecke@users.noreply.github.com> Date: Mon, 18 Sep 2023 17:28:34 -0500 Subject: [PATCH] [v14] Updated OS package repo docs (#32102) * Updated OS package repo docs * Fixed linter issues * Added table for repo channel info on ent installations * Fixed import path --- docs/cspell.json | 3 ++ .../architecture/agent-update-management.mdx | 4 +-- .../includes/cloud/install-linux-cloud.mdx | 35 ++++++++++++++----- .../install-linux-ent-self-hosted.mdx | 27 +++++++++++++- docs/pages/includes/install-linux.mdx | 4 +++ docs/pages/includes/repo-channels.mdx | 10 ++++++ docs/pages/installation.mdx | 17 ++++----- .../enroll-agent-into-automatic-updates.mdx | 4 +-- .../self-hosted-automatic-agent-updates.mdx | 11 +++--- 9 files changed, 86 insertions(+), 29 deletions(-) create mode 100644 docs/pages/includes/repo-channels.mdx diff --git a/docs/cspell.json b/docs/cspell.json index d3c41cca896b9..135049865ed1b 100644 --- a/docs/cspell.json +++ b/docs/cspell.json @@ -162,6 +162,7 @@ "SIEM", "SIGINT", "SLAVEOF", + "SLES", "SLOWLOG", "SSUBSCRIBE", "SSWS", @@ -220,6 +221,7 @@ "acpi", "actionstest", "adcli", + "addrepo", "addserver", "adduser", "adutil", @@ -705,6 +707,7 @@ "signup", "skipreconcile", "slacktokenfromsecret", + "sles", "snowsql", "splunkd", "splunkd", diff --git a/docs/pages/architecture/agent-update-management.mdx b/docs/pages/architecture/agent-update-management.mdx index 95a8079af7e96..e092e03f7add1 100644 --- a/docs/pages/architecture/agent-update-management.mdx +++ b/docs/pages/architecture/agent-update-management.mdx @@ -62,8 +62,8 @@ For this reason, all updaters must subscribe to a release channel targeting versions that are compatible with their Teleport cluster. Teleport Cloud users must use the Teleport Cloud version server with the `stable/cloud` release channel. Self-hosted Teleport users must host their own version server and -updater their release channel each time they update their Auth and Proxy -instances. +either update their release channel each time they update their Auth and Proxy +instances, or use the `stable/rolling` channel. ### Teleport Cloud diff --git a/docs/pages/includes/cloud/install-linux-cloud.mdx b/docs/pages/includes/cloud/install-linux-cloud.mdx index c962b45280a2c..0dead89572ab0 100644 --- a/docs/pages/includes/cloud/install-linux-cloud.mdx +++ b/docs/pages/includes/cloud/install-linux-cloud.mdx @@ -1,5 +1,5 @@ - + Add the Teleport repository to your repository list: @@ -9,7 +9,7 @@ -o /usr/share/keyrings/teleport-archive-keyring.asc # Source variables about OS version $ source /etc/os-release - # Add the Teleport apt repository for cloud. + # Add the Teleport APT repository for cloud. $ echo "deb [signed-by=/usr/share/keyrings/teleport-archive-keyring.asc] \ https://apt.releases.teleport.dev/${ID?} ${VERSION_CODENAME?} stable/cloud" \ | sudo tee /etc/apt/sources.list.d/teleport.list > /dev/null @@ -19,16 +19,16 @@ ``` - + ```code # Source variables about OS version $ source /etc/os-release - # Add the Teleport yum repository for cloud. - # First, get the major version from $VERSION_ID so this fetches the correct + # Add the Teleport YUM repository for cloud. + # First, get the OS major version from $VERSION_ID so this fetches the correct # package version. $ VERSION_ID=$(echo $VERSION_ID | grep -Eo "^[0-9]+") - $ sudo yum-config-manager --add-repo "$(rpm --eval "https://yum.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/cloud/teleport.repo")" + $ sudo yum-config-manager --add-repo "$(rpm --eval "https://yum.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/cloud/teleport-yum.repo")" $ sudo yum install teleport-ent-updater # # Tip: Add /usr/local/bin to path used by sudo (so 'sudo tctl users add' will work as per the docs) @@ -41,12 +41,12 @@ ```code # Source variables about OS version $ source /etc/os-release - # Add the Teleport yum repository for cloud. - # First, get the major version from $VERSION_ID so this fetches the correct + # Add the Teleport YUM repository for cloud. + # First, get the OS major version from $VERSION_ID so this fetches the correct # package version. $ VERSION_ID=$(echo $VERSION_ID | grep -Eo "^[0-9]+") # Use the dnf config manager plugin to add the teleport RPM repo - $ sudo dnf config-manager --add-repo "$(rpm --eval "https://yum.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/cloud/teleport.repo")" + $ sudo dnf config-manager --add-repo "$(rpm --eval "https://yum.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/cloud/teleport-yum.repo")" # Install teleport $ sudo dnf install teleport-ent-updater @@ -55,5 +55,22 @@ # echo "Defaults secure_path = /sbin:/bin:/usr/sbin:/usr/bin:/usr/local/bin" > /etc/sudoers.d/secure_path ``` + + + + ```code + # Source variables about OS version + $ source /etc/os-release + # Add the Teleport Zypper repository for cloud. + # First, get the OS major version from $VERSION_ID so this fetches the correct + # package version. + $ VERSION_ID=$(echo $VERSION_ID | grep -Eo "^[0-9]+") + # Use Zypper to add the teleport RPM repo + $ sudo zypper addrepo --refresh --repo $(rpm --eval "https://zypper.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/cloud/teleport-zypper.repo") + + # Install teleport + $ sudo zypper install teleport-ent-updater + ``` + diff --git a/docs/pages/includes/install-linux-ent-self-hosted.mdx b/docs/pages/includes/install-linux-ent-self-hosted.mdx index 2ffe42b651c44..401c20acbdfb0 100644 --- a/docs/pages/includes/install-linux-ent-self-hosted.mdx +++ b/docs/pages/includes/install-linux-ent-self-hosted.mdx @@ -1,5 +1,5 @@ - + ```code # Download Teleport's PGP public key @@ -47,6 +47,31 @@ For FedRAMP/FIPS-compliant installations, install the `teleport-ent-fips` packag $ sudo yum install teleport-ent-fips ``` + + + +```code +# Source variables about OS version +$ source /etc/os-release +# Add the Teleport Zypper repository for v(=teleport.major_version=). You'll need to update this +# file for each major release of Teleport. +# First, get the OS major version from $VERSION_ID so this fetches the correct +# package version. +$ VERSION_ID=$(echo $VERSION_ID | grep -Eo "^[0-9]+") +# Use zypper to add the teleport RPM repo +$ sudo zypper addrepo --refresh --repo $(rpm --eval "https://zypper.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/cloud/teleport-zypper.repo") +$ sudo yum install teleport-ent +# +# Tip: Add /usr/local/bin to path used by sudo (so 'sudo tctl users add' will work as per the docs) +# echo "Defaults secure_path = /sbin:/bin:/usr/sbin:/usr/bin:/usr/local/bin" > /etc/sudoers.d/secure_path +``` + +For FedRAMP/FIPS-compliant installations, install the `teleport-ent-fips` package instead: + +```code +$ sudo yum install teleport-ent-fips +``` + diff --git a/docs/pages/includes/install-linux.mdx b/docs/pages/includes/install-linux.mdx index 06569d25bb567..a8510bff184c4 100644 --- a/docs/pages/includes/install-linux.mdx +++ b/docs/pages/includes/install-linux.mdx @@ -27,9 +27,13 @@ Select an edition, then follow the instructions for that edition to install Tele (!docs/pages/includes/install-linux-ent-self-hosted.mdx!) + + (!docs/pages/includes/repo-channels.mdx!) (!docs/pages/includes/cloud/install-linux-cloud.mdx!) + + (!docs/pages/includes/repo-channels.mdx!)
Before installing a `teleport` binary with a version besides v(=cloud.major_version=), diff --git a/docs/pages/includes/repo-channels.mdx b/docs/pages/includes/repo-channels.mdx new file mode 100644 index 0000000000000..403dc7002d99e --- /dev/null +++ b/docs/pages/includes/repo-channels.mdx @@ -0,0 +1,10 @@ +### OS repository channels + +The following channels are available for APT, YUM, and Zypper repos. They may be used in place of +`stable/v(=teleport.major_version=)` anywhere in the Teleport documentation. + +| Channel name | Description | +|-------------------|--------------------------------------------------------------------------------------------| +| `stable/` | Receives releases for the specified major release line, i.e. `v(=teleport.major_version=)` | +| `stable/cloud` | Rolling channel that receives releases compatible with current Cloud version | +| `stable/rolling` | Rolling channel that receives all published Teleport releases | diff --git a/docs/pages/installation.mdx b/docs/pages/installation.mdx index 5a6a8376fbffc..1d3f6b4de975a 100644 --- a/docs/pages/installation.mdx +++ b/docs/pages/installation.mdx @@ -31,7 +31,7 @@ running Teleport on UNIX variants other than Linux \[1]. | Operating System | `teleport` Daemon | `tctl` Admin Tool | `tsh` and Teleport Connect User Clients [2] | Web UI (via the browser) | `tbot` Daemon | | - | - | - | - | - | - | -| Linux v2.6.23+ (RHEL/CentOS 7+, Ubuntu 14.04+, and Debian 8+) \[3] | yes | yes | yes | yes | yes | +| Linux v2.6.23+ (RHEL/CentOS 7+, Amazon Linux 2+, Amazon Linux 2023+, Ubuntu 16.04+, Debian 9+, SLES 12 SP 5+, and SLES 15 SP 5+) \[3] | yes | yes | yes | yes | yes | | macOS v10.13+ (High Sierra)| yes | yes | yes | yes | yes | | Windows 10+ (rev. 1607) \[4] | no | no | yes | yes | no | @@ -54,23 +54,24 @@ All installations include `teleport`, `tsh`, `tctl`, and `tbot`. Some Teleport features have additional requirements: -| Feature | Requirement | Debian | Ubuntu | CentOS/RHEL | Amazon Linux | -|--------------------------------------------------------------------------------|---------------|--------------------------|----------|-------------|------------------------| -| [Enhanced Session Recording](./server-access/guides/bpf-session-recording.mdx) | Kernel v5.8+ | 11, or 10 with backports | 20.04.2+ | 9+ | 2 (post 11/2021), 2023 | -| Automatic Updates | systemd-based | 8+ | 16.04+ | 7+ | 2, 2023 | -| Installation through apt/yum repos | systemd-based | 8+ | 16.04+ | 7+ | 2, 2023 | +| Feature | Requirement | Debian | Ubuntu | CentOS/RHEL | Amazon Linux | SLES | +|--------------------------------------------------------------------------------|---------------|--------------------------|----------|-------------|------------------------|----------------| +| [Enhanced Session Recording](./server-access/guides/bpf-session-recording.mdx) | Kernel v5.8+ | 11, or 10 with backports | 20.04.2+ | 9+ | 2 (post 11/2021), 2023 | 12 SP5, 15 SP5 | +| Automatic Updates | systemd-based | 9+ | 16.04+ | 7+ | 2, 2023 | 12 SP5, 15 SP5 | +| Installation through apt/yum/zypper repos | systemd-based | 9+ | 16.04+ | 7+ | 2, 2023 | 12 SP5, 15 SP5 | -`apt` and `yum` repos don't expose packages for all distribution variants. +`apt`, `yum`, and `zypper` repos don't expose packages for all distribution variants. When following installation instructions, you might need to replace `ID` with `ID_LIKE` to install packages of the closest supported distribution. Currently supported distributions (and `ID`) are: - RHEL >= 7 (`rhel`) - CentOS >= 7 (`centos`) -- Debian >= 8 (`debian`) +- Debian >= 9 (`debian`) - Ubuntu >= 16.04 (`ubuntu`) - Amazon Linux 2 and 2023 (`amzn`) +- SLES >= 12 SP5, >= 15 SP5 (`sles`) diff --git a/docs/pages/management/operations/enroll-agent-into-automatic-updates.mdx b/docs/pages/management/operations/enroll-agent-into-automatic-updates.mdx index a95aa9d942e55..66ed02fa58dc3 100644 --- a/docs/pages/management/operations/enroll-agent-into-automatic-updates.mdx +++ b/docs/pages/management/operations/enroll-agent-into-automatic-updates.mdx @@ -23,8 +23,8 @@ description: How to enroll an agent into automatic updates
Teleport supports automatic agent updates for -systemd-based Linux distributions using `apt` or `yum` package managers, -and Kubernetes clusters. The [automatic updates architecture +systemd-based Linux distributions using `apt`, `yum`, or `zypper` package +managers, and Kubernetes clusters. The [automatic updates architecture page](../../architecture/agent-update-management.mdx) describes how agent updating works. diff --git a/docs/pages/management/operations/self-hosted-automatic-agent-updates.mdx b/docs/pages/management/operations/self-hosted-automatic-agent-updates.mdx index 1c1e641442d60..6b822d53f6ebf 100644 --- a/docs/pages/management/operations/self-hosted-automatic-agent-updates.mdx +++ b/docs/pages/management/operations/self-hosted-automatic-agent-updates.mdx @@ -14,7 +14,7 @@ description: How to setup automatic agent update for self-hosted Teleport Teleport supports automatic agent updates for -systemd-based Linux distributions using `apt` or `yum` package managers, +systemd-based Linux distributions using `apt`, `yum`, and `zypper` package managers, and Kubernetes clusters. The [automatic updates architecture page](../../architecture/agent-update-management.mdx) describes how agent updating works. @@ -27,12 +27,9 @@ already done, or you are a Teleport Cloud user, you can directly Systemd agents enrolled into automatic updates can only install versions present in their package repositories. As Teleport 14 won't be published to `stable/v13`, those agents will require manual intervention to be updated to -the next major version (adding a new apt/yum repo for `stable/v14`). - -This limitation will be fixed before Teleport 14. We'll provide a rolling -update channel for agents to be able to automatically update from one major -to another. When this will happen, you will have to update the repos of the -existing agents to point to the new repo. +the next major version (adding a new APT/YUM/zypper repo for `stable/v14`). +Alternatively, you can use the `stable/rolling` channel, which contains +Teleport v13.3.2 forward, including future major releases.