Version Autodetection
Relevant source files
The following files were used as context for generating this wiki page:
Version Autodetection is a mechanism within the Teleport Ansible role that allows the system to dynamically determine the appropriate version of Teleport to install by querying the target cluster's API. This feature ensures compatibility between the node being deployed and the existing Teleport infrastructure without requiring manual version pinning in the playbook.
The process is integrated into the "Validation" stage of the role's execution. It specifically targets the Teleport Web API to fetch the latest version supported by a specific upgrade channel. If autodetection is disabled or fails to find a valid version string, the role falls back to a default version defined in the configuration.
Sources: tasks/main.yml:4-12, README.md:46-52, tasks/preflight/version.yml:4-13
Architecture and Logic Flow
The autodetection logic relies on the teleport_autodetect_version boolean flag. When enabled, the role performs an HTTP GET request to the Teleport Proxy or Auth server.
Logic Flow Diagram
The following diagram illustrates the decision-making process for determining the Teleport version:
This flow ensures that even if autodetection is requested, the resulting version must meet minimum safety and format requirements before installation proceeds.
Sources: tasks/preflight/version.yml:4-24, defaults/main.yml:9-12
API Interaction
The role utilizes the ansible.builtin.uri module to interact with the Teleport automatic upgrade API.
Endpoint Details
| Parameter | Description | Source |
|---|---|---|
| URL | https://{{ server }}/v1/webapi/automaticupgrades/channel/{{ channel }}/version | tasks/preflight/version.yml:5 |
| Server | Derived from teleport_proxy_server or teleport_auth_server | tasks/preflight/version.yml:5 |
| Channel | Defined by teleport_channel (e.g., stable/v17) | defaults/main.yml:18 |
| Validation | Controlled by teleport_validate_certs | tasks/preflight/version.yml:8 |
The API response is expected to contain a version string (e.g., v17.0.1). The role uses regex_replace to strip the leading 'v' and match to ensure the content conforms to a semantic versioning pattern (^v?\d+\.\d+\.\d+).
Sources: tasks/preflight/version.yml:4-17, defaults/main.yml:18-19
Configuration Options
The following variables control the behavior of the version autodetection system:
| Variable | Type | Default | Description |
|---|---|---|---|
teleport_autodetect_version | Boolean | false | Enables/disables API querying for version. |
teleport_version | String | 15.4.11 | Fallback version used if autodetection is disabled. |
teleport_channel | String | stable/v17 | The upgrade channel to query for the latest version. |
teleport_validate_certs | Boolean | true | Whether to validate SSL certificates during API calls. |
Sources: defaults/main.yml:8-20, README.md:46-55
Version Validation and Constraints
Regardless of whether the version was autodetected or manually specified, the role performs mandatory assertions to prevent the installation of incompatible or malformed versions.
- Minimum Version: The version must be greater than or equal to
14.0.0. - Format: The string must match a strict numeric 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:20-26
Integration with Installation
Once the version is determined and validated, it is passed as an environment variable to the Teleport installation script.
Summary
Version Autodetection provides a robust way to maintain parity between Teleport nodes and the cluster control plane. By leveraging the Teleport Web API and applying strict regex validation and version comparisons, the role automates the lifecycle of the binary while ensuring that the system does not install unsupported legacy versions or corrupted version strings.