Skip to content

ansible-collections/dellemc.enterprise_sonic

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

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_ssh Manage SSH 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 before 4.4.0: Use Ansible Enterprise SONiC collection version 2.0.0 or later 2.m.n releases (from the "2.x" branch of this repo).
  • Dell Enterprise SONiC images for release 4.4.0 and later 4.x.y releases: Use Ansible Enterprise SONiC collection version 3.0.0 or later 3.m.n releases (from the "main" branch of this repo).

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

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

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