Ansible Network Collection for Enterprise SONiC Distribution by Dell Technologies

This collection includes Ansible core modules, network resource modules, and plugins needed to provision and manage Dell EMC PowerSwitch platforms running Enterprise SONiC Distribution by Dell Technologies. Sample playbooks and documentation are also included to show how the collection can be used.

Supported connections

The SONiC Ansible collection supports network_cli and httpapi connections.

Plugins

CLICONF plugin

Name	Description
network_cli	Use Ansible CLICONF to run commands on Enterprise SONiC

HTTPAPI plugin

Name	Description
httpapi	Use Ansible HTTPAPI to run commands on Enterprise SONiC

Collection core modules

Name	Description	Connection type
sonic_command	Run commands through the Management Framework CLI	network_cli
sonic_config	Manage configuration through the Management Framework CLI	network_cli
sonic_api	Perform REST operations through the Management Framework REST API	httpapi

Collection network resource modules

Listed are the SONiC Ansible network resource modules which need httpapi as the connection type. Supported operations are merged, deleted, replaced and overridden.

Name	Description
sonic_aaa	Manage AAA and its parameters
sonic_acl_interfaces	Manage access control list (ACL) to interface binding
sonic_bfd	Manage BFD configuration
sonic_bgp	Manage global BGP and its parameters
sonic_bgp_af	Manage global BGP address-family and its parameters
sonic_bgp_as_paths	Manage BGP autonomous system path (or as-path-list) and its parameters
sonic_bgp_communities	Manage BGP community and its parameters
sonic_bgp_ext_communities	Manage BGP extended community-list and its parameters
sonic_bgp_neighbors	Manage a BGP neighbor and its parameters
sonic_bgp_neighbors_af	Manage the BGP neighbor address-family and its parameters
sonic_copp	Manage CoPP configuration
sonic_dhcp_relay	Manage DHCP and DHCPv6 relay configurations
sonic_dhcp_snooping	Manage DHCP Snooping
sonic_fips	Manage FIPS configurations
sonic_image_management	Manage installation of Enterprise SONiC image, software patch and firmware updater.
sonic_interfaces	Configure Interface attributes
sonic_ip_neighbor	Manage IP neighbor global configuration
sonic_l2_acls	Manage Layer 2 access control lists (ACL) configurations
sonic_l2_interfaces	Configure interface-to-VLAN association
sonic_l3_acls	Manage Layer 3 access control lists (ACL) configurations
sonic_l3_interfaces	Configure the IPv4 and IPv6 parameters on Interfaces
sonic_lag_interfaces	Manage link aggregation group (LAG) interface parameters
sonic_ldap	Configure global LDAP server settings
sonic_lldp_global	Manage Global LLDP configurations
sonic_lldp_interfaces	Manage interface LLDP configurations
sonic_logging	Manage logging configuration
sonic_login_lockout	Manage Global Login Lockout configuration
sonic_mac	Manage MAC configuration
sonic_mclag	Manage multi chassis link aggregation groups domain (MCLAG) and its parameters
sonic_mgmt_servers	Manage management servers configuration
sonic_ntp	Manage NTP configuration
sonic_ospf_area	Configure OSPF area setting
sonic_ospfv2	Configure global OSPFv2 protocol settings
sonic_ospfv2_interfaces	Configure OSPFv2 interface mode protocol settings
sonic_pim_global	Manage global PIM configuration
sonic_pim_interfaces	Manage interface-specific PIM configurations
sonic_pki	Manages PKI attributes
sonic_poe	Manage Power over Ethernet PoE configuration
sonic_port_breakout	Configure port breakout settings on physical interfaces
sonic_port_group	Manage port group configuration
sonic_prefix_lists	Manage prefix list configuration
sonic_qos_buffer	Manage QoS buffer configuration
sonic_qos_interfaces	Manage QoS interfaces configuration
sonic_qos_maps	Manage QoS maps configuration
sonic_qos_pfc	Manage QoS PFC configuration
sonic_qos_scheduler	Manage QoS scheduler configuration
sonic_qos_wred	Manage QoS WRED profiles configuration
sonic_radius_server	Manage RADIUS server and its parameters
sonic_roce	Manage RoCE QoS configuration
sonic_route_maps	Manage route map configuration
sonic_sflow	Manage sflow configuration settings
sonic_static_routes	Manage static routes configuration
sonic_stp	Manage STP configuration
sonic_system	Configure system parameters
sonic_tacacs_server	Manage TACACS server and its parameters
sonic_users	Manage users and its parameters
sonic_vlan_mapping	Configure vlan mappings
sonic_vlans	Manage VLAN and its parameters
sonic_vrfs	Manage VRFs and associate VRFs to interfaces
sonic_vrrp	Manage VRRP protocol configuration settings
sonic_vxlans	Manage VxLAN EVPN and its parameters

