Role Variables Overview
Relevant source files
The following files were used as context for generating this wiki page:
The ansible-teleport role utilizes a comprehensive set of variables to manage the installation, configuration, and security of Teleport node services. These variables allow for fine-grained control over the Teleport version, architecture, and specific service components such as SSH, Proxy, and Kubernetes integrations.
The role architecture is designed to handle both fresh installations and upgrades, with variables controlling whether the role should autodetect versions, manage systemd services, or perform configuration backups.
Sources: README.md:1-24, defaults/main.yml:1-10
Core Installation and Package Variables
These variables define the base package properties and the method of installation for the Teleport binary.
| Variable | Default Value | Description |
|---|---|---|
teleport_version | "15.4.11" | The specific version of Teleport to install. |
teleport_edition | "oss" | Teleport edition (oss, enterprise, or cloud). |
teleport_autodetect_version | false | If true, the role queries the Proxy API to find the latest version. |
teleport_architecture | "amd64-bin" | Target architecture (e.g., arm-bin, arm64-bin, amd64-bin). |
teleport_package_state | present | The desired state of the Teleport package. |
Sources: defaults/main.yml:7-14, README.md:61-75
Version Detection Flow
When teleport_autodetect_version is enabled, the role performs a sequence to resolve the version dynamically from the cluster's upgrade channel.
Sources: tasks/preflight/version.yml:4-28
System and Path Configuration
The role manages several directories and file paths for configuration and security artifacts.
| Variable | Default Value | Description |
|---|---|---|
teleport_config_path | "/etc/teleport.yaml" | Path to the main Teleport configuration file. |
teleport_config_dir | "/etc/teleport" | Base directory for Teleport-related files. |
teleport_backup_config | true | Whether to create a .bak of the config before changes. |
teleport_control_systemd | yes | If true, the role manages the systemd unit file and state. |
Sources: defaults/main.yml:21-27, tasks/config/main.yml:33-45
Security and Authentication Variables
Security variables are critical for joining a node to an existing Teleport cluster. The role supports manual entry or automated retrieval of CA pins and tokens.
Cluster Identity
teleport_auth_token: The secret token used to join the cluster.teleport_ca_pin: The CA pin for verifying the Auth server. If empty andteleport_fetch_ca_pinis true, the role attempts to fetch it from the Proxy.teleport_ec2_join_token: Specific token used for AWS EC2 joining methods.
Sources: defaults/main.yml:32-37, README.md:130-135
Certificate Management
The role can generate self-signed certificates for proxy services using the following variables:
teleport_tls_country: "BR"
teleport_tls_state: "São Paulo"
teleport_tls_organization: "Datacosmos"
teleport_tls_valid_days: 365
Sources: defaults/main.yml:43-47, tasks/security/certificate.yml:46-60
Service Specific Configuration
SSH Service
The SSH service is configured via a dictionary of labels and list of commands.
teleport_ssh_enabled: Enables the SSH role (default:true).teleport_ssh_labels: A mapping of key-value pairs (e.g.,{ role: "leader" }).teleport_ssh_commands: A list of external commands to run for dynamic labeling.
Sources: defaults/main.yml:62-92, README.md:175-188
Proxy and App Services
Multiple services can be toggled and configured through specific boolean flags and list variables:
teleport_proxy_enabled: Boolean to enable Proxy service.teleport_kube_enabled: Boolean to enable Kubernetes service.teleport_db_enabled: Boolean to enable Database service.teleport_apps_enabled: Boolean to enable Application service.
Sources: defaults/main.yml:118-150
Configuration Management Logic
The role follows a "render-then-apply" logic to ensure configuration integrity and provide backup capabilities.
- Rendering: The template defined in
teleport_config_template(defaultdefault_teleport.yaml.j2) is rendered to/tmp/new_teleport_config.yaml. - Comparison: The checksum of the new file is compared against the existing file at
teleport_config_path. - Backup: If different and
teleport_backup_configis true, the current file is copied to.bak. - Application: The new file is moved to the destination, and a handler triggers a service reload.
Sources: tasks/config/main.yml:11-54, README.md:110-120
Summary
The ansible-teleport role variables provide a flexible interface for deploying Teleport nodes. By abstracting architecture detection, version management, and security credential handling into configurable variables, the role supports a wide range of deployment scenarios—from simple SSH nodes to complex proxy and database access layers. The use of variables like teleport_template_config and teleport_control_systemd ensures that the role can be integrated into existing environments without overriding local manual configurations if desired.
Sources: README.md:10-30, defaults/main.yml:1-30