opensource/teleport
3
0
Fork 0
mirror of https://github.com/gravitational/teleport.git synced 2026-09-19 01:58:44 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: refactor docker getting started guide (#62856)

Browse Source 
* checkpoints for docker getting started guide

* adding verification commands with expected output preceeding the troubleshooting checkpoints

* adding a few more checkpoint tips

* lint error with  heading

* lint error with  heading

* removing duplicate suggestion and reorganizing

* pulled in master to resolve conflicts as the directory structure changed since I started drafting these updates

* edited checkpoints, formatting, and moved k8 content

* cut down the number of items in the checkpoints, rephrased some sentences, fixed link paths as they were added before the pages was moved

* created a section forcommon troubleshooting items vs so many checkpoints

* changing container to variable

* adding back the sidebar label, and added '-t' (tty) flag to docker exec command to improve text output/alignment

* post-feedback: formatting, troubleshooting content revisions

* post-feedback: formatting, and slimming down troubleshooting content

* post-feedback: formatting, and slimming down troubleshooting content

* rephrasing intro paragraph, as most prod Teleport deployments in containers are running on k8s

* followed AI suggestions and implemented suggestions on removing previous k8 content and streamlining

* cleanup, restored backup guidance

* linter flagged for list spacing - added lines

* Apply suggestions from code review

Co-authored-by: Paul Gottschling <paul.gottschling@gmail.com>

---------