Sample use case playbooks

The playbooks directory includes this sample playbook that show end-to-end use cases.

Name	Description
BGP Layer 3 fabric	Example playbook to build a Layer 3 leaf-spine fabric

Version compatibility

• Recommended Ansible version 2.14 or higher (This is required for enterprise_sonic collection version >= 2.4.0).
• Enterprise SONiC Distribution by Dell Technologies version 3.1 or higher
• Recommended Python 3.9 or higher (This is required for enterprise_sonic collection version >= 2.4.0.).
• Dell Enterprise SONiC images for releases 3.1 - 3.5: Use Ansible Enterprise SONiC collection version 1.1.0 or later 1.m.n versions (from the 1.x branch of this repo)
• Dell Enterprise SONiC images for release 4.0 and later 4.x.y releases: Use Ansible Enterprise SONiC collection version 2.0.0 or later 2.m.n releases (from the "2.x" branch of this repo).
• In general: Dell Enterprise SONiC release versions "R.x.y" are supported by Ansible Enterprise SONiC collection versions "R-2.m.n" on branch "R-2.x".

NOTE: Community SONiC versions that include the Management Framework container should work as well, however, this collection has not been tested nor validated with community versions and is not supported.

Installation of Ansible 2.11+

Dependencies for Ansible Enterprise SONiC collection

  pip3 install paramiko>=2.7
  pip3 install jinja2>=2.8
  pip3 install ansible-core

Installation of Ansible 2.10+

Dependencies for Ansible Enterprise SONiC collection

  pip3 install paramiko>=2.7
  pip3 install jinja2>=2.8
  pip3 install ansible-base

Installation of Ansible 2.9

Dependencies for Ansible Enterprise SONiC collection

  pip3 install paramiko>=2.7
  pip3 install jinja2>=2.8
  pip3 install ansible

Setting Environment Variables

To use the Enterprise SONiC collection in Ansible 2.9, it is required to add one of the two available environment variables.

Option 1: Add the environment variable while running the playbook.

  ANSIBLE_NETWORK_GROUP_MODULES=sonic ansible-playbook sample_playbook.yaml -i inventory.ini

Option 2: Add the environment variable in user profile.

  ANSIBLE_NETWORK_GROUP_MODULES=sonic

Installation of Enterprise SONiC collection from Ansible Galaxy

Install the latest version of the Enterprise SONiC collection from Ansible Galaxy.

  ansible-galaxy collection install dellemc.enterprise_sonic

To install a specific version, specify a version range identifier. For example, to install the most recent version that is greater than or equal to 1.0.0 and less than 2.0.0.

  ansible-galaxy collection install 'dellemc.enterprise_sonic:>=1.0.0,<2.0.0'

Sample playbooks

VLAN configuration using CLICONF

sonic_network_cli.yaml

---

