From 3fbacfefc1569151f79bcf9f5ca2380eccf3d5e7 Mon Sep 17 00:00:00 2001 From: mjohns91 Date: Fri, 27 Feb 2026 13:21:04 -0500 Subject: [PATCH 1/2] modified CI file to better reflect testing strategy and improved README --- CI.md | 111 ++++++++++++++++++++++-- README.md | 247 ++++++++++++++++++++++++++++++++++++++---------------- 2 files changed, 279 insertions(+), 79 deletions(-) diff --git a/CI.md b/CI.md index d35d663..e1fb486 100644 --- a/CI.md +++ b/CI.md @@ -1,12 +1,105 @@ -# CI +# Continuous Integration (CI) -## cloud.aws_troubleshooting Collection +## AWS Troubleshooting Collection Testing -GitHub Actions are used to run the Continuous Integration for redhat-cop/cloud.aws_troubleshooting collection. The workflows used for the CI can be found [here](https://github.com/redhat-cop/cloud.aws_troubleshooting/tree/main/.github/workflows). These workflows include jobs to run the integration tests, sanity tests, linters, and changelog check. The following table lists the python and ansible versions against which these jobs are run. +GitHub Actions are used to run the CI for the cloud.aws_troubleshooting collection. The workflows used for the CI can be found [here](https://github.com/redhat-cop/cloud.aws_troubleshooting/tree/main/.github/workflows). These workflows include jobs to run the sanity tests, linters, integration tests, and changelog checks. -| Jobs | Description | Python Versions | Ansible Versions | -| ------ |-------| ------ | -----------| -| changelog |Checks for the presence of Changelog fragments | 3.9 | devel | -| Linters | Runs `ansible-lint`, `black`, `flake8`, and `isort` on plugins and tests | 3.9 | devel | -| Sanity | Runs ansible sanity checks | 3.9, 3.10, 3.11, 3.12 | Stable-2.14 (not on py3.12), 2.15 (not on py3.12), 2.16 (not on py 3.9), Milestone, Devel | -| Integration tests | Executes the integration test suites| 3.12 | Milestone | +The collection uses reusable workflows from [ansible-network/github_actions](https://github.com/ansible-network/github_actions) for standardized testing. + +### PR Testing Workflows + +The following tests run on every pull request: + +| Job | Description | Python Versions | ansible-core Versions | +| --- | ----------- | --------------- | --------------------- | +| Changelog | Checks for the presence of changelog fragments | ubuntu-latest default | N/A | +| Linters | Runs `ansible-lint` (via dedicated action) and `black`, `flake8`, `isort` (via tox) | 3.10 (tox linters) | N/A | +| Sanity | Runs ansible sanity checks | See compatibility table below | Determined by reusable workflow | +| Integration tests | Executes integration test suites on AWS (split across 2 jobs, requires "safe to test" label) | 3.12 | milestone | + +### Python Version Compatibility by ansible-core Version + +These are determined by the reusable workflows from [ansible-network/github_actions](https://github.com/ansible-network/github_actions) with specific exclusions applied in the collection's CI configuration. + +For the official Ansible core support matrix, see the [Ansible documentation](https://docs.ansible.com/ansible/latest/reference_appendices/release_and_maintenance.html#ansible-core-support-matrix). + +The collection's minimum requirements: +- **ansible-core**: >=2.17.0 +- **Python**: 3.10+ + +| ansible-core Version | Sanity Tests | Integration Tests | +| -------------------- | ------------ | ----------------- | +| devel | 3.12, 3.13, 3.14 | - | +| stable-2.20 | 3.12, 3.13, 3.14 | - | +| stable-2.19 | 3.11, 3.12, 3.13 | - | +| stable-2.18 | 3.11, 3.12, 3.13 | - | +| stable-2.17 | 3.10, 3.11, 3.12 | - | +| milestone | - | 3.12 | + +**Note**: +- ansible-core 2.16 is completely excluded from testing (reached EOL in May 2025) +- ansible-core 2.17 reached EOL in November 2025 + +### Testing with `ansible-test` + +The `tests` directory contains configuration for running sanity and integration tests using [`ansible-test`](https://docs.ansible.com/ansible/latest/dev_guide/testing_integration.html). + +You can run the collection's test suites with the commands: + +```shell +# Run sanity tests +ansible-test sanity + +# Run integration tests (requires AWS credentials) +ansible-test integration [target] +``` + +Before running integration tests, you must configure AWS credentials: + +```shell +# Using the "default" profile on AWS +aws configure set aws_access_key_id your-access-key +aws configure set aws_secret_access_key your-secret-key +aws configure set region us-east-1 +``` + +The collection also uses `tox` for linting. Assuming this repository is checked out in the proper structure (e.g., `collections_root/ansible_collections/cloud/aws_troubleshooting/`), run: + +```shell +# Run all linters (black, flake8, isort) +tox -e linters + +# Run ansible-lint separately +tox -e ansible-lint +``` + +### Integration Test Details + +Integration tests have specific characteristics: +- Run on real AWS infrastructure using Ansible Core CI AWS provider +- Split across 2 parallel jobs using `ansible_test_splitter` to reduce test execution time +- Require the "safe to test" label on pull requests to prevent unauthorized AWS resource creation +- Use Python 3.12 with `milestone` ansible-core version +- AWS credentials are provided via the `ansible_aws_test_provider` action, which creates temporary STS session credentials + +### Available Integration Test Targets + +The collection includes the following integration test targets: +- `test_aws_setup_credentials` - Validates AWS credential setup functionality +- `test_connectivity_troubleshooter` - Tests the main connectivity troubleshooting role and sub-roles +- `test_troubleshoot_rds_connectivity` - Tests RDS-specific connectivity troubleshooting + +### Additional Dependencies + +The collection depends on the following for integration testing: +- **AWS Environment**: Temporary AWS credentials via Ansible Core CI +- **Python packages**: boto3>=1.26.0, botocore>=1.29.0 +- **Collections**: amazon.aws (>=10.0.0), community.aws (>=10.0.0) +- **Collection dependencies source**: Integration tests use the latest `main` branch versions of amazon.aws and community.aws + +### Security Model + +Integration tests use `pull_request_target` trigger and require explicit approval: +- PRs from external contributors require the "safe to test" label to be added by a maintainer +- This prevents unauthorized execution of tests that create AWS resources +- The `safe-to-test` job validates authorization before any AWS resources are created diff --git a/README.md b/README.md index 39423d2..422c2eb 100644 --- a/README.md +++ b/README.md @@ -1,21 +1,67 @@ -# cloud.aws_troubleshooting Validated Content Collection - -This repository hosts the cloud.aws_troubleshooting Ansible Collection. +# AWS Troubleshooting Collection for Ansible +The Ansible AWS Troubleshooting collection includes a variety of Ansible content to help efficiently diagnose and resolve connectivity and configuration issues within AWS environments. This collection is maintained by the Red Hat Communities of Practice. + +## Contents + +- [Description](#description) +- [Communication](#communication) +- [Requirements](#requirements) + - [Ansible Version Compatibility](#ansible-version-compatibility) + - [Python Version Compatibility](#python-version-compatibility) + - [AWS Version Compatibility](#aws-version-compatibility) +- [Included Content](#included-content) +- [Installation](#installation) + - [Installing Dependencies](#installing-dependencies) +- [Use Cases](#use-cases) +- [Testing](#testing) +- [Contributing to This Collection](#contributing-to-this-collection) +- [Support](#support) +- [Release Notes](#release-notes) +- [Related Information](#related-information) +- [Code of Conduct](#code-of-conduct) +- [License Information](#license-information) ## Description -The cloud.aws_troubleshooting validated content collection in Ansible is designed to help users efficiently diagnose and resolve issues within their AWS environments. This collection includes a variety of Ansible roles and playbooks specifically tailored for troubleshooting common problems encountered in AWS infrastructure. +The primary purpose of this collection is to simplify and streamline the diagnosis and resolution of AWS connectivity and resource configuration issues through automation. By leveraging this collection, organizations can reduce manual troubleshooting effort, minimize errors, and ensure consistent diagnostic approaches. This leads to faster issue resolution and a more reliable infrastructure. + +This collection was formerly known as `redhat_cop.cloud_aws_troubleshooting`. + +## Communication + +* Join the Ansible forum: + * [Get Help](https://forum.ansible.com/c/help/6): get help or help others. + * [Posts tagged with 'aws'](https://forum.ansible.com/tag/aws): subscribe to participate in collection-related conversations. + * [Social Spaces](https://forum.ansible.com/c/chat/4): gather and interact with fellow enthusiasts. + * [News & Announcements](https://forum.ansible.com/c/news/5): track project-wide announcements including social events. + +* The Ansible [Bullhorn newsletter](https://docs.ansible.com/ansible/devel/community/communication.html#the-bullhorn): used to announce releases and important changes. + +For more information about communication, see the [Ansible communication guide](https://docs.ansible.com/ansible/devel/community/communication.html). ## Requirements -The [amazon.aws](https://github.com/ansible-collections/amazon.aws) and [community.aws](https://github.com/ansible-collections/amazon.aws) collections MUST be installed in order for this collection to work. +### Ansible Version Compatibility -### Ansible version compatibility +This collection has been tested against the following Ansible versions: **>=2.17.0**. + +Plugins and modules within a collection may be tested with only specific Ansible versions. +A collection may contain metadata that identifies these versions. +PEP440 is the schema used to describe the versions of Ansible. + -This collection has been tested against following Ansible versions: **>=2.17.0**. +### Python Version Compatibility -### Included content +This collection requires Python 3.10+. + +### AWS Version Compatibility + +This collection requires the following collection dependencies: +- [amazon.aws](https://github.com/ansible-collections/amazon.aws) (>=10.0.0) +- [community.aws](https://github.com/ansible-collections/community.aws) (>=10.0.0) + +## Included Content Click on the name of a role to view that content's documentation: @@ -37,7 +83,43 @@ Name | Description ## Installation -To consume this Validated Content from Automation Hub, please ensure that you add the following lines to your ansible.cfg file. +The cloud.aws_troubleshooting collection can be installed with the Ansible Galaxy command-line tool: + +```shell +ansible-galaxy collection install cloud.aws_troubleshooting +``` + +You can also include it in a `requirements.yml` file and install it with `ansible-galaxy collection install -r requirements.yml`, using the format: + +```yaml +--- +collections: + - name: cloud.aws_troubleshooting +``` + +Note that if you install any collections from Ansible Galaxy, they will not be upgraded automatically when you upgrade the Ansible package. +To upgrade the collection to the latest available version, run the following command: + +```shell +ansible-galaxy collection install cloud.aws_troubleshooting --upgrade +``` + +A specific version of the collection can be installed by using the `version` keyword in the `requirements.yml` file: + +```yaml +--- +collections: + - name: cloud.aws_troubleshooting + version: 5.0.0 +``` + +or using the `ansible-galaxy` command as follows: + +```shell +ansible-galaxy collection install cloud.aws_troubleshooting:==5.0.0 +``` + +To consume this Validated Content from Automation Hub, please ensure that you add the following lines to your ansible.cfg file: ```ini [galaxy] @@ -51,87 +133,103 @@ token= The token can be obtained from the [Automation Hub Web UI](https://console.redhat.com/ansible/automation-hub/token). -Once the above steps are done, you can run the following command to install the collection. +### Installing Dependencies + +The collection dependencies are not installed by `ansible-galaxy` by default. They must be installed separately: ```shell -ansible-galaxy collection install cloud.aws_troubleshooting +ansible-galaxy collection install amazon.aws:>=10.0.0 +ansible-galaxy collection install community.aws:>=10.0.0 +``` + +The Python module dependencies can be installed using pip: + +```shell +pip install boto3>=1.26.0 botocore>=1.29.0 ``` -## Use cases +Refer to the following for more details: +* [Using Ansible collections](https://docs.ansible.com/ansible/latest/user_guide/collections_using.html) -Once installed, you can reference the cloud.aws_troubleshooting collection content by its fully qualified collection name (FQCN), for example: +## Use Cases + +You can call roles by their Fully Qualified Collection Name (FQCN), such as `cloud.aws_troubleshooting.connectivity_troubleshooter`, or by their short name if you list the `cloud.aws_troubleshooting` collection in the playbook's `collections` keyword: ```yaml - # Troubleshoot when ec2 instance cannot connect to rds instance - - hosts: all - tasks: - - name: Validate that role is also failing - block: - - name: Include role cloud.aws_troubleshooting.troubleshoot_rds_connectivity - ansible.builtin.include_role: - name: cloud.aws_troubleshooting.troubleshoot_rds_connectivity - vars: - troubleshoot_rds_connectivity_db_instance_id: "{{ rds_identifier }}" - troubleshoot_rds_connectivity_ec2_instance_id: "{{ ec2_instance_id }}" - rescue: - - name: Set role failure info - ansible.builtin.set_fact: - role_failure_action: "{{ ansible_failed_task.action }}" - role_failure_msg: "{{ ansible_failed_result.msg }}" - - # Troubleshoot AWS resource connectivity - - hosts: all - tasks: - - name: Include 'cloud.aws_troubleshooting.connectivity_troubleshooter' role - ansible.builtin.include_role: - name: cloud.aws_troubleshooting.connectivity_troubleshooter - vars: - connectivity_troubleshooter_destination_ip: "{{ ip_instance_2 }}" - connectivity_troubleshooter_destination_port: 80 - connectivity_troubleshooter_source_ip: "{{ ip_instance_1 }}" +--- +- hosts: localhost + gather_facts: false + connection: local + + tasks: + - name: Troubleshoot connectivity between AWS resources + ansible.builtin.include_role: + name: cloud.aws_troubleshooting.connectivity_troubleshooter + vars: + connectivity_troubleshooter_source_ip: "{{ ip_instance_1 }}" + connectivity_troubleshooter_destination_ip: "{{ ip_instance_2 }}" + connectivity_troubleshooter_destination_port: 80 + + - name: Troubleshoot RDS connectivity from EC2 instance + ansible.builtin.include_role: + name: cloud.aws_troubleshooting.troubleshoot_rds_connectivity + vars: + troubleshoot_rds_connectivity_db_instance_id: "{{ rds_identifier }}" + troubleshoot_rds_connectivity_ec2_instance_id: "{{ ec2_instance_id }}" ``` -## Contributing to this collection +If upgrading older playbooks which were built prior to Ansible 2.10 and this collection's existence, you can also define `collections` in your play and refer to this collection's roles as you did in Ansible 2.9 and below, as in this example: -We welcome community contributions to this collection. If you find problems, please open an issue or create a PR against this collection repository. -See [CONTRIBUTING.md](https://github.com/redhat-cop/cloud.aws_troubleshooting/blob/main/CONTRIBUTING.md) for more details. +```yaml +--- +- hosts: localhost + gather_facts: false + connection: local + + collections: + - cloud.aws_troubleshooting + + tasks: + - name: Troubleshoot connectivity between AWS resources + ansible.builtin.include_role: + name: connectivity_troubleshooter + vars: + connectivity_troubleshooter_source_ip: "{{ ip_instance_1 }}" + connectivity_troubleshooter_destination_ip: "{{ ip_instance_2 }}" + connectivity_troubleshooter_destination_port: 80 +``` -### Testing +For documentation on how to use individual roles and other content included in this collection, please see the links in the [Included Content](#included-content) section. -The project uses `ansible-lint` and `black`. -Assuming this repository is checked out in the proper structure, -e.g. `collections_root/ansible_collections/cloud/aws_troubleshooting/`, run: +## Testing -```shell - tox -e linters -``` +This collection is tested using GitHub Actions. To learn more about testing, refer to [CI.md](https://github.com/redhat-cop/cloud.aws_troubleshooting/blob/main/CI.md). -Sanity and unit tests are run as normal: +## Contributing to This Collection -```shell - ansible-test sanity -``` +We welcome community contributions to this collection. If you find problems, please open an issue or create a PR against the [AWS Troubleshooting collection repository](https://github.com/redhat-cop/cloud.aws_troubleshooting). -If you want to run cloud integration tests, ensure you log in to the cloud: +If you want to develop new content for this collection or improve what's already here, the easiest way to work on the collection is to clone it into one of the configured [`COLLECTIONS_PATHS`](https://docs.ansible.com/ansible/latest/reference_appendices/config.html#collections-paths), and work on it there. -```shell -# using the "default" profile on AWS - aws configure set aws_access_key_id my-access-key - aws configure set aws_secret_access_key my-secret-key - aws configure set region eu-north-1 +See [CONTRIBUTING.md](https://github.com/redhat-cop/cloud.aws_troubleshooting/blob/main/CONTRIBUTING.md) for more details. - ansible-test integration [target] -``` +### More information about contributing -This collection is tested using GitHub Actions. To know more about CI, refer to [CI.md](https://github.com/redhat-cop/cloud.aws_troubleshooting/blob/main/CI.md). +- [Ansible Community Guide](https://docs.ansible.com/ansible/latest/community/index.html) - Details on contributing to Ansible +- [Contributing to Collections](https://docs.ansible.com/ansible/devel/dev_guide/developing_collections.html#contributing-to-collections) - How to check out collection git repositories correctly ## Support +We announce releases and important changes through Ansible's [The Bullhorn newsletter](https://github.com/ansible/community/wiki/News#the-bullhorn). Be sure you are [subscribed](https://eepurl.com/gZmiEP). + +We take part in the global quarterly [Ansible Contributor Summit](https://github.com/ansible/community/wiki/Contributor-Summit) virtually or in-person. Track [The Bullhorn newsletter](https://eepurl.com/gZmiEP) and join us. + +For more information about communication, refer to the [Ansible Communication guide](https://docs.ansible.com/ansible/devel/community/communication.html). + For the latest supported versions, refer to the release notes below. If you encounter issues or have questions, you can submit a support request through the following channels: - GitHub Issues: Report bugs, request features, or ask questions by opening an issue in the [GitHub repository](https://github.com/redhat-cop/cloud.aws_troubleshooting/). - - Ansible Community: Engage with the Ansible community on the Ansible Project Mailing List or [Ansible Forum](https://forum.ansible.com/g/AWS). ## Release Notes @@ -139,11 +237,20 @@ See the [raw generated changelog](https://github.com/redhat-cop/cloud.aws_troubl ## Related Information - - [Ansible User guide](https://docs.ansible.com/ansible/latest/user_guide/index.html). - - [Ansible Rulebook documentation](https://ansible.readthedocs.io/projects/rulebook/en/stable/index.html). - - [Ansible Community code of conduct](https://docs.ansible.com/ansible/latest/community/code_of_conduct.html) +- [Ansible Collection overview](https://github.com/ansible-collections/overview) +- [Ansible User guide](https://docs.ansible.com/ansible/latest/user_guide/index.html) +- [Ansible Developer guide](https://docs.ansible.com/ansible/latest/dev_guide/index.html) +- [Ansible Collection Developer Guide](https://docs.ansible.com/ansible/devel/dev_guide/developing_collections.html) +- [Ansible Community code of conduct](https://docs.ansible.com/ansible/latest/community/code_of_conduct.html) + +## Code of Conduct + +We follow the [Ansible Code of Conduct](https://docs.ansible.com/ansible/devel/community/code_of_conduct.html) in all our interactions within this project. + +If you encounter abusive behavior, please refer to the [policy violations](https://docs.ansible.com/ansible/devel/community/code_of_conduct.html#policy-violations) section of the Code for information on how to raise a complaint. + +## License Information -## License +GNU General Public License v3.0 or later. -GNU General Public License v3.0 or later -See [LICENSE](https://github.com/redhat-cop/cloud.aws_troubleshooting/blob/main/LICENSE) to see the full text. +See [COPYING](https://www.gnu.org/licenses/gpl-3.0.txt) to see the full text. From 70fcba023e0ca577fd76cbbcc363a577051e8fdf Mon Sep 17 00:00:00 2001 From: mjohns91 Date: Fri, 27 Feb 2026 13:29:33 -0500 Subject: [PATCH 2/2] removed some references from README --- README.md | 15 --------------- 1 file changed, 15 deletions(-) diff --git a/README.md b/README.md index 422c2eb..8c00053 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,6 @@ The Ansible AWS Troubleshooting collection includes a variety of Ansible content ## Contents - [Description](#description) -- [Communication](#communication) - [Requirements](#requirements) - [Ansible Version Compatibility](#ansible-version-compatibility) - [Python Version Compatibility](#python-version-compatibility) @@ -25,20 +24,6 @@ The Ansible AWS Troubleshooting collection includes a variety of Ansible content The primary purpose of this collection is to simplify and streamline the diagnosis and resolution of AWS connectivity and resource configuration issues through automation. By leveraging this collection, organizations can reduce manual troubleshooting effort, minimize errors, and ensure consistent diagnostic approaches. This leads to faster issue resolution and a more reliable infrastructure. -This collection was formerly known as `redhat_cop.cloud_aws_troubleshooting`. - -## Communication - -* Join the Ansible forum: - * [Get Help](https://forum.ansible.com/c/help/6): get help or help others. - * [Posts tagged with 'aws'](https://forum.ansible.com/tag/aws): subscribe to participate in collection-related conversations. - * [Social Spaces](https://forum.ansible.com/c/chat/4): gather and interact with fellow enthusiasts. - * [News & Announcements](https://forum.ansible.com/c/news/5): track project-wide announcements including social events. - -* The Ansible [Bullhorn newsletter](https://docs.ansible.com/ansible/devel/community/communication.html#the-bullhorn): used to announce releases and important changes. - -For more information about communication, see the [Ansible communication guide](https://docs.ansible.com/ansible/devel/community/communication.html). - ## Requirements ### Ansible Version Compatibility