[minor_change] Added Playbook Optimizing documentation

README.md

@@ -8,22 +8,28 @@ Modules supporting new features introduced in ACI API in specific ACI versions m
 *Note: This collection is not compatible with versions of Ansible before v2.8.*
 
 ## Requirements
+
 Ansible v2.14 or newer
 
 ## Install
+
 Ansible must be installed
-```
+
+```sh
 sudo pip install ansible
 ```
 
 Install the collection
-```
+
+```sh
 ansible-galaxy collection install cisco.aci
 ```
+
 ## Use
+
 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.
 
-```
+```yml
 - hosts: aci
   gather_facts: no
 
@@ -41,33 +47,44 @@ Once the collection is installed, you can use it in a playbook by specifying the
     delegate_to: localhost
 ```
 
+## Optimizing Playbooks
+
+To find out more about optimizing playbook execution, please refer to the [Optimizing Playbooks](docs/optimizing.md) documentation.
+
 ## Update
+
 Getting the latest/nightly collection build
 
 ### First Approach
+
 Clone the ansible-aci repository.
-```
+
+```sh
 git clone https://github.com/CiscoDevNet/ansible-aci.git
 ```
 
 Go to the ansible-aci directory
-```
+
+```sh
 cd ansible-aci
 ```
 
 Pull the latest master on your aci
-```
+
+```sh
 git pull origin master
 ```
 
 Build and Install a collection from source
-```
+
+```sh
 ansible-galaxy collection build --force
 ansible-galaxy collection install cisco-aci-* --force
 ```
 
 ### Second Approach
-Go to: https://github.com/CiscoDevNet/ansible-aci/actions
+
+Go to [ansible-aci Actions](https://github.com/CiscoDevNet/ansible-aci/actions)
 
 Select the latest CI build
 
@@ -76,13 +93,14 @@ Under Artifacts download collection 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-aci-1.0.0.tar.gz —-force
 ```
 
-### See Also:
+### See Also
 
-* [Ansible Using collections](https://docs.ansible.com/ansible/latest/user_guide/collections_using.html) for more details.
+- [Ansible Using collections](https://docs.ansible.com/ansible/latest/user_guide/collections_using.html) for more details.
 
 ## Contributing to this collection
 

docs/optimizing.md

@@ -0,0 +1,129 @@
+# Optimizing Playbooks
+
+By using all of the following optimizations together its estimated that playbook execution time can be reduced by up to 60% compared to default behavior.
+
+## Using the ACI HTTPAPI plugin
+
+The Ansible ACI HTTPAPI plugin instructs Ansible how to interact with an APIC's HTTP based API and execute tasks on the APIC.
+
+### Benefits
+
+- The ACI login credentials and ansible variables can stay in the inventory.
+- Logs in once and executes subsequent tasks without requiring additional logins when using password-based authentication.
+- Automatically refreshes password-based logins if the token expires during the playbook.
+- Assists with overcoming rate limiting on logins.
+- Leverages APIC's high availability by allowing a list of APIC hosts to be defined as a single ansible host.
+
+### Enabling the plugin
+
+The httpapi plugin can be enabled by setting the following variables:
+
+```ini
+ansible_connection=ansible.netcommon.httpapi
+ansible_network_os=cisco.aci.aci
+```
+
+Instead of using `hostname`, `username` & `password` in the playbook, the following variables can be used in the inventory.
+
+```ini
+ansible_user=apicUser
+ansible_password="SomeSecretPassword"
+```
+
+The `ansible_host` variable can contain one or more APIC hosts separated by a comma. If multiple hosts are defined the plugin will try executing tasks on the hosts in the order listed until one completes or they all fail.
+
+```ini
+single_apic  ansible_host=apic.host
+cluster_apic ansible_host=apic1.host,apic2.host,apic3.host
+```
+
+Signature-based authentication can be specified in the inventory.
+
+```ini
+ansible_httpapi_session_key={'admin': "{{ lookup('file', 'admin.key')}}"}
+```
+
+> [!NOTE]
+> `ansible_httpapi_session_key` takes precedence over `ansible_password`.
+
+> [!TIP]
+> Using signature-based authentication with or without ACI HTTPAPI enabled has the same execution time benefit.
+
+### Full Example Inventory using ACI HTTPAPI plugin
+
+```ini
+[aci]
+single_apic  ansible_host=apic.host
+cluster_apic ansible_host=apic1.host,apic2.host,apic3.host
+
+[aci:vars]
+ansible_user=admin
+ansible_password="SomeSecretPassword"
+ansible_connection=ansible.netcommon.httpapi
+ansible_network_os=cisco.aci.aci
+```
+
+## Using the `suppress_` options
+
+Two options are available to users on all ACI modules to assist with optimizing playbook performance by reducing API calls. These options can increase playbook performance at the expense of suppressing some features of the modules.
+
+### `suppress_previous`
+
+If enabled, a GET call to check previous object state will not be sent before a POST update to APIC.
+
+> [!WARNING]
+> This causes the previous return value to be empty. The previous state of the object will not be checked and POST update calls to APIC will contain all properties specified in the task.
+
+#### `suppress_previous` Aliases
+
+- `no_previous`
+- `ignore_previous`
+
+#### `suppress_previous` Example
+
+```yml
+- hosts: aci
+  gather_facts: no
+
+  tasks:
+  - name: Add a new EPG
+    cisco.aci.aci_epg:
+      tenant: production
+      ap: intranet
+      epg: web_epg
+      description: Web Intranet EPG
+      bd: prod_bd
+      suppress_previous: true
+```
+
+### `suppress_verification`
+
+If enabled, a verifying GET call to check current object state will not be sent after a POST call to APIC.
+
+> [!WARNING]
+> This causes the current return value to be set to the proposed value. The current object state including default values will be unverifiable until another task executes for the same object.
+
+#### `suppress_verification` Aliases
+
+- `no_verification`
+- `no_verify`
+- `suppress_verify`
+- `ignore_verify`
+- `ignore_verification`
+
+#### `suppress_verification` Example
+
+```yml
+- hosts: aci
+  gather_facts: no
+
+  tasks:
+  - name: Add a new EPG
+    cisco.aci.aci_epg:
+      tenant: production
+      ap: intranet
+      epg: web_epg
+      description: Web Intranet EPG
+      bd: prod_bd
+      suppress_verification: true
+```