Requirements & Prerequisites
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. To ensure a successful deployment, several infrastructure and system-level prerequisites must be met before executing the playbook. These include a pre-existing Teleport cluster, specific network accessibility, and compatible host environments.
This documentation outlines the mandatory environment checks, supported operating systems, and the data required from an existing Teleport Auth/Proxy server to successfully join new nodes to the cluster.
Sources: README.md:1-12, meta/main.yml:1-5
Infrastructure Requirements
Before deploying this role, a functional Teleport cluster must be reachable. The role operates by connecting nodes to an existing control plane (Auth and Proxy services).
Mandatory Cluster Information
The following table summarizes the data that must be retrieved from the existing Teleport cluster and provided as variables to the role:
| Parameter | Purpose | Example / Retrieval Method |
|---|---|---|
teleport_proxy_server | Address of the Teleport Proxy | teleport.example.com |
teleport_cluster_name | The name of the target cluster | my-cluster |
teleport_auth_token | Secure token for joining nodes | tctl nodes add --roles=node |
teleport_ca_pin | CA Pin for untrusted auth servers | sha256:7f... |
Sources: README.md:33-40, tasks/preflight/check.yml:4-10, defaults/main.yml:33-40
Join Methods
The role supports multiple node joining methods, which influence the prerequisites:
- Token-based Joining: Requires a valid
teleport_auth_token. - EC2 Joining: Requires a specific EC2 join token (
teleport_ec2_join_token) and valid AWS environment metadata. - Version Autodetection: If
teleport_autodetect_versionis enabled, the Ansible controller must have HTTPS access to the Proxy/Auth server's version API.
Sources: README.md:38-39, defaults/main.yml:25-30, tasks/preflight/version.yml:4-10
System & OS Compatibility
The role performs preflight checks to verify that the target host belongs to a supported operating system family and architecture.
Supported Platforms
The role is formally tested and supported on the following platforms:
- EL (Enterprise Linux): Versions 7 and 8.
- Debian: Versions Jessie and Stretch.
- Ubuntu: Trusty, Xenial, and Bionic.
- Alpine: Supported via preflight validation checks.
Sources: meta/main.yml:16-33, tasks/preflight/check.yml:18-23
Architecture Support
The role dynamically handles binary selection for the following architectures:
amd64(x86_64)arm64(ARMv8 64-bit)arm(ARMv7 32-bit)386(Intel 32-bit)
Sources: README.md:65-75, defaults/main.yml:12
Validation Flow
The following diagram illustrates the sequence of requirement validations performed during the "Preflight" stage of the role execution.
The validation logic ensures that basic parameters like teleport_proxy_server and teleport_cluster_name are populated before any network operations occur. It also identifies if the role is running inside a container (docker or containerd) to adjust service management tasks later.
Sources: tasks/preflight/check.yml:4-23, tasks/preflight/version.yml:4-24, tasks/main.yml:4-14
Software Dependencies
Ansible Controller Requirements
- Ansible Version: Minimum version
2.4is required. - Python: Python 3 is enforced on Ubuntu 16.04+ and RedHat 8+.
Sources: meta/main.yml:14, molecule/default/converge.yml:10-25
Remote Node Requirements
The following packages/services are required on the target nodes:
- systemd: Required if
teleport_control_systemdis set toyes. - HTTPS Access: The node must be able to download the install script from
https://{{ teleport_proxy_server }}/scripts/install.sh. - sudo/Root Privileges: Required for package installation and configuration of files in
/etc/teleport.yaml.
Sources: tasks/main.yml:16-20, tasks/service/systemd.yml:4-8, README.md:123-125
Conclusion
Adhering to these requirements is critical for the ansible-teleport role to function. The combination of preflight OS validation, mandatory cluster variable checks, and architecture detection ensures that the Teleport binary and configuration are correctly applied to the target environment. Failure to provide a valid teleport_proxy_server or teleport_auth_token will result in early termination of the playbook during the preflight phase.