Preflight Checks
Relevant source files
The following files were used as context for generating this wiki page:
Preflight Checks serve as the initial validation layer within the Ansible Teleport role, ensuring that the target environment meets the minimum requirements for a successful deployment. This module is executed at the very beginning of the role execution to catch configuration errors and environmental incompatibilities before any installation or modification occurs.
The scope of these checks includes verifying mandatory variables, detecting the virtualization environment, ensuring Operating System (OS) compatibility, and resolving the correct Teleport version to be installed. By centralizing these validations, the role maintains idempotency and prevents failures during the more complex tasks of certificate management and service configuration.
Sources: tasks/main.yml:4-13, tasks/preflight/check.yml:1-19
Execution Flow
The preflight process is organized into two primary logic blocks: requirement validation and version detection. These are triggered via the main task entry point using the validation tag.
The diagram shows the sequential execution of preflight tasks from the initial role entry to the completion of all validation logic.
Sources: tasks/main.yml:4-13, tasks/preflight/check.yml:1-19
Mandatory Configuration Validation
The role enforces the presence of critical variables required for Teleport to communicate with its control plane. If these are missing, the execution fails immediately with a descriptive error message.
| Variable | Check Logic | Purpose |
|---|---|---|
teleport_proxy_server | Length > 0 | Specifies the address of the Teleport Proxy to which the node connects. |
teleport_cluster_name | Length > 0 | Defines the name of the Teleport cluster the node is joining. |
Sources: tasks/preflight/check.yml:3-8, defaults/main.yml:43-46
Environmental Detection
The preflight phase gathers facts about the target system to adjust subsequent task behavior, particularly concerning service management.
Container Detection
The role determines if it is running inside a containerized environment (Docker or containerd). This detection is critical because certain operations, such as systemd service management, are typically bypassed or handled differently in containers.
Sources: tasks/preflight/check.yml:10-13, tasks/service/systemd.yml:13-17
OS Compatibility
The role explicitly supports three OS families. If the target system does not belong to one of these families, the preflight check asserts a failure.
- RedHat
- Debian
- Alpine
Sources: tasks/preflight/check.yml:15-19
Version Resolution Logic
Teleport versioning can either be explicitly defined or automatically detected by querying the Teleport Cluster's API.
Automatic Version Detection
When teleport_autodetect_version is enabled, the role performs a GET request to the cluster's automatic upgrade channel API.
The sequence diagram illustrates the API interaction used to resolve the latest version from a specific Teleport channel.
Sources: tasks/preflight/version.yml:3-17
Version Validation
Regardless of how the version is sourced, it must pass a format and compatibility check. The role requires Teleport version 14.0.0 or higher and expects a semantic versioning format (X.Y.Z).
- name: Validate version format
ansible.builtin.assert:
that:
- teleport_version is version_compare('14.0.0', '>=')
- teleport_version | regex_search('^\\d+\\.\\d+\\.\\d+$') is not none
msg: "Invalid Teleport version: {{ teleport_version }}"
Sources: tasks/preflight/version.yml:19-25
Summary
Preflight checks ensure the target host is a supported OS (RedHat, Debian, or Alpine) and that the user has provided the necessary cluster identifiers. By resolving versioning early and detecting container environments, the role ensures that the subsequent installation and configuration phases are performed using accurate environmental data.
Sources: tasks/preflight/check.yml:1-19, tasks/preflight/version.yml:1-25