The deployment of Teleport within containerized environments represents a strategic shift toward infrastructure-as-code and consistent environment management. By leveraging Docker, organizations can abstract the underlying host operating system, ensuring that the Teleport binary and its necessary runtime dependencies remain consistent from a development laptop to a production Ubuntu server. This containerization strategy simplifies dependency management, which is critical for a security-focused platform where version drift can lead to vulnerabilities or configuration mismatches. Teleport's architecture, which manages access to SSH servers, Kubernetes clusters, applications, and databases, requires high availability and strict state management, making the choice of Docker images and volume persistence a primary architectural concern.
Architectural Overview of Teleport Docker Images
Teleport provides a sophisticated array of pre-built Docker images designed to cater to specific operational requirements, ranging from lean production environments to detailed debugging sessions. These images are centrally hosted on Amazon ECR Public, ensuring high availability and fast pull times across global AWS regions and external networks.
The selection of an image suffix is not merely a naming convention but a technical decision that affects the security posture and utility of the container.
Distroless Images
The images featuring the-distrolesssuffix, such aspublic.ecr.aws/gravitational/teleport-distroless, are engineered for production environments. These images contain only the teleport binary and its essential runtime dependencies. By removing the shell and other utility applications, the attack surface is drastically reduced. From a security perspective, this means that even if a container is compromised, an attacker lacks the basic tools (likeshorls) required to perform reconnaissance or execute lateral movement within the container.Distroless Debug Images
For scenarios requiring troubleshooting, the*-distroless-debugsuffix is utilized, such aspublic.ecr.aws/gravitational/teleport-distroless-debug. These images include a Busybox shell and a suite of toolsets. While indispensable for debugging network connectivity or inspecting file systems inside the container, they are explicitly not intended for production use due to the increased security risk associated with having a shell available in a container.Multi-Architecture Support
Both the-distrolessand-distroless-debugimages natively support multiple CPU architectures. This eliminates the need for architecture-specific image suffixes, allowing the same image tag to be deployed across x86_64 and ARM64 environments, which is essential for hybrid-cloud deployments involving Graviton instances or Apple Silicon development machines.
Infrastructure Prerequisites and Host Preparation
Before initiating the deployment of Teleport, the host environment must be meticulously prepared to ensure stability and network reachability. A standard deployment typically utilizes a Linux Ubuntu Server (version 18.04 LTS or later).
The initial system state must be synchronized with the latest security patches and package updates to mitigate vulnerabilities in the underlying kernel or system libraries. This is achieved through the following sequence:
sudo apt update
sudo apt upgrade
The container runtime is the foundation of this deployment. The installation of Docker and Docker Compose is mandatory to orchestrate the Teleport services.
sudo apt install docker.io docker-compose
Once the binaries are installed, the Docker daemon must be active and configured to persist across system reboots.
sudo systemctl start docker
sudo systemctl enable docker
For users who prefer to manage Docker without constant root escalation, adding the current system user to the docker group is a standard administrative practice.
sudo usermod -aG docker $USER
newgrp docker
Furthermore, Teleport requires a valid domain or subdomain pointing to the server's IP address. This is critical for the Proxy service to handle HTTPS traffic and for the issuance of certificates. The system hostname must be aligned with this domain to ensure the Teleport configuration generates the correct identities.
sudo hostnamectl set-hostname teleport.example.com
The local hosts file must also be updated to map the IP address to the domain, ensuring that internal lookups resolve correctly.
sudo vim /etc/hosts
(Entry: 192.168.1.12 teleport.example.com)
Teleport Configuration and Provisioning Strategies
Teleport can be configured using either a static YAML file or dynamically generated settings. The configuration file, typically named teleport.yaml, governs the behavior of the Auth, Proxy, and Node services.
Manual Configuration Setup
An administrative directory is created to house the configuration files, ensuring they are separated from the root system files.
sudo mkdir -p /etc/teleport
Dynamic Configuration Generation
A highly efficient method for initializing Teleport is to use a temporary Docker container to generate a sample configuration file. This prevents the manual error of typing out complex YAML structures. By exporting the hostname as a variable and running a one-time container, the configuration is piped directly into the local filesystem.
TELEPORT_HOSTNAME="teleport.example.com"
docker run --hostname ${TELEPORT_HOSTNAME} --rm --entrypoint=/bin/sh -v ~/teleport/config:/etc/teleport ${TELEPORT_DOCKER_IMAGE} -c "teleport configure > /etc/teleport/teleport.yaml"
This process leverages the --rm flag to ensure the container is deleted immediately after the configuration is written, leaving only the resulting teleport.yaml in the host's ~/teleport/config directory.
Deployment Methodologies: Docker CLI vs. Docker Compose
Depending on the complexity of the deployment, an operator can choose between the Docker Command Line Interface (CLI) for simple standalone instances or Docker Compose for multi-service orchestration.
Implementation via Docker CLI
The Docker CLI is suitable for rapid prototyping or single-node deployments. The command below demonstrates the mapping of critical ports and the mounting of persistent volumes for configuration and data.
docker run -d --hostname ${TELEPORT_HOSTNAME} --name teleport -v ~/teleport/config:/etc/teleport -v ~/teleport/data:/var/lib/teleport -p 3023:3023 -p 3025:3025 -p 3080:3080 ${TELEPORT_DOCKER_IMAGE}
In this execution, the -v flags ensure that the Teleport state (users, sessions, and certificates) survives container restarts by mapping them to the host filesystem.
Implementation via Docker Compose
Docker Compose allows for a more declarative approach, defining the entire infrastructure in a docker-compose.yml file. This is particularly useful for separating the Auth and Proxy roles into different containers for better scalability.
A comprehensive Docker Compose configuration for Teleport typically looks like this:
yaml
version: '3'
services:
teleport:
image: public.ecr.aws/gravitational/teleport:10.2.1
container_name: teleport
entrypoint: /bin/sh
hostname: teleport.example.com
command: -c "sleep 1 && /bin/dumb-init teleport start -c /etc/teleport/teleport.yaml"
ports:
- "3023:3023"
- "3024:3024"
- "3025:3025"
- "3080:3080"
volumes:
- ./config:/etc/teleport
- ./data:/var/lib/teleport
The use of /bin/dumb-init as a wrapper is a technical requirement to ensure that signals (like SIGTERM) are correctly passed to the Teleport process, allowing for graceful shutdowns of the container.
To launch the environment:
docker-compose up -d
To verify the status of the services:
docker-compose ps
Teleport Service Management and User Administration
Once the container is running, the Teleport control tool (tctl) is used for administrative tasks. Since the tool resides inside the container, the docker-compose exec command is required to bridge the gap between the host and the containerized environment.
Verifying Service Health
To check the current status of the Teleport cluster and ensure all services are operational:
docker-compose exec teleport tctl status
User Onboarding and Access Control
Teleport uses a role-based access control (RBAC) system. Adding a new user involves specifying the desired roles and the Linux logins they are permitted to use on the nodes.
docker-compose exec teleport tctl users add testuser --roles=editor,access --logins=root
This command triggers the creation of a registration token. The user must use this token to complete their identity provider setup (e.g., linking to an email or SSO). The resulting user, testuser, is granted the editor and access roles, allowing them to log in as the root user on the managed Linux nodes.
Accessing the Interface
The Teleport Web UI is the primary gateway for administrators and users. It is accessible via the following URL pattern:
https://<domain or ip>:3080
Advanced Configuration and Alternative Image Variants
Beyond the official Gravitational images, alternative variants such as shufo/teleport offer different configuration mechanisms, including the use of environment variables to define roles.
Role Definition via Environment Variables
In some deployments, instead of a YAML file, environment variables are used to define the instance's identity.
- TELEPORT_ROLES: Specifies the function of the node (e.g.,
auth,proxy,node). - TELEPORTAUTHSERVER: Defines the address of the authentication server.
- TELEPORT_TOKEN: The shared secret used for the node to join the cluster.
- TELEPORT_NODENAME: The unique identifier for the node.
An example deployment using these variables:
docker run -d -e TELEPORT_ROLES=proxy,node -e TELEPORT_AUTH_SERVER=10.0.1.1:3025 -e TELEPORT_TOKEN=foobar -e TELEPORT_NODENAME=teleport.example.com shufo/teleport
Data Persistence and Storage Backends
Persistence is the most critical aspect of a Teleport deployment. If the /var/lib/teleport directory is not persisted, all users, sessions, and cluster state will be lost upon container deletion.
- Host Mounting: Mounting a local directory to
/var/lib/teleportensures that the SQLite database and certificates remain on the host. - External Backends: For high-availability production environments, Teleport v2.0 and later support external storage backends such as DynamoDB or etcd. This removes the dependency on local disk storage and allows for a distributed cluster architecture.
Technical Specifications and Port Mapping
For Teleport to function correctly, specific ports must be open and mapped from the host to the container. Failure to open these ports will result in the inability to connect via SSH or the Web UI.
| Port | Service | Protocol | Description |
|---|---|---|---|
| 3022 | SSH | TCP | Teleport SSH Proxy (Default for SSH) |
| 3023 | SSH | TCP | Teleport SSH Proxy (Alternative) |
| 3024 | SSH | TCP | Teleport SSH Proxy (Alternative) |
| 3025 | Auth | TCP | Teleport Auth Service (Internal Communication) |
| 3080 | Web | TCP | Teleport Web UI / HTTPS Proxy |
Comparative Analysis of Teleport Editions
Depending on the organizational needs, Teleport is available in three distinct editions, each with different deployment and management characteristics.
Open Source Teleport
Designed for individual users or small teams to learn and host their own deployment on a standalone Linux server. It provides the core functionality of secure access and audit logging.Teleport Enterprise
A self-hosted version that provides advanced features, including full customization and expanded support for complex infrastructure requirements.Teleport Cloud
A fully managed, cloud-hosted version that removes the need for the user to manage the Docker containers or the underlying infrastructure, offering a "SaaS" experience for access management.
Conclusion
The deployment of Teleport via Docker transforms a complex infrastructure security tool into a manageable, portable service. By utilizing distroless images, the security posture is significantly hardened, while Docker Compose provides the necessary orchestration to maintain separate roles for authentication and proxying. The critical path to a successful deployment involves correct hostname configuration, strategic volume mapping for data persistence in /var/lib/teleport, and the precise mapping of ports 3023, 3025, and 3080. Whether utilizing the official Amazon ECR images or alternative variants, the core requirement remains the same: a strict adherence to the identity-based access model and the secure handling of the teleport.yaml configuration. The ability to dynamically generate configurations and manage users via tctl ensures that the system remains agile and scalable as the infrastructure grows.