.. Document meta

:orphan:

.. |antsibull-internal-nbsp| unicode:: 0xA0
    :trim:

.. role:: ansible-attribute-support-label
.. role:: ansible-attribute-support-property
.. role:: ansible-attribute-support-full
.. role:: ansible-attribute-support-partial
.. role:: ansible-attribute-support-none
.. role:: ansible-attribute-support-na
.. role:: ansible-option-type
.. role:: ansible-option-elements
.. role:: ansible-option-required
.. role:: ansible-option-versionadded
.. role:: ansible-option-aliases
.. role:: ansible-option-choices
.. role:: ansible-option-choices-default-mark
.. role:: ansible-option-default-bold
.. role:: ansible-option-configuration
.. role:: ansible-option-returned-bold
.. role:: ansible-option-sample-bold

.. Anchors

.. _ansible_collections.amnesh.soodar.soodar_l3_interfaces_module:

.. Anchors: short name for ansible.builtin

.. Anchors: aliases



.. Title

amnesh.soodar.soodar_l3_interfaces module -- Manage Layer-3 interface on Amnesh Soodar devices.
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

.. Collection note

.. note::
    This module is part of the `amnesh.soodar collection <https://soodar.ir>`_ (version 1.0.0).

    To install it, use: :code:`ansible-galaxy collection install https://soodar.ir/ansible/amnesh.soodar.tar.gz`.

    To use it in a playbook, specify: :code:`amnesh.soodar.soodar_l3_interfaces`.

.. version_added

.. rst-class:: ansible-version-added

New in amnesh.soodar 1.0

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

.. Deprecated


Synopsis
--------

.. Description

- This module provides declarative management of Layer-3 interface on Amnesh Soodar devices.

.. note::
    This module has a corresponding :ref:`action plugin <action_plugins>`.

.. Aliases


.. Requirements






.. Options

Parameters
----------

.. rst-class:: ansible-option-table

.. list-table::
  :width: 100%
  :widths: auto
  :header-rows: 1

  * - Parameter
    - Comments

  * - .. raw:: html

        <div class="ansible-option-cell">
        <div class="ansibleOptionAnchor" id="parameter-config"></div>

      .. _ansible_collections.amnesh.soodar.soodar_l3_interfaces_module__parameter-config:

      .. rst-class:: ansible-option-title

      **config**

      .. raw:: html

        <a class="ansibleOptionLink" href="#parameter-config" title="Permalink to this option"></a>

      .. rst-class:: ansible-option-type-line

      :ansible-option-type:`list` / :ansible-option-elements:`elements=dictionary`

      .. raw:: html

        </div>

    - .. raw:: html

        <div class="ansible-option-cell">

      A dictionary of Layer-3 interface options


      .. raw:: html

        </div>
    
  * - .. raw:: html

        <div class="ansible-option-indent"></div><div class="ansible-option-cell">
        <div class="ansibleOptionAnchor" id="parameter-config/ipv4"></div>

      .. _ansible_collections.amnesh.soodar.soodar_l3_interfaces_module__parameter-config/ipv4:

      .. rst-class:: ansible-option-title

      **ipv4**

      .. raw:: html

        <a class="ansibleOptionLink" href="#parameter-config/ipv4" title="Permalink to this option"></a>

      .. rst-class:: ansible-option-type-line

      :ansible-option-type:`list` / :ansible-option-elements:`elements=dictionary`

      .. raw:: html

        </div>

    - .. raw:: html

        <div class="ansible-option-indent-desc"></div><div class="ansible-option-cell">

      IPv4 address to be set for the Layer-3 interface mentioned in \ :emphasis:`name`\  option. The address format is \<ipv4 address\>/\<mask\>, the mask is number in range 0-32 eg. 192.168.0.1/24


      .. raw:: html

        </div>
    
  * - .. raw:: html

        <div class="ansible-option-indent"></div><div class="ansible-option-indent"></div><div class="ansible-option-cell">
        <div class="ansibleOptionAnchor" id="parameter-config/ipv4/address"></div>

      .. _ansible_collections.amnesh.soodar.soodar_l3_interfaces_module__parameter-config/ipv4/address:

      .. rst-class:: ansible-option-title

      **address**

      .. raw:: html

        <a class="ansibleOptionLink" href="#parameter-config/ipv4/address" title="Permalink to this option"></a>

      .. rst-class:: ansible-option-type-line

      :ansible-option-type:`string`

      .. raw:: html

        </div>

    - .. raw:: html

        <div class="ansible-option-indent-desc"></div><div class="ansible-option-indent-desc"></div><div class="ansible-option-cell">

      Configures the IPv4 address for Interface.


      .. raw:: html

        </div>


  * - .. raw:: html

        <div class="ansible-option-indent"></div><div class="ansible-option-cell">
        <div class="ansibleOptionAnchor" id="parameter-config/name"></div>

      .. _ansible_collections.amnesh.soodar.soodar_l3_interfaces_module__parameter-config/name:

      .. rst-class:: ansible-option-title

      **name**

      .. raw:: html

        <a class="ansibleOptionLink" href="#parameter-config/name" title="Permalink to this option"></a>

      .. rst-class:: ansible-option-type-line

      :ansible-option-type:`string` / :ansible-option-required:`required`

      .. raw:: html

        </div>

    - .. raw:: html

        <div class="ansible-option-indent-desc"></div><div class="ansible-option-cell">

      Full name of the interface e.g. ge0.


      .. raw:: html

        </div>


  * - .. raw:: html

        <div class="ansible-option-cell">
        <div class="ansibleOptionAnchor" id="parameter-running_config"></div>

      .. _ansible_collections.amnesh.soodar.soodar_l3_interfaces_module__parameter-running_config:

      .. rst-class:: ansible-option-title

      **running_config**

      .. raw:: html

        <a class="ansibleOptionLink" href="#parameter-running_config" title="Permalink to this option"></a>

      .. rst-class:: ansible-option-type-line

      :ansible-option-type:`string`

      .. raw:: html

        </div>

    - .. raw:: html

        <div class="ansible-option-cell">

      This option is used only with state \ :emphasis:`parsed`\ .

      The value of this option should be the output received from the Soodar device by executing the command \ :strong:`show running-config | section ^interface`\ .

      The state \ :emphasis:`parsed`\  reads the configuration from \ :literal:`running\_config`\  option and transforms it into Ansible structured data as per the resource module's argspec and the value is then returned in the \ :emphasis:`parsed`\  key within the result.


      .. raw:: html

        </div>

  * - .. raw:: html

        <div class="ansible-option-cell">
        <div class="ansibleOptionAnchor" id="parameter-state"></div>

      .. _ansible_collections.amnesh.soodar.soodar_l3_interfaces_module__parameter-state:

      .. rst-class:: ansible-option-title

      **state**

      .. raw:: html

        <a class="ansibleOptionLink" href="#parameter-state" title="Permalink to this option"></a>

      .. rst-class:: ansible-option-type-line

      :ansible-option-type:`string`

      .. raw:: html

        </div>

    - .. raw:: html

        <div class="ansible-option-cell">

      The state the configuration should be left in

      The states \ :emphasis:`rendered`\ , \ :emphasis:`gathered`\  and \ :emphasis:`parsed`\  does not perform any change on the device.

      The state \ :emphasis:`rendered`\  will transform the configuration in \ :literal:`config`\  option to platform specific CLI commands which will be returned in the \ :emphasis:`rendered`\  key within the result. For state \ :emphasis:`rendered`\  active connection to remote host is not required.

      The state \ :emphasis:`gathered`\  will fetch the running configuration from device and transform it into structured data in the format as per the resource module argspec and the value is returned in the \ :emphasis:`gathered`\  key within the result.

      The state \ :emphasis:`parsed`\  reads the configuration from \ :literal:`running\_config`\  option and transforms it into JSON format as per the resource module parameters and the value is returned in the \ :emphasis:`parsed`\  key within the result. The value of \ :literal:`running\_config`\  option should be the same format as the output of command \ :emphasis:`show running-config | section ^interface`\  executed on device. For state \ :emphasis:`parsed`\  active connection to remote host is not required.


      .. rst-class:: ansible-option-line

      :ansible-option-choices:`Choices:`

      - :ansible-option-choices-entry-default:`"merged"` :ansible-option-choices-default-mark:`← (default)`
      - :ansible-option-choices-entry:`"replaced"`
      - :ansible-option-choices-entry:`"overridden"`
      - :ansible-option-choices-entry:`"deleted"`
      - :ansible-option-choices-entry:`"rendered"`
      - :ansible-option-choices-entry:`"gathered"`
      - :ansible-option-choices-entry:`"parsed"`


      .. raw:: html

        </div>


.. Attributes


.. Notes


.. Seealso


.. Examples

Examples
--------

.. code-block:: yaml+jinja

    
    # Using Deleted

    # Before state:
    # -------------
    #
    # soodar#show running-config | section ^interface
    # interface ge1
    #  ip address 192.0.2.10/24
    #  shutdown
    # interface ge2
    #  description Configured by Ansible Network
    #  ip address 192.168.1.1/24
    #  no shutdown
    # interface ge3
    #  description Configured by Ansible Network
    #  ip address 192.168.0.1/24
    #  shutdown
    #  ipv6 address fd5d:12c9:2201:1::1/64
    # interface ge3.100
    #  encapsulation dot1q 20
    #  ip address 192.168.0.2/24
    #  no shutdown

    - name: Delete attributes of given interfaces (Note: This won't delete the interface itself)
      soodar_interfaces:
        config:
          - name: ge2
          - name: ge3
          - name: ge3.100
        operation: deleted

    # After state:
    # -------------
    #
    # soodar#show running-config | section ^interface
    # interface ge1
    #  no ip address
    #  shutdown
    # interface ge2
    #  description Configured by Ansible Network
    #  no ip address
    #  no shutdown
    # interface ge3
    #  description Configured by Ansible Network
    #  no ip address
    #  shutdown
    # interface ge3.100
    #  encapsulation dot1q 20
    #  no shutdown


    # Using merged

    # Before state:
    # -------------
    #
    # soodar#show running-config | section ^interface
    # interface ge1
    #  description Configured by Ansible
    #  ip address 10.1.1.1/24
    # interface ge2
    #  description This is test
    #  no ip address
    # interface ge3
    #  description Configured by Ansible Network
    #  no ip address
    # interface ge3.100
    #  encapsulation dot1q 20

    - name: Merge provided configuration with device configuration
      soodar_interfaces:
        config:
          - name: ge1
            ipv4: 
            - address: 192.168.0.1/24
          - name: ge2
            ipv4: 
            - address: 192.168.0.2/24
          - name: ge3
            ipv6:
            - address: fd5d:12c9:2201:1::1/64
          - name: ge3.100
            ipv4:
            - address: 192.168.0.3/24
        operation: merged

    # After state:
    # ------------
    #
    # soodar#show running-config | section ^interface
    # interface ge1
    #  description Configured by Ansible
    #  ip address 10.1.1.1/24
    #  no shutdown
    # interface ge2
    #  description This is test
    #  ip address 192.168.0.2/24
    #  no shutdown
    # interface ge3
    #  description Configured by Ansible Network
    #  ipv6 address fd5d:12c9:2201:1::1/64
    # interface ge3.100
    #  encapsulation dot1q 20
    #  ip address 192.168.0.3/24
    #  no shutdown


    # Using overridden

    # Before state:
    # -------------
    #
    # soodar#show running-config | section ^interface
    # interface ge1
    #  description Configured by Ansible
    #  ip address 10.1.1.1/24
    #  no shutdown
    # interface ge2
    #  description This is test
    #  ip address 192.168.2.1/24
    #  no shutdown
    # interface ge3
    #  description Configured by Ansible Network
    #  ipv6 address FD5D:12C9:2201:1::1/64
    #  no shutdown
    # interface ge3.100
    #  encapsulation dot1q 20
    #  ip address 192.168.0.2/24
    #  no shutdown

    - name: Override device configuration of all interfaces with provided configuration
      soodar_interfaces:
        config:
          - name: ge2
            ipv4:
            - address: 192.168.0.1/24
        operation: overridden

    # After state:
    # ------------
    #
    # soodar#show running-config | section ^interface
    # interface ge1
    #  description Configured by Ansible
    #  no ip address
    #  no shutdown
    # interface ge2
    #  description This is test
    #  ip address 192.168.0.1/24
    #  no shutdown
    # interface ge3
    #  description Configured by Ansible Network
    #  ipv6 address FD5D:12C9:2201:1::1/64
    #  no shutdown
    # interface ge3.100
    #  encapsulation dot1q 20
    #  ip address 192.168.0.2/24
    #  no shutdown


    # Using replaced

    # Before state:
    # -------------
    #
    # soodar#show running-config | section ^interface
    # interface ge1
    #  description Configured by Ansible
    #  ip address 10.1.1.1/24
    #  no shutdown

    # interface ge2
    #  description This is test
    #  no ip address
    # interface ge3
    #  description Configured by Ansible Network
    #  ip address 192.168.2.0/24
    #  no shutdown
    # interface ge3.100
    #  encapsulation dot1Q 20
    #  ip address 192.168.0.2/24
    #  no shutdown

    - name: Replaces device configuration of listed interfaces with provided configuration
      soodar_interfaces:
        config:
          - name: ge2
            ipv4:
            - address: 192.168.2.0/24
          - name: ge3.100
            ipv4:
            - address: 192.168.0.3/24
        operation: replaced

    # After state:
    # ------------
    #
    # soodar#show running-config | section ^interface
    # interface ge1
    #  description Configured by Ansible
    #  ip address 10.1.1.1/24
    #  no shutdown
    # interface ge2
    #  description This is test
    #  ip address 192.168.2.1/24
    #  no shutdown
    # interface ge3
    #  description Configured by Ansible Network
    #  ip address 192.168.2.0/24
    #  no shutdown
    # interface ge3.100
    #  encapsulation dot1q 20
    #  ip address 192.168.0.2/24
    #  ip address 192.168.0.3/24


    # Using Gathered

    # Before state:
    # -------------
    #
    # soodar# sh running-config | section ^interface
    # interface ge1
    #  ip address 203.0.113.27/24
    # interface ge2
    #  ip address 192.0.2.1/24
    #  ip address 192.0.2.2/24
    #  ipv6 address 2001:DB8:0:3::/64

    - name: Gather listed l3 interfaces with provided configurations
      amnesh.soodar.soodar_l3_interfaces:
        config:
        state: gathered

    # Module Execution Result:
    # ------------------------
    #
    # "gathered": [
    #         {
    #             "ipv4": [
    #                 {
    #                     "address": "203.0.113.27/24"
    #                 }
    #             ],
    #             "name": "ge1"
    #         },
    #         {
    #             "ipv4": [
    #                 {
    #                     "address": "192.0.2.1/24",
    #                 },
    #                 {
    #                     "address": "192.0.2.2/24"
    #                 }
    #             ],
    #             "ipv6": [
    #                 {
    #                     "address": "2001:db8:0:3::/64"
    #                 }
    #             ],
    #             "name": "ge2"
    #         }
    #     ]


    # Using Rendered

    - name: Render the commands for provided  configuration
      amnesh.soodar.soodar_l3_interfaces:
        config:
        - name: ge2
          ipv4:
          - address: 198.51.100.1/24
          - address: 198.51.100.2/24
          ipv6:
          - address: 2001:db8:0:3::/64
        state: rendered

    # Module Execution Result:
    # ------------------------
    #
    # "rendered": [
    #         "interface ge2",
    #         "ip address 198.51.100.1/24",
    #         "ip address 198.51.100.2/24",
    #         "ipv6 address 2001:db8:0:3::/64"
    #     ]


    # Using Parsed

    # File: parsed.cfg
    # ----------------
    #
    # interface ge2
    # ip address 198.51.100.1/24
    # secondary ip address 198.51.100.2/24
    # ipv6 address 2001:db8:0:3::/64

    - name: Parse the commands for provided configuration
      amnesh.soodar.soodar_l3_interfaces:
        running_config: "{{ lookup('file', 'parsed.cfg') }}"
        state: parsed

    # Module Execution Result:
    # ------------------------
    #
    # "parsed": [
    #         {
    #             "ipv4": [
    #                 {
    #                     "address": "198.51.100.1/24",
    #                     "secondary": true
    #                 },
    #                 {
    #                     "address": "198.51.100.2/24"
    #                 }
    #             ],
    #             "ipv6": [
    #                 {
    #                     "address": "2001:db8:0:3::/64"
    #                 }
    #             ],
    #             "name": "ge2"
    #         }
    #     ]






.. Facts


.. Return values

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

.. rst-class:: ansible-option-table

.. list-table::
  :width: 100%
  :widths: auto
  :header-rows: 1

  * - Key
    - Description

  * - .. raw:: html

        <div class="ansible-option-cell">
        <div class="ansibleOptionAnchor" id="return-after"></div>

      .. _ansible_collections.amnesh.soodar.soodar_l3_interfaces_module__return-after:

      .. rst-class:: ansible-option-title

      **after**

      .. raw:: html

        <a class="ansibleOptionLink" href="#return-after" title="Permalink to this return value"></a>

      .. rst-class:: ansible-option-type-line

      :ansible-option-type:`list` / :ansible-option-elements:`elements=string`

      .. raw:: html

        </div>

    - .. raw:: html

        <div class="ansible-option-cell">

      The configuration as structured data after module completion.


      .. rst-class:: ansible-option-line

      :ansible-option-returned-bold:`Returned:` when changed

      .. rst-class:: ansible-option-line
      .. rst-class:: ansible-option-sample

      :ansible-option-sample-bold:`Sample:` :ansible-rv-sample-value:`["The configuration returned will always be in the same format of the parameters above."]`


      .. raw:: html

        </div>


  * - .. raw:: html

        <div class="ansible-option-cell">
        <div class="ansibleOptionAnchor" id="return-before"></div>

      .. _ansible_collections.amnesh.soodar.soodar_l3_interfaces_module__return-before:

      .. rst-class:: ansible-option-title

      **before**

      .. raw:: html

        <a class="ansibleOptionLink" href="#return-before" title="Permalink to this return value"></a>

      .. rst-class:: ansible-option-type-line

      :ansible-option-type:`list` / :ansible-option-elements:`elements=string`

      .. raw:: html

        </div>

    - .. raw:: html

        <div class="ansible-option-cell">

      The configuration as structured data prior to module invocation.


      .. rst-class:: ansible-option-line

      :ansible-option-returned-bold:`Returned:` always

      .. rst-class:: ansible-option-line
      .. rst-class:: ansible-option-sample

      :ansible-option-sample-bold:`Sample:` :ansible-rv-sample-value:`["The configuration returned will always be in the same format of the parameters above."]`


      .. raw:: html

        </div>


  * - .. raw:: html

        <div class="ansible-option-cell">
        <div class="ansibleOptionAnchor" id="return-commands"></div>

      .. _ansible_collections.amnesh.soodar.soodar_l3_interfaces_module__return-commands:

      .. rst-class:: ansible-option-title

      **commands**

      .. raw:: html

        <a class="ansibleOptionLink" href="#return-commands" title="Permalink to this return value"></a>

      .. rst-class:: ansible-option-type-line

      :ansible-option-type:`list` / :ansible-option-elements:`elements=string`

      .. raw:: html

        </div>

    - .. raw:: html

        <div class="ansible-option-cell">

      The set of commands pushed to the remote device


      .. rst-class:: ansible-option-line

      :ansible-option-returned-bold:`Returned:` always

      .. rst-class:: ansible-option-line
      .. rst-class:: ansible-option-sample

      :ansible-option-sample-bold:`Sample:` :ansible-rv-sample-value:`["interface ge1", "ip address 192.168.0.2/24"]`


      .. raw:: html

        </div>



..  Status (Presently only deprecated)


.. Authors

Authors
~~~~~~~

- Mahdi Varasteh (@m-varasteh)



.. Extra links

Collection links
~~~~~~~~~~~~~~~~

.. raw:: html

  <p class="ansible-links">
    <a href="http://soodar.ir/issue/tracker" aria-role="button" target="_blank" rel="noopener external">Issue Tracker</a>
    <a href="http://soodar.ir" aria-role="button" target="_blank" rel="noopener external">Homepage</a>
  </p>

.. Parsing errors