diff --git a/README.md b/README.md index f6d08f6f..90a901cb 100644 --- a/README.md +++ b/README.md @@ -1,35 +1,116 @@ # ansible-mso -The `ansible-mso` project provides an Ansible collection for managing and automating your Cisco ACI Multi-Site environment. +## Description + +The `ansible-mso` project provides an Ansible collection for managing and automating your Cisco ACI Multi-Site or Nexus Dashboard Orchestrator environments. It consists of a set of modules and roles for performing tasks related to ACI Multi-Site. -This collection has been tested and supports MSO 2.1+. -Modules supporting new features introduced in MSO API in specific MSO versions might not be supported in earlier MSO releases. +See the [cisco.mso collection index](https://galaxy.ansible.com/ui/repo/published/cisco/mso/content/) for a full list of modules and plugins. -*Note: This collection is not compatible with versions of Ansible before v2.8.* *Note: The Nexus Dashboard (ND) HTTPAPI connection plugin should be used when Cisco ACI Multi-Site is installed on Nexus Dashboard (v3.2+) or when using this collection with Nexus Dashboard Orchestrator (v3.6+).* ## Requirements -- Ansible v2.14 or newer -## Install -Ansible must be installed +- Ansible v2.15 or newer +- Python v3.10 or newer + +Follow the [Installing Ansible](https://docs.ansible.com/ansible/latest/installation_guide/intro_installation.html) guide for detailed instructions. + +## Installation + +Before using this collection, you need to install it with the Ansible Galaxy command-line tool: + +```sh +ansible-galaxy collection install cisco.mso ``` -sudo pip install ansible + +You can also include this collection in a requirements.yml file and install it with: + +```sh +ansible-galaxy collection install -r requirements.yml ``` -Install the collection +Using the following `requirements.yml` format: + +```yaml +collections: + - name: cisco.mso ``` -ansible-galaxy collection install cisco.mso + +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: + +```sh +ansible-galaxy collection install cisco.mso --upgrade ``` -Install the Nexus Dashboard (ND) collection when Cisco ACI Multi-Site is installed on Nexus Dashboard (v3.2+) or when using this collection with Nexus Dashboard Orchestrator (v3.6+) +You can also install a specific version of the collection. For example, to install version 1.0.0, use the following syntax: + +```sh +ansible-galaxy collection install cisco.mso:==1.0.0 ``` + +See [using Ansible collections](https://docs.ansible.com/ansible/devel/user_guide/collections_using.html) for more details. + +### Installation with Nexus Dashboard + +Install the Nexus Dashboard (ND) collection when Cisco ACI Multi-Site is installed on Nexus Dashboard (v3.2+) or when using this collection with Nexus Dashboard Orchestrator (v3.6+) + +```sh ansible-galaxy collection install cisco.nd ``` -## Usage +### Latest Build + +Follow these instructions to get the latest collection. + +#### First Approach - Build From Source Code + +Clone the `ansible-mso` repository. + +```sh +git clone https://github.com/CiscoDevNet/ansible-mso.git +``` + +Go to the `ansible-mso` directory + +```sh +cd ansible-mso +``` + +Pull the latest master on your mso + +```sh +git pull origin master +``` + +Build and Install a collection from source + +```sh +ansible-galaxy collection build --force +ansible-galaxy collection install cisco-mso-* --force +``` + +#### Second Approach - Download From Latest CI Build + +Go to [ansible-mso Actions](https://github.com/CiscoDevNet/ansible-mso/actions/workflows/ansible-test.yml?query=branch%3Amaster) and select the latest CI build. + +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.* + +Install the unarchived tar.gz file + +```sh +ansible-galaxy collection install cisco-mso-1.0.0.tar.gz —-force +``` + +## 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 site EPG + ```yaml - hosts: mso gather_facts: no @@ -48,13 +129,17 @@ Once the collection is installed, you can use it in a playbook by specifying the state: present ``` -You can also use the MSO HTTPAPI connection plugin by setting the following variables in your inventory file (cisco.mso collection v1.2+). +## MSO HTTPAPI Plugin + +You can use the MSO HTTPAPI connection plugin by setting the following variables in your inventory file (cisco.mso collection v1.2+). + ```yaml ansible_connection=ansible.netcommon.httpapi ansible_network_os=cisco.mso.mso ``` The HTTPAPI connection plugin will also allow you to specify additional parameters as variable and omit them from the task itself. Module parameters will override global variables. + ```yaml ansible_host=10.0.0.1 ansible_user=admin @@ -65,57 +150,49 @@ ansible_httpapi_use_proxy=True ``` You should use the Nexus Dashboard (ND) collection plugin, which is available in the [cisco.nd](https://galaxy.ansible.com/cisco/nd) collection, when Cisco ACI Multi-Site is installed on Nexus Dashboard (v3.2+) or when using this collection with Nexus Dashboard Orchestrator (v3.6+) by changing the following variables. + ```yaml ansible_connection=ansible.netcommon.httpapi ansible_network_os=cisco.nd.nd ansible_httpapi_use_ssl=True ``` -## Update -Getting the latest/nightly collection build +## Testing -### First Approach -Clone the ansible-mso repository. -``` -git clone https://github.com/CiscoDevNet/ansible-mso.git -``` +Integration tests for each module in the `cisco.mso` collection are executed on the following Nexus Dashboard Orchestrator versions: -Go to the ansible-mso directory -``` -cd ansible-mso -``` +- 3.7 +- 4.1 +- 4.2 +- 4.3 -Pull the latest master on your mso -``` -git pull origin master -``` +## Contributing -Build and Install a collection from source -``` -ansible-galaxy collection build --force -ansible-galaxy collection install cisco-mso-* --force -``` +Ongoing development efforts and contributions to this collection are tracked as issues in this repository. -### Second Approach -Go to: https://github.com/CiscoDevNet/ansible-mso/actions +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 MSO collection repository](https://github.com/CiscoDevNet/ansible-mso/issues). -Select the latest CI build +## Support -Under Artifacts download collection and unzip it using Terminal or Console. +This collection supports any MSO/NDO version within the Last Day of Support (LDOS) date. -*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.* +Certain modules and options in the collection are only available from specific versions of MSO/NDO. The versions that a module or option supports are documented in the individual module documentation. -Install the unarchived tar.gz file -``` -ansible-galaxy collection install cisco-mso-1.0.0.tar.gz —-force -``` +To find EOL announcements for MSO/NDO versions, refer to the [End-of-Life and End-of-Sale Notices](https://www.cisco.com/c/en/us/products/cloud-systems-management/multi-site-orchestrator/eos-eol-notice-listing.html) page. -### See Also: +## Release Notes -* [Ansible Using collections](https://docs.ansible.com/ansible/latest/user_guide/collections_using.html) for more details. +See the [Changelog](CHANGELOG.rst) for full release notes. -## Contributing to this collection +## Related Information -Ongoing development efforts and contributions to this collection are tracked as issues in this repository. +For further information, refer to the following: -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 MSO collection repository](https://github.com/CiscoDevNet/ansible-mso/issues). +- [Automating Cisco MSO with Ansible Learning Lab](https://developer.cisco.com/learning/labs/mso-ansible_part1-intro/setup-an-ansible-and-mso-environment/) +- [Nexus Dashboard Orchestrator Overview](https://www.cisco.com/c/en/us/products/collateral/cloud-systems-management/multi-site-orchestrator/nb-06-mso-so-cte-en.html) +- [Nexus Dashboard Orchestrator Support Documentation](https://www.cisco.com/c/en/us/support/cloud-systems-management/multi-site-orchestrator/series.html) +- [Nexus Dashboard Orchestrator API Release Notes](https://developer.cisco.com/docs/search/?q=Nexus+Dashboard+Orchestrator) + +## License Information + +This collection is licensed under the [GNU General Public License v3.0](LICENSE)