From dbb39d818b8d76cddcf5cb2f8f63c7e838186485 Mon Sep 17 00:00:00 2001 From: samitab Date: Thu, 3 Oct 2024 15:06:12 +1000 Subject: [PATCH] [bug_fix] Updated README to match RedHat's ansible collection template. --- README.md | 116 +++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 79 insertions(+), 37 deletions(-) diff --git a/README.md b/README.md index 03cc7cac1..48ed72629 100644 --- a/README.md +++ b/README.md @@ -1,61 +1,54 @@ # ansible-aci +## Description + The ansible-aci project provides an Ansible collection for managing and automating your Cisco ACI environment. It consists of a set of modules and roles for performing tasks related to ACI. -This collection has been tested and supports ACI 3.2+. -Modules supporting new features introduced in ACI API in specific ACI versions might not be supported in earlier ACI releases. +This collection supports ACI 4.2+ -*Note: This collection is not compatible with versions of Ansible before v2.8.* +See the [Cisco.Aci collection index](https://galaxy.ansible.com/ui/repo/published/cisco/aci/content/) for a full list of modules and plugins. ## Requirements -Ansible v2.14 or newer +Ansible v2.15 or newer -## Install +*Note: This collection is not compatible with versions of Ansible before v2.8.* -Ansible must be installed +## Installation -```sh -sudo pip install ansible -``` - -Install the collection +Before using this collection, you need to install it with the Ansible Galaxy command-line tool: ```sh ansible-galaxy collection install cisco.aci ``` -## Use +You can also include it in a requirements.yml file and install it with ansible-galaxy collection install -r requirements.yml, using the format: -Once the collection is installed, you can use it in a playbook by specifying the full namespace path to the module, plugin and/or role. +```yaml +collections: + - name: cisco.aci +``` -```yml -- hosts: aci - gather_facts: no +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: - tasks: - - name: Add a new EPG - cisco.aci.aci_epg: - hostname: apic - username: admin - password: SomeSecretPassword - tenant: production - ap: intranet - epg: web_epg - description: Web Intranet EPG - bd: prod_bd - delegate_to: localhost +```sh +ansible-galaxy collection install cisco.aci --upgrade ``` -## Optimizing Playbooks +You can also install a specific version of the collection, for example, if you need to downgrade when something is broken in the latest version (please report an issue in this repository). Use the following syntax to install version 1.0.0: -To find out more about optimizing playbook execution, please refer to the [Optimizing Playbooks](docs/optimizing.md) documentation. +```sh +ansible-galaxy collection install cisco.aci:==1.0.0 +``` -## Update +See [using Ansible collections](https://docs.ansible.com/ansible/devel/user_guide/collections_using.html) for more details. + +### Latest Build Getting the latest/nightly collection build -### First Approach +#### First Approach Clone the ansible-aci repository. @@ -82,13 +75,13 @@ ansible-galaxy collection build --force ansible-galaxy collection install cisco-aci-* --force ``` -### Second Approach +#### Second Approach Go to [ansible-aci Actions](https://github.com/CiscoDevNet/ansible-aci/actions) Select the latest CI build -Under Artifacts download collection and unzip it using Terminal or Console. +Under Artifacts download the collection prefixed with latest Ansible version and unzip it using Terminal or Console. *Note: The collection file is a zip file containing a tar.gz file. We recommend using CLI because some GUI-based unarchiver might unarchive both nested archives in one go.* @@ -98,12 +91,61 @@ Install the unarchived tar.gz file ansible-galaxy collection install cisco-aci-1.0.0.tar.gz —-force ``` -### See Also +## Use Cases + +Once the collection is installed, you can use it in a playbook by specifying the full namespace path to the module, plugin and/or role. + +### Adding a new EPG + +```yml +- hosts: aci + gather_facts: no + + tasks: + - name: Add a new EPG + cisco.aci.aci_epg: + hostname: apic + username: admin + password: SomeSecretPassword + tenant: production + ap: intranet + epg: web_epg + description: Web Intranet EPG + bd: prod_bd + delegate_to: localhost +``` + +## Optimizing Playbooks + +To find out more about optimizing playbook execution, please refer to the [Optimizing Playbooks](docs/optimizing.md) documentation. + +## Testing -- [Ansible Using collections](https://docs.ansible.com/ansible/latest/user_guide/collections_using.html) for more details. +Integration tests for each module in the cisco.aci collections are executed against the following ACI versions: -## Contributing to this collection +- 4.2(7s) +- 5.2(7g) +- 6.0(2h) + +## Contributing Ongoing development efforts and contributions to this collection are tracked as issues in this repository. We welcome community contributions to this collection. If you find problems, need an enhancement or need a new module, please open an issue or create a PR against the [Cisco ACI collection repository](https://github.com/CiscoDevNet/ansible-aci/issues). + +## Support + +This collection has supports the ACI versions listed in the Testing section. +Modules supporting new features introduced in ACI API in specific ACI versions might not be supported in earlier ACI releases. + +## Release Notes + +See the [Changelog](CHANGELOG.rst) for full release notes. + +## Related Information + +For additional information and guides see the [Cisco ACI DevNet documentation](https://developer.cisco.com/docs/aci/ansible/#cisco-aci-ansible-modules). + +## License Information + +This collection is licensed under the [GNU General Public License v3.0](LICENSE)