- name: SONiC Management Framework CLI configuration examples
  hosts: sonic_switches
  gather_facts: no
  connection: network_cli
  tasks:
    - name: Add VLAN entry
      dellemc.enterprise_sonic.sonic_config:
        commands: ['interface Vlan 700','exit']
        save: yes
      register: config_op
    - name: Test SONiC single command
      dellemc.enterprise_sonic.sonic_command:
        commands: 'show vlan'
      register: cmd_op

VLAN configuration using HTTPAPI

sonic_httpapi.yaml

---

- name: SONiC Management Framework REST API examples
  hosts: sonic_switches
  gather_facts: no
  connection: httpapi
  tasks:
    - name: Perform PUT operation to add a VLAN network instance
      dellemc.enterprise_sonic.sonic_api:
        url: data/openconfig-network-instance:network-instances/network-instance=Vlan100
        method: "PUT"
        body: {"openconfig-network-instance:network-instance": [{"name": "Vlan100","config": {"name": "Vlan100"}}]}
        status_code: 204
    - name: Perform GET operation to view VLAN network instance
      dellemc.enterprise_sonic.sonic_api:
        url: data/openconfig-network-instance:network-instances/network-instance=Vlan100
        method: "GET"
        status_code: 200
      register: api_op

Configuration using network resource modules

sonic_resource_modules.yaml

---

- name: VLANs, Layer 2 and Layer 3 interfaces configuration using Enterprise SONiC resource modules
  hosts: sonic_switches
  gather_facts: no
  connection: httpapi
  tasks:
   - name: Configure VLANs
     dellemc.enterprise_sonic.sonic_vlans:
        config:
         - vlan_id: 701
         - vlan_id: 702
         - vlan_id: 703
         - vlan_id: 704
        state: merged
     register: sonic_vlans_output
   - name: Configure Layer 2 interfaces
     dellemc.enterprise_sonic.sonic_l2_interfaces:
        config:
        - name: Eth1/2
          access:
            vlan: 701
          trunk:
            allowed_vlans:
              - vlan: 702
              - vlan: 703
        state: merged
     register: sonic_l2_interfaces_output
   - name: Configure Layer 3 interfaces
     dellemc.enterprise_sonic.sonic_l3_interfaces:
       config:
        - name: Eth1/3
          ipv4:
            - address: 8.1.1.1/16
          ipv6:
            - address: 3333::1/16
       state: merged
     register: sonic_l3_interfaces_output

host_vars/sonic_sw1.yaml

hostname: sonic_sw1

# Common parameters for connection type httpapi or network_cli:
ansible_user: xxxx
ansible_password: xxxx
ansible_network_os: dellemc.enterprise_sonic.sonic

# Additional parameters for connection type httpapi:
ansible_httpapi_use_ssl: true
ansible_httpapi_validate_certs: false

inventory.ini

[sonic_sw1]
sonic_sw1 ansible_host=100.104.28.119

[sonic_sw2]
sonic_sw2 ansible_host=100.104.28.120

[sonic_switches:children]
sonic_sw1
sonic_sw2

Releasing, Versioning and Deprecation

This collection follows Semantic Versioning. More details on versioning can be found in the Ansible docs.

We plan to regularly release new minor or bugfix versions once new features or bugfixes have been implemented.

Enterprise SONiC Ansible Modules deprecation cycle is aligned with Ansible.

Source control branches on Github:

• Released code versions are located on "release" branches with names of the form "M.x", where "M" specifies the "major" release version for releases residing on the branch.
• Unreleased and pre-release code versions are located on sub-branches of the "main" branch. This is a development branch, and is not intended for use in production environments.

Code of Conduct

This repository adheres to the Ansible Community code of conduct

Communication

• Join the Ansible forum:

  • Get Help: get help or help others.
  • Social Spaces: gather and interact with fellow enthusiasts.
  • News & Announcements: track project-wide announcements including social events.

• The Ansible Bullhorn newsletter: used to announce releases and important changes.

For more information about communication, see the Ansible communication guide.

(c) 2020-2021 Dell Inc. or its subsidiaries. All Rights Reserved.