More improvements to ACI module docs (#36689)

* More improvements to ACI module docs * Asorted improvements * Found 2 more * Improvements to aci_rest documentation
2018-02-25 19:13:16 +01:00 · 2018-02-25 19:13:16 +01:00 · 8f6eea50db
commit 8f6eea50db
parent 984bface14
53 changed files with 87 additions and 80 deletions
--- a/docs/docsite/rst/scenario_guides/guide_aci.rst
+++ b/docs/docsite/rst/scenario_guides/guide_aci.rst
@ -262,15 +262,20 @@ While already a lot of ACI modules exists in the Ansible distribution, and the m
 The :ref:`aci_rest <aci_rest>` module provides you with direct access to the APIC REST API and enables you to perform any task not already covered by the existing modules. This may seem like a complex undertaking, but you can generate the needed REST payload for any action performed in the ACI web interface effortlessly.


-Using the aci-rest module
+Built-in idempotency
+....................
+Because the APIC REST API is intrinsically idempotent and can report whether a change was made, the :ref:`aci_rest <aci_rest>` module automatically inherits both capabilities and is a first-class solution for automating your ACI infrastructure. As a result, users that require more powerful low-level access to their ACI infrastructure don't have to give up on idempotency and don't have to guess whether a change was performed when using the :ref:`aci_rest <aci_rest>` module.
+
+
+Using the aci_rest module
 .........................
-The :ref:`aci_rest <aci_rest>` module accepts the native XML and JSON payloads, but additionally accepts inline YAML payload (structured like JSON). The XML payload requires you to use a path ending with ``.xml`` whereas JSON or YAML require path to end with ``.json``.
+The :ref:`aci_rest <aci_rest>` module accepts the native XML and JSON payloads, but additionally accepts inline YAML payload (structured like JSON). The XML payload requires you to use a path ending with ``.xml`` whereas JSON or YAML require the path to end with ``.json``.

 When you're making modifications, you can use the POST or DELETE methods, whereas doing just queries require the GET method.

-For instance, if you would like to ensure a specific tenant exists on ACI, these below four examples are identical:
+For instance, if you would like to ensure a specific tenant exists on ACI, these below four examples are functionally identical:

-**XML** (Native ACI)
+**XML** (Native ACI REST)

 .. code-block:: yaml

@ -283,7 +288,7 @@ For instance, if you would like to ensure a specific tenant exists on ACI, these
        content: |
          <fvTenant name="customer-xyz" descr="Customer XYZ"/>

-**JSON** (Native ACI)
+**JSON** (Native ACI REST)

 .. code-block:: yaml

@ -303,7 +308,7 @@ For instance, if you would like to ensure a specific tenant exists on ACI, these
            }
          }

-**YAML** (Ansible-style)
+**YAML** (Ansible-style REST)

 .. code-block:: yaml

@ -332,6 +337,9 @@ For instance, if you would like to ensure a specific tenant exists on ACI, these
        state: present


+.. hint:: The XML format is more practical when there is a need to template the REST payload (inline), but the YAML format is more convenient for maintaing your infrastructure-as-code and feels more naturely integrated with Ansible playbooks. The dedicated modules offer a more simple, abstracted, but also a more limited experience. Use what feels best for your use-case.
+
+
 More information
 ................
 Plenty of resources exist to learn about ACI's APIC REST interface, we recommend the links below:
@ -347,7 +355,8 @@ Plenty of resources exist to learn about ACI's APIC REST interface, we recommend
 Operational examples
 --------------------
 Here is a small overview of useful operational tasks to reuse in your playbooks.
-Feel free to contribute more snippets that are useful to others.
+
+Feel free to contribute more useful snippets.


 Waiting for all controllers to be ready
@ -359,13 +368,11 @@ You can use the below task after you started to build your APICs and configured
    - name: Waiting for all controllers to be ready
      aci_rest:
        host: '{{ apic_ip }}'
-        username: '{{ apic_username }}'
        private_key: pki/admin.key
        method: get
        path: /api/node/class/topSystem.json?query-target-filter=eq(topSystem.role,"controller")
-      changed_when: no
-      register: aci_ready
-      until: aci_ready|success and aci_ready.totalCount|int >= groups['apic']|count
+      register: topsystem
+      until: topsystem|success and topsystem.totalCount|int >= groups['apic']|count >= 3
      retries: 20
      delay: 30

@ -379,19 +386,17 @@ The below example waits until the cluster is fully-fit. In this example you know
    - name: Waiting for cluster to be fully-fit
      aci_rest:
        host: '{{ apic_ip }}'
-        username: '{{ apic_username }}'
        private_key: pki/admin.key
        method: get
        path: /api/node/class/infraWiNode.json?query-target-filter=wcard(infraWiNode.dn,"topology/pod-1/node-1/av")
-      changed_when: no
-      register: aci_fit
+      register: infrawinode
      until: >
