Reporting Bugs
Relevant source files
The following files were used as context for generating this wiki page:
Reporting bugs is a critical process for maintaining the reliability of the ansible-teleport role. It involves providing structured feedback when the automation fails to install, configure, or manage the Teleport node service correctly across supported Linux distributions like RedHat, Debian, and Alpine.
Effective bug reports help maintainers identify issues within the multi-step deployment pipeline, which includes preflight checks, version detection, security credential management, and service orchestration. Users are encouraged to validate their environment against the role's requirements before submitting a report.
Bug Report Structure
The project utilizes a standardized template to ensure all necessary technical context is captured during the reporting process. This structure helps distinguish between environment-specific issues and logic errors within the Ansible tasks.
Required Information
When a bug is encountered, the following details must be provided:
- Description: A clear and concise description of what the bug is.
- Steps To Reproduce: The exact steps taken that lead to the behavior.
- Expected Behavior: A description of what was expected to happen.
- Screenshots/Logs: Visual aids or terminal output (e.g., Ansible-playbook execution logs) to help explain the problem.
Sources: .github/ISSUE_TEMPLATE/bug_report.md:4-22, README.md:1-20
Common Failure Points and Debugging
The role includes several validation and verification stages where bugs are frequently identified. Understanding these stages assists in providing more accurate reports.
Preflight and Versioning Failures
The automation begins with mandatory configuration checks and version detection. Issues often arise if the teleport_proxy_server or teleport_cluster_name are missing, or if an unsupported OS family is detected.
The diagram shows the initial validation flow where preflight checks may trigger a failure.
Sources: tasks/preflight/check.yml:4-21, tasks/preflight/version.yml:19-25
Infrastructure and Service Verification
The project uses Molecule for testing. Failures in the verify.yml stage often indicate bugs in service persistence or network binding.
| Component | Validation Method | Expected State |
|---|---|---|
| Config File | stat /etc/teleport.yaml | File must exist |
| Binary | stat /usr/local/bin/teleport | Mode 0755, owned by root |
| Service | systemctl / pgrep | Process running as root |
| Networking | wait_for port 3022 | Port listening (non-containers) |
Sources: molecule/default/verify.yml:25-85, defaults/main.yml:102-104
Technical Environment Context
When reporting a bug, it is essential to specify the architecture and edition of Teleport being used, as the role handles multiple binary types and installation methods (tar vs. package).
Environment Variables for Debugging
The following configuration variables often impact the behavior of the role and should be included in bug reports if they deviate from defaults:
| Variable | Default Value | Description |
|---|---|---|
teleport_architecture | amd64-bin | Supported: arm-bin, arm64-bin, amd64-bin, 386-bin |
teleport_edition | oss | Options: oss, enterprise, cloud |
teleport_version | 15.4.11 | Minimum supported version is 14.0.0 |
is_container | Autodetected | Boolean flag for Docker/Containerd environments |
Sources: defaults/main.yml:8-20, tasks/preflight/check.yml:13-16, tasks/preflight/version.yml:20-21
Conclusion
Reporting bugs with comprehensive logs and environment details ensures that issues regarding Teleport installation, security credential migration, and service management are resolved efficiently. By utilizing the provided templates and understanding the internal validation logic of the role, contributors can significantly improve the project's stability.