Introduction

The ansible-teleport role is an Ansible-based automation tool designed to install, update, and configure the Teleport node service on Linux systems. It supports native package management (RPM and DEB) and is compatible with multiple architectures, including amd64, arm64, and armv7. The primary objective of the role is to facilitate the joining of nodes to an existing Teleport cluster by managing the binary installation, security credentials (CA pins and auth tokens), and configuration file templating.

Sources: README.md:1-15, meta/main.yml:1-35

Core Execution Flow

The role follows a structured lifecycle that begins with system validation and version detection, followed by the installation of the Teleport binary and the application of security and service configurations.

The execution flow ensures that the system meets prerequisites before any changes are applied.
Sources: tasks/main.yml:4-53

Preflight and Versioning

Before installation, the role validates that mandatory variables such as teleport_proxy_server and teleport_cluster_name are defined. It also identifies if the target environment is a container (Docker or containerd) and verifies OS compatibility for RedHat, Debian, and Alpine families.

The role can automatically detect the required Teleport version by querying the Teleport Proxy API or using a default version defined in variables.

Sources: tasks/preflight/check.yml:4-21, tasks/preflight/version.yml:4-26, defaults/main.yml:8-12

Installation Mechanism

Installation is primarily handled via a shell script downloaded from the Teleport proxy server. This script facilitates the installation of the specified Teleport edition (OSS or Enterprise).

Security and Authentication

A critical component of the role is managing node identity and cluster authentication. The role can automatically retrieve the Cluster CA PIN from the proxy if it is not manually provided. It also supports migrating credentials from existing legacy configurations.

Security Procedures:

• CA PIN Retrieval: Fetches the CA PIN via https://{{ teleport_proxy_server }}:443/webapi/auth/export.
• Legacy Migration: Parses existing /etc/teleport.yaml files to extract auth_token and ca_pin for reuse during upgrades.
• Certificate Management: Generates private keys and CSRs (Certificate Signing Requests) for proxy configurations.

Sources: tasks/security/ca_pin.yml:4-38, tasks/security/auth.yml:4-18, tasks/security/parse_legacy_config.yml:4-16

Configuration Management

The role manages the /etc/teleport.yaml file using Jinja2 templates. By default, it uses default_teleport.yaml.j2, but it also supports EC2-specific templates for automatic node joining.

Configuration Lifecycle:

1. Directory Creation: Ensures /etc/teleport exists with 0700 permissions.
2. Staging: Renders the new configuration to a temporary file (/tmp/new_teleport_config.yaml).
3. Idempotency Check: Compares the checksum of the new configuration against the existing one.
4. Backup: Backs up the existing config to .bak if changes are detected and teleport_backup_config is enabled.
5. Deployment: Moves the new configuration to the final path and notifies the reload handler.

Sources: tasks/config/main.yml:4-53, defaults/main.yml:21-25

Service Management

Teleport is managed as a systemd service. The role creates the service unit from a template and ensures it is enabled and started.

Summary

The ansible-teleport role provides a comprehensive framework for deploying Teleport nodes. By automating version detection, package installation, and security credential management, it ensures that nodes are consistently configured and securely joined to the Teleport cluster. It includes robust features for configuration backups and legacy migrations, making it suitable for both fresh installations and version upgrades.

Sources: README.md:65-80, tasks/main.yml:1-53