.. Document meta

:orphan:

.. Anchors

.. _ansible_collections.netbox.netbox.netbox_ip_address_module:

.. Anchors: short name for ansible.builtin

.. Anchors: aliases



.. Title

netbox.netbox.netbox_ip_address -- Creates or removes IP addresses from Netbox
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

.. Collection note

.. note::
    This plugin is part of the `netbox.netbox collection <https://galaxy.ansible.com/netbox/netbox>`_.

    To install it use: :code:`ansible-galaxy collection install netbox.netbox`.

    To use it in a playbook, specify: :code:`netbox.netbox.netbox_ip_address`.

.. version_added

.. versionadded:: 0.1.0 of 

.. contents::
   :local:
   :depth: 1

.. Deprecated


Synopsis
--------

.. Description

- Creates or removes IP addresses from Netbox

.. Aliases


.. Requirements

Requirements
------------
The below requirements are needed on the host that executes this module.

- pynetbox


.. Options

Parameters
----------

.. raw:: html

    <table  border=0 cellpadding=0 class="documentation-table">
        <tr>
            <th colspan="3">Parameter</th>
            <th>Choices/<font color="blue">Defaults</font></th>
                        <th width="100%">Comments</th>
        </tr>
                    <tr>
                                                                <td colspan="3">
                    <div class="ansibleOptionAnchor" id="parameter-data"></div>
                    <b>data</b>
                    <a class="ansibleOptionLink" href="#parameter-data" title="Permalink to this option"></a>
                    <div style="font-size: small">
                        <span style="color: purple">dictionary</span>
                                                 / <span style="color: red">required</span>                    </div>
                                                        </td>
                                <td>
                                                                                                                                                            </td>
                                                                <td>
                                            <div>Defines the IP address configuration</div>
                                                        </td>
            </tr>
                                        <tr>
                                                    <td class="elbow-placeholder"></td>
                                                <td colspan="2">
                    <div class="ansibleOptionAnchor" id="parameter-data/address"></div>
                    <b>address</b>
                    <a class="ansibleOptionLink" href="#parameter-data/address" title="Permalink to this option"></a>
                    <div style="font-size: small">
                        <span style="color: purple">string</span>
                                                                    </div>
                                                        </td>
                                <td>
                                                                                                                                                            </td>
                                                                <td>
                                            <div>Required if state is <code>present</code></div>
                                                        </td>
            </tr>
                                <tr>
                                                    <td class="elbow-placeholder"></td>
                                                <td colspan="2">
                    <div class="ansibleOptionAnchor" id="parameter-data/assigned_object"></div>
                    <b>assigned_object</b>
                    <a class="ansibleOptionLink" href="#parameter-data/assigned_object" title="Permalink to this option"></a>
                    <div style="font-size: small">
                        <span style="color: purple">dictionary</span>
                                                                    </div>
                                                        </td>
                                <td>
                                                                                                                                                            </td>
                                                                <td>
                                            <div>Definition of the assigned object.</div>
                                                        </td>
            </tr>
                                        <tr>
                                                    <td class="elbow-placeholder"></td>
                                    <td class="elbow-placeholder"></td>
                                                <td colspan="1">
                    <div class="ansibleOptionAnchor" id="parameter-data/assigned_object/device"></div>
                    <b>device</b>
                    <a class="ansibleOptionLink" href="#parameter-data/assigned_object/device" title="Permalink to this option"></a>
                    <div style="font-size: small">
                        <span style="color: purple">string</span>
                                                                    </div>
                                                        </td>
                                <td>
                                                                                                                                                            </td>
                                                                <td>
                                            <div>The device the interface is attached to.</div>
                                                        </td>
            </tr>
                                <tr>
                                                    <td class="elbow-placeholder"></td>
                                    <td class="elbow-placeholder"></td>
                                                <td colspan="1">
                    <div class="ansibleOptionAnchor" id="parameter-data/assigned_object/name"></div>
                    <b>name</b>
                    <a class="ansibleOptionLink" href="#parameter-data/assigned_object/name" title="Permalink to this option"></a>
                    <div style="font-size: small">
                        <span style="color: purple">string</span>
                                                                    </div>
                                                        </td>
                                <td>
                                                                                                                                                            </td>
                                                                <td>
                                            <div>The name of the interface</div>
                                                        </td>
            </tr>
                                <tr>
                                                    <td class="elbow-placeholder"></td>
                                    <td class="elbow-placeholder"></td>
                                                <td colspan="1">
                    <div class="ansibleOptionAnchor" id="parameter-data/assigned_object/virtual_machine"></div>
                    <b>virtual_machine</b>
                    <a class="ansibleOptionLink" href="#parameter-data/assigned_object/virtual_machine" title="Permalink to this option"></a>
                    <div style="font-size: small">
                        <span style="color: purple">string</span>
                                                                    </div>
                                                        </td>
                                <td>
                                                                                                                                                            </td>
                                                                <td>
                                            <div>The virtual machine the interface is attached to.</div>
                                                        </td>
            </tr>
                    
                                <tr>
                                                    <td class="elbow-placeholder"></td>
                                                <td colspan="2">
                    <div class="ansibleOptionAnchor" id="parameter-data/custom_fields"></div>
                    <b>custom_fields</b>
                    <a class="ansibleOptionLink" href="#parameter-data/custom_fields" title="Permalink to this option"></a>
                    <div style="font-size: small">
                        <span style="color: purple">dictionary</span>
                                                                    </div>
                                                        </td>
                                <td>
                                                                                                                                                            </td>
                                                                <td>
                                            <div>must exist in Netbox</div>
                                                        </td>
            </tr>
                                <tr>
                                                    <td class="elbow-placeholder"></td>
                                                <td colspan="2">
                    <div class="ansibleOptionAnchor" id="parameter-data/description"></div>
                    <b>description</b>
                    <a class="ansibleOptionLink" href="#parameter-data/description" title="Permalink to this option"></a>
                    <div style="font-size: small">
                        <span style="color: purple">string</span>
                                                                    </div>
                                                        </td>
                                <td>
                                                                                                                                                            </td>
                                                                <td>
                                            <div>The description of the interface</div>
                                                        </td>
            </tr>
                                <tr>
                                                    <td class="elbow-placeholder"></td>
                                                <td colspan="2">
                    <div class="ansibleOptionAnchor" id="parameter-data/dns_name"></div>
                    <b>dns_name</b>
                    <a class="ansibleOptionLink" href="#parameter-data/dns_name" title="Permalink to this option"></a>
                    <div style="font-size: small">
                        <span style="color: purple">string</span>
                                                                    </div>
                                                        </td>
                                <td>
                                                                                                                                                            </td>
                                                                <td>
                                            <div>Hostname or FQDN</div>
                                                        </td>
            </tr>
                                <tr>
                                                    <td class="elbow-placeholder"></td>
                                                <td colspan="2">
                    <div class="ansibleOptionAnchor" id="parameter-data/family"></div>
                    <b>family</b>
                    <a class="ansibleOptionLink" href="#parameter-data/family" title="Permalink to this option"></a>
                    <div style="font-size: small">
                        <span style="color: purple">integer</span>
                                                                    </div>
                                                        </td>
                                <td>
                                                                                                                            <ul style="margin: 0; padding: 0"><b>Choices:</b>
                                                                                                                                                                <li>4</li>
                                                                                                                                                                                                <li>6</li>
                                                                                    </ul>
                                                                            </td>
                                                                <td>
                                            <div>Specifies with address family the IP address belongs to</div>
                                                        </td>
            </tr>
                                <tr>
                                                    <td class="elbow-placeholder"></td>
                                                <td colspan="2">
                    <div class="ansibleOptionAnchor" id="parameter-data/interface"></div>
                    <b>interface</b>
                    <a class="ansibleOptionLink" href="#parameter-data/interface" title="Permalink to this option"></a>
                    <div style="font-size: small">
                        <span style="color: purple">raw</span>
                                                                    </div>
                                                        </td>
                                <td>
                                                                                                                                                            </td>
                                                                <td>
                                            <div>The name and device of the interface that the IP address should be assigned to
    Required if state is <code>present</code> and a prefix specified.</div>
                                                        </td>
            </tr>
                                <tr>
                                                    <td class="elbow-placeholder"></td>
                                                <td colspan="2">
                    <div class="ansibleOptionAnchor" id="parameter-data/nat_inside"></div>
                    <b>nat_inside</b>
                    <a class="ansibleOptionLink" href="#parameter-data/nat_inside" title="Permalink to this option"></a>
                    <div style="font-size: small">
                        <span style="color: purple">raw</span>
                                                                    </div>
                                                        </td>
                                <td>
                                                                                                                                                            </td>
                                                                <td>
                                            <div>The inside IP address this IP is assigned to</div>
                                                        </td>
            </tr>
                                <tr>
                                                    <td class="elbow-placeholder"></td>
                                                <td colspan="2">
                    <div class="ansibleOptionAnchor" id="parameter-data/prefix"></div>
                    <b>prefix</b>
                    <a class="ansibleOptionLink" href="#parameter-data/prefix" title="Permalink to this option"></a>
                    <div style="font-size: small">
                        <span style="color: purple">raw</span>
                                                                    </div>
                                                        </td>
                                <td>
                                                                                                                                                            </td>
                                                                <td>
                                            <div>With state <code>present</code>, if an interface is given, it will ensure
    that an IP inside this prefix (and vrf, if given) is attached
    to this interface. Otherwise, it will get the next available IP
    of this prefix and attach it.
    With state <code>new</code>, it will force to get the next available IP in
    this prefix. If an interface is given, it will also force to attach
    it.
    Required if state is <code>present</code> or <code>new</code> when no address is given.
    Unused if an address is specified.</div>
                                                        </td>
            </tr>
                                <tr>
                                                    <td class="elbow-placeholder"></td>
                                                <td colspan="2">
                    <div class="ansibleOptionAnchor" id="parameter-data/role"></div>
                    <b>role</b>
                    <a class="ansibleOptionLink" href="#parameter-data/role" title="Permalink to this option"></a>
                    <div style="font-size: small">
                        <span style="color: purple">string</span>
                                                                    </div>
                                                        </td>
                                <td>
                                                                                                                            <ul style="margin: 0; padding: 0"><b>Choices:</b>
                                                                                                                                                                <li>Loopback</li>
                                                                                                                                                                                                <li>Secondary</li>
                                                                                                                                                                                                <li>Anycast</li>
                                                                                                                                                                                                <li>VIP</li>
                                                                                                                                                                                                <li>VRRP</li>
                                                                                                                                                                                                <li>HSRP</li>
                                                                                                                                                                                                <li>GLBP</li>
                                                                                                                                                                                                <li>CARP</li>
                                                                                    </ul>
                                                                            </td>
                                                                <td>
                                            <div>The role of the IP address</div>
                                                        </td>
            </tr>
                                <tr>
                                                    <td class="elbow-placeholder"></td>
                                                <td colspan="2">
                    <div class="ansibleOptionAnchor" id="parameter-data/status"></div>
                    <b>status</b>
                    <a class="ansibleOptionLink" href="#parameter-data/status" title="Permalink to this option"></a>
                    <div style="font-size: small">
                        <span style="color: purple">raw</span>
                                                                    </div>
                                                        </td>
                                <td>
                                                                                                                                                            </td>
                                                                <td>
                                            <div>The status of the IP address</div>
                                                        </td>
            </tr>
                                <tr>
                                                    <td class="elbow-placeholder"></td>
                                                <td colspan="2">
                    <div class="ansibleOptionAnchor" id="parameter-data/tags"></div>
                    <b>tags</b>
                    <a class="ansibleOptionLink" href="#parameter-data/tags" title="Permalink to this option"></a>
                    <div style="font-size: small">
                        <span style="color: purple">list</span>
                         / <span style="color: purple">elements=string</span>                                            </div>
                                                        </td>
                                <td>
                                                                                                                                                            </td>
                                                                <td>
                                            <div>Any tags that the IP address may need to be associated with</div>
                                                        </td>
            </tr>
                                <tr>
                                                    <td class="elbow-placeholder"></td>
                                                <td colspan="2">
                    <div class="ansibleOptionAnchor" id="parameter-data/tenant"></div>
                    <b>tenant</b>
                    <a class="ansibleOptionLink" href="#parameter-data/tenant" title="Permalink to this option"></a>
                    <div style="font-size: small">
                        <span style="color: purple">raw</span>
                                                                    </div>
                                                        </td>
                                <td>
                                                                                                                                                            </td>
                                                                <td>
                                            <div>The tenant that the device will be assigned to</div>
                                                        </td>
            </tr>
                                <tr>
                                                    <td class="elbow-placeholder"></td>
                                                <td colspan="2">
                    <div class="ansibleOptionAnchor" id="parameter-data/vrf"></div>
                    <b>vrf</b>
                    <a class="ansibleOptionLink" href="#parameter-data/vrf" title="Permalink to this option"></a>
                    <div style="font-size: small">
                        <span style="color: purple">raw</span>
                                                                    </div>
                                                        </td>
                                <td>
                                                                                                                                                            </td>
                                                                <td>
                                            <div>VRF that IP address is associated with</div>
                                                        </td>
            </tr>
                    
                                <tr>
                                                                <td colspan="3">
                    <div class="ansibleOptionAnchor" id="parameter-netbox_token"></div>
                    <b>netbox_token</b>
                    <a class="ansibleOptionLink" href="#parameter-netbox_token" title="Permalink to this option"></a>
                    <div style="font-size: small">
                        <span style="color: purple">string</span>
                                                 / <span style="color: red">required</span>                    </div>
                                                        </td>
                                <td>
                                                                                                                                                            </td>
                                                                <td>
                                            <div>The token created within Netbox to authorize API access</div>
                                                        </td>
            </tr>
                                <tr>
                                                                <td colspan="3">
                    <div class="ansibleOptionAnchor" id="parameter-netbox_url"></div>
                    <b>netbox_url</b>
                    <a class="ansibleOptionLink" href="#parameter-netbox_url" title="Permalink to this option"></a>
                    <div style="font-size: small">
                        <span style="color: purple">string</span>
                                                 / <span style="color: red">required</span>                    </div>
                                                        </td>
                                <td>
                                                                                                                                                            </td>
                                                                <td>
                                            <div>URL of the Netbox instance resolvable by Ansible control host</div>
                                                        </td>
            </tr>
                                <tr>
                                                                <td colspan="3">
                    <div class="ansibleOptionAnchor" id="parameter-query_params"></div>
                    <b>query_params</b>
                    <a class="ansibleOptionLink" href="#parameter-query_params" title="Permalink to this option"></a>
                    <div style="font-size: small">
                        <span style="color: purple">list</span>
                         / <span style="color: purple">elements=string</span>                                            </div>
                                                        </td>
                                <td>
                                                                                                                                                            </td>
                                                                <td>
                                            <div>This can be used to override the specified values in ALLOWED_QUERY_PARAMS that is defined</div>
                                            <div>in plugins/module_utils/netbox_utils.py and provides control to users on what may make</div>
                                            <div>an object unique in their environment.</div>
                                                        </td>
            </tr>
                                <tr>
                                                                <td colspan="3">
                    <div class="ansibleOptionAnchor" id="parameter-state"></div>
                    <b>state</b>
                    <a class="ansibleOptionLink" href="#parameter-state" title="Permalink to this option"></a>
                    <div style="font-size: small">
                        <span style="color: purple">string</span>
                                                                    </div>
                                                        </td>
                                <td>
                                                                                                                            <ul style="margin: 0; padding: 0"><b>Choices:</b>
                                                                                                                                                                <li>absent</li>
                                                                                                                                                                                                <li>new</li>
                                                                                                                                                                                                <li><div style="color: blue"><b>present</b>&nbsp;&larr;</div></li>
                                                                                    </ul>
                                                                            </td>
                                                                <td>
                                            <div>Use <code>present</code>, <code>new</code> or <code>absent</code> for adding, force adding or removing.
    <code>present</code> will check if the IP is already created, and return it if
    true. <code>new</code> will force to create it anyway (useful for anycasts, for
    example).</div>
                                                        </td>
            </tr>
                                <tr>
                                                                <td colspan="3">
                    <div class="ansibleOptionAnchor" id="parameter-validate_certs"></div>
                    <b>validate_certs</b>
                    <a class="ansibleOptionLink" href="#parameter-validate_certs" title="Permalink to this option"></a>
                    <div style="font-size: small">
                        <span style="color: purple">raw</span>
                                                                    </div>
                                                        </td>
                                <td>
                                                                                                                                                                                                                <b>Default:</b><br/><div style="color: blue">"yes"</div>
                                    </td>
                                                                <td>
                                            <div>If <code>no</code>, SSL certificates will not be validated. This should only be used on personally controlled sites using self-signed certificates.</div>
                                                        </td>
            </tr>
                        </table>
    <br/>

