Example Playbooks
Relevant source files
The following files were used as context for generating this wiki page:
Example playbooks provide a standardized way to deploy and configure the Teleport Node Service across various infrastructure environments. These playbooks leverage the role's modular task structure to handle everything from preflight validation and binary installation to security credential management and systemd service integration.
The role is designed to be flexible, supporting multiple installation methods (tarball, apt, yum), different Teleport editions (OSS, Enterprise, Cloud), and various join methods, including static tokens and AWS EC2 dynamic joining.
Sources: README.md:1-20, tasks/main.yml:1-60
Standard Node Configuration
The most common use case involves deploying a Teleport node that joins an existing cluster using an authentication token and CA pin. This setup typically enables the SSH service and configures custom labels or commands for node monitoring.
Deployment Workflow
The following diagram illustrates the internal execution flow when a standard playbook is executed.
The workflow ensures that prerequisites are met before attempting installation and that configuration is backed up before updates are applied.
Sources: tasks/main.yml:4-58, tasks/config/main.yml:32-48
Playbook Example: Standard Node
This example demonstrates a playbook utilizing inline variables to define SSH labels and periodic commands.
- hosts: all
roles:
- datacosmos-br.teleport
vars:
teleport_auth_token: "super secret auth token"
teleport_ca_pin: "sha256:example_pin_here"
teleport_auth_server: "teleport.example.com:443"
teleport_ssh_labels:
- k: "environment"
v: "production"
teleport_ssh_commands:
- name: uptime
command: [uptime, -p]
period: 5m0s
Sources: README.md:154-177
AWS EC2 Join Method
For nodes running in Amazon Web Services, the role supports the EC2 joining method. This removes the need for static, long-lived authentication tokens by using the AWS Instance Identity Document.
Architecture Comparison
The EC2 join method utilizes a specific configuration template (ec2_teleport.yaml.j2) that differs from the default node configuration.
| Feature | Standard Join | EC2 Join |
|---|---|---|
| Template | default_teleport.yaml.j2 | ec2_teleport.yaml.j2 |
| Token Type | Static/Dynamic Auth Token | EC2 Join Token |
| Required Vars | teleport_auth_token | teleport_ec2_join_token |
| Host Labels | Defined in teleport_ssh_labels | Defined in teleport_host_labels |
Sources: README.md:141-152, defaults/main.yml:25-33
Playbook Example: EC2 Integration
This example shows how to separate role invocation from variable definition, often used in group_vars.
# playbook.yml
- hosts: all
roles:
- datacosmos-br.teleport
# group_vars/all.yaml
teleport_config_template: ec2_teleport.yaml.j2
teleport_auth_servers:
- https://teleport.company.cc:443
teleport_ec2_join_token: ec2-teleport-join-token
teleport_host_labels:
owner: datacosmos-br
type: standalone
Sources: README.md:141-152
Infrastructure Testing (Molecule)
The project includes a "Converge" playbook used for automated testing via Molecule. This serves as a reference for a clean, minimal implementation suitable for CI/CD pipelines.
Convergence Sequence
The convergence process includes pre-tasks to ensure the environment (such as Docker containers used for testing) has the necessary Python interpreters.
Key Configuration Variables
The following variables are commonly overridden in example playbooks to customize node behavior.
| Variable | Default Value | Description |
|---|---|---|
teleport_version | 15.4.11 | The specific version of Teleport to install. |
teleport_edition | oss | Can be oss, enterprise, or cloud. |
teleport_architecture | amd64-bin | Binary architecture (e.g., arm64-bin, 386-bin). |
teleport_proxy_server | "" | The address of the Teleport Proxy. |
teleport_control_systemd | yes | Whether the role manages the systemd unit. |
teleport_backup_config | true | Creates .bak of config before overwriting. |
Sources: defaults/main.yml:6-45
Security and Migration Logic
When updating an existing installation via a playbook, the role performs specific checks to determine if security credentials have changed. If the teleport_auth_token or teleport_ca_pin differ from the values currently residing in the legacy configuration on the host, the role can trigger a flush of ephemeral data.
Summary
Example playbooks for this role provide a declarative way to manage Teleport across diverse Linux distributions (RedHat, Debian, Alpine). By adjusting variables like teleport_config_template and teleport_auth_token, users can transition from simple standalone SSH nodes to complex, automated EC2-joined clusters while ensuring configuration safety through automatic backups and credential migration logic.