Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[bug_fix] Updated README to match RedHat's ansible collection template (DCNE-198) #692

Merged
merged 1 commit into from
Oct 28, 2024
Merged

[bug_fix] Updated README to match RedHat's ansible collection template (DCNE-198) #692

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
137 changes: 97 additions & 40 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,61 +1,59 @@
# ansible-aci

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.
## Description

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.
The `ansible-aci` project provides an Ansible collection for managing and automating your Cisco Application Centric Infrastructure (ACI) environment. It consists of a set of modules and roles for performing tasks related to ACI.

*Note: This collection is not compatible with versions of Ansible before v2.8.*
anvitha-jain marked this conversation as resolved.
Show resolved Hide resolved
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
- Python v3.10 or newer

## Install
Follow the [Installing Ansible](https://docs.ansible.com/ansible/latest/installation_guide/intro_installation.html) guide for detailed instructions.

Ansible must be installed
## Installation

Before using this collection, you need to install it with the Ansible Galaxy command-line tool:
samiib marked this conversation as resolved.
Show resolved Hide resolved

```sh
sudo pip install ansible
ansible-galaxy collection install cisco.aci
```

Install the collection
You can also include this collection in a `requirements.yml` file and install it with:

```sh
ansible-galaxy collection install cisco.aci
ansible-galaxy collection install -r requirements.yml
```

## Use
Using the following `requirements.yml` 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, to install version 1.0.0, use the following syntax:

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
```

See [using Ansible collections](https://docs.ansible.com/ansible/devel/user_guide/collections_using.html) for more details.

## Update
### Latest Build

Getting the latest/nightly collection build
Follow these instructions to get the latest collection.

### First Approach
#### First Approach - Build From Source Code

Clone the ansible-aci repository.

Expand All @@ -82,13 +80,11 @@ ansible-galaxy collection build --force
ansible-galaxy collection install cisco-aci-* --force
```

### Second Approach
#### Second Approach - Download From Latest CI Build

Go to [ansible-aci Actions](https://github.com/CiscoDevNet/ansible-aci/actions)
Go to [ansible-aci Actions](https://github.com/CiscoDevNet/ansible-aci/actions/workflows/ansible-test.yml?query=branch%3Amaster) and select the latest CI build.

Select the latest CI build

Under Artifacts download collection and unzip it using Terminal or Console.
Under Artifacts download collection suffixed with the latest version of Ansible (eg. `collection-stable-2.17`) 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.*

Expand All @@ -98,12 +94,73 @@ 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.

- [Ansible Using collections](https://docs.ansible.com/ansible/latest/user_guide/collections_using.html) for more details.
### Adding a new EPG

## Contributing to this collection
```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
samiib marked this conversation as resolved.
Show resolved Hide resolved
```

## Optimizing Playbooks

There are two main methods to optimize the execution of ACI modules in your playbooks.

1. Using the ACI HTTPAPI plugin
1. Using the `suppress_` options

To find out more about optimizing playbook execution, please refer to the [Optimizing Playbooks](docs/optimizing.md) documentation.
samiib marked this conversation as resolved.
Show resolved Hide resolved

## Testing

Integration tests for each module in the `cisco.aci` collection are executed on the following ACI versions:

- 4.2
- 5.2
- 6.0

## 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 supports any ACI version within the Last Day of Support (LDOS) date.

Certain modules and options in the collection are only available from specific versions of ACI. The versions that a module or option supports are documented in the individual module documentation.

To find EOL announcements for ACI versions, refer to the [End-of-Life and End-of-Sale Notices](https://www.cisco.com/c/en/us/products/cloud-systems-management/application-policy-infrastructure-controller-apic/eos-eol-notice-listing.html) page.

## Release Notes

See the [Changelog](CHANGELOG.rst) for full release notes.

## Related Information

For further information and guides, refer to the following:

- [Cisco ACI DevNet Documentation](https://developer.cisco.com/docs/aci/ansible/#cisco-aci-ansible-modules)
- [Automating ACI using Ansible](https://developer.cisco.com/docs/nexus-as-code/aci-with-ansible/#automating-aci-using-ansible)
- [ACI Programmability Learning Lab](https://developer.cisco.com/learning/tracks/aci-programmability/)

## License Information

This collection is licensed under the [GNU General Public License v3.0](LICENSE)
Loading