Teleport Configuration File

Relevant source files

The following files were used as context for generating this wiki page:

• tasks/config/main.yml
• defaults/main.yml
• tasks/main.yml
• tasks/security/auth.yml
• tasks/security/parse_legacy_config.yml
• README.md

The Teleport configuration file is the central mechanism for defining the behavior, security parameters, and enabled services of a Teleport node. In this project, the configuration is managed via Ansible templates, allowing for dynamic generation based on host variables and cluster requirements. The file typically resides at /etc/teleport.yaml and is written in YAML format using version v3 specifications.

The configuration lifecycle involves several stages: preflight validation of parameters, security credential extraction (handling both new and legacy settings), template rendering to a temporary location, and atomic deployment with optional backups. This process ensures that nodes can join a cluster using methods such as static auth tokens, CA pins, or EC2-based dynamic tokens while maintaining consistent service definitions for SSH, Proxy, Kubernetes, and Database services.

Sources: README.md:129-170, tasks/config/main.yml:10-45, defaults/main.yml:23-28

Configuration Lifecycle and Flow

The project implements a structured flow to manage the configuration file, ensuring that manual changes are backed up and security credentials are preserved during upgrades.

Generation and Deployment Flow

The following diagram illustrates the logic used to apply a new configuration:

The system utilizes a temporary file strategy to validate the configuration before overwriting the production file, minimizing service downtime.
Sources: tasks/config/main.yml:2-45

Security Parameters and Migration

The configuration file serves as the primary store for sensitive cluster membership data. The role includes logic to parse existing configurations to prevent the loss of join credentials during automated runs.

Key Security Elements

• Auth Token: The secret used to join the cluster.
• CA Pin: The certificate authority pin used to validate the authentication server.
• Legacy Parsing: The role slurps the existing /etc/teleport.yaml, decodes it from YAML, and extracts auth_token and ca_pin to reuse them if new ones are not provided.

Sources: tasks/security/parse_legacy_config.yml:4-25, tasks/security/auth.yml:5-20

Security Parameter Extraction

Parameter	Source Location in YAML	Project Variable
Version	version	legacy_config.version
Auth Token	teleport.auth_token	teleport_auth_token
CA Pin	teleport.ca_pin	teleport_ca_pin

Sources: tasks/security/parse_legacy_config.yml:17-25

Core Configuration Options

The behavior of the configuration file is controlled by variables defined in the defaults. These variables determine where the file is located and how it is updated.

File Path and Templates

• Path: Defaulted to /etc/teleport.yaml.
• Directory: Defaulted to /etc/teleport with 0700 permissions.
• Templates: Supports default_teleport.yaml.j2 for standard nodes and ec2_teleport.yaml.j2 for AWS environments.

Sources: defaults/main.yml:23-26, tasks/config/main.yml:2-10

Variable Summary

Variable	Default Value	Description
teleport_config_path	/etc/teleport.yaml	The absolute path to the Teleport configuration.
teleport_backup_config	true	Whether to create a .bak file before updating.
teleport_template_config	yes	Controls if the role is allowed to modify the config.
teleport_log_severity	INFO	The log level defined in the configuration.

Sources: defaults/main.yml:23-45

Service Service Definitions

The configuration file enables various Teleport services. The role allows for granular control over the ssh_service, proxy_service, and others via boolean flags and structured data.

SSH Service

The SSH service is the most common component, supporting static labels and dynamic command-based labels.

• Static Labels: Provided as a mapping via teleport_ssh_labels.
• Commands: A list of dictionaries defining executable scripts and their execution period.

Sources: defaults/main.yml:68-88, README.md:144-155

Proxy and Application Services

Service	Enable Variable	Purpose
ssh_service	teleport_ssh_enabled	Provides secure shell access.
proxy_service	teleport_proxy_enabled	Handles incoming connections and web UI.
kube_service	teleport_kube_enabled	Connects Kubernetes clusters to Teleport.
db_service	teleport_db_enabled	Manages secure access to databases.
app_service	teleport_apps_enabled	Exposes internal web applications.

Sources: defaults/main.yml:68-155

Summary

The Teleport Configuration File managed by this role acts as the bridge between host-level environment settings and cluster-level security requirements. By automating the rendering and deployment of /etc/teleport.yaml, the role ensures that security credentials like CA pins and auth tokens are correctly persisted or rotated while providing a flexible template system for enabling various Teleport roles (SSH, Proxy, etc.). The built-in backup and validation mechanisms further ensure system stability during configuration updates.

Sources: README.md:162-170, tasks/main.yml:45-55