Skip to main content
Version: 18.x (unreleased)

Installing Teleport on Docker

Report an issue with this page

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.

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.

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.

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-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.

*-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:

  • The major, minor, and patch version (e.g., 17.0.0-dev 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, 17 implies 17.0.0-dev.
Image nameIncludes troubleshooting toolsImage base
public.ecr.aws/gravitational/teleport-ent-distroless:17.5.2NoDistroless Debian 12
public.ecr.aws/gravitational/teleport-ent-distroless-debug:17.5.2YesDistroless Debian 12

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:17.5.2.

Interacting with distroless images​

Since version 15, Teleport images are based on Google's Distroless images. Those images don't contain any shell.

To execute Teleport commands on containers based on these images, run commands similar to the following:

in docker
docker run -i my-container tctl status

in Kubernetes
kubectl exec -i my-pod -- tctl status

sending local files via stdin
kubectl exec -i my-pod -- 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
ls -l local
total 24-rw-------  1 trent  staff  1318 Jul 24 15:52 admin.cas-rw-------  1 trent  staff  1895 Jul 24 15:52 admin.crt-rw-------  1 trent  staff  1679 Jul 24 15:52 admin.key

Alternatively, you can use the debug variant of the image, which contains busybox and a minimal shell invocable via busybox sh:

docker run -it --entrypoint="" public.ecr.aws/gravitational/teleport-distroless-debug:13.3.7 busybox sh

Machine ID (tbot)​

We also provide a slimmed down distroless image that only contains the tbot binary for use with Teleport Machine ID.

Image nameFIPS SupportImage base
public.ecr.aws/gravitational/tbot-distroless:17.0.0-devNoDistroless Debian 12
public.ecr.aws/gravitational/tbot-fips-distroless:17.0.0-devYesDistroless Debian 12

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 ID 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.

To learn more, read the Deploying Machine ID on Kubernetes 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.

Configuration​

Teleport processes read their configuration from a local file path, which is /etc/teleport.yaml by default. Make sure this file path is mounted to your Teleport container.

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.

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.

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.

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:

proxy_service:
  https_keypairs:
  - key_file: /my/path/key.pem
    cert_file: /my/path/cert.pem

See the Teleport Configuration Reference 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 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.

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.

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.

For example:

docker exec ${TELEPORT_CONTAINER} \  tctl auth sign --user alice --format tls -o alice.local --tar | tar xv
x alice.local.crtx alice.local.keyx alice.local.cas

Example of running a Teleport container​

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.

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.

First, create directories in your home directory to mount to the container. The Teleport container will write its configuration and data to these directories:

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:

docker run --hostname localhost --rm \  --entrypoint=/usr/local/bin/teleport \  public.ecr.aws/gravitational/teleport-distroless:13.3.7 configure --roles=proxy,auth > ~/teleport/config/teleport.yaml

Start Teleport on your container:

docker run --hostname localhost --name teleport \  -v ~/teleport/config:/etc/teleport \  -v ~/teleport/data:/var/lib/teleport \  -p 3025:3025 -p 3080:3080 \  public.ecr.aws/gravitational/teleport-distroless:13.3.7

From there, open another terminal and make sure your Teleport container's web API is functioning as intended:

curl --insecure https://localhost:3080/webapi/ping

You should see JSON output similar to the following:

{
  "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
}

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.

Upgrading Teleport on Docker​

To upgrade a Teleport container running on Docker:

  1. Leave the container's data directory in place.
  2. Stop the container.
  3. 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.