ACI: Add specific info about running locally (#43903)

Since the ACI modules (like most network-related modules) run on the
local controller, this PR adds the necessary details so users are aware
of this particular feature.

docs/docsite/rst/scenario_guides/guide_aci.rst

@@ -82,6 +82,7 @@ A module can also be used to query a specific object.
     
         tenant: customer-xyz
         state: query
+      register: my_tenant
 
 Or query all objects.
 
@@ -99,6 +100,73 @@ Or query all objects.
 After registering the return values of the :ref:`aci_tenant <aci_tenant_module>` task as shown above, you can access all tenant information from variable ``all_tenants``.
 
 
+Running on the controller locally
+---------------------------------
+As originally designed, Ansible modules are shipped to and run on the remote target(s), however the ACI modules (like most network-related modules) do not run on the network devices or controller (in this case the APIC), but they talk directly to the APIC's REST interface.
+
+For this very reason, the modules need to run on the local Ansible controller (or are delegated to another system that *can* connect to the APIC).
+
+
+Delegating to localhost
+.......................
+So let us assume we have our target configured in the inventory using the FQDN name as the ``ansible_host`` value, as shown below.
+
+.. code-block:: yaml
+
+    apics:
+      my-apic-1:
+        ansible_host: apic01.fqdn.intra
+        ansible_user: admin
+        ansible_pass: my-password
+
+One way to set this up is to add to every task the directive: ``delegate_to: localhost``.
+
+.. code-block:: yaml
+
+    - name: Query all tenants
+      aci_tenant:
+        host: '{{ ansible_host }}'
+        username: '{{ ansible_user }}'
+        password: '{{ ansible_pass }}'
+    
+        state: query
+      delegate_to: localhost
+      register: all_tenants
+
+If one would forget to add this directive, Ansible will attempt to connect to the APIC using SSH and attempt to copy the module and run it remotely. This will fail with a clear error, yet may be confusing to some.
+
+
+Using the local connection method
+.................................
+Another option frequently used, is to tie the ``local`` connection method to this target so that every subsequent task for this target will use the local connection method (hence run it locally, rather than use SSH).
+
+In this case the inventory may look like this:
+
+.. code-block:: yaml
+
+    apics:
+      my-apic-1:
+        ansible_host: apic01.fqdn.intra
+        ansible_user: admin
+        ansible_pass: my-password
+        ansible_connection: local
+
+But used tasks do not need anything special added.
+
+.. code-block:: yaml
+
+    - name: Query all tenants
+      aci_tenant:
+        host: '{{ ansible_host }}'
+        username: '{{ ansible_user }}'
+        password: '{{ ansible_pass }}'
+    
+        state: query
+      register: all_tenants
+
+.. hint:: For clarity we have added ``delegate_to: localhost`` to all the examples in the module documentation. This helps to ensure first-time users can easily copy&paste parts and make them work with a minimum of effort.
+
+
 Common parameters
 .................
 Every Ansible ACI module accepts the following parameters that influence the module's communication with the APIC REST API:
@@ -141,9 +209,9 @@ Proxy support
 .............
 By default, if an environment variable ``<protocol>_proxy`` is set on the target host, requests will be sent through that proxy. This behaviour can be overridden by setting a variable for this task (see :ref:`playbooks_environment`), or by using the ``use_proxy`` module parameter.
 
-HTTP redirects can redirect from HTTP to HTTPS so you should be sure that your proxy environment for both protocols is correct.
+HTTP redirects can redirect from HTTP to HTTPS so ensure that the proxy environment for both protocols is correctly configured.
 
-If you don't need proxy support, but the system may have it configured nevertheless, you can add this parameter setting: ``use_proxy: no`` to avoid accidental proxy usage.
+If proxy support is not needed, but the system may have it configured nevertheless, use the parameter ``use_proxy: no`` to avoid accidental system proxy usage.
 
 .. hint:: Selective proxy support using the ``no_proxy`` environment variable is also supported.
 
@@ -398,7 +466,7 @@ 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 }}'
+        host: my-apic-1
         private_key: pki/admin.key
         method: get
         path: /api/node/class/topSystem.json?query-target-filter=eq(topSystem.role,"controller")
@@ -416,7 +484,7 @@ 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 }}'
+        host: my-apic-1
         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")
@@ -488,17 +556,17 @@ ACI Ansible community
 ---------------------
 If you have specific issues with the ACI modules, or a feature request, or you like to contribute to the ACI project by proposing changes or documentation updates, look at the Ansible Community wiki ACI page at: https://github.com/ansible/community/wiki/Network:-ACI
 
-You will find our roadmap, an overview of open ACI issues and pull-requests and more information about who we are. If you have an interest in using ACI with Ansible, feel free to join ! We occasionally meet online to track progress and prepare for new Ansible releases.
+You will find our roadmap, an overview of open ACI issues and pull-requests, and more information about who we are. If you have an interest in using ACI with Ansible, feel free to join! We occasionally meet online to track progress and prepare for new Ansible releases.
 
 
 .. seealso::
 
-   :ref:`network_guide`
-       A detailed guide on how to use Ansible for automating network infrastructure.
    :ref:`List of ACI modules <aci_network_modules>`
        A complete list of supported ACI modules.
    `ACI community <https://github.com/ansible/community/wiki/Network:-ACI>`_
        The Ansible ACI community wiki page, includes roadmap, ideas and development documentation.
+   :ref:`network_guide`
+       A detailed guide on how to use Ansible for automating network infrastructure.
    `Network Working Group <https://github.com/ansible/community/tree/master/group-network>`_
        The Ansible Network community page, includes contact information and meeting information.
    `#ansible-network <https://webchat.freenode.net/?channels=ansible-network>`_

lib/ansible/modules/network/aci/aci_rest.py

@@ -69,7 +69,7 @@ extends_documentation_fragment: aci
 '''
 
 EXAMPLES = r'''
-- name: Add a tenant using certifcate authentication
+- name: Add a tenant using certificate authentication
   aci_rest:
     host: apic
     username: admin