diff --git a/docs/pages/includes/docker-images-oss.mdx b/docs/pages/includes/docker-images-oss.mdx index cc93575904ca2..a7c86c82f03ca 100644 --- a/docs/pages/includes/docker-images-oss.mdx +++ b/docs/pages/includes/docker-images-oss.mdx @@ -1,5 +1,6 @@ We provide a pre-built multi-arch Docker image for every version of Teleport, -including images for `amd64`, `arm`, and `arm64` architectures. +including images for `amd64`, `arm`, and `arm64` architectures. Our images contain only Teleport binaries +and their application dependencies. These images are hosted on Amazon ECR Public. All tags under `public.ecr.aws/gravitational/teleport-distroless` [are Teleport Open Source images](https://gallery.ecr.aws/gravitational/teleport-distroless). diff --git a/docs/pages/includes/enterprise/docker-images.mdx b/docs/pages/includes/enterprise/docker-images.mdx index 1261a2f3641ed..25ad0334044ed 100644 --- a/docs/pages/includes/enterprise/docker-images.mdx +++ b/docs/pages/includes/enterprise/docker-images.mdx @@ -1,13 +1,21 @@ -This table gives an idea of how our image naming scheme works. We offer images which point to a static version of Teleport Enterprise, as well as images which are -automatically rebuilt every night. +This table gives an idea of how our image naming scheme works. We offer images +which point to a static version of Teleport Enterprise, as well as images which are +automatically rebuilt every night. Our images contain only Teleport binaries and their application dependencies. -Nightly images point to the latest version of Teleport Enterprise from the three most recent release branches. -They are stable, and we recommend their use to easily keep your Teleport Enterprise installation up to date. +Nightly images point to the latest version of Teleport Enterprise from the three +most recent release branches. They are stable, and we recommend their use to easily +keep your Teleport Enterprise installation up to date. -These images are hosted on our [Amazon ECR Public repository](https://gallery.ecr.aws/gravitational/teleport-ent-distroless). All tags under `public.ecr.aws/gravitational/teleport-ent-distroless` are Teleport Enterprise images. Each tag points to a multi-arch image, containing Teleport for `arm`, `arm64` and `amd64`. +These images are hosted on our [Amazon ECR Public repository](https://gallery.ecr.aws/gravitational/teleport-ent-distroless). +All tags under `public.ecr.aws/gravitational/teleport-ent-distroless` are +Teleport Enterprise images. Each tag points to a multi-arch image, containing +Teleport for `arm`, `arm64` and `amd64`. FIPS images are still posted to our [Legacy Amazon ECR Public repository](https://gallery.ecr.aws/gravitational/teleport-ent). -You can specify the architecture of a Teleport FIPS Docker image by adding a postfix to the image tag, e.g., `public.ecr.aws/gravitational/teleport:(=teleport.major_version=)-arm64`. Versions without an architecture postfix use the `amd64` architecture, e.g., `public.ecr.aws/gravitational/teleport:(=teleport.major_version=)`. +You can specify the architecture of a Teleport FIPS Docker image by adding a +postfix to the image tag, e.g., `public.ecr.aws/gravitational/teleport:(=teleport.major_version=)-arm64`. +Versions without an architecture postfix use the `amd64` architecture, e.g., +`public.ecr.aws/gravitational/teleport:(=teleport.major_version=)`. | Image name | Open Source or Enterprise? | Teleport version | Image automatically updated? | Includes troubleshooting tools | Image base | | - | - | - | - | - | - | @@ -18,10 +26,12 @@ You can specify the architecture of a Teleport FIPS Docker image by adding a pos | `(=teleport.latest_ent_debug_docker_image=)` | Enterprise | The version specified in the image's tag (i.e. (=teleport.version=)) | No | Yes | [Distroless Debian 11](https://github.com/GoogleContainerTools/distroless) | | `(=teleport.latest_ent_docker_image=)-fips` | Enterprise FIPS | The version specified in the image's tag (i.e. (=teleport.version=)) | No | Yes | [Ubuntu 20.04](https://hub.docker.com/\_/ubuntu) | -For testing, we always recommend that you use the latest release version of Teleport Enterprise, which is currently `(=teleport.latest_ent_docker_image=)`. +For testing, we always recommend that you use the latest release version of +Teleport Enterprise, which is currently `(=teleport.latest_ent_docker_image=)`. [Ubuntu 20.04](https://hub.docker.com/\_/ubuntu)-based images for non-FIPS Teleport are available from our [Legacy Amazon ECR Public repository](https://gallery.ecr.aws/gravitational/teleport-ent). -The `*-debug` images include a Busybox shell and tool suite in addition to Teleport, and are intended for troubleshooting deployments only. They are not intended for production use. +The `*-debug` images include a Busybox shell and tool suite in addition to Teleport, +and are intended for troubleshooting deployments only. They are not intended for production use. diff --git a/docs/pages/management/guides/docker.mdx b/docs/pages/management/guides/docker.mdx index 84dc4979f3af4..aa129761315b8 100644 --- a/docs/pages/management/guides/docker.mdx +++ b/docs/pages/management/guides/docker.mdx @@ -7,13 +7,9 @@ h1: Run Teleport using Docker This guide will explain how to run a container using one of Teleport's Docker images and execute commands on that container via Teleport's `tsh` client. - - Since all of Teleport's services are run from the same binary, you can -use our Docker image to run Node services (e.g., the Database Service or App -Service) or explore the Auth and Proxy Services locally. - - +use our Docker image to run Teleport services (e.g., the Database Service or Application +Service) or explore the Auth and Proxy Services locally. In this guide, we will also show you how to join a server (in this case, an Ubuntu container) to your local Dockerized Teleport cluster. ## Prerequisites @@ -22,11 +18,11 @@ Service) or explore the Auth and Proxy Services locally. - Docker v(=docker.version=) or later. -```code -$ docker version -# Client: Docker Engine - Community -# Version: (=docker.version=) -``` + ```code + $ docker version + # Client: Docker Engine - Community + # Version: (=docker.version=) + ``` - The `tsh` client tool, which ships with the `teleport` binary. Visit [Download Teleport](https://goteleport.com/download/) to download `tsh`. @@ -36,13 +32,14 @@ $ docker version - A Teleport Enterprise account. If you do not have one, use our [signup form](https://goteleport.com/signup/enterprise/) to schedule a demo with the Teleport Sales Team. + - Docker v(=docker.version=) or later. -```code -$ docker version -# Client: Docker Engine - Community -# Version: (=docker.version=) -``` + ```code + $ docker version + # Client: Docker Engine - Community + # Version: (=docker.version=) + ``` - The `tsh` client tool, which ships with the `teleport` binary. Visit the [customer portal](https://dashboard.gravitational.com/web/login) to download Teleport. @@ -81,12 +78,12 @@ $ mkdir -p ~/teleport/config ~/teleport/data # This container will write the config and immediately exit--this is expected. $ docker run --hostname localhost --rm \ --entrypoint=/usr/local/bin/teleport \ - ${TELEPORT_DOCKER_IMAGE} configure > ~/teleport/config/teleport.yaml + ${TELEPORT_DOCKER_IMAGE} configure --roles=proxy,auth > ~/teleport/config/teleport.yaml # Start Teleport with mounted config and data directories, plus all ports $ docker run --hostname localhost --name teleport \ -v ~/teleport/config:/etc/teleport \ -v ~/teleport/data:/var/lib/teleport \ - -p 3023:3023 -p 3025:3025 -p 3080:3080 \ + -p 3025:3025 -p 3080:3080 \ ${TELEPORT_DOCKER_IMAGE} ``` @@ -106,6 +103,7 @@ $ TELEPORT_DOCKER_IMAGE=(=teleport.latest_ent_docker_image=) # into the container. $ mkdir -p ~/teleport/config ~/teleport/data ``` + (!docs/pages/includes/enterprise/obtainlicense.mdx!) Move your `license.pem` file to `~/teleport/data`. @@ -115,12 +113,12 @@ Move your `license.pem` file to `~/teleport/data`. # This container will write the config and immediately exit--this is expected. $ docker run --hostname localhost --rm \ --entrypoint=/usr/local/bin/teleport \ - ${TELEPORT_DOCKER_IMAGE} configure > ~/teleport/config/teleport.yaml + ${TELEPORT_DOCKER_IMAGE} configure --roles=proxy,auth > ~/teleport/config/teleport.yaml # Start Teleport with mounted config and data directories, plus all ports $ docker run --hostname localhost --name teleport \ -v ~/teleport/config:/etc/teleport \ -v ~/teleport/data:/var/lib/teleport \ - -p 3023:3023 -p 3025:3025 -p 3080:3080 \ + -p 3025:3025 -p 3080:3080 \ ${TELEPORT_DOCKER_IMAGE} ``` @@ -149,10 +147,108 @@ The Web UI will be available at the displayed URL. (!docs/pages/includes/insecure-certificate.mdx!) -## Step 4/4. tsh into your Teleport container +## Step 4/4. Try server access + +The Teleport container we spun up earlier runs the Teleport Proxy and Auth Services. You can try +accessing a server through Teleport by installing the Teleport SSH Service +on an Ubuntu Docker container. Here are the steps. + +First start an Ubuntu container: + +```code +$ docker run -it --name=example-server --hostname=example-server ubuntu:latest bash +``` +After you start your shell within the Ubuntu container, run the following commands to install the Teleport SSH Service: + + + +```code +# Docker container will start and you can install Teleport +$ apt update && apt install curl -y +# Download Teleport's PGP public key + +$ curl https://apt.releases.teleport.dev/gpg \ +-o /usr/share/keyrings/teleport-archive-keyring.asc +# Source variables about OS version + +$ source /etc/os-release +# Add the Teleport APT repository for v12. You'll need to update this +# file for each major release of Teleport. +# Note: if using a fork of Debian or Ubuntu you may need to use '$ID_LIKE' +# and the codename your distro was forked from instead of '$ID' and '$VERSION_CODENAME'. +# Supported versions are listed here: https://github.com/gravitational/teleport/blob/master/build.assets/tooling/cmd/build-os-package-repos/runners.go#L42-L67 + +$ echo "deb [signed-by=/usr/share/keyrings/teleport-archive-keyring.asc] \ +https://apt.releases.teleport.dev/${ID?} ${VERSION_CODENAME?} stable/v12" \ +| tee /etc/apt/sources.list.d/teleport.list > /dev/null +$ apt-get update +$ apt-get install teleport +``` + + + + +```code +# Docker container will start and you can install Teleport +$ apt update && apt install curl -y +# Download Teleport's PGP public key + +$ curl https://apt.releases.teleport.dev/gpg \ +-o /usr/share/keyrings/teleport-archive-keyring.asc +# Source variables about OS version + +$ source /etc/os-release +# Add the Teleport APT repository for v12. You'll need to update this +# file for each major release of Teleport. +# Note: if using a fork of Debian or Ubuntu you may need to use '$ID_LIKE' +# and the codename your distro was forked from instead of '$ID' and '$VERSION_CODENAME'. +# Supported versions are listed here: https://github.com/gravitational/teleport/blob/master/build.assets/tooling/cmd/build-os-package-repos/runners.go#L42-L67 + +$ echo "deb [signed-by=/usr/share/keyrings/teleport-archive-keyring.asc] \ +https://apt.releases.teleport.dev/${ID?} ${VERSION_CODENAME?} stable/v12" \ +| tee /etc/apt/sources.list.d/teleport.list > /dev/null +$ apt-get update +$ apt-get install teleport-ent +``` + + + + +Keep the Docker `example-server` terminal running and run a separate command +in another terminal to create a join token that the Teleport SSH Service will use to establish trust with your Teleport cluster: + +```code +$ docker exec teleport tctl nodes add +# The invite token: 02adc78db14c4958a94a78e216fba689 +# This token will expire in 30 minutes. + +# Run this on the new node to join the cluster: + +# > teleport start \ + --roles=node \ + --token=02adc78db14c4958a94a78e216fba689 \ + --ca-pin=sha256:51c0e24825fae3133da0d8659f4dd533808e2dc92c000b577c8725b6cbcb66ae \ + --auth-server=172.17.0.2:3025 -After you have finished creating your user, open a second terminal and issue the -command, which will log in to your Teleport cluster via the Proxy Service at +# Please note: + +# - This invitation token will expire in 30 minutes +# - 172.17.0.2:3025 must be reachable from the new node + ``` + +Copy the full `teleport start` command and run it in the `example-server` Docker container shell. + +Open another terminal window and confirm that you joined the SSH Service to the cluster + with `tctl nodes ls` on the `teleport` container. + +```code +$ docker exec teleport tctl nodes ls +# Host UUID Public Address Labels Version +# -------------- ------------------- --------------- ------ ------- +# example-server edc6b7ae-0ae5-43... 172.17.0.3:3022 12.2.2 +``` + +Issue this command, which will log in to your Teleport cluster via the Proxy Service at `localhost`. ```code @@ -160,7 +256,7 @@ $ tsh login --proxy=localhost --insecure --user=testuser ``` - The `--insecure` flag is not recommended in production but can be used to bypass certain TLS and port requirements when testing locally. +The `--insecure` flag is not recommended in production but can be used to bypass certain TLS and port requirements when testing locally. You will be prompted to enter the password and One-Time Passcode you created for your user `testuser`: @@ -173,7 +269,7 @@ Enter your OTP token: After successfully authenticating you should see the following in your terminal: -``` +```text WARNING: You are using insecure connection to Teleport proxy https://localhost:3080 > Profile URL: https://localhost:3080 Logged in as: testuser @@ -189,22 +285,88 @@ Running the next command will display all Teleport Nodes you're connected to: ```code $ tsh ls - -# Node Name Address Labels -# --------- -------------- ------------------------------- -# localhost 127.0.0.1:3022 env=example, hostname=localhost +# Node Name Address Labels +# -------------- --------------- ------ +# example-server 172.17.0.3:3022 ``` -To SSH into the local Node called `localhost`: +To SSH into the local container called `example-server`: ```code -$ tsh ssh root@localhost +$ tsh ssh root@example-server ``` This will bring up the Linux command prompt where you can issue Bash commands, traverse the directory tree, and explore the container contents: ```txt -root@localhost:~# +root@example-server:~# +``` + +After exiting the session you can replay the interaction from the command line: + +```code +$ tsh recordings ls +# ID Type Participants Hostname Timestamp +# ------------------------------------ ---- ------------ -------------- ------------------------ +# 1da4faa9-01e9-4241-875f-4143f302c9c4 ssh testuser example-server Apr 13 2023 16:46:59 UTC +$ tsh play 1da4faa9-01e9-4241-875f-4143f302c9c4 +``` + +## Troubleshooting + +Teleport provides a container image that includes a Busybox shell. This image is not intended +for production. You will need to stop the non-debug container and start again with the +debug version to use. + +```code +# Stop teleport container +$ docker stop teleport +# Remove teleport container so another can be started with the same name +$ docker rm teleport +``` + + + + +Use the debug image with the same data and configuration. + +```code +# Debug Docker image to use. Defaults to the host architecture. Use the `--platform` +# option in `docker run` to override. +$ TELEPORT_DOCKER_IMAGE=(=teleport.latest_oss_debug_docker_image=) +# Start Teleport with mounted config and data directories, plus all ports +$ docker run --hostname localhost --name teleport \ + -v ~/teleport/config:/etc/teleport \ + -v ~/teleport/data:/var/lib/teleport \ + -p 3025:3025 -p 3080:3080 \ + ${TELEPORT_DOCKER_IMAGE} +``` + + + + +Use the debug image with the same data and configuration. + +```code +# Debug Docker image to use. Defaults to the host architecture. Use the `--platform` +# option in `docker run` to override. +$ TELEPORT_DOCKER_IMAGE=(=teleport.latest_ent_debug_docker_image=) +# Start Teleport with mounted config and data directories, plus all ports +$ docker run --hostname localhost --name teleport \ + -v ~/teleport/config:/etc/teleport \ + -v ~/teleport/data:/var/lib/teleport \ + -p 3025:3025 -p 3080:3080 \ + ${TELEPORT_DOCKER_IMAGE} +``` + + + + +Now you can open a `sh` shell within the Docker container to perform any troubleshooting. + +```code +$ docker exec -it teleport sh +$ tctl status ``` ## Next steps