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.