Custom Configuration Templates

Relevant source files

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

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

Introduction

The Custom Configuration Templates system in this Ansible role provides a flexible framework for deploying and managing Teleport node configurations across various environments. By leveraging Jinja2 templating, users can define complex Teleport setups including SSH, Application, Database, and Kubernetes services while maintaining a single point of control for cluster-wide settings.

The system is designed to handle both fresh installations and upgrades, with specific logic to preserve existing security credentials like authentication tokens and CA pins during configuration updates. This ensures that nodes remain connected to the cluster even when their service definitions or labels are modified.
Sources: README.md:12-16, README.md:144-150

Configuration Rendering Logic

The deployment process follows a multi-stage workflow to ensure configuration integrity. The role first renders the template to a temporary location, performs a checksum comparison against the existing configuration, and optionally creates a backup before applying changes.

Lifecycle of a Configuration Update

The following diagram illustrates the sequence of operations performed when a configuration template is applied:

Template Selection and Variable Injection

The system supports multiple built-in templates and allows users to provide their own via the teleport_config_template variable. Data injection is handled through a structured set of variables that map directly to Teleport's YAML configuration schema.

Available Core Templates

Template Name	Use Case
default_teleport.yaml.j2	Basic node configuration with SSH service and uptime labels.
ec2_teleport.yaml.j2	Specialized for AWS environments using automatic node join with EC2 tokens.
Sources: README.md:73-81, defaults/main.yml:25

Key Configuration Variables

Variable	Default Value	Description
teleport_config_template	default_teleport.yaml.j2	The Jinja2 source file for the configuration.
teleport_config_path	/etc/teleport.yaml	The final destination for the config on the remote host.
teleport_backup_config	true	Enables automatic backup of the old config before overwriting.
teleport_template_config	yes	Global toggle to enable/disable configuration management.
Sources: defaults/main.yml:24-28, README.md:54-56

Security and Migration Handling

A critical component of the templating system is the "Legacy Configuration" parser. During upgrades, the role attempts to read the existing configuration file to extract active tokens. This prevents service disruption if the Ansible variables for teleport_auth_token or teleport_ca_pin are not explicitly provided in the playbook.

Token Migration Workflow

The following sequence diagram shows how the system reconciles existing security credentials with new template requirements:

Ephemeral Data Management

If security credentials (tokens or CA pins) are detected to have changed during the templating process, the role triggers a flush of ephemeral data located at /var/lib/teleport/proc/ to ensure a clean state for the new authentication parameters.
Sources: tasks/config/main.yml:82-96

Service-Specific Configuration Blocks

The templates are organized into modular service blocks (SSH, Proxy, Auth, etc.). This allows for the dynamic enablement or disablement of specific Teleport functionalities based on Boolean flags.

• SSH Service: Configured via teleport_ssh_labels (key/value mapping) and teleport_ssh_commands (list of dictionaries including name, command, and period).
• Network Interfaces: Managed through teleport_ssh_listen_addr and teleport_ssh_public_addr.
• Security Features: Includes toggles for PAM integration (teleport_ssh_pam_enabled), X11 forwarding, and Enhanced Session Recording.
  Sources: defaults/main.yml:68-124, README.md:162-185

Conclusion

The Custom Configuration Template system allows for the seamless management of Teleport nodes by balancing flexibility with operational safety. By incorporating automated backups, checksum validation, and legacy credential migration, the system provides a robust mechanism for maintaining complex cluster configurations through code.