diff --git a/README.md b/README.md index 68d1d5ac..d8e8609d 100644 --- a/README.md +++ b/README.md @@ -1,15 +1,23 @@ -# cloud.aws_ops roles/playbooks/rulebooks to demo Ansible on AWS +# cloud.aws_ops Validated Content Collection This repository hosts the `cloud.aws_ops` Ansible Collection. -The collection includes a variety of Ansible roles, playbooks, and rulebooks to help automate the management of resources on AWS. +## Description + +This collection is curated to provide users with a robust set of roles, playbooks, and rulebooks that simplify and streamline various AWS operations. + +## 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 following Ansible versions: **>=2.15.0**. -## Included content +### Included content Click on the name of a role, playbook, or rulebook to view that content's documentation: @@ -48,15 +56,7 @@ 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. -## Installation and Usage - -### 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. - -### Installation +## Installation To consume this Validated Content from Automation Hub, please ensure that you add the following lines to your ansible.cfg file. @@ -77,11 +77,12 @@ Once the above steps are done, you can run the following command to install the ansible-galaxy collection install cloud.aws_ops ``` -### Using this collection +## Use Cases 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 - hosts: all tasks: - name: Include 'enable_cloudtrail_encryption_with_kms' role @@ -90,18 +91,35 @@ Once installed, you can reference the cloud.aws_ops collection content by its fu vars: enable_cloudtrail_encryption_with_kms_trail_name: "{{ cloudtrail_name }}" enable_cloudtrail_encryption_with_kms_kms_key_id: "{{ kms_alias }}" -``` - -### See Also -* [Ansible Using collections](https://docs.ansible.com/ansible/latest/user_guide/collections_using.html) for more details. -* [Ansible Rulebook documentation](https://ansible.readthedocs.io/projects/rulebook/en/stable/index.html) for information on using rulebooks. - -## Contributing to this collection + # 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. -We welcome community contributions to this collection. If you find problems, please open an issue or create a PR against this collection repository. + - 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: + clone_on_prem_vm_source_vm_name: "{{ source_vm_name }}" + clone_on_prem_vm_image_name: "{{ image_name }}" + clone_on_prem_vm_uri: "{{ uri }}" + clone_on_prem_vm_local_image_path: "{{ local_image_path }}" + clone_on_prem_vm_overwrite: "{{ overwrite }}" + delegate_to: kvm + + - 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: + import_image_and_run_aws_instance_bucket_name: "{{ bucket_name }}" + import_image_and_run_aws_instance_image_path: "{{ raw_image_path }}" + import_image_and_run_aws_instance_instance_name: "{{ instance_name }}" + import_image_and_run_aws_instance_instance_type: "{{ instance_type }}" + import_image_and_run_aws_instance_import_image_task_name: "{{ import_image_task_name }}" + import_image_and_run_aws_instance_keypair_name: "{{ keypair_name }}" +``` -### Testing and Development +## Testing The project uses `ansible-lint` and `black`. Assuming this repository is checked out in the proper structure, @@ -130,6 +148,30 @@ If you want to run cloud integration tests, ensure you log in to the cloud: 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). +## 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. + +## Support + +For the latest supported versions, refer to the release notes below. + +If you encounter issues or have questions, you can submit a support request through the following channels: + - GitHub Issues: Report bugs, request features, or ask questions by opening an issue in the [GitHub repository](https://github.com/redhat-cop/cloud.aws_ops/). + - Ansible Community: Engage with the Ansible community on the Ansible Project Mailing List or [Ansible Forum](https://forum.ansible.com/g/AWS). + +## Release Notes + +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) + ## License GNU General Public License v3.0 or later diff --git a/changelogs/fragments/readme_template_update.yml b/changelogs/fragments/readme_template_update.yml new file mode 100644 index 00000000..421756ad --- /dev/null +++ b/changelogs/fragments/readme_template_update.yml @@ -0,0 +1,3 @@ +--- +trivial: + - Update the README doc to match https://access.redhat.com/articles/7068606.