Quick Start Guide
Relevant source files
The following files were used as context for generating this wiki page:
The ansible-teleport role is designed to automate the installation, configuration, and management of the Teleport node service on Linux systems. It supports native package management (RPM and DEB) or binary installations, allowing for seamless integration of SSH, App, Database, and Kubernetes services into an existing Teleport cluster.
This guide provides the necessary steps to deploy a Teleport node using this role, covering prerequisite checks, installation methods, and configuration management.
Sources: README.md:1-10, meta/main.yml:1-15
Core Installation Workflow
The role follows a structured execution path to ensure the target system is compatible before attempting installation or configuration.
The diagram shows the sequential stages of the Ansible role from validation to service activation.
Sources: tasks/main.yml:4-65
1. Preflight Validations
Before installation, the role validates that the mandatory variables teleport_proxy_server and teleport_cluster_name are defined. It also verifies OS compatibility, supporting RedHat, Debian, and Alpine families.
Sources: tasks/preflight/check.yml:3-20
2. Version Detection
The role can automatically detect the required Teleport version by querying the Proxy server's API if teleport_autodetect_version is set to true. Otherwise, it defaults to a specified version (e.g., 15.4.11).
Sources: defaults/main.yml:8-10, tasks/preflight/version.yml:4-15
Configuration Management
Configuration is handled through Jinja2 templates, primarily default_teleport.yaml.j2. The role manages the lifecycle of the /etc/teleport.yaml file, including backup procedures.
| Option | Type | Default | Description |
|---|---|---|---|
teleport_config_path | String | /etc/teleport.yaml | Path to the main configuration file. |
teleport_backup_config | Boolean | true | Create a .bak file before overwriting. |
teleport_auth_token | String | "" | The token used to join the cluster. |
teleport_ca_pin | String | "" | The CA pin for cluster identity verification. |
teleport_proxy_server | String | "" | Address of the Teleport Proxy. |
Sources: defaults/main.yml:21-45, tasks/config/main.yml:30-45
Configuration Update Process
When the configuration changes, the role performs a safe update:
- Renders a new config to a temporary file.
- Compares checksums between the new and existing config.
- Backs up the old config if a difference is detected.
- Atomically replaces the config and notifies the service reload handler.
Sources: tasks/config/main.yml:12-65
Service Operation
Teleport is managed as a systemd service by default. The role ensures the service unit is created, enabled for persistence, and started.
The sequence diagram illustrates how Ansible interacts with systemd to manage the Teleport daemon lifecycle.
Sources: tasks/service/systemd.yml:10-37, molecule/default/verify.yml:76-100
Quick Start Example
To deploy a basic node, include the role in your playbook and provide the cluster authentication details.
- hosts: teleport_nodes
roles:
- datacosmos-br.teleport
vars:
teleport_proxy_server: "teleport.example.com"
teleport_cluster_name: "main-cluster"
teleport_auth_token: "your-secure-join-token"
teleport_ssh_labels:
env: "production"
dept: "it"
Sources: README.md:143-165
Summary
The ansible-teleport role provides a robust "Quick Start" path for integrating Linux hosts into a Teleport cluster. By automating version detection, configuration templating with backups, and systemd service management, it ensures a consistent and secure deployment across diverse environment architectures.
Sources: README.md:1-25