Package Upgrades & Backup Mechanisms
Relevant source files
The following files were used as context for generating this wiki page:
The Ansible Teleport role implements a robust lifecycle management system for Teleport node services. It focuses on automated version detection, seamless package upgrades using native installation scripts, and a multi-layered backup strategy to ensure configuration persistence during updates. This system allows administrators to update binaries and configurations without losing critical security tokens or CA pins.
Sources: README.md:167-185, tasks/main.yml:1-74
Version Detection and Installation Flow
The upgrade process begins with version validation and environment detection. The role supports two primary methods for determining the target version: manual specification via teleport_version or automated detection via the Teleport Proxy API.
Version Autodetection
When teleport_autodetect_version is enabled, the role queries the Teleport Proxy's automatic upgrade endpoint. It retrieves the version associated with a specific channel (e.g., stable/v17) and sets it as the installation target.
Sources: defaults/main.yml:10-15, tasks/preflight/version.yml:5-23
Installation and Upgrade Logic
Teleport is installed using a shell script retrieved from the proxy server. For tar based installations, the role compares the current version against the target; for apt or yum methods, native package managers handle the update. The installation is performed with the specific version and edition (oss, enterprise, or cloud) defined in the variables.
Sources: README.md:170-175, tasks/main.yml:21-41
The diagram above illustrates the decision logic for versioning and the subsequent installation execution path.
Sources: tasks/main.yml:7-41, tasks/preflight/version.yml:4-23
Configuration Backup Mechanisms
To prevent data loss during configuration updates, the role implements a safety-first approach using temporary files and checksum comparisons before overwriting existing files.
Backup Procedure
- Rendering: The new configuration is rendered to
/tmp/new_teleport_config.yaml. - Checksum Comparison: The role registers the checksum of both the current
/etc/teleport.yamland the new temporary file. - Conditional Backup: If
teleport_backup_configis true and the files differ, the current configuration is copied to/etc/teleport.yaml.bak. - Atomic Replacement: The temporary file is copied to the final destination, and the service is notified for a reload.
Sources: tasks/config/main.yml:11-54
| Variable | Default Value | Description |
|---|---|---|
teleport_backup_config | true | Enables/disables automatic backup of existing config |
teleport_config_path | /etc/teleport.yaml | The filesystem path for the Teleport config |
teleport_config_template | default_teleport.yaml.j2 | The Jinja2 template used for rendering |
Sources: defaults/main.yml:21-23, tasks/config/main.yml:45-54
Security State Preservation
A critical feature of the upgrade mechanism is the preservation of authentication state. During an upgrade, the role attempts to read the "legacy" (existing) configuration to extract the auth_token and ca_pin.
Migration Logic
If a legacy configuration exists, the role parses the YAML content. It extracts the security credentials and migrates them into the current execution facts if new ones haven't been provided. This allows the node to rejoin the cluster after an upgrade without requiring a new invitation token.
Sources: tasks/security/auth.yml:1-25, tasks/security/parse_legacy_config.yml:1-35
This sequence shows how security credentials are recovered from existing files to maintain cluster connectivity across version changes.
Sources: tasks/security/auth.yml:5-20, tasks/security/parse_legacy_config.yml:10-25
Ephemeral Data Management
If security credentials change during an upgrade or configuration update, the role identifies the discrepancy. In such cases, it flushes ephemeral data located in /var/lib/teleport/proc/ to ensure the service starts with a clean state matching the new credentials.
Sources: tasks/config/main.yml:76-98
Summary
The package upgrade and backup system provides a lifecycle management approach that prioritizes uptime and security. By integrating version autodetection from the Teleport Proxy API with automated configuration backups and credential migration, the role ensures that node upgrades are idempotent and non-destructive to the cluster's trust relationship.
Sources: README.md:170-185, tasks/main.yml:7-41, tasks/config/main.yml:45-54