Test Scenarios (Converge & Verify)
Relevant source files
The following files were used as context for generating this wiki page:
The Test Scenarios within the Teleport Ansible role utilize the Molecule framework to automate the lifecycle of testing the deployment and configuration of the Teleport node service. This process is divided into two primary phases: Converge, which applies the Ansible role to a target infrastructure (typically Docker containers), and Verify, which executes assertions to ensure the system reached the desired state.
These scenarios ensure that the role can successfully install the Teleport binary, generate appropriate configurations, and manage the systemd service across supported distributions such as Ubuntu and RedHat.
Sources: molecule/default/molecule.yml, molecule/default/converge.yml:1-5, molecule/default/verify.yml:1-5
Converge Phase
The Converge phase represents the actual execution of the Ansible role. It prepares the environment by installing necessary dependencies (like Python 3) and then runs the datacosmos-br.teleport role.
Environment Preparation
Before the role is applied, pre_tasks are executed to ensure the target host is ready for Ansible. This includes installing python3-minimal on Ubuntu 16+ or python3 on RedHat 8+ if not already present.
The diagram shows the sequence of pre-tasks required to bootstrap the environment before role execution.
Sources: molecule/default/converge.yml:7-33
Role Execution Flow
Once the environment is prepared, the main role logic is triggered. This involves a series of task inclusions that handle validation, installation, and service management.
| Task Block | Description | Source File |
|---|---|---|
| Validations | Checks prerequisites and detects Teleport version | tasks/main.yml:5-13 |
| Install | Downloads and runs the official Teleport install script | tasks/main.yml:15-32 |
| Security | Handles CA pins, certificates, and auth tokens | tasks/main.yml:34-43 |
| Configuration | Renders and applies the teleport.yaml config | tasks/main.yml:45-52 |
| Service | Integrates with systemd to start/enable the daemon | tasks/main.yml:54-61 |
Sources: tasks/main.yml, tasks/preflight/check.yml
Verify Phase
The Verify phase executes after the Converge phase to validate the success of the deployment. It uses Ansible modules to check file existence, permissions, and process status.
Verification Logic Flow
The verification process follows a strict sequence of checks to ensure all components of the Teleport service are correctly placed and operational.
The sequence diagram illustrates the functional checks performed during the verification stage.
Sources: molecule/default/verify.yml:21-95
Critical Assertions
The following table summarizes the mandatory checks performed during the Verify phase:
| Component | Target Path | Criteria |
|---|---|---|
| Configuration | /etc/teleport.yaml | File must exist |
| Binary | /usr/local/bin/teleport | Mode: 0755, Owner: root, Size: > 0 |
| Systemd Unit | /etc/systemd/system/teleport.service | Mode: 0644, Owner: root |
| Process | teleport | Running under root (skipped in containers) |
| Networking | 0.0.0.0:3022 | Port must be listening (skipped in containers) |
Sources: molecule/default/verify.yml:25-95
Platform Configuration
Molecule is configured to use the Docker driver for testing. The default platform is defined via environment variables, allowing for cross-distribution testing.
platforms:
- name: instance
image: ${MOLECULE_DISTRO:-ubuntu:22.04}
groups:
- teleportclients
Sources: molecule/default/molecule.yml:6-15
Container Detection
Both the deployment and verification tasks include logic to detect if they are running inside a container. This is used to skip tasks that are incompatible with standard Docker environments, such as direct systemd service manipulation or process monitoring.
- name: Detect container environment
ansible.builtin.set_fact:
is_container: "{{ ansible_virtualization_type in ['docker', 'containerd'] }}"
Sources: tasks/preflight/check.yml:11-13, molecule/default/verify.yml:12-19
Conclusion
The Test Scenarios provide a robust framework for validating Teleport deployments. By separating the process into a Converge phase (implementation) and a Verify phase (validation), the project ensures that the Teleport binary, its configuration, and its service management are functioning correctly across different Linux distributions before production deployment.
Sources: molecule/default/converge.yml, molecule/default/verify.yml