Co-authored-by: Paul Gottschling <paul.gottschling@gmail.com>
This commit is contained in:
mica
2026-06-11 17:49:04 +00:00
committed by GitHub
co-authored by Paul Gottschling
parent f583472e9a
commit 7449cd5dbf
1 changed files with 132 additions and 175 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/pages/installation/single-machine/docker.mdx
+132 -175
View File
@@ -7,48 +7,29 @@ tags:
- platform-wide
---
Docker provides a convenient way to deploy Teleport in containerized environments, offering consistent deployment across platforms and simplified dependency management. Teleport's pre-built Docker images are optimized for different use cases, from production deployments to development and troubleshooting scenarios.
In this installation guide, you'll learn how to choose the right image, configure your containers, and run Teleport services with Docker.
This guide shows you how to install and run Teleport using the official Docker images.
It covers selecting an image, configuring the container, running Teleport services, and upgrading.
## Images
We provide a pre-built Docker image for every version of Teleport. This section
describes the available Docker images.
These images are hosted on [Amazon ECR
Public](https://gallery.ecr.aws/gravitational).
Teleport publishes a pre-built Docker image for every release. Images are hosted on [Amazon ECR Public](https://gallery.ecr.aws/gravitational).
### Image suffixes
For each of the image names listed in this section, you can specify attributes
of the image by appending a suffix to the repository name or tag.
You can specify attributes of an image by appending a suffix to the repository name or tag.
Images with the `-distroless` suffix within the repository name include only the
`teleport` binary and its runtime dependencies, with no shell or utility
applications. An example is `public.ecr.aws/gravitational/teleport-distroless`
for Teleport Community Edition.
Images with the `-distroless` suffix include only the `teleport` binary and its runtime dependencies, with no shell or utility applications. An example is `public.ecr.aws/gravitational/teleport-distroless` for Teleport Community Edition.
Images with the `*-distroless-debug` suffix within the repository name 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. An
example is `public.ecr.aws/gravitational/teleport-distroless-debug`.
Images with the `-distroless-debug` suffix 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. An example is `public.ecr.aws/gravitational/teleport-distroless-debug`.
`*-distroless` and `*-distroless-debug` images support multiple architectures
natively, and do not require (or support) image suffixes. You can specify an
architecture using the `--platform` flag of `docker pull` to pull the `arm`,
`arm64` or `amd64` version of an image.
`-distroless` and `-distroless-debug` images support multiple architectures natively, and do not require (or support) image suffixes. You can specify an architecture using the `--platform` flag of `docker pull` to pull the `arm`, `arm64`, or `amd64` version of an image.
### Version tags
Images point to a static version of Teleport. Use the image's tag to specify
either:
Images point to a static version of Teleport. Use the image's tag to specify either:
- The major, minor, and patch version (e.g., `(=teleport.version=)` for the
latest version of Teleport Community Edition).
- The major version only, which implies the latest minor and patch numbers for
that major version. For example, `(=teleport.major_version=)` implies
`(=teleport.version=)`.
- The major, minor, and patch version (e.g., `(=teleport.version=)` for the latest version of Teleport Community Edition).
- The major version only, which implies the latest minor and patch numbers for that major version. For example, `(=teleport.major_version=)` implies `(=teleport.version=)`.
<Tabs>
<TabItem label="Teleport Enterprise (Managed)" scope={["team", "cloud"]}>
@@ -58,8 +39,7 @@ either:
| `public.ecr.aws/gravitational/teleport-ent-distroless:(=cloud.version=)` | No | [Distroless Debian 12](https://github.com/GoogleContainerTools/distroless) |
| `public.ecr.aws/gravitational/teleport-ent-distroless-debug:(=cloud.version=)` | Yes | [Distroless Debian 12](https://github.com/GoogleContainerTools/distroless) |
For testing, we always recommend that you use the latest Cloud release version of
Teleport Enterprise, which is currently `public.ecr.aws/gravitational/teleport-ent-distroless:(=cloud.version=)`.
For testing, we always recommend that you use the latest Cloud release version of Teleport Enterprise, which is currently `public.ecr.aws/gravitational/teleport-ent-distroless:(=cloud.version=)`.
</TabItem>
<TabItem label="Teleport Enterprise (Self-Hosted)" scope={["enterprise"]}>
@@ -69,52 +49,49 @@ Teleport Enterprise, which is currently `public.ecr.aws/gravitational/teleport-e
| `(=teleport.latest_ent_docker_image=)` | No | [Distroless Debian 12](https://github.com/GoogleContainerTools/distroless) |
| `(=teleport.latest_ent_debug_docker_image=)` | Yes | [Distroless Debian 12](https://github.com/GoogleContainerTools/distroless) |
We also provide the following images for FIPS builds of Teleport Enterprise:
We provide the following images for FIPS builds of Teleport Enterprise:
| Image name | Includes troubleshooting tools | Image base |
| - | - | - |
| `public.ecr.aws/gravitational/teleport-ent-fips-distroless:(=teleport.version=)` | No | [Distroless Debian 12](https://github.com/GoogleContainerTools/distroless) |
| `public.ecr.aws/gravitational/teleport-ent-fips-distroless-debug:(=teleport.version=)` | Yes | [Distroless Debian 12](https://github.com/GoogleContainerTools/distroless) |
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=)`.
</TabItem>
<TabItem label="Teleport Community Edition" scope={["oss"]}>
|Image name|Troubleshooting Tools?|Image base|
|-|-|-|
|`(=teleport.latest_oss_docker_image=)`|No|[Distroless Debian 12](https://github.com/GoogleContainerTools/distroless)|
|`(=teleport.latest_oss_debug_docker_image=)`|Yes|[Distroless Debian 12](https://github.com/GoogleContainerTools/distroless)|
| Image name | Includes troubleshooting tools | Image base |
| - | - | - |
| `(=teleport.latest_oss_docker_image=)` | No | [Distroless Debian 12](https://github.com/GoogleContainerTools/distroless) |
| `(=teleport.latest_oss_debug_docker_image=)` | Yes | [Distroless Debian 12](https://github.com/GoogleContainerTools/distroless) |
For testing, we always recommend that you use the latest release version of
Teleport, which is currently `(=teleport.latest_oss_docker_image=)`.
For testing, we always recommend that you use the latest release version of Teleport, which is currently `(=teleport.latest_oss_docker_image=)`.
</TabItem>
</Tabs>
### Interacting with distroless images
Teleport images are based on Google's [Distroless](https://github.com/GoogleContainerTools/distroless) images.
Those images don't contain any shell.
Teleport images are based on Google's [Distroless](https://github.com/GoogleContainerTools/distroless) images. These images do not contain a shell.
To execute Teleport commands on containers based on these images, run commands similar to the following:
```code
# in docker
$ docker run -i my-container tctl status
$ docker exec -it <Var name="teleport-container"/> tctl status
# in Kubernetes
$ kubectl exec -i my-pod -- tctl status
$ kubectl exec -i <Var name="pod-name"/> -- tctl status
# sending local files via stdin
$ kubectl exec -i my-pod -- tctl create -f < my-local-file.yaml
$ kubectl exec -i <Var name="pod-name"/> -- tctl create -f < my-local-file.yaml
# retrieving the teleport service config file from the configmap
$ kubectl get configmap teleport-cluster-auth -o jsonpath="{.data['teleport\.yaml']}"
# retrieving output via stdout and tar
$ kubectl exec -i my-pod -- tctl auth sign --user admin --format tls --ttl 10m --tar -o admin| tar xv -C local
$ kubectl exec -i <Var name="pod-name"/> -- tctl auth sign --user admin --format tls --ttl 10m --tar -o admin | tar xv -C local
$ ls -l local
total 24
-rw------- 1 trent staff 1318 Jul 24 15:52 admin.cas
@@ -128,34 +105,25 @@ Alternatively, you can use the debug variant of the image, which contains [busyb
$ docker run -it --entrypoint="" (=teleport.latest_oss_debug_docker_image=) busybox sh
```
### Machine & Workload Identity (tbot)
### Machine & Workload Identity (tbot) image
We also provide a slimmed down distroless image that only contains the `tbot`
binary for use with Teleport Machine & Workload Identity.
We also provide a slimmed-down distroless image that contains only the `tbot` binary for use with Teleport Machine & Workload Identity.
| Image name | FIPS Support | Image base |
|--------------------------------------------------------------------------|--------------|----------------------------------------------------------------------------|
| `public.ecr.aws/gravitational/tbot-distroless:(=teleport.version=)` | No | [Distroless Debian 12](https://github.com/GoogleContainerTools/distroless) |
| `public.ecr.aws/gravitational/tbot-fips-distroless:(=teleport.version=)` | Yes | [Distroless Debian 12](https://github.com/GoogleContainerTools/distroless) |
| Image name | FIPS support | Image base |
| - | - | - |
| `public.ecr.aws/gravitational/tbot-distroless:(=teleport.version=)` | No | [Distroless Debian 12](https://github.com/GoogleContainerTools/distroless) |
| `public.ecr.aws/gravitational/tbot-fips-distroless:(=teleport.version=)` | Yes | [Distroless Debian 12](https://github.com/GoogleContainerTools/distroless) |
The version tagging follows the same pattern as the main `teleport-distroless`
image.
The version tagging follows the same pattern as the main `teleport-distroless` image.
Whilst the `teleport-distroless` image also includes `tbot`, using the `tbot`
specific image should be preferred for Machine & Workload Identity deployments.
This image is smaller, improving pull times, and has a smaller attack surface.
In addition, the image is customized in order to improve the experience of
running `tbot` in a container environment.
While the `teleport-distroless` image also includes `tbot`, prefer the `tbot`-specific image for Machine & Workload Identity deployments.
This image is smaller, which improves pull times, and has a smaller attack surface. The image is also customized to improve the experience of running `tbot` in a container environment.
To learn more, read the
[Deploying Machine & Workload Identity on Kubernetes](../../machine-workload-identity/deployment/kubernetes.mdx)
guide.
To learn more, read the [Deploying Machine & Workload Identity on Kubernetes](../../machine-workload-identity/deployment/kubernetes.mdx) guide.
## Running Teleport on Docker
When running a container from one of the images listed above, consider the
container equivalent to running the `teleport` binary. The Teleport container
requires access to a file system and network ports.
When running a container from one of the images listed above, treat the container as equivalent to running the `teleport` binary directly. The Teleport container requires access to a file system and network ports.
### Configuration
@@ -165,27 +133,21 @@ configuration directory to `/etc/teleport` in the container so Teleport can find
### Data directory
All Teleport processes read from and write to a data directory, which by default
is `/var/lib/teleport`. Make sure the data directory is mounted to your Teleport
container.
All Teleport processes read from and write to a data directory, which by default is `/var/lib/teleport`.
Make sure the data directory is mounted to your Teleport container. If you do not mount persistent storage, cluster state is lost when the container is recreated.
### License file
If your Teleport Enterprise container runs the Auth Service, you will need to
give it access to a license file at the path named in the configuration, which
is `/var/lib/teleport/license.pem` by default. Make sure a license exists at
this location in the Teleport container's data directory.
If your Teleport Enterprise container runs the Auth Service, you will need to give it access to a license file at the path named in the configuration,
which is `/var/lib/teleport/license.pem` by default. Make sure a license exists at this location in the Teleport container's data directory.
### Other file paths
Depending on the configuration settings you assign on your Teleport container,
you will need to make sure that any file paths you name are mounted on the
container.
Depending on the configuration settings you assign on your Teleport container, you will need to make sure that any
file paths you name are mounted on the container.
For example, if you are running the Teleport Proxy Service on a container, you
need to mount the directory containing TLS credentials to your Teleport
container, then assign the following fields in the container's configuration
file to the appropriate paths:
For example, if you are running the Teleport Proxy Service on a container, mount the directory containing TLS credentials
to your Teleport container, then assign the following fields in the container's configuration file to the appropriate paths:
```yaml
proxy_service:
@@ -194,135 +156,130 @@ proxy_service:
cert_file: /my/path/cert.pem
```
See the Teleport [Configuration Reference](../../reference/deployment/config.mdx) for whether a
field you would like to assign requires a file path.
See the Teleport [Configuration Reference](../../reference/deployment/config.mdx) for whether a field you would like to assign
requires a file path.
### Ports
A single Teleport process can run multiple services, each of which listens on a
specific set of ports depending on your configuration. See our [Networking
Reference](../../reference/deployment/networking.mdx#ports) for the ports on your Teleport
container to expose.
A single Teleport process can run multiple services, each of which listens on a specific set of ports depending on your configuration.
See our [Networking Reference](../../reference/deployment/networking.mdx#ports) for the ports on your Teleport container to expose.
### Extracting certificates from distroless images
Extracting certificates created with `tctl auth sign` from a container running
a distroless image can be tricky due to the absence of a shell and other OS tools.
Extracting certificates created with `tctl auth sign` from a container running a distroless image can be tricky due to the absence of a shell and other OS tools.
Where possible you should log into the Teleport cluster using `tsh` and use
`tctl auth sign` locally to generate certificates. This way the action will be
logged against your Teleport user and be subject to all of the usual Teleport
RBAC policies in your cluster.
Where possible, log into the Teleport cluster using `tsh` and use `tctl auth sign` locally to generate certificates. This way the action is logged against your Teleport user and is subject to all of the usual Teleport RBAC policies in your cluster.
If this is not possible, use `tctl auth sign --tar` to collect all the files
generated by `tctl auth sign` into a `tar` archive, which is streamed directly
to `stdout`. The resulting certificates are never stored on the container
filesystem. You can either pipe this output directly to `tar`, or redirect it
to a local file for later use.
If this is not possible, use `tctl auth sign --tar` to collect all the files generated by `tctl auth sign` into a `tar` archive, which is streamed directly to `stdout`. When you use `--tar`, the `-o` flag changes meaning: instead of writing files to disk, it acts as a name prefix for the entries inside the tar stream. As a result, no certificate files are written to the container filesystem.
You can either pipe this output directly to `tar`, or redirect it to a local file for later use.
For example:
```code
$ docker exec ${TELEPORT_CONTAINER} \
$ docker exec <Var name="teleport-container"/> \
tctl auth sign --user alice --format tls -o alice.local --tar | tar xv
x alice.local.crt
x alice.local.key
x alice.local.cas
```
## Example of running a Teleport container
## Example: running a Teleport container locally
In this example, we will show you how to run the Teleport Auth Service and Proxy
Service on a local Docker container using Teleport Community Edition.
In this example, you will run the Teleport Auth Service and Proxy Service on a local Docker container using Teleport Community Edition.
Since this container uses a self-signed certificate, we do not recommend using
this configuration to protect any infrastructure outside your workstation. You
can, however, join other local Docker containers to it using the [token
method](../agents/join-token.mdx).
Since this container uses a self-signed certificate, we do not recommend using this configuration to protect any infrastructure outside your workstation.
You can, however, join other local Docker containers to it using the [token method](../../installation/agents/join-token.mdx).
First, create directories in your home directory to mount to the container. The
Teleport container will write its configuration and data to these directories:
1. Create directories in your home directory to mount to the container. The Teleport container will write its configuration and data to these directories:
```code
$ mkdir -p ~/teleport/config ~/teleport/data
```
```code
$ mkdir -p ~/teleport/config ~/teleport/data
```
Run `teleport configure` from the Teleport container to generate a configuration
file. This sets the container's name to `localhost` so your browser can trust
the Proxy Service's self-signed TLS certificate:
1. Run `teleport configure` from the Teleport container to generate a configuration file. This sets the container's name to `localhost`
so your browser can trust the Proxy Service's self-signed TLS certificate:
```code
$ docker run --hostname localhost --rm \
--entrypoint=/usr/local/bin/teleport \
<Var name="(=teleport.latest_oss_docker_image=)" /> configure --roles=proxy,auth > ~/teleport/config/teleport.yaml
```
```code
$ docker run --hostname localhost --rm \
--entrypoint=/usr/local/bin/teleport \
(=teleport.latest_oss_docker_image=) configure --roles=proxy,auth > ~/teleport/config/teleport.yaml
```
Start Teleport on your container:
1. Start Teleport on your container. This container runs both the Auth Service and Proxy Service in a single process for local testing:
```code
$ docker run --hostname localhost --name teleport \
-v ~/teleport/config:/etc/teleport \
-v ~/teleport/data:/var/lib/teleport \
-p 3025:3025 -p 3080:3080 \
<Var name="(=teleport.latest_oss_docker_image=)" />
```
```code
$ docker run --hostname localhost --name teleport \
-v ~/teleport/config:/etc/teleport \
-v ~/teleport/data:/var/lib/teleport \
-p 3025:3025 -p 3080:3080 \
(=teleport.latest_oss_docker_image=)
```
From there, open another terminal and make sure your Teleport container's web
API is functioning as intended:
1. In a new terminal, confirm that the Teleport container's web API is functioning as intended:
```code
$ curl --insecure https://localhost:3080/webapi/ping | jq
```
```code
$ curl --insecure https://localhost:3080/webapi/ping | jq
```
You should see JSON output similar to the following:
The command returns JSON describing the cluster, including `server_version`, `cluster_name`, and details for each service. The `--insecure` flag is required because Teleport is using a self-signed certificate.
In production, provision TLS credentials to the Proxy Service from a trusted CA, e.g., Let's Encrypt.
```json
{
"auth": {
"type": "local",
"second_factor": "otp",
"preferred_local_mfa": "otp",
"local": {
"name": ""
},
"private_key_policy": "none",
"device_trust_disabled": true,
"has_motd": false
},
"proxy": {
"kube": {
"enabled": true,
"listen_addr": "0.0.0.0:3080"
},
"ssh": {
"listen_addr": "0.0.0.0:3080",
"tunnel_listen_addr": "0.0.0.0:3080",
"web_listen_addr": "0.0.0.0:3080"
},
"db": {
"postgres_listen_addr": "0.0.0.0:3080",
"mysql_listen_addr": "0.0.0.0:3080"
},
"tls_routing_enabled": true
},
"server_version": "12.1.5",
"min_client_version": "11.0.0",
"cluster_name": "localhost",
"automatic_upgrades": false
}
```
<Checkpoint
title="The Teleport container's Web API is functioning as intended"
description="The command above returns a JSON document describing the cluster."
>
We are using the `--insecure` flag to trust Teleport's self-signed certificate.
In production, you will want to provision TLS credentials to the Proxy Service
from a trusted CA, e.g., Let's Encrypt.
- If you see `curl: (7) Failed to connect to localhost port 3080`, verify the container is running with `docker ps` and that port 3080 is correctly mapped.
- If you see `curl: (35) SSL connect error` or certificate errors, ensure you're using the `--insecure` flag for self-signed certificates.
- If the response is empty or malformed, check container logs with `docker logs teleport` for startup errors.
- If you see `connection refused`, the Teleport process may still be initializing. Wait a few seconds and try again.
</Checkpoint>
## Upgrading Teleport on Docker
To upgrade a Teleport container running on Docker:
1. Back up the Teleport backend before upgrading. Major-version upgrades run schema migrations on the data directory that cannot be reversed by starting an older image. For backup procedures and supported upgrade paths, see [Upgrading Teleport](../../upgrading/overview.mdx).
1. Stop the container with `docker stop teleport`.
1. Leave the container's data directory in place.
1. Stop the container.
1. Run a new container with an image based on a newer Teleport version, mounting
the data directory as you did while running the container initially. As long
as the data directory contains the same content as before the upgrade, the
Teleport container does not need to re-join the cluster.
1. Run a new container with an image based on a newer Teleport version, mounting the data directory as you did when running the container initially. As long as the data directory contains the same content as before the upgrade, the Teleport container does not need to re-join the cluster.
1. Verify the upgraded version:
```code
$ curl --insecure https://localhost:3080/webapi/ping | jq '.server_version'
```
If the upgrade fails or the container doesn't start, see [Container fails to start after upgrade](#container-fails-to-start-after-upgrade) below.
## Troubleshooting
The sections below cover common issues when running Teleport on Docker. Each section names a specific symptom so you can scan for what you are seeing.
### Port already in use
If `docker run` fails with `bind: address already in use` for ports 3025 or 3080, another process on the host is using those ports. Find the conflicting process with `lsof -i :3080` (macOS or Linux), then either stop it or map Teleport to a different host port (for example, `-p 3081:3080`).
### Configuration file not found
If the container exits immediately with `failed to read configuration` or `no such file or directory` for `/etc/teleport/teleport.yaml`, the configuration file is not mounted into the container at the expected path. Verify that the configuration file exists on the host and that you mount its parent directory to `/etc/teleport` inside the container, not the file itself. Mounting a single file rather than its parent directory can cause issues when the file is replaced or symlinked.
### Permission denied writing to the data directory
If the container fails to start with `permission denied` errors against `/var/lib/teleport`, the container's user does not have write access to the mounted data directory. Distroless images run as a non-root user, so host directory permissions need to allow that user to write. Adjust permissions on the host directory with `chmod` or `chown` so the container's user can write to it.
### `tctl auth sign --tar` produces no output
If `tctl auth sign --tar | tar xv` runs but no certificate files appear locally, the underlying `tctl auth sign` call most likely failed and emitted an error message instead of a tar archive. You may also see `tar: This does not look like a tar archive`.
To diagnose, run `tctl auth sign` without the `--tar` flag and confirm that the user, format, and other parameters are valid. Once the command succeeds, add `--tar` back and pipe the output to `tar xv`.
### Container fails to start after upgrade
If the container fails to start after upgrading to a newer Teleport version, check the logs with `docker logs teleport` for migration or compatibility errors. Confirm that you did not skip a major version: Teleport supports upgrades from one major version to the next, and skipping versions is not supported.
Do not roll back by starting the previous image version against the upgraded data directory. Major-version upgrades run schema migrations that an older Auth Service cannot read, and doing so can leave the backend in an unusable state. To roll back safely, restore the backend from the backup taken before the upgrade. See [Upgrading Teleport](../../upgrading/overview.mdx) for the supported procedure.