Molecule Testing Strategy
Relevant source files
The following files were used as context for generating this wiki page:
The Molecule testing strategy for the ansible-teleport role provides a structured framework for validating the installation, configuration, and service health of Teleport nodes across different environments. By utilizing Docker as the primary driver, the strategy ensures that the role can be tested in isolated, reproducible containers that simulate various Linux distributions.
The testing lifecycle follows the standard Molecule workflow: dependency resolution, linting (via GitHub Actions), instance creation, convergence (applying the role), and verification of the resulting state. This strategy is critical for maintaining compatibility across RedHat, Debian, and Alpine families while supporting multiple architectures like amd64 and arm64.
Sources: molecule/default/molecule.yml:1-20, README.md:1-15, tasks/preflight/check.yml:13-18
Test Infrastructure and Environment
The testing environment is defined in the default Molecule scenario. It utilizes Docker to provision instances, allowing for rapid testing across multiple operating systems.
Driver and Platform Configuration
The strategy employs the Docker driver to manage test instances. The platform configuration is dynamic, allowing the distribution to be set via environment variables.
- Driver: Docker
- Default Image: ubuntu:22.04 (overridable via
MOLECULE_DISTRO) - Groups: Test instances are assigned to the
teleportclientsgroup for targeted verification.
Sources: molecule/default/molecule.yml:4-16
Lifecycle Flow
The following diagram illustrates the sequence of operations during a Molecule test run:
The diagram shows the standard Molecule test lifecycle from initialization to cleanup.
Sources: molecule/default/molecule.yml:1-25, molecule/default/converge.yml:1-35
Convergence Logic
The convergence phase (defined in converge.yml) is responsible for preparing the host and executing the datacosmos-br.teleport role.
Pre-tasks and Environment Setup
Before the role is applied, the strategy performs several critical environment checks and setup steps:
- Python 3 Installation: Ensures
/usr/bin/python3is available on Ubuntu (16+) and RedHat (8+) systems. - Fact Gathering: Explicitly gathers facts after Python 3 is verified.
- Interpreter Enforcement: Sets
ansible_python_interpreterto/usr/bin/python3. - Package Cache: Refreshes the apt cache on Debian-based systems.
Sources: molecule/default/converge.yml:7-34
Verification Strategy
The verification phase (defined in verify.yml) uses Ansible assertions to ensure the system state matches expectations after the role has been applied.
Key Verification Checks
| Component | Verification Method | Expected Result |
|---|---|---|
| Config File | ansible.builtin.stat | /etc/teleport.yaml must exist |
| Binary | ansible.builtin.stat | /usr/local/bin/teleport must exist, be mode 0755, and owned by root |
| Systemd Unit | ansible.builtin.stat | /etc/systemd/system/teleport.service must exist and be mode 0644 |
| Process | pgrep | The teleport process should be running (skipped in containers) |
| Network | wait_for | Port 3022 (SSH) should be listening (skipped in containers) |
Sources: molecule/default/verify.yml:21-95
Verification Logic Flow
This flow describes the conditional verification logic used to accommodate container-based testing.
Sources: molecule/default/verify.yml:10-95
Continuous Integration
The testing strategy is integrated into the project's GitHub Actions workflows. The README identifies three primary badges that reflect the status of the Molecule testing strategy:
- Ansible Lint: Validates code quality and best practices.
- Molecule Tests: Executes the full testing lifecycle on every push or pull request to ensure functional integrity.
Sources: README.md:4-6
Constraints and Future Strategy
The current testing strategy has specific limitations identified in the project documentation:
- Container Support: While Molecule uses Docker for testing, the project officially states that installing Teleport in a production docker container is "currently not supported".
- Idempotence: Future improvements aim to add specific idempotence tests to verify that repeated runs do not cause unnecessary changes to config, services, or binaries.
- Variable Templating: Additional tests for complex variable templating are planned.
Sources: README.md:18-21, tasks/preflight/check.yml:8-11
The Molecule testing strategy ensures that the ansible-teleport role is robust, providing developers with confidence that configuration changes and version updates will behave as expected across supported Linux distributions.