ansible/docs/docsite/rst/scenario_guides/guide_infoblox.rst

289 lines
11 KiB
ReStructuredText
Raw Normal View History

.. _nios_guide:
************************
Infoblox Guide
************************
.. contents:: Topics
This guide describes how to use Ansible with the Infoblox Network Identity Operating System (NIOS). With Ansible integration, you can use Ansible playbooks to automate Infoblox Core Network Services for IP address management (IPAM), DNS, and inventory tracking.
You can review simple example tasks in the documentation for any of the :ref:`NIOS modules <nios_net tools_modules>` or look at the `Use cases with modules`_ section for more elaborate examples. See the `Infoblox <https://www.infoblox.com/>`_ website for more information on the Infoblox product.
.. note:: You can retrieve most of the example playbooks used in this guide from the `network-automation/infoblox_ansible <https://github.com/network-automation/infoblox_ansible>`_ GitHub repository.
Prerequisites
=============
Before using Ansible ``nios`` modules with Infoblox, you must install the ``infoblox-client`` on your Ansible control node:
.. code-block:: bash
$ sudo pip install infoblox-client
.. note::
You need an NIOS account with the WAPI feature enabled to use Ansible with Infoblox.
.. _nios_credentials:
Credentials and authenticating
==============================
To use Infoblox ``nios`` modules in playbooks, you need to configure the credentials to access your Infoblox system. The examples in this guide use credentials stored in ``<playbookdir>/group_vars/nios.yml``. Replace these values with your Infoblox credentials:
.. code-block:: yaml
---
nios_provider:
host: 192.0.0.2
username: admin
password: ansible
NIOS lookup plugins
===================
Ansible includes the following lookup plugins for NIOS:
- :ref:`nios <nios_lookup>` Uses the Infoblox WAPI API to fetch NIOS specified objects, for example network views, DNS views, and host records.
- :ref:`nios_next_ip <nios_next_ip_lookup>` Provides the next available IP address from a network. You'll see an example of this in `Creating a host record`_.
- :ref:`nios_next_network <nios_next_network_lookup>` - Returns the next available network range for a network-container.
You must run the NIOS lookup plugins locally by specifying ``connection: local``. See :ref:`lookup plugins <lookup_plugins>` for more detail.
Retrieving all network views
----------------------------
To retrieve all network views and save them in a variable, use the :ref:`set_fact <set_fact_module>` module with the :ref:`nios <nios_lookup>` lookup plugin:
.. code-block:: yaml
---
- hosts: nios
connection: local
tasks:
- name: fetch all networkview objects
set_fact:
networkviews: "{{ lookup('nios', 'networkview', provider=nios_provider) }}"
- name: check the networkviews
debug:
var: networkviews
Retrieving a host record
------------------------
To retrieve a set of host records, use the ``set_fact`` module with the ``nios`` lookup plugin and include a filter for the specific hosts you want to retrieve:
.. code-block:: yaml
---
- hosts: nios
connection: local
tasks:
- name: fetch host leaf01
set_fact:
host: "{{ lookup('nios', 'record:host', filter={'name': 'leaf01.ansible.com'}, provider=nios_provider) }}"
- name: check the leaf01 return variable
debug:
var: host
- name: debug specific variable (ipv4 address)
debug:
var: host.ipv4addrs[0].ipv4addr
- name: fetch host leaf02
set_fact:
host: "{{ lookup('nios', 'record:host', filter={'name': 'leaf02.ansible.com'}, provider=nios_provider) }}"
- name: check the leaf02 return variable
debug:
var: host
If you run this ``get_host_record.yml`` playbook, you should see results similar to the following:
.. code-block:: none
$ ansible-playbook get_host_record.yml
PLAY [localhost] ***************************************************************************************
TASK [fetch host leaf01] ******************************************************************************
ok: [localhost]
TASK [check the leaf01 return variable] *************************************************************
ok: [localhost] => {
< ...output shortened...>
"host": {
"ipv4addrs": [
{
"configure_for_dhcp": false,
"host": "leaf01.ansible.com",
}
],
"name": "leaf01.ansible.com",
"view": "default"
}
}
TASK [debug specific variable (ipv4 address)] ******************************************************
ok: [localhost] => {
"host.ipv4addrs[0].ipv4addr": "192.168.1.11"
}
TASK [fetch host leaf02] ******************************************************************************
ok: [localhost]
TASK [check the leaf02 return variable] *************************************************************
ok: [localhost] => {
< ...output shortened...>
"host": {
"ipv4addrs": [
{
"configure_for_dhcp": false,
"host": "leaf02.example.com",
"ipv4addr": "192.168.1.12"
}
],
}
}
PLAY RECAP ******************************************************************************************
localhost : ok=5 changed=0 unreachable=0 failed=0
The output above shows the host record for ``leaf01.ansible.com`` and ``leaf02.ansible.com`` that were retrieved by the ``nios`` lookup plugin. This playbook saves the information in variables which you can use in other playbooks. This allows you to use Infoblox as a single source of truth to gather and use information that changes dynamically. See :ref:`playbooks_variables` for more information on using Ansible variables. See the :ref:`nios <nios_lookup>` examples for more data options that you can retrieve.
You can access these playbooks at `Infoblox lookup playbooks <https://github.com/network-automation/infoblox_ansible/tree/master/lookup_playbooks>`_.
Use cases with modules
======================
You can use the ``nios`` modules in tasks to simplify common Infoblox workflows. Be sure to set up your :ref:`NIOS credentials<nios_credentials>` before following these examples.
Configuring an IPv4 network
---------------------------
To configure an IPv4 network, use the :ref:`nios_network <nios_network_module>` module:
.. code-block:: yaml
---
- hosts: nios
connection: local
tasks:
- name: Create a network on the default network view
nios_network:
network: 192.168.100.0/24
comment: sets the IPv4 network
options:
- name: domain-name
value: ansible.com
state: present
provider: "{{nios_provider}}"
Notice the last parameter, ``provider``, uses the variable ``nios_provider`` defined in the ``group_vars/`` directory.
Creating a host record
----------------------
To create a host record named `leaf03.ansible.com` on the newly-created IPv4 network:
.. code-block:: yaml
---
- hosts: nios
connection: local
tasks:
- name: configure an IPv4 host record
nios_host_record:
name: leaf03.ansible.com
ipv4addrs:
- ipv4addr:
"{{ lookup('nios_next_ip', '192.168.100.0/24', provider=nios_provider)[0] }}"
state: present
provider: "{{nios_provider}}"
Notice the IPv4 address in this example uses the :ref:`nios_next_ip <nios_next_ip_lookup>` lookup plugin to find the next available IPv4 address on the network.
Creating a forward DNS zone
---------------------------
To configure a forward DNS zone use, the ``nios_zone`` module:
.. code-block:: yaml
---
- hosts: nios
connection: local
tasks:
- name: Create a forward DNS zone called ansible-test.com
nios_zone:
name: ansible-test.com
comment: local DNS zone
state: present
provider: "{{ nios_provider }}"
Creating a reverse DNS zone
---------------------------
To configure a reverse DNS zone:
.. code-block:: yaml
---
- hosts: nios
connection: local
tasks:
- name: configure a reverse mapping zone on the system using IPV6 zone format
nios_zone:
name: 100::1/128
zone_format: IPV6
state: present
provider: "{{ nios_provider }}"
Dynamic inventory script
========================
You can use the Infoblox dynamic inventory script to import your network node inventory with Infoblox NIOS. To gather the inventory from Infoblox, you need two files:
[backport][docs][2.10]Docsbackportapalooza 8 (#71379) * Move 2.10.0rc1 release date a few days forward. (#71270) At yesterday's meeting it was decided to have ansible-2.10.0 depend on ansible-base-2.10.1 so that we can get several fixes for ansible-base's routing (including adding the gluster.gluster collection). ansible-base-2.10.1 will release on September 8th. So we will plan on releasing ansible-2.10.0rc1 on the 10th. https://meetbot.fedoraproject.org/ansible-community/2020-08-12/ansible_community_meeting.2020-08-12-18.00.html (cherry picked from commit e507c127e58791755d207b46f6c829dacd7ad55c) * a few writing style updates (#71212) (cherry picked from commit 4f0bd5de38fb72c4aa686fa8736a3d8cc75393c0) * Fix code markups and add link to CVE (#71082) (cherry picked from commit 92d59a58c09f2a8baf811abe1beb09e4f911eb54) * Fix 404 links (#71256) Signed-off-by: Abhijeet Kasurde <akasurde@redhat.com> (cherry picked from commit ecea0185064b4ce8932917702a84962a75280fcf) * Writing style updates to Developing dynamic inventory topic (#71245) * modified the writing style * incorporated peer feedback (cherry picked from commit ecd3b52ad7e0dbe9042b71b2e22b33e5cef79141) * Fix roadmap formatting. (#71275) (cherry picked from commit ee48e0b0ad33dab245ff6a64f3ac0344de06ae56) * Update password.py (#71295) List md5_crypt, bcrypt, sha256_crypt, sha512_crypt as hash schemes in the password plugin. (cherry picked from commit 1d1de2c6fd2231a88b494574eba7f4d3fd7ba5b5) * Update ansible european IRC channel (#71326) Signed-off-by: Rémi VERCHERE <remi@verchere.fr> (cherry picked from commit 824cd4cbeb0a576bcd9b8a118c1f9fdcc7816ce1) * Add warning about copyright year change (#71251) To simplify project administration and avoid any legal issues, add a warning in the docs. This reflects - https://github.com/ansible/ansible/issues/45989#issuecomment-423635622 and fixes: #45989 Signed-off-by: Abhijeet Kasurde <akasurde@redhat.com> (cherry picked from commit 606604bb97ab7ab94b42a53669f09c51f7e4d818) * subelements: Clarify parameter docs (#71177) skip_missing parameter in subelements lookup plugin is accepted from inside the dictionary. Fixes: #38182 Signed-off-by: Abhijeet Kasurde <akasurde@redhat.com> (cherry picked from commit 6d17736ef45cbb81bdcbafd5b52dc45f75535baf) * Writing style updates to Using Variables topic (#71194) * updated topic title, underline length for headings, and incorporated peer feedback (cherry picked from commit 4d68efbe248cdf75b4a9d87c9a04bd19db81a1d1) * cron module defaults to current user, not root (#71337) (cherry picked from commit 4792d83e13d7622832e3885ffa2d3d0e543d42b6) * Update Network Getting Started for FQCN/collection world (#71188) * pull out network roles, cleanup, update first playbook examples, update gather facts section, some inventory conversion to .yml, update inventory and roles, simplify the navigation titles, fix tocs, feedback comments (cherry picked from commit f79a7c558574a44016d2ff978aaddf00f241a08c) * Add documentation about info/facts module development (#71250) Fixes: #40151 Signed-off-by: Abhijeet Kasurde <akasurde@redhat.com> (cherry picked from commit 4f993922c87a6f12821f40c460750471bd6ee1e7) * network: Correct documentation (#71246) ini-style inventory does not support Ansible Vault password. This fixes network_best_practices_2.5 doc. Fixes: #69039 Signed-off-by: Abhijeet Kasurde <akasurde@redhat.com> (cherry picked from commit a1257d75aa2f874ea2768dd99c4affe8b37a886f) * tidies up vars page (#71339) (cherry picked from commit 02ea80f6d77f03ebb06ac78efc4bff183afe3c6e) * base.yml: Fix typos (#71346) (cherry picked from commit 41d7d53573e4f1bf366299b7f1eff15d6643c7ab) * quick fix to change main back to devel (#71342) * quick fix to change main back to devel * Update docs/docsite/rst/dev_guide/developing_collections.rst Co-authored-by: Felix Fontein <felix@fontein.de> (cherry picked from commit 74f88c56a515d7edbc2c0572ad56c367a3775fd0) * Add note about integration tests for new modules to the dev guide (#71345) (cherry picked from commit b82889eef550cbb4074859b9fa0c38b6c04f56f1) * update fest link (#71376) (cherry picked from commit 80b8fde94652ba5a183a8dd3df64c1780a86c57d) * incorporate minimalism feedback on debugging page (#71272) Co-authored-by: bobjohnsrh <50667510+bobjohnsrh@users.noreply.github.com> (cherry picked from commit 5073cfc8bc0dbd3c8796e460891aee971921faa2) * fix header problem Co-authored-by: Toshio Kuratomi <a.badger@gmail.com> Co-authored-by: Sayee <57951841+sayee-jadhav@users.noreply.github.com> Co-authored-by: Baptiste Mille-Mathias <baptiste.millemathias@gmail.com> Co-authored-by: Abhijeet Kasurde <akasurde@redhat.com> Co-authored-by: Felix Fontein <felix@fontein.de> Co-authored-by: rovshango <rovshan.go@gmail.com> Co-authored-by: Remi Verchere <rverchere@users.noreply.github.com> Co-authored-by: Jake Howard <RealOrangeOne@users.noreply.github.com> Co-authored-by: Alicia Cozine <879121+acozine@users.noreply.github.com> Co-authored-by: Per Lundberg <perlun@gmail.com> Co-authored-by: Andrew Klychkov <aaklychkov@mail.ru>
2020-08-21 00:44:50 +02:00
- `infoblox.yaml <https://raw.githubusercontent.com/ansible-collections/community.general/main/scripts/inventory/infoblox.yaml>`_ - A file that specifies the NIOS provider arguments and optional filters.
[backport][docs][2.10]Docsbackportapalooza 8 (#71379) * Move 2.10.0rc1 release date a few days forward. (#71270) At yesterday's meeting it was decided to have ansible-2.10.0 depend on ansible-base-2.10.1 so that we can get several fixes for ansible-base's routing (including adding the gluster.gluster collection). ansible-base-2.10.1 will release on September 8th. So we will plan on releasing ansible-2.10.0rc1 on the 10th. https://meetbot.fedoraproject.org/ansible-community/2020-08-12/ansible_community_meeting.2020-08-12-18.00.html (cherry picked from commit e507c127e58791755d207b46f6c829dacd7ad55c) * a few writing style updates (#71212) (cherry picked from commit 4f0bd5de38fb72c4aa686fa8736a3d8cc75393c0) * Fix code markups and add link to CVE (#71082) (cherry picked from commit 92d59a58c09f2a8baf811abe1beb09e4f911eb54) * Fix 404 links (#71256) Signed-off-by: Abhijeet Kasurde <akasurde@redhat.com> (cherry picked from commit ecea0185064b4ce8932917702a84962a75280fcf) * Writing style updates to Developing dynamic inventory topic (#71245) * modified the writing style * incorporated peer feedback (cherry picked from commit ecd3b52ad7e0dbe9042b71b2e22b33e5cef79141) * Fix roadmap formatting. (#71275) (cherry picked from commit ee48e0b0ad33dab245ff6a64f3ac0344de06ae56) * Update password.py (#71295) List md5_crypt, bcrypt, sha256_crypt, sha512_crypt as hash schemes in the password plugin. (cherry picked from commit 1d1de2c6fd2231a88b494574eba7f4d3fd7ba5b5) * Update ansible european IRC channel (#71326) Signed-off-by: Rémi VERCHERE <remi@verchere.fr> (cherry picked from commit 824cd4cbeb0a576bcd9b8a118c1f9fdcc7816ce1) * Add warning about copyright year change (#71251) To simplify project administration and avoid any legal issues, add a warning in the docs. This reflects - https://github.com/ansible/ansible/issues/45989#issuecomment-423635622 and fixes: #45989 Signed-off-by: Abhijeet Kasurde <akasurde@redhat.com> (cherry picked from commit 606604bb97ab7ab94b42a53669f09c51f7e4d818) * subelements: Clarify parameter docs (#71177) skip_missing parameter in subelements lookup plugin is accepted from inside the dictionary. Fixes: #38182 Signed-off-by: Abhijeet Kasurde <akasurde@redhat.com> (cherry picked from commit 6d17736ef45cbb81bdcbafd5b52dc45f75535baf) * Writing style updates to Using Variables topic (#71194) * updated topic title, underline length for headings, and incorporated peer feedback (cherry picked from commit 4d68efbe248cdf75b4a9d87c9a04bd19db81a1d1) * cron module defaults to current user, not root (#71337) (cherry picked from commit 4792d83e13d7622832e3885ffa2d3d0e543d42b6) * Update Network Getting Started for FQCN/collection world (#71188) * pull out network roles, cleanup, update first playbook examples, update gather facts section, some inventory conversion to .yml, update inventory and roles, simplify the navigation titles, fix tocs, feedback comments (cherry picked from commit f79a7c558574a44016d2ff978aaddf00f241a08c) * Add documentation about info/facts module development (#71250) Fixes: #40151 Signed-off-by: Abhijeet Kasurde <akasurde@redhat.com> (cherry picked from commit 4f993922c87a6f12821f40c460750471bd6ee1e7) * network: Correct documentation (#71246) ini-style inventory does not support Ansible Vault password. This fixes network_best_practices_2.5 doc. Fixes: #69039 Signed-off-by: Abhijeet Kasurde <akasurde@redhat.com> (cherry picked from commit a1257d75aa2f874ea2768dd99c4affe8b37a886f) * tidies up vars page (#71339) (cherry picked from commit 02ea80f6d77f03ebb06ac78efc4bff183afe3c6e) * base.yml: Fix typos (#71346) (cherry picked from commit 41d7d53573e4f1bf366299b7f1eff15d6643c7ab) * quick fix to change main back to devel (#71342) * quick fix to change main back to devel * Update docs/docsite/rst/dev_guide/developing_collections.rst Co-authored-by: Felix Fontein <felix@fontein.de> (cherry picked from commit 74f88c56a515d7edbc2c0572ad56c367a3775fd0) * Add note about integration tests for new modules to the dev guide (#71345) (cherry picked from commit b82889eef550cbb4074859b9fa0c38b6c04f56f1) * update fest link (#71376) (cherry picked from commit 80b8fde94652ba5a183a8dd3df64c1780a86c57d) * incorporate minimalism feedback on debugging page (#71272) Co-authored-by: bobjohnsrh <50667510+bobjohnsrh@users.noreply.github.com> (cherry picked from commit 5073cfc8bc0dbd3c8796e460891aee971921faa2) * fix header problem Co-authored-by: Toshio Kuratomi <a.badger@gmail.com> Co-authored-by: Sayee <57951841+sayee-jadhav@users.noreply.github.com> Co-authored-by: Baptiste Mille-Mathias <baptiste.millemathias@gmail.com> Co-authored-by: Abhijeet Kasurde <akasurde@redhat.com> Co-authored-by: Felix Fontein <felix@fontein.de> Co-authored-by: rovshango <rovshan.go@gmail.com> Co-authored-by: Remi Verchere <rverchere@users.noreply.github.com> Co-authored-by: Jake Howard <RealOrangeOne@users.noreply.github.com> Co-authored-by: Alicia Cozine <879121+acozine@users.noreply.github.com> Co-authored-by: Per Lundberg <perlun@gmail.com> Co-authored-by: Andrew Klychkov <aaklychkov@mail.ru>
2020-08-21 00:44:50 +02:00
- `infoblox.py <https://raw.githubusercontent.com/ansible-collections/community.general/main/scripts/inventory/infoblox.py>`_ - The python script that retrieves the NIOS inventory.
To use the Infoblox dynamic inventory script:
#. Download the ``infoblox.yaml`` file and save it in the ``/etc/ansible`` directory.
#. Modify the ``infoblox.yaml`` file with your NIOS credentials.
#. Download the ``infoblox.py`` file and save it in the ``/etc/ansible/hosts`` directory.
#. Change the permissions on the ``infoblox.py`` file to make the file an executable:
.. code-block:: bash
$ sudo chmod +x /etc/ansible/hosts/infoblox.py
You can optionally use ``./infoblox.py --list`` to test the script. After a few minutes, you should see your Infoblox inventory in JSON format. You can explicitly use the Infoblox dynamic inventory script as follows:
.. code-block:: bash
$ ansible -i infoblox.py all -m ping
You can also implicitly use the Infoblox dynamic inventory script by including it in your inventory directory (``etc/ansible/hosts`` by default). See :ref:`dynamic_inventory` for more details.
.. seealso::
`Infoblox website <https://www.infoblox.com//>`_
The Infoblox website
`Infoblox and Ansible Deployment Guide <https://www.infoblox.com/resources/deployment-guides/infoblox-and-ansible-integration>`_
The deployment guide for Ansible integration provided by Infoblox.
`Infoblox Integration in Ansible 2.5 <https://www.ansible.com/blog/infoblox-integration-in-ansible-2.5>`_
Ansible blog post about Infoblox.
:ref:`Ansible NIOS modules <nios_net tools_modules>`
The list of supported NIOS modules, with examples.
`Infoblox Ansible Examples <https://github.com/network-automation/infoblox_ansible>`_
Infoblox example playbooks.