.. Notes

Notes
-----

.. note::
   - Tags should be defined as a YAML list
   - This should be ran with connection ``local`` and hosts ``localhost``

.. Seealso


.. Examples

Examples
--------

.. code-block:: yaml+jinja

    
    - name: "Test Netbox IP address module"
      connection: local
      hosts: localhost
      gather_facts: False

      tasks:
        - name: Create IP address within Netbox with only required information
          netbox_ip_address:
            netbox_url: http://netbox.local
            netbox_token: thisIsMyToken
            data:
              address: 192.168.1.10
            state: present
        - name: Force to create (even if it already exists) the IP
          netbox_ip_address:
            netbox_url: http://netbox.local
            netbox_token: thisIsMyToken
            data:
              address: 192.168.1.10
            state: new
        - name: Get a new available IP inside 192.168.1.0/24
          netbox_ip_address:
            netbox_url: http://netbox.local
            netbox_token: thisIsMyToken
            data:
              prefix: 192.168.1.0/24
            state: new
        - name: Delete IP address within netbox
          netbox_ip_address:
            netbox_url: http://netbox.local
            netbox_token: thisIsMyToken
            data:
              address: 192.168.1.10
            state: absent
        - name: Create IP address with several specified options
          netbox_ip_address:
            netbox_url: http://netbox.local
            netbox_token: thisIsMyToken
            data:
              family: 4
              address: 192.168.1.20
              vrf: Test
              tenant: Test Tenant
              status: Reserved
              role: Loopback
              description: Test description
              tags:
                - Schnozzberry
            state: present
        - name: Create IP address and assign a nat_inside IP
          netbox_ip_address:
            netbox_url: http://netbox.local
            netbox_token: thisIsMyToken
            data:
              family: 4
              address: 192.168.1.30
              vrf: Test
              nat_inside:
                address: 192.168.1.20
                vrf: Test
              interface:
                name: GigabitEthernet1
                device: test100
        - name: Ensure that an IP inside 192.168.1.0/24 is attached to GigabitEthernet1
          netbox_ip_address:
            netbox_url: http://netbox.local
            netbox_token: thisIsMyToken
            data:
              prefix: 192.168.1.0/24
              vrf: Test
              interface:
                name: GigabitEthernet1
                device: test100
            state: present
        - name: Attach a new available IP of 192.168.1.0/24 to GigabitEthernet1
          netbox_ip_address:
            netbox_url: http://netbox.local
            netbox_token: thisIsMyToken
            data:
              prefix: 192.168.1.0/24
              vrf: Test
              interface:
                name: GigabitEthernet1
                device: test100
            state: new
        - name: Attach a new available IP of 192.168.1.0/24 to GigabitEthernet1 (NetBox 2.9+)
          netbox_ip_address:
            netbox_url: http://netbox.local
            netbox_token: thisIsMyToken
            data:
              prefix: 192.168.1.0/24
              vrf: Test
              assigned_object:
                name: GigabitEthernet1
                device: test100
            state: new




