From cc2164f92aecf118407ca60f0cfc9210a8d9f3af Mon Sep 17 00:00:00 2001 From: Dag Wieers Date: Fri, 24 Aug 2018 01:28:39 +0200 Subject: [PATCH] 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. --- .../docsite/rst/scenario_guides/guide_aci.rst | 82 +++++++++++++++++-- lib/ansible/modules/network/aci/aci_rest.py | 2 +- 2 files changed, 76 insertions(+), 8 deletions(-) diff --git a/docs/docsite/rst/scenario_guides/guide_aci.rst b/docs/docsite/rst/scenario_guides/guide_aci.rst index 2c10d26beb..b6e303c97e 100644 --- a/docs/docsite/rst/scenario_guides/guide_aci.rst +++ b/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 ` 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 ``_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 ` A complete list of supported ACI modules. `ACI community `_ 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 `_ The Ansible Network community page, includes contact information and meeting information. `#ansible-network `_ diff --git a/lib/ansible/modules/network/aci/aci_rest.py b/lib/ansible/modules/network/aci/aci_rest.py index 9058665043..31018d9229 100644 --- a/lib/ansible/modules/network/aci/aci_rest.py +++ b/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