-        aci_fit|success and
-        aci_fit.totalCount|int >= groups['apic']|count >= 3 and
-        aci_fit.imdata[0].infraWiNode.attributes.health == 'fully-fit' and
-        aci_fit.imdata[1].infraWiNode.attributes.health == 'fully-fit' and
-        aci_fit.imdata[2].infraWiNode.attributes.health == 'fully-fit'
-    #    all(apic.infraWiNode.attributes.health == 'fully-fit' for apic in aci_fit.imdata)
+        infrawinode|success and
+        infrawinode.totalCount|int >= groups['apic']|count >= 3 and
+        infrawinode.imdata[0].infraWiNode.attributes.health == 'fully-fit' and
+        infrawinode.imdata[1].infraWiNode.attributes.health == 'fully-fit' and
+        infrawinode.imdata[2].infraWiNode.attributes.health == 'fully-fit'
+    #    all(apic.infraWiNode.attributes.health == 'fully-fit' for apic in infrawinode.imdata)
      retries: 30
      delay: 30

@ -407,7 +412,7 @@ The following error messages may occur and this section can help you understand


    APIC Error 400: invalid data at line '1'. Attributes are missing, tag 'attributes' must be specified first, before any other tag
-        Although the JSON specification allows unordered elements, the APIC REST API requires that the JSON ``attributes`` element precede the ``children`` array or other elements. So you need to ensure that your payload conforms to this requirement. Sorting your dictionary keys will do the trick just fine. If you don't have any attributes, it may be necessary to add: ``attributes: {}`` as the APIC does expect the entry to proceed any ``children``.
+        Although the JSON specification allows unordered elements, the APIC REST API requires that the JSON ``attributes`` element precede the ``children`` array or other elements. So you need to ensure that your payload conforms to this requirement. Sorting your dictionary keys will do the trick just fine. If you don't have any attributes, it may be necessary to add: ``attributes: {}`` as the APIC does expect the entry to precede any ``children``.


    APIC Error 801: property descr of uni/tn-TENANT/ap-AP failed validation for value 'A "legacy" network'
--- a/lib/ansible/modules/network/aci/aci_aaa_user.py
+++ b/lib/ansible/modules/network/aci/aci_aaa_user.py
@ -23,7 +23,7 @@ notes:
  appears to be an inconsistency wrt. the idempotent nature
  of the APIC REST API. The vendor has been informed.
  More information in :ref:`the ACI documentation <aci_guide_known_issues>`.