.. Facts


.. Return values

Return Values
-------------
Common return values are documented :ref:`here <common_return_values>`, the following are the fields unique to this module:

.. raw:: html

    <table border=0 cellpadding=0 class="documentation-table">
        <tr>
            <th colspan="1">Key</th>
            <th>Returned</th>
            <th width="100%">Description</th>
        </tr>
                    <tr>
                                <td colspan="1">
                    <div class="ansibleOptionAnchor" id="return-ip_address"></div>
                    <b>ip_address</b>
                    <a class="ansibleOptionLink" href="#return-ip_address" title="Permalink to this return value"></a>
                    <div style="font-size: small">
                      <span style="color: purple">dictionary</span>
                                          </div>
                                    </td>
                <td>on creation</td>
                <td>
                                            <div>Serialized object as created or already existent within Netbox</div>
                                        <br/>
                                    </td>
            </tr>
                                <tr>
                                <td colspan="1">
                    <div class="ansibleOptionAnchor" id="return-msg"></div>
                    <b>msg</b>
                    <a class="ansibleOptionLink" href="#return-msg" title="Permalink to this return value"></a>
                    <div style="font-size: small">
                      <span style="color: purple">string</span>
                                          </div>
                                    </td>
                <td>always</td>
                <td>
                                            <div>Message indicating failure or info about what has been achieved</div>
                                        <br/>
                                    </td>
            </tr>
                        </table>
    <br/><br/>

..  Status (Presently only deprecated)


.. Authors

Authors
~~~~~~~

- Mikhail Yohman (@FragmentedPacket)
- Anthony Ruhier (@Anthony25)



.. Parsing errors

