From 92d3a0828be13952dcea1408c88c09828f09f10b Mon Sep 17 00:00:00 2001 From: mjohns91 Date: Fri, 27 Feb 2026 13:59:54 -0500 Subject: [PATCH 1/6] modified CI file and enhance the README --- CI.md | 128 ++++++++++++++++++++++-- README.md | 293 +++++++++++++++++++++++++++++++++++++++--------------- 2 files changed, 332 insertions(+), 89 deletions(-) diff --git a/CI.md b/CI.md index 8283992d..ef5becf1 100644 --- a/CI.md +++ b/CI.md @@ -1,11 +1,123 @@ -# CI +# Continuous Integration (CI) -## cloud.aws_ops Collection +## AWS Operations Collection Testing -GitHub Actions are used to run the Continuous Integration for redhat-cop/cloud.aws_ops collection. The workflows used for the CI can be found [here](https://github.com/redhat-cop/cloud.aws_ops/tree/main/.github/workflows). These workflows include jobs to run the 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_ops collection. The workflows used for the CI can be found [here](https://github.com/redhat-cop/cloud.aws_ops/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` and `flake8` on plugins and tests | 3.8, 3.9(ansible-lint) | devel | -| Sanity | Runs ansible sanity checks | 3.8, 3.9, 3.10, 3.11 | Stable-2.12, 2.13, 2.14 (not on py 3.11), Stable-2.15+ (not on 3.8) | +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`, `yamllint` (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.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 +- Additional exclusions: devel and milestone on Python 3.10-3.11, stable-2.18/2.19 on Python 3.10, stable-2.17 on Python 3.13 + +### 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_ops/`), run: + +```shell +# Run all linters (black, flake8, yamllint) +tox -e linters + +# Run ansible-lint separately +tox -e ansible-lint + +# Run black formatter +tox -e black +``` + +### 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_awsconfig_apigateway_with_lambda_integration` - Tests API Gateway with Lambda integration setup +- `test_awsconfig_detach_and_delete_internet_gateway` - Tests detaching and deleting Internet Gateways +- `test_awsconfig_multiregion_cloudtrail` - Tests multi-region CloudTrail configuration +- `test_aws_setup_credentials` - Validates AWS credential setup functionality +- `test_backup_create_plan` - Tests AWS Backup plan creation +- `test_backup_select_resources` - Tests AWS Backup resource selection +- `test_create_rds_global_cluster` - Tests RDS global cluster creation +- `test_customized_ami` - Tests custom AMI creation and management +- `test_deploy_flask_app` - Tests Flask application deployment on AWS +- `test_ec2_instance_terminate_by_tag` - Tests EC2 instance termination by tags +- `test_ec2_networking_resources` - Tests EC2 networking resource setup +- `test_enable_cloudtrail_encryption_with_kms` - Tests CloudTrail encryption with KMS +- `test_manage_ec2_instance` - Tests EC2 instance lifecycle management +- `test_manage_transit_gateway` - Tests Transit Gateway management +- `test_manage_vpc_peering` - Tests VPC peering configuration +- `test_move_objects_between_buckets` - Tests S3 object movement between buckets +- `test_upload_file_to_s3` - Tests file upload to S3 + +### 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 (>=5.1.0), community.aws (>=5.0.0), amazon.cloud (>=0.4.0), community.libvirt (>=1.2.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 5eb7060b..78c5a6e7 100644 --- a/README.md +++ b/README.md @@ -1,66 +1,149 @@ -# cloud.aws_ops Validated Content Collection - -This repository hosts the `cloud.aws_ops` Ansible Collection. +# AWS Operations Collection for Ansible +The Ansible AWS Operations collection includes a variety of Ansible content to help automate, manage, and streamline common operational tasks within AWS environments. This collection is maintained by the Red Hat Communities of Practice. + +## Contents + +- [Description](#description) +- [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 -This collection is curated to provide users with a robust set of roles, playbooks, and rulebooks that simplify and streamline various AWS operations. +The primary purpose of this collection is to simplify and streamline AWS operations through automation. By leveraging this collection, organizations can reduce manual operational effort, minimize errors, and ensure consistent approaches to managing AWS infrastructure. This leads to faster deployments, better security posture, and more reliable infrastructure management. ## 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. - -To run rulebooks, [ansible-rulebook](https://ansible.readthedocs.io/projects/rulebook/en/latest/) must be installed. +### 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. + + +### Python Version Compatibility + +This collection requires Python 3.10+. -This collection has been tested against following Ansible versions: **>=2.17.0**. +### AWS Version Compatibility -### Included content +This collection requires the following collection dependencies: +- [amazon.aws](https://github.com/ansible-collections/amazon.aws) (>=5.1.0) +- [community.aws](https://github.com/ansible-collections/community.aws) (>=5.0.0) +- [amazon.cloud](https://github.com/ansible-collections/amazon.cloud) (>=0.4.0) +- [community.libvirt](https://github.com/ansible-collections/community.libvirt) (>=1.2.0) + +For Event-Driven Ansible features, [ansible-rulebook](https://ansible.readthedocs.io/projects/rulebook/en/latest/) must be installed separately. + +## Included Content Click on the name of a role, playbook, or rulebook to view that content's documentation: ### Roles + Name | Description --- | --- -[cloud.aws_ops.aws_setup_credentials](roles/aws_setup_credentials/README.md)|A role to define credentials for aws modules. -[cloud.aws_ops.awsconfig_detach_and_delete_internet_gateway](roles/awsconfig_detach_and_delete_internet_gateway/README.md)|A role to detach and delete the internet gateway you specify from virtual private cloud. -[cloud.aws_ops.awsconfig_multiregion_cloudtrail](roles/awsconfig_multiregion_cloudtrail/README.md)|A role to create/delete a Trail for multiple regions. -[cloud.aws_ops.backup_create_plan](roles/backup_create_plan/README.md)|A role to create an AWS backup plan. -[cloud.aws_ops.backup_select_resources](roles/backup_select_resources/README.md)|A role to select resources to back up with an existing backup plan. -[cloud.aws_ops.customized_ami](roles/customized_ami/README.md)|A role to manage custom AMIs on AWS. -[cloud.aws_ops.ec2_instance_terminate_by_tag](roles/ec2_instance_terminate_by_tag/README.md)|A role to terminate the EC2 instances based on a specific tag you specify. -[cloud.aws_ops.enable_cloudtrail_encryption_with_kms](roles/enable_cloudtrail_encryption_with_kms/README.md)|A role to encrypt an AWS CloudTrail trail using the AWS Key Management Service (AWS KMS) customer managed key you specify. -[cloud.aws_ops.manage_vpc_peering](roles/manage_vpc_peering/README.md)|A role to create, delete and accept existing VPC peering connections. -[cloud.aws_ops.move_objects_between_buckets](roles/move_objects_between_buckets/README.md)|A role to move objects from one bucket to another bucket. -[cloud.aws_ops.awsconfig_apigateway_with_lambda_integration](roles/awsconfig_apigateway_with_lambda_integration/README.md)|A role to create/delete an API gateway with lambda function integration. -[cloud.aws_ops.manage_transit_gateway](roles/manage_transit_gateway/README.md)|A role to create/delete transit_gateway with vpc and vpn attachments. -[cloud.aws_ops.deploy_flask_app](roles/deploy_flask_app/README.md)|A role to deploy a flask web application on AWS. -[cloud.aws_ops.create_rds_global_cluster](roles/create_rds_global_cluster/README.md)|A role to create, delete aurora global cluster with a primary cluster and a replica cluster in different regions. -[cloud.aws_ops.clone_on_prem_vm](roles/clone_on_prem_vm/README.md)|A role to clone an existing on prem VM using the KVM hypervisor. -[cloud.aws_ops.import_image_and_run_aws_instance](roles/import_image_and_run_aws_instance/README.md)|A role that imports a local .raw image into an Amazon Machine Image (AMI) and run an AWS EC2 instance. +[cloud.aws_ops.aws_setup_credentials](https://github.com/redhat-cop/cloud.aws_ops/blob/main/roles/aws_setup_credentials/README.md)|A role to define credentials for AWS modules. +[cloud.aws_ops.awsconfig_apigateway_with_lambda_integration](https://github.com/redhat-cop/cloud.aws_ops/blob/main/roles/awsconfig_apigateway_with_lambda_integration/README.md)|A role to create/delete an API Gateway with Lambda function integration. +[cloud.aws_ops.awsconfig_detach_and_delete_internet_gateway](https://github.com/redhat-cop/cloud.aws_ops/blob/main/roles/awsconfig_detach_and_delete_internet_gateway/README.md)|A role to detach and delete the internet gateway you specify from a virtual private cloud. +[cloud.aws_ops.awsconfig_multiregion_cloudtrail](https://github.com/redhat-cop/cloud.aws_ops/blob/main/roles/awsconfig_multiregion_cloudtrail/README.md)|A role to create/delete a trail for multiple regions. +[cloud.aws_ops.backup_create_plan](https://github.com/redhat-cop/cloud.aws_ops/blob/main/roles/backup_create_plan/README.md)|A role to create an AWS Backup plan. +[cloud.aws_ops.backup_select_resources](https://github.com/redhat-cop/cloud.aws_ops/blob/main/roles/backup_select_resources/README.md)|A role to select resources to back up with an existing backup plan. +[cloud.aws_ops.clone_on_prem_vm](https://github.com/redhat-cop/cloud.aws_ops/blob/main/roles/clone_on_prem_vm/README.md)|A role to clone an existing on-premises VM using the KVM hypervisor. +[cloud.aws_ops.create_rds_global_cluster](https://github.com/redhat-cop/cloud.aws_ops/blob/main/roles/create_rds_global_cluster/README.md)|A role to create/delete Aurora global cluster with a primary cluster and a replica cluster in different regions. +[cloud.aws_ops.customized_ami](https://github.com/redhat-cop/cloud.aws_ops/blob/main/roles/customized_ami/README.md)|A role to manage custom AMIs on AWS. +[cloud.aws_ops.deploy_flask_app](https://github.com/redhat-cop/cloud.aws_ops/blob/main/roles/deploy_flask_app/README.md)|A role to deploy a Flask web application on AWS. +[cloud.aws_ops.ec2_instance_terminate_by_tag](https://github.com/redhat-cop/cloud.aws_ops/blob/main/roles/ec2_instance_terminate_by_tag/README.md)|A role to terminate EC2 instances based on a specific tag you specify. +[cloud.aws_ops.ec2_networking_resources](https://github.com/redhat-cop/cloud.aws_ops/blob/main/roles/ec2_networking_resources/README.md)|A role to manage EC2 networking resources. +[cloud.aws_ops.enable_cloudtrail_encryption_with_kms](https://github.com/redhat-cop/cloud.aws_ops/blob/main/roles/enable_cloudtrail_encryption_with_kms/README.md)|A role to encrypt an AWS CloudTrail trail using the AWS Key Management Service (AWS KMS) customer managed key you specify. +[cloud.aws_ops.import_image_and_run_aws_instance](https://github.com/redhat-cop/cloud.aws_ops/blob/main/roles/import_image_and_run_aws_instance/README.md)|A role that imports a local .raw image into an Amazon Machine Image (AMI) and runs an AWS EC2 instance. +[cloud.aws_ops.manage_ec2_instance](https://github.com/redhat-cop/cloud.aws_ops/blob/main/roles/manage_ec2_instance/README.md)|A role to manage EC2 instance lifecycle operations. +[cloud.aws_ops.manage_transit_gateway](https://github.com/redhat-cop/cloud.aws_ops/blob/main/roles/manage_transit_gateway/README.md)|A role to create/delete transit gateway with VPC and VPN attachments. +[cloud.aws_ops.manage_vpc_peering](https://github.com/redhat-cop/cloud.aws_ops/blob/main/roles/manage_vpc_peering/README.md)|A role to create, delete, and accept existing VPC peering connections. +[cloud.aws_ops.move_objects_between_buckets](https://github.com/redhat-cop/cloud.aws_ops/blob/main/roles/move_objects_between_buckets/README.md)|A role to move objects from one S3 bucket to another bucket. ### Playbooks + Name | Description --- | --- -[cloud.aws_ops.eda](playbooks/README.md)|A set of playbooks to restore AWS Cloudtrail configurations, created for use with the [cloud.aws_manage_cloudtrail_encryption rulebook](extensions/eda/AWS_MANAGE_CLOUDTRAIL_ENCRYPTION.md). -[cloud.aws_ops.webapp](playbooks/webapp/README.md)|A set of playbooks to create, delete, or migrate a webapp on AWS. -[cloud.aws_ops.upload_file_to_s3](playbooks/UPLOAD_FILE_TO_S3.md)|A playbook to upload a local file to S3. -[cloud.aws_ops.move_vm_from_on_prem_to_aws](playbooks/move_vm_from_on_prem_to_aws/README.md)|A playbook to migrate an existing on prem VM running on KVM hypervisor to AWS. +[cloud.aws_ops.eda](https://github.com/redhat-cop/cloud.aws_ops/blob/main/playbooks/README.md)|A set of playbooks to restore AWS CloudTrail configurations, created for use with Event-Driven Ansible rulebooks. +[cloud.aws_ops.webapp](https://github.com/redhat-cop/cloud.aws_ops/blob/main/playbooks/webapp/README.md)|A set of playbooks to create, delete, or migrate a web application on AWS. +[cloud.aws_ops.upload_file_to_s3](https://github.com/redhat-cop/cloud.aws_ops/blob/main/playbooks/UPLOAD_FILE_TO_S3.md)|A playbook to upload a local file to S3. +[cloud.aws_ops.move_vm_from_on_prem_to_aws](https://github.com/redhat-cop/cloud.aws_ops/blob/main/playbooks/move_vm_from_on_prem_to_aws/README.md)|A playbook to migrate an existing on-premises VM running on KVM hypervisor to AWS. ### Rulebooks + +Name | Description +--- | --- +[cloud.aws_ops.aws_manage_cloudtrail_encryption](https://github.com/redhat-cop/cloud.aws_ops/blob/main/extensions/eda/AWS_MANAGE_CLOUDTRAIL_ENCRYPTION.md)|An Event-Driven Ansible rulebook to ensure that an existing encrypted AWS CloudTrail trail will not be deleted or have its encryption removed. + +### Modules + Name | Description --- | --- -[cloud.aws_ops.aws_manage_cloudtrail_encryption](extensions/eda/AWS_MANAGE_CLOUDTRAIL_ENCRYPTION.md)|An Event-Driven Ansible rulebook to ensure that an existing encrypted AWS Cloudtrail trail will not be deleted or have its encryption removed. +[cloud.aws_ops.validate_network_acls](https://github.com/redhat-cop/cloud.aws_ops/blob/main/plugins/modules/validate_network_acls.py)|Validates network ACL configurations for connectivity between AWS resources. +[cloud.aws_ops.validate_route_tables](https://github.com/redhat-cop/cloud.aws_ops/blob/main/plugins/modules/validate_route_tables.py)|Validates route table configurations for connectivity between AWS resources. +[cloud.aws_ops.validate_security_group_rules](https://github.com/redhat-cop/cloud.aws_ops/blob/main/plugins/modules/validate_security_group_rules.py)|Validates security group rules for connectivity between AWS resources. + ## 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_ops collection can be installed with the Ansible Galaxy command-line tool: +```shell +ansible-galaxy collection install cloud.aws_ops ``` + +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_ops +``` + +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_ops --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_ops + version: 5.0.0 +``` + +or using the `ansible-galaxy` command as follows: + +```shell +ansible-galaxy collection install cloud.aws_ops:==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] server_list = automation_hub @@ -69,34 +152,83 @@ url=https://cloud.redhat.com/api/automation-hub/ auth_url=https://sso.redhat.com/auth/realms/redhat-external/protocol/openid-connect/token 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 amazon.aws:>=5.1.0 +ansible-galaxy collection install community.aws:>=5.0.0 +ansible-galaxy collection install amazon.cloud:>=0.4.0 +ansible-galaxy collection install community.libvirt:>=1.2.0 ``` -ansible-galaxy collection install cloud.aws_ops + +The Python module dependencies can be installed using pip: + +```shell +pip install boto3>=1.26.0 botocore>=1.29.0 ``` +Refer to the following for more details: +* [Using Ansible collections](https://docs.ansible.com/ansible/latest/user_guide/collections_using.html) + ## Use Cases -Once installed, you can reference the cloud.aws_ops collection content by its fully qualified collection name (FQCN), for example: +You can call roles by their Fully Qualified Collection Name (FQCN), such as `cloud.aws_ops.enable_cloudtrail_encryption_with_kms`, or by their short name if you list the `cloud.aws_ops` collection in the playbook's `collections` keyword: + +```yaml +--- +- hosts: localhost + gather_facts: false + connection: local + + tasks: + - name: Restore encryption to an existing AWS CloudTrail trail + ansible.builtin.include_role: + name: cloud.aws_ops.enable_cloudtrail_encryption_with_kms + vars: + enable_cloudtrail_encryption_with_kms_trail_name: "{{ cloudtrail_name }}" + enable_cloudtrail_encryption_with_kms_kms_key_id: "{{ kms_alias }}" + + - name: Create VPC peering connection + ansible.builtin.include_role: + name: cloud.aws_ops.manage_vpc_peering + vars: + manage_vpc_peering_operation: create + manage_vpc_peering_vpc_id: "{{ vpc_id_1 }}" + manage_vpc_peering_peer_vpc_id: "{{ vpc_id_2 }}" +``` + +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: ```yaml - # The following example restores encryption to an existing AWS Cloudtrail trail using the enable_cloudtrail_encryption_with_kms role - - hosts: all - tasks: - - name: Include 'enable_cloudtrail_encryption_with_kms' role - ansible.builtin.include_role: - name: cloud.aws_ops.enable_cloudtrail_encryption_with_kms - vars: - enable_cloudtrail_encryption_with_kms_trail_name: "{{ cloudtrail_name }}" - enable_cloudtrail_encryption_with_kms_kms_key_id: "{{ kms_alias }}" - - # The following example uses the ``cloud.aws_ops.clone_on_prem_vm`` role to clone an existing VM on prem using the KVM hypervisor and the ``cloud.aws_ops.import_image_and_run_aws_instance`` role to import a local .raw image into an Amazon machine image (AMI) and run an AWS EC2 instance. - - - hosts: all - tasks: - - name: Import 'cloud.aws_ops.clone_on_prem_vm' role +--- +- hosts: localhost + gather_facts: false + connection: local + + collections: + - cloud.aws_ops + + tasks: + - name: Create AWS Backup plan + ansible.builtin.include_role: + name: backup_create_plan + vars: + backup_create_plan_name: "{{ backup_plan_name }}" + backup_create_plan_rules: "{{ backup_rules }}" +``` + +For migrating VMs from on-premises to AWS: + +```yaml +--- +- hosts: all + tasks: + - name: Clone on-premises VM ansible.builtin.import_role: name: cloud.aws_ops.clone_on_prem_vm vars: @@ -107,7 +239,7 @@ Once installed, you can reference the cloud.aws_ops collection content by its fu clone_on_prem_vm_overwrite: "{{ overwrite }}" delegate_to: kvm - - name: Import 'cloud.aws_ops.import_image_and_run_aws_instance' role + - name: Import image and run AWS instance ansible.builtin.import_role: name: cloud.aws_ops.import_image_and_run_aws_instance vars: @@ -119,41 +251,32 @@ Once installed, you can reference the cloud.aws_ops collection content by its fu import_image_and_run_aws_instance_keypair_name: "{{ keypair_name }}" ``` +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. + ## Testing -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_ops/`, run: +This collection is tested using GitHub Actions. To learn more about testing, refer to [CI.md](https://github.com/redhat-cop/cloud.aws_ops/blob/main/CI.md). -```shell - tox -e linters -``` +## Contributing to This Collection -Sanity and unit tests are run as normal: +We welcome community contributions to this collection. If you find problems, please open an issue or create a PR against the [AWS Operations collection repository](https://github.com/redhat-cop/cloud.aws_ops). -```shell - ansible-test sanity -``` +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. -If you want to run cloud integration tests, ensure you log in to the cloud: +See [CONTRIBUTING.md](https://github.com/redhat-cop/cloud.aws_ops/blob/main/CONTRIBUTING.md) for more details. -```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 +### More information about contributing - ansible-test integration [target] -``` +- [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 -This collection is tested using GitHub Actions. To know more about CI, refer to [CI.md](https://github.com/https://github.com/redhat-cop/cloud.aws_ops/blob/main/CI.md). +## Support -## Contributing to this collection +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 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_ops/blob/main/CONTRIBUTING.md) for more details. +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. -## Support +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. @@ -165,15 +288,23 @@ If you encounter issues or have questions, you can submit a support request thro See the [raw generated changelog](https://github.com/redhat-cop/cloud.aws_ops/blob/main/CHANGELOG.rst). - ## 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 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) + +## 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 +## License Information -GNU General Public License v3.0 or later +GNU General Public License v3.0 or later. -See [LICENSE](LICENSE) to see the full text. +See [COPYING](https://www.gnu.org/licenses/gpl-3.0.txt) to see the full text. From d7a4ce3b7a4605f08031638c0296d6bd18d62749 Mon Sep 17 00:00:00 2001 From: mjohns91 Date: Fri, 6 Mar 2026 15:09:21 -0500 Subject: [PATCH 2/6] addressed all feedback from review, simplified the docs --- CI.md | 112 +++---------------------- README.md | 241 ++++++++++++++++++++++-------------------------------- 2 files changed, 108 insertions(+), 245 deletions(-) diff --git a/CI.md b/CI.md index ef5becf1..69101dbd 100644 --- a/CI.md +++ b/CI.md @@ -10,110 +10,20 @@ The collection uses reusable workflows from [ansible-network/github_actions](htt 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`, `yamllint` (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 | +| Job | Description | Configuration | +| --- | ----------- | ------------- | +| Changelog | Checks for the presence of changelog fragments | ubuntu-latest | +| Linters | Runs `ansible-lint`, `black`, `flake8`, `yamllint` | Python 3.10 (via tox) | +| Sanity | Runs ansible sanity checks across multiple Python and ansible-core versions | Determined by [ansible-network reusable workflows](https://github.com/ansible-network/github_actions) | +| Integration tests | Executes integration test suites on AWS (split across 2 parallel jobs) | Python 3.12, ansible-core milestone, requires "safe to test" label | -### Python Version Compatibility by ansible-core Version +For the official Ansible core support matrix, see the [Ansible Release and Maintenance documentation](https://docs.ansible.com/ansible/latest/reference_appendices/release_and_maintenance.html#ansible-core-support-matrix). -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. +### Collection Dependencies -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.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 -- Additional exclusions: devel and milestone on Python 3.10-3.11, stable-2.18/2.19 on Python 3.10, stable-2.17 on Python 3.13 - -### 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_ops/`), run: - -```shell -# Run all linters (black, flake8, yamllint) -tox -e linters - -# Run ansible-lint separately -tox -e ansible-lint - -# Run black formatter -tox -e black -``` - -### 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_awsconfig_apigateway_with_lambda_integration` - Tests API Gateway with Lambda integration setup -- `test_awsconfig_detach_and_delete_internet_gateway` - Tests detaching and deleting Internet Gateways -- `test_awsconfig_multiregion_cloudtrail` - Tests multi-region CloudTrail configuration -- `test_aws_setup_credentials` - Validates AWS credential setup functionality -- `test_backup_create_plan` - Tests AWS Backup plan creation -- `test_backup_select_resources` - Tests AWS Backup resource selection -- `test_create_rds_global_cluster` - Tests RDS global cluster creation -- `test_customized_ami` - Tests custom AMI creation and management -- `test_deploy_flask_app` - Tests Flask application deployment on AWS -- `test_ec2_instance_terminate_by_tag` - Tests EC2 instance termination by tags -- `test_ec2_networking_resources` - Tests EC2 networking resource setup -- `test_enable_cloudtrail_encryption_with_kms` - Tests CloudTrail encryption with KMS -- `test_manage_ec2_instance` - Tests EC2 instance lifecycle management -- `test_manage_transit_gateway` - Tests Transit Gateway management -- `test_manage_vpc_peering` - Tests VPC peering configuration -- `test_move_objects_between_buckets` - Tests S3 object movement between buckets -- `test_upload_file_to_s3` - Tests file upload to S3 - -### 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 (>=5.1.0), community.aws (>=5.0.0), amazon.cloud (>=0.4.0), community.libvirt (>=1.2.0) -- **Collection dependencies source**: Integration tests use the latest `main` branch versions of amazon.aws and community.aws +The collection depends on several other collections for integration testing. These dependencies are defined in: +- [`galaxy.yml`](galaxy.yml) - Production dependencies +- [`tests/integration/requirements.yml`](tests/integration/requirements.yml) - Test-time dependencies ### Security Model diff --git a/README.md b/README.md index 78c5a6e7..45d8acfe 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,5 @@ -# AWS Operations Collection for Ansible -The Ansible AWS Operations collection includes a variety of Ansible content to help automate, manage, and streamline common operational tasks within AWS environments. This collection is maintained by the Red Hat Communities of Practice. +# cloud.aws_ops Validated Content Collection +The Ansible AWS Operations collection includes a variety of Ansible content to help automate, manage, and streamline common operational tasks within AWS environments. This collection is maintained by the [Red Hat Communities of Practice](https://github.com/redhat-cop). ## Contents @@ -9,10 +9,16 @@ The Ansible AWS Operations collection includes a variety of Ansible content to h - [Python Version Compatibility](#python-version-compatibility) - [AWS Version Compatibility](#aws-version-compatibility) - [Included Content](#included-content) + - [Roles](#roles) + - [Playbooks](#playbooks) + - [Rulebooks](#rulebooks) + - [Modules](#modules) - [Installation](#installation) - [Installing Dependencies](#installing-dependencies) - [Use Cases](#use-cases) - [Testing](#testing) + - [Continuous Integration](#continuious-integration) + - [Testing with ansible-test](#testing-with-ansible-test) - [Contributing to This Collection](#contributing-to-this-collection) - [Support](#support) - [Release Notes](#release-notes) @@ -22,20 +28,14 @@ The Ansible AWS Operations collection includes a variety of Ansible content to h ## Description -The primary purpose of this collection is to simplify and streamline AWS operations through automation. By leveraging this collection, organizations can reduce manual operational effort, minimize errors, and ensure consistent approaches to managing AWS infrastructure. This leads to faster deployments, better security posture, and more reliable infrastructure management. +This collection is curated to provide users with a robust set of roles, playbooks, and rulebooks that simplify and streamline various AWS operations. By leveraging this collection, organizations can reduce manual operational effort, minimize errors, and ensure consistent approaches to managing AWS infrastructure. This leads to faster deployments, better security posture, and more reliable infrastructure management. ## Requirements ### 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. - - ### Python Version Compatibility This collection requires Python 3.10+. @@ -59,91 +59,55 @@ Click on the name of a role, playbook, or rulebook to view that content's docume Name | Description --- | --- -[cloud.aws_ops.aws_setup_credentials](https://github.com/redhat-cop/cloud.aws_ops/blob/main/roles/aws_setup_credentials/README.md)|A role to define credentials for AWS modules. -[cloud.aws_ops.awsconfig_apigateway_with_lambda_integration](https://github.com/redhat-cop/cloud.aws_ops/blob/main/roles/awsconfig_apigateway_with_lambda_integration/README.md)|A role to create/delete an API Gateway with Lambda function integration. -[cloud.aws_ops.awsconfig_detach_and_delete_internet_gateway](https://github.com/redhat-cop/cloud.aws_ops/blob/main/roles/awsconfig_detach_and_delete_internet_gateway/README.md)|A role to detach and delete the internet gateway you specify from a virtual private cloud. -[cloud.aws_ops.awsconfig_multiregion_cloudtrail](https://github.com/redhat-cop/cloud.aws_ops/blob/main/roles/awsconfig_multiregion_cloudtrail/README.md)|A role to create/delete a trail for multiple regions. -[cloud.aws_ops.backup_create_plan](https://github.com/redhat-cop/cloud.aws_ops/blob/main/roles/backup_create_plan/README.md)|A role to create an AWS Backup plan. -[cloud.aws_ops.backup_select_resources](https://github.com/redhat-cop/cloud.aws_ops/blob/main/roles/backup_select_resources/README.md)|A role to select resources to back up with an existing backup plan. -[cloud.aws_ops.clone_on_prem_vm](https://github.com/redhat-cop/cloud.aws_ops/blob/main/roles/clone_on_prem_vm/README.md)|A role to clone an existing on-premises VM using the KVM hypervisor. -[cloud.aws_ops.create_rds_global_cluster](https://github.com/redhat-cop/cloud.aws_ops/blob/main/roles/create_rds_global_cluster/README.md)|A role to create/delete Aurora global cluster with a primary cluster and a replica cluster in different regions. -[cloud.aws_ops.customized_ami](https://github.com/redhat-cop/cloud.aws_ops/blob/main/roles/customized_ami/README.md)|A role to manage custom AMIs on AWS. -[cloud.aws_ops.deploy_flask_app](https://github.com/redhat-cop/cloud.aws_ops/blob/main/roles/deploy_flask_app/README.md)|A role to deploy a Flask web application on AWS. -[cloud.aws_ops.ec2_instance_terminate_by_tag](https://github.com/redhat-cop/cloud.aws_ops/blob/main/roles/ec2_instance_terminate_by_tag/README.md)|A role to terminate EC2 instances based on a specific tag you specify. -[cloud.aws_ops.ec2_networking_resources](https://github.com/redhat-cop/cloud.aws_ops/blob/main/roles/ec2_networking_resources/README.md)|A role to manage EC2 networking resources. -[cloud.aws_ops.enable_cloudtrail_encryption_with_kms](https://github.com/redhat-cop/cloud.aws_ops/blob/main/roles/enable_cloudtrail_encryption_with_kms/README.md)|A role to encrypt an AWS CloudTrail trail using the AWS Key Management Service (AWS KMS) customer managed key you specify. -[cloud.aws_ops.import_image_and_run_aws_instance](https://github.com/redhat-cop/cloud.aws_ops/blob/main/roles/import_image_and_run_aws_instance/README.md)|A role that imports a local .raw image into an Amazon Machine Image (AMI) and runs an AWS EC2 instance. -[cloud.aws_ops.manage_ec2_instance](https://github.com/redhat-cop/cloud.aws_ops/blob/main/roles/manage_ec2_instance/README.md)|A role to manage EC2 instance lifecycle operations. -[cloud.aws_ops.manage_transit_gateway](https://github.com/redhat-cop/cloud.aws_ops/blob/main/roles/manage_transit_gateway/README.md)|A role to create/delete transit gateway with VPC and VPN attachments. -[cloud.aws_ops.manage_vpc_peering](https://github.com/redhat-cop/cloud.aws_ops/blob/main/roles/manage_vpc_peering/README.md)|A role to create, delete, and accept existing VPC peering connections. -[cloud.aws_ops.move_objects_between_buckets](https://github.com/redhat-cop/cloud.aws_ops/blob/main/roles/move_objects_between_buckets/README.md)|A role to move objects from one S3 bucket to another bucket. +[cloud.aws_ops.aws_setup_credentials](roles/aws_setup_credentials/README.md)|A role to define credentials for AWS modules. +[cloud.aws_ops.awsconfig_apigateway_with_lambda_integration](roles/awsconfig_apigateway_with_lambda_integration/README.md)|A role to create/delete an API Gateway with Lambda function integration. +[cloud.aws_ops.awsconfig_detach_and_delete_internet_gateway](roles/awsconfig_detach_and_delete_internet_gateway/README.md)|A role to detach and delete the internet gateway you specify from a virtual private cloud. +[cloud.aws_ops.awsconfig_multiregion_cloudtrail](roles/awsconfig_multiregion_cloudtrail/README.md)|A role to create/delete a trail for multiple regions. +[cloud.aws_ops.backup_create_plan](roles/backup_create_plan/README.md)|A role to create an AWS Backup plan. +[cloud.aws_ops.backup_select_resources](roles/backup_select_resources/README.md)|A role to select resources to back up with an existing backup plan. +[cloud.aws_ops.clone_on_prem_vm](roles/clone_on_prem_vm/README.md)|A role to clone an existing on-premises VM using the KVM hypervisor. +[cloud.aws_ops.create_rds_global_cluster](roles/create_rds_global_cluster/README.md)|A role to create/delete Aurora global cluster with a primary cluster and a replica cluster in different regions. +[cloud.aws_ops.customized_ami](roles/customized_ami/README.md)|A role to manage custom AMIs on AWS. +[cloud.aws_ops.deploy_flask_app](roles/deploy_flask_app/README.md)|A role to deploy a Flask web application on AWS. +[cloud.aws_ops.ec2_instance_terminate_by_tag](roles/ec2_instance_terminate_by_tag/README.md)|A role to terminate EC2 instances based on a specific tag you specify. +[cloud.aws_ops.ec2_networking_resources](roles/ec2_networking_resources/README.md)|A role to manage EC2 networking resources. +[cloud.aws_ops.enable_cloudtrail_encryption_with_kms](roles/enable_cloudtrail_encryption_with_kms/README.md)|A role to encrypt an AWS CloudTrail trail using the AWS Key Management Service (AWS KMS) customer managed key you specify. +[cloud.aws_ops.import_image_and_run_aws_instance](roles/import_image_and_run_aws_instance/README.md)|A role that imports a local .raw image into an Amazon Machine Image (AMI) and runs an AWS EC2 instance. +[cloud.aws_ops.manage_ec2_instance](roles/manage_ec2_instance/README.md)|A role to manage EC2 instance lifecycle operations. +[cloud.aws_ops.manage_transit_gateway](roles/manage_transit_gateway/README.md)|A role to create/delete transit gateway with VPC and VPN attachments. +[cloud.aws_ops.manage_vpc_peering](roles/manage_vpc_peering/README.md)|A role to create, delete, and accept existing VPC peering connections. +[cloud.aws_ops.move_objects_between_buckets](roles/move_objects_between_buckets/README.md)|A role to move objects from one S3 bucket to another bucket. ### Playbooks Name | Description --- | --- -[cloud.aws_ops.eda](https://github.com/redhat-cop/cloud.aws_ops/blob/main/playbooks/README.md)|A set of playbooks to restore AWS CloudTrail configurations, created for use with Event-Driven Ansible rulebooks. -[cloud.aws_ops.webapp](https://github.com/redhat-cop/cloud.aws_ops/blob/main/playbooks/webapp/README.md)|A set of playbooks to create, delete, or migrate a web application on AWS. -[cloud.aws_ops.upload_file_to_s3](https://github.com/redhat-cop/cloud.aws_ops/blob/main/playbooks/UPLOAD_FILE_TO_S3.md)|A playbook to upload a local file to S3. -[cloud.aws_ops.move_vm_from_on_prem_to_aws](https://github.com/redhat-cop/cloud.aws_ops/blob/main/playbooks/move_vm_from_on_prem_to_aws/README.md)|A playbook to migrate an existing on-premises VM running on KVM hypervisor to AWS. +[cloud.aws_ops.eda](playbooks/README.md)|A set of playbooks to restore AWS CloudTrail configurations, created for use with Event-Driven Ansible rulebooks. +[cloud.aws_ops.webapp](playbooks/webapp/README.md)|A set of playbooks to create, delete, or migrate a web application on AWS. +[cloud.aws_ops.upload_file_to_s3](playbooks/UPLOAD_FILE_TO_S3.md)|A playbook to upload a local file to S3. +[cloud.aws_ops.move_vm_from_on_prem_to_aws](playbooks/move_vm_from_on_prem_to_aws/README.md)|A playbook to migrate an existing on-premises VM running on KVM hypervisor to AWS. ### Rulebooks Name | Description --- | --- -[cloud.aws_ops.aws_manage_cloudtrail_encryption](https://github.com/redhat-cop/cloud.aws_ops/blob/main/extensions/eda/AWS_MANAGE_CLOUDTRAIL_ENCRYPTION.md)|An Event-Driven Ansible rulebook to ensure that an existing encrypted AWS CloudTrail trail will not be deleted or have its encryption removed. +[cloud.aws_ops.aws_manage_cloudtrail_encryption](extensions/eda/AWS_MANAGE_CLOUDTRAIL_ENCRYPTION.md)|An Event-Driven Ansible rulebook to ensure that an existing encrypted AWS CloudTrail trail will not be deleted or have its encryption removed. ### Modules Name | Description --- | --- -[cloud.aws_ops.validate_network_acls](https://github.com/redhat-cop/cloud.aws_ops/blob/main/plugins/modules/validate_network_acls.py)|Validates network ACL configurations for connectivity between AWS resources. -[cloud.aws_ops.validate_route_tables](https://github.com/redhat-cop/cloud.aws_ops/blob/main/plugins/modules/validate_route_tables.py)|Validates route table configurations for connectivity between AWS resources. -[cloud.aws_ops.validate_security_group_rules](https://github.com/redhat-cop/cloud.aws_ops/blob/main/plugins/modules/validate_security_group_rules.py)|Validates security group rules for connectivity between AWS resources. +[cloud.aws_ops.validate_network_acls](plugins/modules/validate_network_acls.py)|Validates network ACL configurations for connectivity between AWS resources. +[cloud.aws_ops.validate_route_tables](plugins/modules/validate_route_tables.py)|Validates route table configurations for connectivity between AWS resources. +[cloud.aws_ops.validate_security_group_rules](plugins/modules/validate_security_group_rules.py)|Validates security group rules for connectivity between AWS resources. ## Installation -The cloud.aws_ops collection can be installed with the Ansible Galaxy command-line tool: - -```shell -ansible-galaxy collection install cloud.aws_ops -``` - -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_ops -``` - -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_ops --upgrade -``` - -A specific version of the collection can be installed by using the `version` keyword in the `requirements.yml` file: +To consume this Validated Content from Automation Hub, please ensure that you add the following lines to your ansible.cfg file. -```yaml ---- -collections: - - name: cloud.aws_ops - version: 5.0.0 ``` - -or using the `ansible-galaxy` command as follows: - -```shell -ansible-galaxy collection install cloud.aws_ops:==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] server_list = automation_hub @@ -152,24 +116,12 @@ url=https://cloud.redhat.com/api/automation-hub/ auth_url=https://sso.redhat.com/auth/realms/redhat-external/protocol/openid-connect/token token= ``` - The token can be obtained from the [Automation Hub Web UI](https://console.redhat.com/ansible/automation-hub/token). -### Installing Dependencies +Once the above steps are done, you can run the following command to install the collection. -The collection dependencies are not installed by `ansible-galaxy` by default. They must be installed separately: - -```shell -ansible-galaxy collection install amazon.aws:>=5.1.0 -ansible-galaxy collection install community.aws:>=5.0.0 -ansible-galaxy collection install amazon.cloud:>=0.4.0 -ansible-galaxy collection install community.libvirt:>=1.2.0 ``` - -The Python module dependencies can be installed using pip: - -```shell -pip install boto3>=1.26.0 botocore>=1.29.0 +ansible-galaxy collection install cloud.aws_ops ``` Refer to the following for more details: @@ -177,58 +129,24 @@ Refer to the following for more details: ## Use Cases -You can call roles by their Fully Qualified Collection Name (FQCN), such as `cloud.aws_ops.enable_cloudtrail_encryption_with_kms`, or by their short name if you list the `cloud.aws_ops` collection in the playbook's `collections` keyword: +You can call roles by their Fully Qualified Collection Name (FQCN), such as `cloud.aws_ops.enable_cloudtrail_encryption_with_kms`: ```yaml ---- -- hosts: localhost - gather_facts: false - connection: local - - tasks: - - name: Restore encryption to an existing AWS CloudTrail trail - ansible.builtin.include_role: - name: cloud.aws_ops.enable_cloudtrail_encryption_with_kms - vars: - enable_cloudtrail_encryption_with_kms_trail_name: "{{ cloudtrail_name }}" - enable_cloudtrail_encryption_with_kms_kms_key_id: "{{ kms_alias }}" - - - name: Create VPC peering connection - ansible.builtin.include_role: - name: cloud.aws_ops.manage_vpc_peering - vars: - manage_vpc_peering_operation: create - manage_vpc_peering_vpc_id: "{{ vpc_id_1 }}" - manage_vpc_peering_peer_vpc_id: "{{ vpc_id_2 }}" -``` - -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: - -```yaml ---- -- hosts: localhost - gather_facts: false - connection: local - - collections: - - cloud.aws_ops - - tasks: - - name: Create AWS Backup plan - ansible.builtin.include_role: - name: backup_create_plan - vars: - backup_create_plan_name: "{{ backup_plan_name }}" - backup_create_plan_rules: "{{ backup_rules }}" -``` - -For migrating VMs from on-premises to AWS: - -```yaml ---- -- hosts: all - tasks: - - name: Clone on-premises VM + # The following example restores encryption to an existing AWS Cloudtrail trail using the enable_cloudtrail_encryption_with_kms role + - hosts: all + tasks: + - name: Include 'enable_cloudtrail_encryption_with_kms' role + ansible.builtin.include_role: + name: cloud.aws_ops.enable_cloudtrail_encryption_with_kms + vars: + enable_cloudtrail_encryption_with_kms_trail_name: "{{ cloudtrail_name }}" + enable_cloudtrail_encryption_with_kms_kms_key_id: "{{ kms_alias }}" + + # The following example uses the ``cloud.aws_ops.clone_on_prem_vm`` role to clone an existing VM on prem using the KVM hypervisor and the ``cloud.aws_ops.import_image_and_run_aws_instance`` role to import a local .raw image into an Amazon machine image (AMI) and run an AWS EC2 instance. + + - hosts: all + tasks: + - name: Import 'cloud.aws_ops.clone_on_prem_vm' role ansible.builtin.import_role: name: cloud.aws_ops.clone_on_prem_vm vars: @@ -239,7 +157,7 @@ For migrating VMs from on-premises to AWS: clone_on_prem_vm_overwrite: "{{ overwrite }}" delegate_to: kvm - - name: Import image and run AWS instance + - name: Import 'cloud.aws_ops.import_image_and_run_aws_instance' role ansible.builtin.import_role: name: cloud.aws_ops.import_image_and_run_aws_instance vars: @@ -255,7 +173,45 @@ For documentation on how to use individual roles and other content included in t ## Testing -This collection is tested using GitHub Actions. To learn more about testing, refer to [CI.md](https://github.com/redhat-cop/cloud.aws_ops/blob/main/CI.md). +### Continuious Integration + +This collection is tested using GitHub Actions. To learn more about the continuous integration process, refer to [CI.md](./CI.md). + +### 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_ops/`), run: + +```shell +# Run all linters (black, flake8, yamllint) +tox -e linters + +# Run ansible-lint separately +tox -e ansible-lint + +# Run black formatter +tox -e black +``` ## Contributing to This Collection @@ -272,12 +228,9 @@ See [CONTRIBUTING.md](https://github.com/redhat-cop/cloud.aws_ops/blob/main/CONT ## 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). - +- We announce releases and important changes through Ansible's [The Bullhorn newsletter](https://github.com/ansible/community/wiki/News#the-bullhorn). +- We take part in the global quarterly [Ansible Contributor Summit](https://github.com/ansible/community/wiki/Contributor-Summit) virtually or in-person. +- 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: From d4e2a59edc7c94245c3b86517a139ac541a2ee9b Mon Sep 17 00:00:00 2001 From: mjohns91 Date: Tue, 17 Mar 2026 15:13:27 -0400 Subject: [PATCH 3/6] Revert README changes and update CI.md format - Reset README.md to main branch version - Update CI.md to match kubernetes.core format with improved table structure - Add Python version compatibility matrix by ansible-core version --- CI.md | 37 +++++------ README.md | 182 +++++++++++++++--------------------------------------- 2 files changed, 66 insertions(+), 153 deletions(-) diff --git a/CI.md b/CI.md index 69101dbd..8f90ec67 100644 --- a/CI.md +++ b/CI.md @@ -2,32 +2,29 @@ ## AWS Operations Collection Testing -GitHub Actions are used to run the CI for the cloud.aws_ops collection. The workflows used for the CI can be found [here](https://github.com/redhat-cop/cloud.aws_ops/tree/main/.github/workflows). These workflows include jobs to run the sanity tests, linters, integration tests, and changelog checks. - -The collection uses reusable workflows from [ansible-network/github_actions](https://github.com/ansible-network/github_actions) for standardized testing. +GitHub Actions are used to run the CI for the cloud.aws_ops collection. The workflows used for the CI can be found in the [.github/workflows](.github/workflows) directory. ### PR Testing Workflows The following tests run on every pull request: -| Job | Description | Configuration | -| --- | ----------- | ------------- | -| Changelog | Checks for the presence of changelog fragments | ubuntu-latest | -| Linters | Runs `ansible-lint`, `black`, `flake8`, `yamllint` | Python 3.10 (via tox) | -| Sanity | Runs ansible sanity checks across multiple Python and ansible-core versions | Determined by [ansible-network reusable workflows](https://github.com/ansible-network/github_actions) | -| Integration tests | Executes integration test suites on AWS (split across 2 parallel jobs) | Python 3.12, ansible-core milestone, requires "safe to test" label | - -For the official Ansible core support matrix, see the [Ansible Release and Maintenance documentation](https://docs.ansible.com/ansible/latest/reference_appendices/release_and_maintenance.html#ansible-core-support-matrix). +| Job | Description | Python Versions | ansible-core Versions | +| --- | ----------- | --------------- | --------------------- | +| [Changelog](.github/workflows/changelog.yml) | Checks for the presence of changelog fragments | 3.12 | devel | +| [Linters](.github/workflows/linters.yml) | Runs `black`, `flake8`, `yamllint`, and `ansible-lint` on plugins and tests | 3.10 | devel | +| [Sanity](.github/workflows/sanity.yml) | Runs ansible sanity checks | See compatibility table below | devel, stable-2.17, stable-2.18, stable-2.19, stable-2.20 | +| [Integration](.github/workflows/integration.yml) | Executes integration test suites on AWS (split across 2 parallel jobs, requires "safe to test" label) | 3.12 | milestone | -### Collection Dependencies +**Note:** Integration tests require AWS credentials and use the `pull_request_target` trigger. PRs from external contributors require the "safe to test" label to be added by a maintainer before tests will run. -The collection depends on several other collections for integration testing. These dependencies are defined in: -- [`galaxy.yml`](galaxy.yml) - Production dependencies -- [`tests/integration/requirements.yml`](tests/integration/requirements.yml) - Test-time dependencies +### Python Version Compatibility by ansible-core Version -### Security Model +These are outlined in the collection's [tox.ini](tox.ini) file (`envlist`) and GitHub Actions workflow configurations. -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 +| ansible-core Version | Sanity Tests | Integration Tests | +| -------------------- | ------------ | ----------------- | +| devel | 3.12, 3.13, 3.14 | 3.12 | +| stable-2.20 | 3.12, 3.13, 3.14 | 3.12 | +| stable-2.19 | 3.11, 3.12, 3.13 | 3.12 | +| stable-2.18 | 3.11, 3.12, 3.13 | 3.12 | +| stable-2.17 | 3.10, 3.11, 3.12 | 3.12 | diff --git a/README.md b/README.md index 45d8acfe..5eb7060b 100644 --- a/README.md +++ b/README.md @@ -1,106 +1,59 @@ # cloud.aws_ops Validated Content Collection -The Ansible AWS Operations collection includes a variety of Ansible content to help automate, manage, and streamline common operational tasks within AWS environments. This collection is maintained by the [Red Hat Communities of Practice](https://github.com/redhat-cop). - -## Contents - -- [Description](#description) -- [Requirements](#requirements) - - [Ansible Version Compatibility](#ansible-version-compatibility) - - [Python Version Compatibility](#python-version-compatibility) - - [AWS Version Compatibility](#aws-version-compatibility) -- [Included Content](#included-content) - - [Roles](#roles) - - [Playbooks](#playbooks) - - [Rulebooks](#rulebooks) - - [Modules](#modules) -- [Installation](#installation) - - [Installing Dependencies](#installing-dependencies) -- [Use Cases](#use-cases) -- [Testing](#testing) - - [Continuous Integration](#continuious-integration) - - [Testing with ansible-test](#testing-with-ansible-test) -- [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) + +This repository hosts the `cloud.aws_ops` Ansible Collection. ## Description -This collection is curated to provide users with a robust set of roles, playbooks, and rulebooks that simplify and streamline various AWS operations. By leveraging this collection, organizations can reduce manual operational effort, minimize errors, and ensure consistent approaches to managing AWS infrastructure. This leads to faster deployments, better security posture, and more reliable infrastructure management. +This collection is curated to provide users with a robust set of roles, playbooks, and rulebooks that simplify and streamline various AWS operations. ## Requirements -### Ansible Version Compatibility - -This collection has been tested against the following Ansible versions: **>=2.17.0**. - -### Python Version Compatibility - -This collection requires Python 3.10+. +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. -### AWS Version Compatibility +To run rulebooks, [ansible-rulebook](https://ansible.readthedocs.io/projects/rulebook/en/latest/) must be installed. -This collection requires the following collection dependencies: -- [amazon.aws](https://github.com/ansible-collections/amazon.aws) (>=5.1.0) -- [community.aws](https://github.com/ansible-collections/community.aws) (>=5.0.0) -- [amazon.cloud](https://github.com/ansible-collections/amazon.cloud) (>=0.4.0) -- [community.libvirt](https://github.com/ansible-collections/community.libvirt) (>=1.2.0) + +### Ansible version compatibility -For Event-Driven Ansible features, [ansible-rulebook](https://ansible.readthedocs.io/projects/rulebook/en/latest/) must be installed separately. +This collection has been tested against following Ansible versions: **>=2.17.0**. -## Included Content +### Included content Click on the name of a role, playbook, or rulebook to view that content's documentation: ### Roles - Name | Description --- | --- -[cloud.aws_ops.aws_setup_credentials](roles/aws_setup_credentials/README.md)|A role to define credentials for AWS modules. -[cloud.aws_ops.awsconfig_apigateway_with_lambda_integration](roles/awsconfig_apigateway_with_lambda_integration/README.md)|A role to create/delete an API Gateway with Lambda function integration. -[cloud.aws_ops.awsconfig_detach_and_delete_internet_gateway](roles/awsconfig_detach_and_delete_internet_gateway/README.md)|A role to detach and delete the internet gateway you specify from a virtual private cloud. -[cloud.aws_ops.awsconfig_multiregion_cloudtrail](roles/awsconfig_multiregion_cloudtrail/README.md)|A role to create/delete a trail for multiple regions. -[cloud.aws_ops.backup_create_plan](roles/backup_create_plan/README.md)|A role to create an AWS Backup plan. +[cloud.aws_ops.aws_setup_credentials](roles/aws_setup_credentials/README.md)|A role to define credentials for aws modules. +[cloud.aws_ops.awsconfig_detach_and_delete_internet_gateway](roles/awsconfig_detach_and_delete_internet_gateway/README.md)|A role to detach and delete the internet gateway you specify from virtual private cloud. +[cloud.aws_ops.awsconfig_multiregion_cloudtrail](roles/awsconfig_multiregion_cloudtrail/README.md)|A role to create/delete a Trail for multiple regions. +[cloud.aws_ops.backup_create_plan](roles/backup_create_plan/README.md)|A role to create an AWS backup plan. [cloud.aws_ops.backup_select_resources](roles/backup_select_resources/README.md)|A role to select resources to back up with an existing backup plan. -[cloud.aws_ops.clone_on_prem_vm](roles/clone_on_prem_vm/README.md)|A role to clone an existing on-premises VM using the KVM hypervisor. -[cloud.aws_ops.create_rds_global_cluster](roles/create_rds_global_cluster/README.md)|A role to create/delete Aurora global cluster with a primary cluster and a replica cluster in different regions. [cloud.aws_ops.customized_ami](roles/customized_ami/README.md)|A role to manage custom AMIs on AWS. -[cloud.aws_ops.deploy_flask_app](roles/deploy_flask_app/README.md)|A role to deploy a Flask web application on AWS. -[cloud.aws_ops.ec2_instance_terminate_by_tag](roles/ec2_instance_terminate_by_tag/README.md)|A role to terminate EC2 instances based on a specific tag you specify. -[cloud.aws_ops.ec2_networking_resources](roles/ec2_networking_resources/README.md)|A role to manage EC2 networking resources. +[cloud.aws_ops.ec2_instance_terminate_by_tag](roles/ec2_instance_terminate_by_tag/README.md)|A role to terminate the EC2 instances based on a specific tag you specify. [cloud.aws_ops.enable_cloudtrail_encryption_with_kms](roles/enable_cloudtrail_encryption_with_kms/README.md)|A role to encrypt an AWS CloudTrail trail using the AWS Key Management Service (AWS KMS) customer managed key you specify. -[cloud.aws_ops.import_image_and_run_aws_instance](roles/import_image_and_run_aws_instance/README.md)|A role that imports a local .raw image into an Amazon Machine Image (AMI) and runs an AWS EC2 instance. -[cloud.aws_ops.manage_ec2_instance](roles/manage_ec2_instance/README.md)|A role to manage EC2 instance lifecycle operations. -[cloud.aws_ops.manage_transit_gateway](roles/manage_transit_gateway/README.md)|A role to create/delete transit gateway with VPC and VPN attachments. -[cloud.aws_ops.manage_vpc_peering](roles/manage_vpc_peering/README.md)|A role to create, delete, and accept existing VPC peering connections. -[cloud.aws_ops.move_objects_between_buckets](roles/move_objects_between_buckets/README.md)|A role to move objects from one S3 bucket to another bucket. +[cloud.aws_ops.manage_vpc_peering](roles/manage_vpc_peering/README.md)|A role to create, delete and accept existing VPC peering connections. +[cloud.aws_ops.move_objects_between_buckets](roles/move_objects_between_buckets/README.md)|A role to move objects from one bucket to another bucket. +[cloud.aws_ops.awsconfig_apigateway_with_lambda_integration](roles/awsconfig_apigateway_with_lambda_integration/README.md)|A role to create/delete an API gateway with lambda function integration. +[cloud.aws_ops.manage_transit_gateway](roles/manage_transit_gateway/README.md)|A role to create/delete transit_gateway with vpc and vpn attachments. +[cloud.aws_ops.deploy_flask_app](roles/deploy_flask_app/README.md)|A role to deploy a flask web application on AWS. +[cloud.aws_ops.create_rds_global_cluster](roles/create_rds_global_cluster/README.md)|A role to create, delete aurora global cluster with a primary cluster and a replica cluster in different regions. +[cloud.aws_ops.clone_on_prem_vm](roles/clone_on_prem_vm/README.md)|A role to clone an existing on prem VM using the KVM hypervisor. +[cloud.aws_ops.import_image_and_run_aws_instance](roles/import_image_and_run_aws_instance/README.md)|A role that imports a local .raw image into an Amazon Machine Image (AMI) and run an AWS EC2 instance. ### Playbooks - Name | Description --- | --- -[cloud.aws_ops.eda](playbooks/README.md)|A set of playbooks to restore AWS CloudTrail configurations, created for use with Event-Driven Ansible rulebooks. -[cloud.aws_ops.webapp](playbooks/webapp/README.md)|A set of playbooks to create, delete, or migrate a web application on AWS. +[cloud.aws_ops.eda](playbooks/README.md)|A set of playbooks to restore AWS Cloudtrail configurations, created for use with the [cloud.aws_manage_cloudtrail_encryption rulebook](extensions/eda/AWS_MANAGE_CLOUDTRAIL_ENCRYPTION.md). +[cloud.aws_ops.webapp](playbooks/webapp/README.md)|A set of playbooks to create, delete, or migrate a webapp on AWS. [cloud.aws_ops.upload_file_to_s3](playbooks/UPLOAD_FILE_TO_S3.md)|A playbook to upload a local file to S3. -[cloud.aws_ops.move_vm_from_on_prem_to_aws](playbooks/move_vm_from_on_prem_to_aws/README.md)|A playbook to migrate an existing on-premises VM running on KVM hypervisor to AWS. +[cloud.aws_ops.move_vm_from_on_prem_to_aws](playbooks/move_vm_from_on_prem_to_aws/README.md)|A playbook to migrate an existing on prem VM running on KVM hypervisor to AWS. ### Rulebooks - Name | Description --- | --- -[cloud.aws_ops.aws_manage_cloudtrail_encryption](extensions/eda/AWS_MANAGE_CLOUDTRAIL_ENCRYPTION.md)|An Event-Driven Ansible rulebook to ensure that an existing encrypted AWS CloudTrail trail will not be deleted or have its encryption removed. - -### Modules - -Name | Description ---- | --- -[cloud.aws_ops.validate_network_acls](plugins/modules/validate_network_acls.py)|Validates network ACL configurations for connectivity between AWS resources. -[cloud.aws_ops.validate_route_tables](plugins/modules/validate_route_tables.py)|Validates route table configurations for connectivity between AWS resources. -[cloud.aws_ops.validate_security_group_rules](plugins/modules/validate_security_group_rules.py)|Validates security group rules for connectivity between AWS resources. - +[cloud.aws_ops.aws_manage_cloudtrail_encryption](extensions/eda/AWS_MANAGE_CLOUDTRAIL_ENCRYPTION.md)|An Event-Driven Ansible rulebook to ensure that an existing encrypted AWS Cloudtrail trail will not be deleted or have its encryption removed. ## Installation @@ -124,12 +77,9 @@ Once the above steps are done, you can run the following command to install the ansible-galaxy collection install cloud.aws_ops ``` -Refer to the following for more details: -* [Using Ansible collections](https://docs.ansible.com/ansible/latest/user_guide/collections_using.html) - ## Use Cases -You can call roles by their Fully Qualified Collection Name (FQCN), such as `cloud.aws_ops.enable_cloudtrail_encryption_with_kms`: +Once installed, you can reference the cloud.aws_ops collection content by its fully qualified collection name (FQCN), for example: ```yaml # The following example restores encryption to an existing AWS Cloudtrail trail using the enable_cloudtrail_encryption_with_kms role @@ -169,68 +119,42 @@ You can call roles by their Fully Qualified Collection Name (FQCN), such as `clo import_image_and_run_aws_instance_keypair_name: "{{ keypair_name }}" ``` -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. - ## Testing -### Continuious Integration - -This collection is tested using GitHub Actions. To learn more about the continuous integration process, refer to [CI.md](./CI.md). - -### 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: +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_ops/`, run: ```shell -# Run sanity tests -ansible-test sanity - -# Run integration tests (requires AWS credentials) -ansible-test integration [target] + tox -e linters ``` -Before running integration tests, you must configure AWS credentials: +Sanity and unit tests are run as normal: ```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 + ansible-test sanity ``` -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_ops/`), run: +If you want to run cloud integration tests, ensure you log in to the cloud: ```shell -# Run all linters (black, flake8, yamllint) -tox -e linters - -# Run ansible-lint separately -tox -e ansible-lint +# 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 -# Run black formatter -tox -e black + ansible-test integration [target] ``` -## Contributing to This Collection - -We welcome community contributions to this collection. If you find problems, please open an issue or create a PR against the [AWS Operations collection repository](https://github.com/redhat-cop/cloud.aws_ops). +This collection is tested using GitHub Actions. To know more about CI, refer to [CI.md](https://github.com/https://github.com/redhat-cop/cloud.aws_ops/blob/main/CI.md). -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. +## Contributing to this collection +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_ops/blob/main/CONTRIBUTING.md) for more details. -### More information about contributing - -- [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). -- We take part in the global quarterly [Ansible Contributor Summit](https://github.com/ansible/community/wiki/Contributor-Summit) virtually or in-person. -- 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: @@ -241,23 +165,15 @@ If you encounter issues or have questions, you can submit a support request thro See the [raw generated changelog](https://github.com/redhat-cop/cloud.aws_ops/blob/main/CHANGELOG.rst). -## Related Information - -- [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 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) - -## 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. +## Related Information -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. + - [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) -## License Information +## License -GNU General Public License v3.0 or later. +GNU General Public License v3.0 or later -See [COPYING](https://www.gnu.org/licenses/gpl-3.0.txt) to see the full text. +See [LICENSE](LICENSE) to see the full text. From f407ec7f0987afbfd7489407483105fbf1e026f2 Mon Sep 17 00:00:00 2001 From: Matthew Johnson <90540643+mjohns91@users.noreply.github.com> Date: Mon, 30 Mar 2026 16:33:51 -0400 Subject: [PATCH 4/6] Update CI.md Co-authored-by: Alina Buzachis --- CI.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CI.md b/CI.md index 8f90ec67..ddeb747b 100644 --- a/CI.md +++ b/CI.md @@ -2,7 +2,7 @@ ## AWS Operations Collection Testing -GitHub Actions are used to run the CI for the cloud.aws_ops collection. The workflows used for the CI can be found in the [.github/workflows](.github/workflows) directory. +GitHub Actions are used to run the CI for the `cloud.aws_ops` collection. The workflows used for the CI can be found in the [.github/workflows](.github/workflows) directory. ### PR Testing Workflows From bcf32f10f0e870319d7ad7a11c408476ba22e69a Mon Sep 17 00:00:00 2001 From: mjohns91 Date: Tue, 31 Mar 2026 15:04:19 -0400 Subject: [PATCH 5/6] Update CI.md with expanded documentation and Python version compatibility --- CI.md | 45 +++++++++++++++++++++++++++++++++------------ 1 file changed, 33 insertions(+), 12 deletions(-) diff --git a/CI.md b/CI.md index ddeb747b..ba040f69 100644 --- a/CI.md +++ b/CI.md @@ -10,21 +10,42 @@ The following tests run on every pull request: | Job | Description | Python Versions | ansible-core Versions | | --- | ----------- | --------------- | --------------------- | -| [Changelog](.github/workflows/changelog.yml) | Checks for the presence of changelog fragments | 3.12 | devel | +| [Changelog](.github/workflows/changelog.yml) | Checks for the presence of changelog fragments | 3.12 | N/A | | [Linters](.github/workflows/linters.yml) | Runs `black`, `flake8`, `yamllint`, and `ansible-lint` on plugins and tests | 3.10 | devel | | [Sanity](.github/workflows/sanity.yml) | Runs ansible sanity checks | See compatibility table below | devel, stable-2.17, stable-2.18, stable-2.19, stable-2.20 | -| [Integration](.github/workflows/integration.yml) | Executes integration test suites on AWS (split across 2 parallel jobs, requires "safe to test" label) | 3.12 | milestone | - -**Note:** Integration tests require AWS credentials and use the `pull_request_target` trigger. PRs from external contributors require the "safe to test" label to be added by a maintainer before tests will run. +| [Integration](.github/workflows/integration.yml) | 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 outlined in the collection's [tox.ini](tox.ini) file (`envlist`) and GitHub Actions workflow configurations. +These are outlined in the collection's [tox.ini](tox.ini) file (`envlist`) and GitHub Actions workflow exclusions. + +| ansible-core Version | Sanity Tests | +| -------------------- | ------------ | +| devel | 3.12, 3.13, 3.14 | +| stable-2.20 | 3.10, 3.11, 3.12, 3.13, 3.14 | +| stable-2.19 | 3.11, 3.12, 3.13, 3.14 | +| stable-2.18 | 3.11, 3.12, 3.13, 3.14 | +| stable-2.17 | 3.10, 3.11, 3.12, 3.14 | + +### Integration Test Security and "Safe to Test" Label + +Integration tests run on real AWS infrastructure and require the "safe to test" label to prevent unauthorized resource creation and ensure security. + +**Label Assignment:** +- **Automatically added** for PRs from users with write, maintain, or admin permissions +- **Manually added** by a maintainer for external contributors after code review + +**Security Model:** +- Uses `pull_request_target` event (runs in base repository context) +- Prevents untrusted code from automatically accessing AWS credentials +- Label acts as an approval gate before tests consume AWS resources + +**Test Execution:** +- Tests trigger when PRs are opened, reopened, synchronized (new commits), or when the label is added/removed +- Tests will **not run** if the label is missing +- Removing the label stops tests from running on subsequent pushes until re-added -| ansible-core Version | Sanity Tests | Integration Tests | -| -------------------- | ------------ | ----------------- | -| devel | 3.12, 3.13, 3.14 | 3.12 | -| stable-2.20 | 3.12, 3.13, 3.14 | 3.12 | -| stable-2.19 | 3.11, 3.12, 3.13 | 3.12 | -| stable-2.18 | 3.11, 3.12, 3.13 | 3.12 | -| stable-2.17 | 3.10, 3.11, 3.12 | 3.12 | +**Job Organization:** +- Integration targets are automatically split across 2 parallel jobs +- Split is determined by `ansible_test_splitter` action based on changed files +- Each job runs the subset of tests relevant to the PR's changes From 235af7174b028ffd6e2077493e8acc7ec246f207 Mon Sep 17 00:00:00 2001 From: mjohns91 Date: Tue, 31 Mar 2026 15:14:05 -0400 Subject: [PATCH 6/6] linters now shows ansible-core 2.17 --- CI.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CI.md b/CI.md index ba040f69..7a75e36a 100644 --- a/CI.md +++ b/CI.md @@ -11,7 +11,7 @@ The following tests run on every pull request: | Job | Description | Python Versions | ansible-core Versions | | --- | ----------- | --------------- | --------------------- | | [Changelog](.github/workflows/changelog.yml) | Checks for the presence of changelog fragments | 3.12 | N/A | -| [Linters](.github/workflows/linters.yml) | Runs `black`, `flake8`, `yamllint`, and `ansible-lint` on plugins and tests | 3.10 | devel | +| [Linters](.github/workflows/linters.yml) | Runs `black`, `flake8`, `yamllint`, and `ansible-lint` on plugins and tests | 3.10 | 2.17 | | [Sanity](.github/workflows/sanity.yml) | Runs ansible sanity checks | See compatibility table below | devel, stable-2.17, stable-2.18, stable-2.19, stable-2.20 | | [Integration](.github/workflows/integration.yml) | Executes integration test suites on AWS (split across 2 jobs, requires "safe to test" label) | 3.12 | milestone |