Legacy Configuration Parsing
Relevant source files
The following files were used as context for generating this wiki page:
Legacy Configuration Parsing is a critical mechanism within the Ansible Teleport role designed to maintain continuity during software updates or configuration changes. Its primary purpose is to detect existing Teleport configuration files, extract sensitive credentials such as authentication tokens and CA pins, and migrate them into the new configuration state. This process ensures that nodes can re-join the cluster or update their parameters without requiring the manual re-entry of security credentials.
The scope of this system includes file detection, YAML parsing, version validation, and conditional variable migration. By automating the extraction of data from /etc/teleport.yaml (the default path), the role avoids the need to store sensitive tokens in plaintext within Ansible variables or inventory files when a system is already provisioned.
Sources: tasks/security/parse_legacy_config.yml:1-32, README.md:129-140
Detection and Loading Logic
The process begins by checking for the presence of an existing configuration file at the path defined by teleport_config_path. If the file exists, the role triggers the legacy parsing tasks.
Detection Workflow
The system utilizes the ansible.builtin.stat module to verify the existence of the configuration file before attempting any read operations. This prevents task failures on fresh installations where no previous configuration exists.
The diagram above illustrates the decision logic used to determine if a migration is necessary.
Sources: tasks/security/legacy.yml:3-10, tasks/security/parse_legacy_config.yml:1-18
Parsing and Validation
Once the file is detected, the role performs several data transformation steps to make the legacy information usable for the current execution.
Extraction Steps
- Slurp and Decode: The raw file content is read and decoded from Base64.
- YAML Conversion: The decoded string is converted into a structured YAML object.
- Version Assertion: The system explicitly checks that the
versionfield in the configuration isv3. If the version is unsupported, the process fails unless forced. - Credential Assignment: Specific fields are mapped to legacy variables for comparison and migration.
| Parameter | Source Key in YAML | Target Ansible Variable |
|---|---|---|
| Auth Token | teleport.auth_token | legacy_auth_token |
| CA PIN | teleport.ca_pin | legacy_ca_pin |
Sources: tasks/security/parse_legacy_config.yml:3-23, tasks/security/auth.yml:5-20
Migration and Security Changes
The core value of parsing legacy data is the conditional migration of credentials and the detection of security-impacting changes.
Conditional Migration
If teleport_auth_token or teleport_ca_pin are not provided via Ansible variables, the values extracted from the legacy configuration are used as defaults. This ensures that a role run against an existing node preserves its cluster membership.
Security Credential Change Detection
The role compares the legacy values against the desired state to determine if security credentials have changed. If a mismatch is detected, the system sets security_credentials_changed to true.
The sequence diagram shows how the system reacts when existing credentials differ from the new configuration.
Sources: tasks/security/auth.yml:5-20, tasks/config/main.yml:76-102
Error Handling and Migration Enforcement
The parsing process includes a rescue block to handle failures during YAML decoding or validation.
- Failure Handling: If parsing fails, the role will fail with a message stating "Manual migration required."
- Force Migration: This failure can be bypassed if the variable
teleport_force_migrationis set totrue, allowing the role to proceed even if the old config is unreadable.
Sources: tasks/security/parse_legacy_config.yml:25-32
Summary of Impact
Legacy configuration parsing allows for seamless upgrades by reusing existing node identities. By extracting the CA PIN and Auth Token from /etc/teleport.yaml, the role can update other configuration aspects (like labels or commands) without requiring the user to provide sensitive join credentials for every run.