Role Execution Flow
Relevant source files
The following files were used as context for generating this wiki page:
The Role Execution Flow defines the structured sequence of operations used by this Ansible role to install, configure, and manage a Teleport node service. The flow is designed to ensure environment compatibility, handle versioning, secure the node through certificate and token management, and maintain the service via systemd or legacy init systems.
The execution is organized into five primary phases: Validations (Preflight), Installation, Security Configuration, Service Configuration, and Service Management. This modular approach allows for conditional execution, such as skipping proxy-specific tasks or handling legacy configuration migrations automatically.
Sources: tasks/main.yml:1-70, README.md:95-108
High-Level Execution Architecture
The role follows a linear progression from environment validation to service start. The following diagram illustrates the primary logical blocks executed in order.
The diagram shows the sequential execution of task blocks as defined in the main entry point.
Sources: tasks/main.yml:4-68
Phase 1: Preflight Validations
Before any changes are made, the role validates that the target system meets the necessary requirements and determines the Teleport version to be deployed.
System Prerequisite Checks
The role verifies mandatory variables and OS compatibility:
- Mandatory Variables:
teleport_proxy_serverandteleport_cluster_namemust be defined. - OS Family: Supports
RedHat,Debian, andAlpine. - Environment: Detects if the role is running inside a container (Docker/Containerd).
Sources: tasks/preflight/check.yml:4-21
Version Detection
If teleport_autodetect_version is enabled, the role queries the Teleport Proxy API to find the latest version for the specified channel. It then validates that the version is at least 14.0.0.
Sources: tasks/preflight/version.yml:4-26
Phase 2: Installation Process
The installation is handled by downloading an official installation script from the proxy server and executing it with specific environment variables.
This flow details the transition from downloading the script to binary installation.
Sources: tasks/main.yml:19-40
Phase 3: Security & Authentication
This phase ensures the node can securely join the cluster. It includes logic for migrating legacy settings and managing cryptographic materials.
Security Workflow Features
| Feature | Implementation Detail | Source |
|---|---|---|
| Legacy Migration | Loads existing /etc/teleport.yaml to extract auth_token and ca_pin if missing. | tasks/security/auth.yml:3-17 |
| CA PIN Retrieval | Exports the cluster CA PIN from the Proxy API via /webapi/auth/export. | tasks/security/ca_pin.yml:4-12 |
| TLS Management | Generates RSA 4096-bit private keys and self-signed certificates or CSRs. | tasks/security/certificate.yml:32-60 |
| ACME Support | Integrates with certbot for automated Let's Encrypt certificate issuance. | tasks/config/proxy.yml:68-88 |
Phase 4: Configuration Generation
Configuration is managed through a templating system that supports both fresh installs and upgrades.
- Rendering: The configuration is first rendered to a temporary file (
/tmp/new_teleport_config.yaml). - Comparison: The role compares the checksum of the existing config against the new one.
- Backup: If differences are found and
teleport_backup_configis true, a.bakfile is created. - Application: The temporary file is moved to the final path, notifying the service reload handler.
Sources: tasks/config/main.yml:11-53
Phase 5: Service Management
The final phase ensures the Teleport daemon is running and integrated with the host's init system.
- Systemd: Creates a unit file from
teleport.service.j2, sets permissions to0640, and enables the service. - Legacy Systems: Supports SysV init scripts for platforms not using systemd.
- Handlers: Changes to configuration or binaries trigger
Reload Teleport service(systemd reload) orRestart Teleport service.
Sources: tasks/service/systemd.yml:4-36, handlers/main.yml:3-18
Conclusion
The Role Execution Flow ensures a robust deployment by combining strict pre-execution validation with flexible security management. By automating the migration of legacy credentials and supporting various installation methods (tarball vs package), the role maintains consistency across different Linux distributions and Teleport versions.
Sources: README.md:95-108, tasks/main.yml:4-68