- More information from the internal APIC class I(aaa:User) at
+- More information about the internal APIC class B(aaa:User) at
  U(https://developer.cisco.com/docs/apic-mim-ref/).
 author:
 - Dag Wieers (@dagwieers)
--- a/lib/ansible/modules/network/aci/aci_aaa_user_certificate.py
+++ b/lib/ansible/modules/network/aci/aci_aaa_user_certificate.py
@ -20,7 +20,7 @@ description:
 notes:
 - The C(aaa_user) must exist before using this module in your playbook.
  The M(aci_aaa_user) module can be used for this.
- More information from the internal APIC class I(aaa:UserCert) at
+- More information about the internal APIC class B(aaa:UserCert) at
  U(https://developer.cisco.com/docs/apic-mim-ref/).
 author:
 - Dag Wieers (@dagwieers)
--- a/lib/ansible/modules/network/aci/aci_access_port_to_interface_policy_leaf_profile.py
+++ b/lib/ansible/modules/network/aci/aci_access_port_to_interface_policy_leaf_profile.py
@ -18,7 +18,7 @@ short_description: Manage Fabric interface policy leaf profile interface selecto
 description:
 - Manage Fabric interface policy leaf profile interface selectors on Cisco ACI fabrics.
 notes:
- More information from the internal APIC class I(infra:HPortS, infra:RsAccBaseGrp, infra:PortBlk) at
+- More information about the internal APIC classes B(infra:HPortS), B(infra:RsAccBaseGrp) and B(infra:PortBlk) at
  U(https://developer.cisco.com/media/mim-ref).
 author:
 - Bruno Calogero (@brunocalogero)
--- a/lib/ansible/modules/network/aci/aci_aep.py
+++ b/lib/ansible/modules/network/aci/aci_aep.py
@ -13,12 +13,12 @@ ANSIBLE_METADATA = {'metadata_version': '1.1',
 DOCUMENTATION = r'''
 ---
 module: aci_aep
-short_description: Manage attachable Access Entity Profile (AEP) objects (infra:AttEntityP|infra:ProvAcc)
+short_description: Manage attachable Access Entity Profile (AEP) objects (infra:AttEntityP, infra:ProvAcc)
 description:
 - Connect to external virtual and physical domains by using
  attachable Access Entity Profiles (AEP) on Cisco ACI fabrics.
 notes:
- More information from the internal APIC classes I(infra:AttEntityP) and I(infra:ProvAcc) at
+- More information about the internal APIC classes B(infra:AttEntityP) and B(infra:ProvAcc) at
  U(https://developer.cisco.com/docs/apic-mim-ref/).
 author:
 - Swetha Chunduri (@schunduri)
--- a/lib/ansible/modules/network/aci/aci_aep_to_domain.py
+++ b/lib/ansible/modules/network/aci/aci_aep_to_domain.py
@ -20,7 +20,7 @@ description:
 notes:
 - The C(aep) and C(domain) parameters should exist before using this module.
  The M(aci_aep) and M(aci_domain) can be used for these.
- More information from the internal APIC class I(infra:RsDomP) at
+- More information about the internal APIC class B(infra:RsDomP) at
  U(https://developer.cisco.com/docs/apic-mim-ref/).
 author:
 - Dag Wieers (@dagwieers)
--- a/lib/ansible/modules/network/aci/aci_ap.py
+++ b/lib/ansible/modules/network/aci/aci_ap.py
@ -20,7 +20,7 @@ notes:
 - This module does not manage EPGs, see M(aci_epg) to do this.
 - The C(tenant) used must exist before using this module in your playbook.
  The M(aci_tenant) module can be used for this.
- More information from the internal APIC class I(fv:Ap) at
+- More information about the internal APIC class B(fv:Ap) at
  U(https://developer.cisco.com/docs/apic-mim-ref/).
 author:
 - Swetha Chunduri (@schunduri)
--- a/lib/ansible/modules/network/aci/aci_bd.py
+++ b/lib/ansible/modules/network/aci/aci_bd.py
@ -19,7 +19,7 @@ description:
 notes:
 - The C(tenant) used must exist before using this module in your playbook.
  The M(aci_tenant) module can be used for this.
- More information from the internal APIC class I(fv:BD) at
+- More information about the internal APIC class B(fv:BD) at
  U(https://developer.cisco.com/docs/apic-mim-ref/).
 author:
 - Jacob McGill (@jmcgill298)
--- a/lib/ansible/modules/network/aci/aci_bd_subnet.py
+++ b/lib/ansible/modules/network/aci/aci_bd_subnet.py
@ -21,7 +21,7 @@ notes:
  is required when the state is C(absent) or C(present).
 - The C(tenant) and C(bd) used must exist before using this module in your playbook.
  The M(aci_tenant) module and M(aci_bd) can be used for these.
- More information from the internal APIC class I(fv:Subnet) at
+- More information about the internal APIC class B(fv:Subnet) at
  U(https://developer.cisco.com/docs/apic-mim-ref/).
 author:
 - Jacob McGill (@jmcgill298)
--- a/lib/ansible/modules/network/aci/aci_bd_to_l3out.py
+++ b/lib/ansible/modules/network/aci/aci_bd_to_l3out.py
@ -19,7 +19,7 @@ description:
 notes:
 - The C(bd) and C(l3out) parameters should exist before using this module.
  The M(aci_bd) and M(aci_l3out) can be used for these.
- More information from the internal APIC class I(fv:RsBDToOut) at
+- More information about the internal APIC class B(fv:RsBDToOut) at
  U(https://developer.cisco.com/docs/apic-mim-ref/).
 author:
 - Jacob McGill (@jmcgill298)
--- a/lib/ansible/modules/network/aci/aci_config_rollback.py
+++ b/lib/ansible/modules/network/aci/aci_config_rollback.py
@ -18,7 +18,7 @@ description:
 - Provides rollback and rollback preview functionality for Cisco ACI fabrics.
 - Config Rollbacks are done using snapshots C(aci_snapshot) with the configImportP class.
 notes:
- More information from the internal APIC class I(config:ImportP) at
+- More information about the internal APIC class B(config:ImportP) at
  U(https://developer.cisco.com/docs/apic-mim-ref/).
 author:
 - Jacob McGill (@jmcgill298)
--- a/lib/ansible/modules/network/aci/aci_config_snapshot.py
+++ b/lib/ansible/modules/network/aci/aci_config_snapshot.py
@ -22,7 +22,7 @@ notes:
 - The APIC does not provide a mechanism for naming the snapshots.
 - 'Snapshot files use the following naming structure: ce_<config export policy name>-<yyyy>-<mm>-<dd>T<hh>:<mm>:<ss>.<mss>+<hh>:<mm>.'
 - 'Snapshot objects use the following naming structure: run-<yyyy>-<mm>-<dd>T<hh>-<mm>-<ss>.'
- More information from the internal APIC classes I(config:Snapshot) and I(config:ExportP) at
+- More information about the internal APIC classes B(config:Snapshot) and B(config:ExportP) at
  U(https://developer.cisco.com/docs/apic-mim-ref/).
 author:
 - Jacob McGill (@jmcgill298)
--- a/lib/ansible/modules/network/aci/aci_contract.py
+++ b/lib/ansible/modules/network/aci/aci_contract.py
@ -21,7 +21,7 @@ notes:
  Contract Subjects can still be removed using this module.
 - The C(tenant) used must exist before using this module in your playbook.
  The M(aci_tenant) module can be used for this.
- More information from the internal APIC class I(vz:BrCP) at
+- More information about the internal APIC class B(vz:BrCP) at
  U(https://developer.cisco.com/docs/apic-mim-ref/).
 author:
 - Dag Wieers (@dagwieers)
--- a/lib/ansible/modules/network/aci/aci_contract_subject.py
+++ b/lib/ansible/modules/network/aci/aci_contract_subject.py
@ -19,7 +19,7 @@ description:
 notes:
 - The C(tenant) and C(contract) used must exist before using this module in your playbook.
 - The M(aci_tenant) and M(aci_contract) modules can be used for this.
- More information from the internal APIC class I(vz:Subj) at
+- More information about the internal APIC class B(vz:Subj) at
  U(https://developer.cisco.com/docs/apic-mim-ref/).
 author:
 - Swetha Chunduri (@schunduri)
--- a/lib/ansible/modules/network/aci/aci_contract_subject_to_filter.py
+++ b/lib/ansible/modules/network/aci/aci_contract_subject_to_filter.py
@ -19,7 +19,7 @@ description:
 notes:
 - The C(tenant), C(contract), C(subject), and C(filter_name) must exist before using this module in your playbook.
 - The M(aci_tenant), M(aci_contract), M(aci_contract_subject), and M(aci_filter) modules can be used for these.
- More information from the internal APIC class I(vz:RsSubjFiltAtt) at
+- More information about the internal APIC class B(vz:RsSubjFiltAtt) at
  U(https://developer.cisco.com/docs/apic-mim-ref/).
 author:
 - Jacob McGill (@jmcgill298)
--- a/lib/ansible/modules/network/aci/aci_domain.py
+++ b/lib/ansible/modules/network/aci/aci_domain.py
@ -17,8 +17,8 @@ short_description: Manage physical, virtual, bridged, routed or FC domain profil
 description:
 - Manage physical, virtual, bridged, routed or FC domain profiles on Cisco ACI fabrics.
 notes:
- More information from the internal APIC classes I(phys:DomP),
-  I(vmm:DomP), I(l2ext:DomP), I(l3ext:DomP), I(fc:DomP) at
+- More information about the internal APIC classes B(phys:DomP),
+  B(vmm:DomP), B(l2ext:DomP), B(l3ext:DomP) and B(fc:DomP) at
  U(https://developer.cisco.com/docs/apic-mim-ref/).
 author:
 - Dag Wieers (@dagwieers)
--- a/lib/ansible/modules/network/aci/aci_domain_to_encap_pool.py
+++ b/lib/ansible/modules/network/aci/aci_domain_to_encap_pool.py
@ -20,7 +20,7 @@ description:
 notes:
 - The C(domain) and C(encap_pool) parameters should exist before using this module.
  The M(aci_domain) and M(aci_encap_pool) can be used for these.
- More information from the internal APIC class I(infra:RsVlanNs) at
+- More information about the internal APIC class B(infra:RsVlanNs) at
  U(https://developer.cisco.com/docs/apic-mim-ref/).
 author:
 - Dag Wieers (@dagwieers)
--- a/lib/ansible/modules/network/aci/aci_domain_to_vlan_pool.py
+++ b/lib/ansible/modules/network/aci/aci_domain_to_vlan_pool.py
@ -20,7 +20,7 @@ description:
 notes:
 - The C(domain) and C(vlan_pool) parameters should exist before using this module.
  The M(aci_domain) and M(aci_vlan_pool) can be used for these.
- More information from the internal APIC class I(infra:RsVlanNs) at
+- More information about the internal APIC class B(infra:RsVlanNs) at
  U(https://developer.cisco.com/docs/apic-mim-ref/).
 author:
 - Dag Wieers (@dagwieers)
--- a/lib/ansible/modules/network/aci/aci_encap_pool.py
+++ b/lib/ansible/modules/network/aci/aci_encap_pool.py
@ -17,8 +17,7 @@ short_description: Manage encap pools (fvns:VlanInstP, fvns:VxlanInstP, fvns:Vsa
 description:
 - Manage vlan, vxlan, and vsan pools on Cisco ACI fabrics.
 notes:
- More information from the internal APIC class
-  I(fvns:VlanInstP), I(fvns:VxlanInstP), and I(fvns:VsanInstP) at
+- More information about the internal APIC classes B(fvns:VlanInstP), B(fvns:VxlanInstP) and B(fvns:VsanInstP) at
  U(https://developer.cisco.com/docs/apic-mim-ref/).
 author:
 - Jacob McGill (@jmcgill298)
--- a/lib/ansible/modules/network/aci/aci_encap_pool_range.py
+++ b/lib/ansible/modules/network/aci/aci_encap_pool_range.py
@ -18,7 +18,7 @@ description:
 - Manage vlan, vxlan, and vsan ranges that are assigned to pools on Cisco ACI fabrics.
 notes:
 - The C(pool) must exist in order to add or delete a range.
- More information from the internal APIC class I(fvns:EncapBlk) and I(fvns:VsanEncapBlk) at
+- More information about the internal APIC classes B(fvns:EncapBlk) and B(fvns:VsanEncapBlk) at
  U(https://developer.cisco.com/docs/apic-mim-ref/).
 author:
 - Jacob McGill (@jmcgill298)
--- a/lib/ansible/modules/network/aci/aci_epg.py
+++ b/lib/ansible/modules/network/aci/aci_epg.py
@ -19,7 +19,7 @@ description:
 notes:
 - The C(tenant) and C(app_profile) used must exist before using this module in your playbook.
  The M(aci_tenant) and M(aci_ap) modules can be used for this.
- More information from the internal APIC class I(fv:AEPg) at
+- More information about the internal APIC class B(fv:AEPg) at
  U(https://developer.cisco.com/docs/apic-mim-ref/).
 author:
 - Swetha Chunduri (@schunduri)
--- a/lib/ansible/modules/network/aci/aci_epg_monitoring_policy.py
+++ b/lib/ansible/modules/network/aci/aci_epg_monitoring_policy.py
@ -19,7 +19,7 @@ description:
 notes:
 - The C(tenant) used must exist before using this module in your playbook.
  The M(aci_tenant) module can be used for this.
- More information from the internal APIC class I(mon:EPGPol) at
+- More information about the internal APIC class B(mon:EPGPol) at
  U(https://developer.cisco.com/docs/apic-mim-ref/).
 author:
 - Dag Wieers (@dagwieers)
--- a/lib/ansible/modules/network/aci/aci_epg_to_contract.py
+++ b/lib/ansible/modules/network/aci/aci_epg_to_contract.py
@ -19,7 +19,7 @@ description:
 notes:
 - The C(tenant), C(app_profile), C(EPG), and C(Contract) used must exist before using this module in your playbook.
  The M(aci_tenant), M(aci_ap), M(aci_epg), and M(aci_contract) modules can be used for this.
- More information from the internal APIC classes I(fv:RsCons) and I(fv:RsProv) at
+- More information about the internal APIC classes B(fv:RsCons) and B(fv:RsProv) at
  U(https://developer.cisco.com/docs/apic-mim-ref/).
 author:
 - Jacob McGill (@jmcgill298)
--- a/lib/ansible/modules/network/aci/aci_epg_to_domain.py
+++ b/lib/ansible/modules/network/aci/aci_epg_to_domain.py
@ -22,7 +22,7 @@ notes:
 - OpenStack VMM domains must not be created using this module. The OpenStack VMM domain is created directly
  by the Cisco APIC Neutron plugin as part of the installation and configuration.
  This module can be used to query status of an OpenStack VMM domain.
- More information from the internal APIC class I(fv:RsDomAtt) at
+- More information about the internal APIC class B(fv:RsDomAtt) at
  U(https://developer.cisco.com/docs/apic-mim-ref/).
 author:
 - Jacob McGill (@jmcgill298)
--- a/lib/ansible/modules/network/aci/aci_fabric_node.py
+++ b/lib/ansible/modules/network/aci/aci_fabric_node.py
@ -18,8 +18,8 @@ short_description: Manage Fabric Node Members (fabric:NodeIdentP)
 description:
 - Manage Fabric Node Members on Cisco ACI fabrics.
 notes:
- More information from the internal APIC class
-  I(fabric:NodeIdentP) at U(https://developer.cisco.com/site/aci/docs/apis/apic-mim-ref/).
+- More information about the internal APIC class B(fabric:NodeIdentP) at
+  U(https://developer.cisco.com/site/aci/docs/apis/apic-mim-ref/).
 author:
 - Bruno Calogero (@brunocalogero)
 version_added: '2.5'
--- a/lib/ansible/modules/network/aci/aci_filter.py
+++ b/lib/ansible/modules/network/aci/aci_filter.py
@ -20,7 +20,7 @@ description:
 notes:
 - The C(tenant) used must exist before using this module in your playbook.
  The M(aci_tenant) module can be used for this.
- More information from the internal APIC class I(vz:Filter) at
+- More information about the internal APIC class B(vz:Filter) at
  U(https://developer.cisco.com/docs/apic-mim-ref/).
 author:
 - Dag Wieers (@dagwieers)
--- a/lib/ansible/modules/network/aci/aci_filter_entry.py
+++ b/lib/ansible/modules/network/aci/aci_filter_entry.py
@ -19,7 +19,7 @@ description:
 notes:
 - The C(tenant) and C(filter) used must exist before using this module in your playbook.
  The M(aci_tenant) and M(aci_filter) modules can be used for this.
- More information from the internal APIC class I(vz:Entry) at
+- More information about the internal APIC class B(vz:Entry) at
  U(https://developer.cisco.com/docs/apic-mim-ref/).
 author:
 - Jacob McGill (@jmcgill298)
--- a/lib/ansible/modules/network/aci/aci_firmware_source.py
+++ b/lib/ansible/modules/network/aci/aci_firmware_source.py
@ -21,7 +21,7 @@ author:
 - Dag Wieers (@dagwieers)
 version_added: '2.5'
 notes:
- More information from the internal APIC class I(firmware:OSource) at
+- More information about the internal APIC class B(firmware:OSource) at
  U(https://developer.cisco.com/docs/apic-mim-ref/).
 options:
  source:
--- a/lib/ansible/modules/network/aci/aci_interface_policy_fc.py
+++ b/lib/ansible/modules/network/aci/aci_interface_policy_fc.py
@ -20,7 +20,7 @@ author:
 - Dag Wieers (@dagwieers)
 version_added: '2.4'
 notes:
- More information from the internal APIC class I(fc:IfPol) at
+- More information about the internal APIC class B(fc:IfPol) at
  U(https://developer.cisco.com/docs/apic-mim-ref/).
 options:
  fc_policy:
--- a/lib/ansible/modules/network/aci/aci_interface_policy_l2.py
+++ b/lib/ansible/modules/network/aci/aci_interface_policy_l2.py
@ -20,7 +20,7 @@ author:
 - Dag Wieers (@dagwieers)
 version_added: '2.4'
 notes:
- More information from the internal APIC class I(l2:IfPol) at
+- More information about the internal APIC class B(l2:IfPol) at
  U(https://developer.cisco.com/docs/apic-mim-ref/).
 options:
  l2_policy:
--- a/lib/ansible/modules/network/aci/aci_interface_policy_leaf_policy_group.py
+++ b/lib/ansible/modules/network/aci/aci_interface_policy_leaf_policy_group.py
@ -20,7 +20,7 @@ description:
 notes:
 - When using the module please select the appropriate link_aggregation_type (lag_type).
  C(link) for Port Channel(PC), C(node) for Virtual Port Channel(VPC) and C(leaf) for Leaf Access Port Policy Group.
- More information from the internal APIC class I(infra:AccBndlGrp), I(infra:AccPortGrp) at
+- More information about the internal APIC classes B(infra:AccBndlGrp) and B(infra:AccPortGrp) at
  U(https://developer.cisco.com/site/aci/docs/apis/apic-mim-ref/).
 author:
 - Bruno Calogero (@brunocalogero)
--- a/lib/ansible/modules/network/aci/aci_interface_policy_leaf_profile.py
+++ b/lib/ansible/modules/network/aci/aci_interface_policy_leaf_profile.py
@ -18,7 +18,7 @@ short_description: Manage fabric interface policy leaf profiles (infra:AccPortP)
 description:
 - Manage fabric interface policy leaf profiles on Cisco ACI fabrics.
 notes:
- More information from the internal APIC class I(infra:AccPortP) at
+- More information about the internal APIC class B(infra:AccPortP) at
  U(https://developer.cisco.com/docs/apic-mim-ref/).
 author:
 - Bruno Calogero (@brunocalogero)
--- a/lib/ansible/modules/network/aci/aci_interface_policy_lldp.py
+++ b/lib/ansible/modules/network/aci/aci_interface_policy_lldp.py
@ -17,7 +17,7 @@ short_description: Manage LLDP interface policies (lldp:IfPol)
 description:
 - Manage LLDP interface policies on Cisco ACI fabrics.
 notes:
- More information from the internal APIC class I(lldp:IfPol) at
+- More information about the internal APIC class B(lldp:IfPol) at
  U(https://developer.cisco.com/docs/apic-mim-ref/).
 author:
 - Dag Wieers (@dagwieers)
--- a/lib/ansible/modules/network/aci/aci_interface_policy_mcp.py
+++ b/lib/ansible/modules/network/aci/aci_interface_policy_mcp.py
@ -17,7 +17,7 @@ short_description: Manage MCP interface policies (mcp:IfPol)
 description:
 - Manage MCP interface policies on Cisco ACI fabrics.
 notes:
- More information from the internal APIC class I(mcp:IfPol) at
+- More information about the internal APIC class B(mcp:IfPol) at
  U(https://developer.cisco.com/docs/apic-mim-ref/).
 author:
 - Dag Wieers (@dagwieers)
--- a/lib/ansible/modules/network/aci/aci_interface_policy_port_channel.py
+++ b/lib/ansible/modules/network/aci/aci_interface_policy_port_channel.py
@ -17,7 +17,7 @@ short_description: Manage port channel interface policies (lacp:LagPol)
 description:
 - Manage port channel interface policies on Cisco ACI fabrics.
 notes:
- More information from the internal APIC class I(lacp:LagPol) at
+- More information about the internal APIC class B(lacp:LagPol) at
  U(https://developer.cisco.com/docs/apic-mim-ref/).
 author:
 - Dag Wieers (@dagwieers)
--- a/lib/ansible/modules/network/aci/aci_interface_policy_port_security.py
+++ b/lib/ansible/modules/network/aci/aci_interface_policy_port_security.py
@ -17,7 +17,7 @@ short_description: Manage port security (l2:PortSecurityPol)
 description:
 - Manage port security on Cisco ACI fabrics.
 notes:
- More information from the internal APIC class I(l2:PortSecurityPol) at
+- More information about the internal APIC class B(l2:PortSecurityPol) at
  U(https://developer.cisco.com/docs/apic-mim-ref/).
 author:
 - Dag Wieers (@dagwieers)
--- a/lib/ansible/modules/network/aci/aci_interface_selector_to_switch_policy_leaf_profile.py
+++ b/lib/ansible/modules/network/aci/aci_interface_selector_to_switch_policy_leaf_profile.py
@ -19,7 +19,7 @@ description:
 - Bind interface selector profiles to switch policy leaf profiles on Cisco ACI fabrics.
 notes:
 - This module requires an existing leaf profile, the module M(aci_switch_policy_leaf_profile) can be used for this.
- More information from the internal APIC class I(infra:RsAccPortP) at
+- More information about the internal APIC class B(infra:RsAccPortP) at
  U(https://developer.cisco.com/docs/apic-mim-ref/).
 author:
 - Bruno Calogero (@brunocalogero)
--- a/lib/ansible/modules/network/aci/aci_l3out_route_tag_policy.py
+++ b/lib/ansible/modules/network/aci/aci_l3out_route_tag_policy.py
@ -19,7 +19,7 @@ description:
 notes:
 - The C(tenant) used must exist before using this module in your playbook.
  The M(aci_tenant) module can be used for this.
- More information from the internal APIC class I(l3ext:RouteTagPol) at
+- More information about the internal APIC class B(l3ext:RouteTagPol) at
  U(https://developer.cisco.com/docs/apic-mim-ref/).
 author:
 - Dag Wieers (@dagwieers)
--- a/lib/ansible/modules/network/aci/aci_static_binding_to_epg.py
+++ b/lib/ansible/modules/network/aci/aci_static_binding_to_epg.py
@ -20,7 +20,7 @@ description:
 notes:
 - The C(tenant), C(ap), C(epg) used must exist before using this module in your playbook.
  The M(aci_tenant), M(aci_ap), M(aci_epg) modules can be used for this.
- More information from the internal APIC classes I(fv:RsPathAtt) at
+- More information about the internal APIC classes B(fv:RsPathAtt) at
  U(https://developer.cisco.com/docs/apic-mim-ref/).
 author:
 - Bruno Calogero (@brunocalogero)
--- a/lib/ansible/modules/network/aci/aci_switch_leaf_selector.py
+++ b/lib/ansible/modules/network/aci/aci_switch_leaf_selector.py
@ -20,7 +20,7 @@ description:
 notes:
 - This module is to be used with M(aci_switch_policy_leaf_profile)
  One first creates a leaf profile (infra:NodeP) and then creates an associated selector (infra:LeafS),
- More information from the internal APIC class I(infra:LeafS), I(infra:NodeBlk), I(infra:RsAccNodePGrp) at
+- More information about the internal APIC classes B(infra:LeafS), B(infra:NodeBlk) and B(infra:RsAccNodePGrp) at
  U(https://developer.cisco.com/docs/apic-mim-ref/).
 author:
 - Bruno Calogero (@brunocalogero)
--- a/lib/ansible/modules/network/aci/aci_switch_policy_leaf_profile.py
+++ b/lib/ansible/modules/network/aci/aci_switch_policy_leaf_profile.py
@ -18,7 +18,7 @@ short_description: Manage switch policy leaf profiles (infra:NodeP)
 description:
 - Manage switch policy leaf profiles on Cisco ACI fabrics.
 notes:
- More information from the internal APIC class I(infra:NodeP) at
+- More information about the internal APIC class B(infra:NodeP) at
  U(https://developer.cisco.com/docs/apic-mim-ref/).
 author:
 - Bruno Calogero (@brunocalogero)
--- a/lib/ansible/modules/network/aci/aci_switch_policy_vpc_protection_group.py
+++ b/lib/ansible/modules/network/aci/aci_switch_policy_vpc_protection_group.py
@ -18,8 +18,8 @@ short_description: Manage switch policy explicit vPC protection groups (fabric:E
 description:
 - Manage switch policy explicit vPC protection groups on Cisco ACI fabrics.
 notes:
- More information from the internal APIC class
-  I(fabric:ExplicitGEp) and I(fabric:NodePEp) at U(https://developer.cisco.com/site/aci/docs/apis/apic-mim-ref/).
+- More information about the internal APIC classes B(fabric:ExplicitGEp) and B(fabric:NodePEp) at
+  U(https://developer.cisco.com/site/aci/docs/apis/apic-mim-ref/).
 author:
 - Bruno Calogero (@brunocalogero)
 version_added: '2.5'
--- a/lib/ansible/modules/network/aci/aci_taboo_contract.py
+++ b/lib/ansible/modules/network/aci/aci_taboo_contract.py
@ -20,7 +20,7 @@ description:
 notes:
 - The C(tenant) used must exist before using this module in your playbook.
  The M(aci_tenant) module can be used for this.
- More information from the internal APIC class I(vz:BrCP) at
+- More information about the internal APIC class B(vz:BrCP) at
  U(https://developer.cisco.com/docs/apic-mim-ref/).
 author:
 - Dag Wieers (@dagwieers)
--- a/lib/ansible/modules/network/aci/aci_tenant.py
+++ b/lib/ansible/modules/network/aci/aci_tenant.py
@ -17,7 +17,7 @@ short_description: Manage tenants (fv:Tenant)
 description:
 - Manage tenants on Cisco ACI fabrics.
 notes:
- More information from the internal APIC class I(fv:Tenant) at
+- More information about the internal APIC class B(fv:Tenant) at
  U(https://developer.cisco.com/docs/apic-mim-ref/).
 author:
 - Jacob McGill (@jmcgill298)
--- a/lib/ansible/modules/network/aci/aci_tenant_action_rule_profile.py
+++ b/lib/ansible/modules/network/aci/aci_tenant_action_rule_profile.py
@ -19,7 +19,7 @@ description:
 notes:
 - The C(tenant) used must exist before using this module in your playbook.
  The M(aci_tenant) module can be used for this.
- More information from the internal APIC class I(rtctrl:AttrP) at
+- More information about the internal APIC class B(rtctrl:AttrP) at
  U(https://developer.cisco.com/docs/apic-mim-ref/).
 author:
 - Dag Wieers (@dagwieers)
--- a/lib/ansible/modules/network/aci/aci_tenant_ep_retention_policy.py
+++ b/lib/ansible/modules/network/aci/aci_tenant_ep_retention_policy.py
@ -19,7 +19,7 @@ description:
 notes:
 - The C(tenant) used must exist before using this module in your playbook.
  The M(aci_tenant) module can be used for this.
- More information from the internal APIC class I(fv:EpRetPol) at
+- More information about the internal APIC class B(fv:EpRetPol) at
  U(https://developer.cisco.com/docs/apic-mim-ref/).
 author:
 - Swetha Chunduri (@schunduri)
--- a/lib/ansible/modules/network/aci/aci_tenant_span_dst_group.py
+++ b/lib/ansible/modules/network/aci/aci_tenant_span_dst_group.py
@ -19,7 +19,7 @@ description:
 notes:
 - The C(tenant) used must exist before using this module in your playbook.
  The M(aci_tenant) module can be used for this.
- More information from the internal APIC class I(span:DestGrp) at
+- More information about the internal APIC class B(span:DestGrp) at
  U(https://developer.cisco.com/docs/apic-mim-ref/).
 author:
 - Dag Wieers (@dagwieers)
--- a/lib/ansible/modules/network/aci/aci_tenant_span_src_group.py
+++ b/lib/ansible/modules/network/aci/aci_tenant_span_src_group.py
@ -19,7 +19,7 @@ description:
 notes:
 - The C(tenant) used must exist before using this module in your playbook.
  The M(aci_tenant) module can be used for this.
- More information from the internal APIC class I(span:SrcGrp) at
+- More information about the internal APIC class B(span:SrcGrp) at
  U(https://developer.cisco.com/docs/apic-mim-ref/).
 author:
 - Jacob McGill (@jmcgill298)
--- a/lib/ansible/modules/network/aci/aci_tenant_span_src_group_to_dst_group.py
+++ b/lib/ansible/modules/network/aci/aci_tenant_span_src_group_to_dst_group.py
@ -19,7 +19,7 @@ description:
 notes:
 - The C(tenant), C(src_group), and C(dst_group) must exist before using this module in your playbook.
  The M(aci_tenant), M(aci_tenant_span_src_group), and M(aci_tenant_span_dst_group) modules can be used for this.
- More information from the internal APIC class I(span:SrcGrp) at
+- More information about the internal APIC class B(span:SrcGrp) at
  U(https://developer.cisco.com/docs/apic-mim-ref/).
 author:
 - Jacob McGill (@jmcgill298)
--- a/lib/ansible/modules/network/aci/aci_vlan_pool.py
+++ b/lib/ansible/modules/network/aci/aci_vlan_pool.py
@ -19,7 +19,7 @@ short_description: Manage VLAN pools (fvns:VlanInstP)
 description:
 - Manage VLAN pools on Cisco ACI fabrics.
 notes:
- More information from the internal APIC class I(fvns:VlanInstP) at
+- More information about the internal APIC class B(fvns:VlanInstP) at
  U(https://developer.cisco.com/docs/apic-mim-ref/).
 author:
 - Jacob McGill (@jmcgill298)
--- a/lib/ansible/modules/network/aci/aci_vlan_pool_encap_block.py
+++ b/lib/ansible/modules/network/aci/aci_vlan_pool_encap_block.py
@ -20,7 +20,7 @@ description:
 - Manage VLAN encap blocks that are assigned to VLAN pools on Cisco ACI fabrics.
 notes:
 - The C(pool) must exist in order to add or delete a encap block.
- More information from the internal APIC class I(fvns:EncapBlk) at
+- More information about the internal APIC class B(fvns:EncapBlk) at
  U(https://developer.cisco.com/docs/apic-mim-ref/).
 author:
 - Jacob McGill (@jmcgill298)
--- a/lib/ansible/modules/network/aci/aci_vrf.py
+++ b/lib/ansible/modules/network/aci/aci_vrf.py
@ -20,7 +20,7 @@ description:
 notes:
 - The C(tenant) used must exist before using this module in your playbook.
  The M(aci_tenant) module can be used for this.
- More information from the internal APIC class I(fv:Ctx) at
+- More information about the internal APIC class B(fv:Ctx) at
  U(https://developer.cisco.com/docs/apic-mim-ref/).
 author:
 - Jacob McGill (@jmcgill298)
--- a/lib/ansible/utils/module_docs_fragments/aci.py
+++ b/lib/ansible/utils/module_docs_fragments/aci.py
@ -19,7 +19,7 @@ options:
    description:
    - Port number to be used for REST connection.
    type: int
-    default: 443 (for https) and 80 (for http)
+    default: 443 (for https), 80 (for http)
  username:
    description:
    - The username to use for authentication.
@ -29,17 +29,20 @@ options:
  password:
    description:
    - The password to use for authentication.
+    - This option is mutual exclusive with C(private_key). If C(private_key) is provided too, it will be used instead.
    required: yes
  private_key:
    description:
    - PEM formatted file that contains your private key to be used for signature-based authentication.
    - The name of the key (without extension) is used as the certificate name in ACI, unless C(certificate_name) is specified.
+    - This option is mutual exclusive with C(password). If C(password) is provided too, it will be ignored.
+    required: yes
    aliases: [ cert_key ]
  certificate_name:
    description:
    - The X.509 certificate name attached to the APIC AAA user used for signature-based authentication.
    - It defaults to the C(private_key) basename, without extension.
-    default: C(private_key) basename
+    default: private_key basename
    aliases: [ cert_name ]
  output_level:
    description:
@ -67,7 +70,7 @@ options:
  validate_certs:
    description:
    - If C(no), SSL certificates will not be validated.
-    - This should only set to C(no) used on personally controlled sites using self-signed certificates.
+    - This should only set to C(no) when used on personally controlled sites using self-signed certificates.
    type: bool
    default: 'yes'
 notes: