Ansible Network interfaces

[! OpenSSF Best Practices](https://bestpractices.coreinfrastructure.org/projects/7650)

This repository contains the network.interfaces Ansible Collection.

About

• Ansible Network interfaces Collection contains the role that provides a platform-agnostic way of managing interfaces protocol/resources. This collection provides the user the capabilities to gather, deploy, remediate, configure and perform health checks for network interfaces resources.

• Network interfaces collection can be used by anyone who is looking to manage and maintain interfaces protocol/resources. This includes system administrators and IT professionals.

Requirements

• Requires Ansible
• Requires Content Collections
• Testing Requirements
• Users also need to include platform collections as per their requirements. The supported platform collections are:
  • arista.eos
  • cisco.ios
  • cisco.iosxr
  • cisco.nxos
  • junipernetworks.junos

Installation

To consume this Validated Content from Automation Hub, the following needs to be added to ansible.cfg:

[galaxy]
server_list = automation_hub

[galaxy_server.automation_hub]
url=https://console.redhat.com/api/automation-hub/content/published/
auth_url=https://sso.redhat.com/auth/realms/redhat-external/protocol/openid-connect/token
token=<SuperSecretToken>

Get the required token from the Automation Hub Web UI.

With this configured, simply run the following commands:

ansible-galaxy collection install network.base
ansible-galaxy collection install network.interfaces

Use Cases

Build Brownfield Inventory:

• Users want to be able to get the facts for INTERFACES resources and store it as host_vars thus enabling the capability to get facts for all the hosts within the inventory and store facts in a structured format that acts as SOT.

interfaces Resource Management:

• Users want to be able to manage the interfaces, L2 interfaces and L3 interfaces configurations. This also includes the enablement of gathering facts, updating INTERFACE resource host-vars and deploying config onto the appliance.

Detect Drift and remediate: This enables users to detect any drift between the provided config and the running config and if required then override the running config.

interfaces Health Checks: Users want to be able to perform health checks for INTERFACES resources. These health checks should be able to provide the interface's admin operational state with the necessary details.

• So in summary this platform-agnostic role enables the user to perform interfaces health checks. Users can perform the following health checks: all_operational_state_up min_operational_state_up all_administratnal_state_up min_administratnal_state_up

This role enables users to create a runtime brownfield inventory with all the INTERFACES configurations in terms of host vars. These host vars are ansible facts that have been gathered through the *_interfaces, *_l2_interfaces and *_l3_interfaces network resource module. The tasks offered by this role could be observed below:

Perform interfaces Health Checks

• Health Checks operation fetches the current status of INTERFACES operation state health.

health_checks.yml
---
- name: Perform interfaces health checks
  hosts: iosxr
  gather_facts: false
  tasks:
  - name: INTERFACES Manager
    ansible.builtin.include_role:
      name: network.interfaces.run
    vars:
      ansible_network_os: cisco.iosxr.iosxr
      operations:
        - name: health_check
          vars:
            details: True
            checks:
              - name: all_operational_state_up
              - name: min_operational_state_up
                min_count: 1
              - name: all_admin_state_up
              - name: min_admin_state_up
                min_count: 1

Building Brownfield Inventory with Persist

• Persist operation fetches the interfaces, L2 interfaces and L3 interfaces facts and stores them as host vars.
• The result of a successful Persist operation would be host_vars having YAML formatted resource facts.
• These host_vars could exist locally or even be published to a remote repository acting as SOT for operations like deploy, remediate, detect, etc.

fetch interfaces resource facts and build local data_store.

- name: Persist the facts into host vars
  hosts: rtr1
  gather_facts: false
  tasks:
  - name: Network interfaces Manager
    ansible.builtin.include_role:
      name: network.interfaces.run
    vars:
      ansible_network_os: cisco.ios.ios
      operations:
        - name: persist
      data_store:
        local: "~/interfaces/network"

fetch interfaces resource facts and publish persisted host_vars inventory to GitHub repository.

- name: Persist the facts into remote data_store which is a GitHub repository
  hosts: rtr1
  gather_facts: false
  tasks:
  - name: Network interfaces Manager
    ansible.builtin.include_role:
      name: network.interfaces.run
    vars:
      ansible_network_os: cisco.ios.ios
      operations:
        - name: persist
      persist_empty: false
      data_store:
        scm:
          origin:
            url: "{{ your_github_repo }}"
            token: "{{ github_access_token }}"
            user:
              name: "{{ ansible_github }}"
              email: "{{ your_email@example.com }}"

Display Structured Data with Gather

• gather operation gathers the running configuration specific to interfaces, l2-interfaces and, l3-interfaces resources. resources and displays these facts in YAML formatted structures.

- name: Display interfaces resources in a structured format
  hosts: rtr1
  gather_facts: false
  tasks:
  - name: interfaces Manager
    ansible.builtin.include_role:
      name: network.interfaces.run
    vars:
      ansible_network_os: cisco.ios.ios
      operations:
        - name: gather

Deploy interfaces Configuration

• Deploy operation will read the facts from the provided/default or remote inventory and deploy the changes onto the appliances.

read host_vars from local data_store and deploy onto the field.

- name: Deploy changes
  hosts: rtr1
  gather_facts: false
  tasks:
  - name: Network interfaces Manager
    ansible.builtin.include_role:
      name: network.interfaces.run
    vars:
      ansible_network_os: cisco.ios.ios
      operations:
        - name: deploy
      data_store:
        local: "~/interfaces/network"

retrieve host_cars from the GitHub repository and deploy changes onto the field.

- name: retrieve config from GitHub repo and deploy changes
  hosts: rtr1
  gather_facts: false
  tasks:
  - name: Network interfaces Manager
    ansible.builtin.include_role:
      name: network.interfaces.run
    vars:
      ansible_network_os: cisco.ios.ios
      operations:
        - name: deploy
      persist_empty: false
      data_store:
        scm:
          origin:
            url: "{{ your_github_repo }}"
            token: "{{ github_access_token }}"
            user:
              name: "{{ ansible_github }}"
              email: "{{ your_email@example.com }}"

Detect configuration drift in interfaces Configuration

• Detect operation will read the facts from the local provided/default inventory and detect if any configuration diff exists w.r.t running-config.

detect the config difference between host_vars in local data_store and running-config.

- name: Configuration drift detection
  hosts: rtr1
  gather_facts: false
  tasks:
  - name: Network interfaces Manager
    ansible.builtin.include_role:
      name: network.interfaces.run
    vars:
      ansible_network_os: cisco.ios.ios
      operations:
        - name: detect
      data_store:
        local: "~/interfaces/network"

• Detect operation will read the facts from the GitHub repository inventory and detect if any configuration diff exists w.r.t running-config.

detect the config difference between host_vars in local data_store and running-config.

- name: Configuration drift detection
  hosts: rtr1
  gather_facts: false
  tasks:
  - name: Network interfaces Manager
    include_role:
      name: network.interfaces.run
    vars:
      ansible_network_os: cisco.ios.ios
      operations:
        - name: detect
      data_store:
        scm:
          origin:
            url: "{{ your_github_repo }}"
            token: "{{ github_access_token }}"
            user:
              name: "{{ ansible_github }}"
              email: "{{ your_email@example.com }}"

Remediate configuration drift in interfaces Configuration

• remediate operation will read the facts from the locally provided/default inventory and remediate if any configuration changes are there on the appliances using the overridden state.

- name: Remediate configuration
  hosts: rtr1
  gather_facts: false
  tasks:
  - name: Network interfaces Manager
    include_role:
      name: network.interfaces.run
    vars:
      ansible_network_os: cisco.ios.ios
      operations:
        - name: remediate
      data_store:
        local: "~/interfaces/network"

• remediate operation will read the facts from the GitHub repository and remediate if any configuration changes are there on the appliances using the overridden state.

- name: Remediate configuration
  hosts: rtr1
  gather_facts: false
  tasks:
  - name: Network interfaces Manager
    include_role:
      name: network.interfaces.run
    vars:
      ansible_network_os: cisco.ios.ios
      operations:
        - name: remediate
      data_store:
        scm:
          origin:
            url: "{{ your_github_repo }}"
            token: "{{ github_access_token }}"
            user:
              name: "{{ ansible_github }}"
              email: "{{ your_email@example.com }}"

Testing

The project uses tox to run ansible-lint and ansible-test sanity. Assuming this repository is checked out in the proper structure, e.g. collections_root/ansible_collections/network/interfaces, run:

  tox -e ansible-lint
  tox -e py39-sanity

To run integration tests, ensure that your inventory has a network_base group. Depending on what test target you are running, comment out the host(s).

[network_hosts]
ios
junos

[ios:vars]
< enter inventory details for this group >

[junos:vars]
< enter inventory details for this group >

  ansible-test network-integration -i /path/to/inventory --python 3.9 [target]

Contributing

We welcome community contributions to this collection. If you find problems, please open an issue or create a PR against this repository.

Don't know how to start? Refer to the Ansible community guide!

Want to submit code changes? Take a look at the Quick-start development guide.

We also use the following guidelines:

• Collection review checklist
• Ansible development guide
• Ansible collection development guide

Code of Conduct

This collection follows the Ansible project's Code of Conduct. Please read and familiarize yourself with this document.

Release notes

Release notes are available here.

Related information

• Developing network resource modules
• Ansible Networking docs
• Ansible Collection Overview
• Ansible Roles overview
• Ansible User guide
• Ansible Developer guide
• Ansible Community Code of Conduct

Licensing

GNU General Public License v3.0 or later.

See LICENSE to see the full text.