1Ansible Network Collection for Enterprise SONiC Distribution by Dell Technologies 2================================================================================= 3 4This 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. 5 6Supported connections 7--------------------- 8The SONiC Ansible collection supports network_cli and httpapi connections. 9 10Plugins 11-------- 12**CLICONF plugin** 13 14Name | Description 15--- | --- 16[network_cli](https://github.com/ansible-collections/dellemc.enterprise_sonic)|Use Ansible CLICONF to run commands on Enterprise SONiC 17 18**HTTPAPI plugin** 19 20Name | Description 21--- | --- 22[httpapi](https://github.com/ansible-collections/dellemc.enterprise_sonic)|Use Ansible HTTPAPI to run commands on Enterprise SONiC 23 24Collection core modules 25------------------------ 26Name | Description | Connection type 27--- | --- | --- 28[**sonic_command**](https://docs.ansible.com/ansible/latest/collections/dellemc/enterprise_sonic/sonic_command_module.html#ansible-collections-dellemc-enterprise-sonic-sonic-command-module)|Run commands through the Management Framework CLI|network_cli 29[**sonic_config**](https://docs.ansible.com/ansible/latest/collections/dellemc/enterprise_sonic/sonic_config_module.html#ansible-collections-dellemc-enterprise-sonic-sonic-config-module)|Manage configuration through the Management Framework CLI|network_cli 30[**sonic_api**](https://docs.ansible.com/ansible/latest/collections/dellemc/enterprise_sonic/sonic_api_module.html#ansible-collections-dellemc-enterprise-sonic-sonic-api-module)|Perform REST operations through the Management Framework REST API|httpapi 31 32Collection network resource modules 33----------------------------------- 34Listed are the SONiC Ansible network resource modules which need ***httpapi*** as the connection type. Supported operations are ***merged*** and ***deleted***. 35 36| **Interfaces** | **BGP** | **VRF** | **Users** | 37| -------------- | ------- | ------- | ------- | 38| [**sonic_interfaces**](https://docs.ansible.com/ansible/latest/collections/dellemc/enterprise_sonic/sonic_interfaces_module.html#ansible-collections-dellemc-enterprise-sonic-sonic-interfaces-module)|[**sonic_bgp**](https://docs.ansible.com/ansible/latest/collections/dellemc/enterprise_sonic/sonic_bgp_module.html#ansible-collections-dellemc-enterprise-sonic-sonic-bgp-module)| [**sonic_vrfs**](https://docs.ansible.com/ansible/latest/collections/dellemc/enterprise_sonic/sonic_vrfs_module.html#ansible-collections-dellemc-enterprise-sonic-sonic-vrfs-module)|[**sonic_users**](https://docs.ansible.com/ansible/latest/collections/dellemc/enterprise_sonic/sonic_users_module.html#ansible-collections-dellemc-enterprise-sonic-sonic-users-module)| 39| [**sonic_l2_interfaces**](https://docs.ansible.com/ansible/latest/collections/dellemc/enterprise_sonic/sonic_l2_interfaces_module.html#ansible-collections-dellemc-enterprise-sonic-sonic-l2-interfaces-module)| [**sonic_bgp_af**](https://docs.ansible.com/ansible/latest/collections/dellemc/enterprise_sonic/sonic_bgp_af_module.html#ansible-collections-dellemc-enterprise-sonic-sonic-bgp-af-module)| **MCLAG** | **AAA** | 40| [**sonic_l3_interfaces**](https://docs.ansible.com/ansible/latest/collections/dellemc/enterprise_sonic/sonic_l3_interfaces_module.html#ansible-collections-dellemc-enterprise-sonic-sonic-l3-interfaces-module) |[**sonic_bgp_as_paths**](https://docs.ansible.com/ansible/latest/collections/dellemc/enterprise_sonic/sonic_bgp_as_paths_module.html#ansible-collections-dellemc-enterprise-sonic-sonic-bgp-as-paths-module)| [**sonic_mclag**](https://docs.ansible.com/ansible/latest/collections/dellemc/enterprise_sonic/sonic_mclag_module.html#ansible-collections-dellemc-enterprise-sonic-sonic-mclag-module)| [**sonic_aaa**](https://docs.ansible.com/ansible/latest/collections/dellemc/enterprise_sonic/sonic_aaa_module.html#ansible-collections-dellemc-enterprise-sonic-sonic-aaa-module)| 41|**Port channel**|[**sonic_bgp_communities**](https://docs.ansible.com/ansible/latest/collections/dellemc/enterprise_sonic/sonic_bgp_communities_module.html#ansible-collections-dellemc-enterprise-sonic-sonic-bgp-communities-module)| **VxLANs** |[**sonic_tacacs_server**](https://docs.ansible.com/ansible/latest/collections/dellemc/enterprise_sonic/sonic_tacacs_server_module.html#ansible-collections-dellemc-enterprise-sonic-sonic-tacacs-server-module)| 42|[**sonic_lag_interfaces**](https://docs.ansible.com/ansible/latest/collections/dellemc/enterprise_sonic/sonic_lag_interfaces_module.html#ansible-collections-dellemc-enterprise-sonic-sonic-lag-interfaces-module)|[**sonic_bgp_ext_communities**](https://docs.ansible.com/ansible/latest/collections/dellemc/enterprise_sonic/sonic_bgp_ext_communities_module.html#ansible-collections-dellemc-enterprise-sonic-sonic-bgp-ext-communities-module)| [**sonic_vxlans**](https://docs.ansible.com/ansible/latest/collections/dellemc/enterprise_sonic/sonic_vxlans_module.html#ansible-collections-dellemc-enterprise-sonic-sonic-vxlans-module)|[**sonic_radius_server**](https://docs.ansible.com/ansible/latest/collections/dellemc/enterprise_sonic/sonic_radius_server_module.html#ansible-collections-dellemc-enterprise-sonic-sonic-radius-server-module)| 43|**VLANs**|[**sonic_bgp_neighbors**](https://docs.ansible.com/ansible/latest/collections/dellemc/enterprise_sonic/sonic_bgp_neighbors_module.html#ansible-collections-dellemc-enterprise-sonic-sonic-bgp-neighbors-module)| **Port breakout** | **System** | 44|[**sonic_vlans**](https://docs.ansible.com/ansible/latest/collections/dellemc/enterprise_sonic/sonic_vlans_module.html#ansible-collections-dellemc-enterprise-sonic-sonic-vlans-module)|[**sonic_bgp_neighbors_af**](https://docs.ansible.com/ansible/latest/collections/dellemc/enterprise_sonic/sonic_bgp_neighbors_af_module.html#ansible-collections-dellemc-enterprise-sonic-sonic-bgp-neighbors-af-module)|[**sonic_port_breakout**](https://docs.ansible.com/ansible/latest/collections/dellemc/enterprise_sonic/sonic_port_breakout_module.html#ansible-collections-dellemc-enterprise-sonic-sonic-port-breakout-module) |[**sonic_system**](https://docs.ansible.com/ansible/latest/collections/dellemc/enterprise_sonic/sonic_system_module.html#ansible-collections-dellemc-enterprise-sonic-sonic-system-module) | 45 46Sample use case playbooks 47------------------------- 48The playbooks directory includes this sample playbook that show end-to-end use cases. 49 50Name | Description 51--- | --- 52[**BGP Layer 3 fabric**](https://github.com/ansible-collections/dellemc.enterprise_sonic/tree/master/playbooks/bgp_l3_fabric)|Example playbook to build a Layer 3 leaf-spine fabric 53 54Version compatibility 55---------------------- 56* Recommended Ansible version 2.10 or higher 57* Enterprise SONiC Distribution by Dell Technologies version 3.1 or higher 58* Recommended Python 3.5 or higher, or Python 2.7 59 60 61> **NOTE**: Community SONiC versions that include the Management Framework container should work as well, however, this collection has not been tested nor validated 62 with community versions and is not supported. 63 64Installation of Ansible 2.11+ 65----------------------------- 66##### Dependencies for Ansible Enterprise SONiC collection 67 68 pip3 install paramiko>=2.7 69 pip3 install jinja2>=2.8 70 pip3 install ansible-core 71 72Installation of Ansible 2.10+ 73----------------------------- 74##### Dependencies for Ansible Enterprise SONiC collection 75 76 pip3 install paramiko>=2.7 77 pip3 install jinja2>=2.8 78 pip3 install ansible-base 79 80 81Installation of Ansible 2.9 82--------------------------- 83##### Dependencies for Ansible Enterprise SONiC collection 84 85 pip3 install paramiko>=2.7 86 pip3 install jinja2>=2.8 87 pip3 install ansible 88 89##### Setting Environment Variables 90 91To use the Enterprise SONiC collection in Ansible 2.9, it is required to add one of the two available environment variables. 92 93Option 1: Add the environment variable while running the playbook. 94 95 96 ANSIBLE_NETWORK_GROUP_MODULES=sonic ansible-playbook sample_playbook.yaml -i inventory.yaml 97 98 99Option 2: Add the environment variable in user profile. 100 101 102 ANSIBLE_NETWORK_GROUP_MODULES=sonic 103 104 105Installation of Enterprise SONiC collection from Ansible Galaxy 106--------------------------------------------------------------- 107 108Install the latest version of the Enterprise SONiC collection from Ansible Galaxy. 109 110 ansible-galaxy collection install dellemc.enterprise_sonic 111 112To 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. 113 114 ansible-galaxy collection install 'dellemc.enterprise_sonic:>=1.0.0,<2.0.0' 115 116 117Sample playbooks 118----------------- 119**VLAN configuration using CLICONF** 120 121***sonic_network_cli.yaml*** 122 123 --- 124 125 - name: SONiC Management Framework CLI configuration examples 126 hosts: sonic_switches 127 gather_facts: no 128 connection: network_cli 129 tasks: 130 - name: Add VLAN entry 131 dellemc.enterprise_sonic.sonic_config: 132 commands: ['interface Vlan 700','exit'] 133 save: yes 134 register: config_op 135 - name: Test SONiC single command 136 dellemc.enterprise_sonic.sonic_command: 137 commands: 'show vlan' 138 register: cmd_op 139 140**VLAN configuration using HTTPAPI** 141 142***sonic_httpapi.yaml*** 143 144 --- 145 146 - name: SONiC Management Framework REST API examples 147 hosts: sonic_switches 148 gather_facts: no 149 connection: httpapi 150 tasks: 151 - name: Perform PUT operation to add a VLAN network instance 152 dellemc.enterprise_sonic.sonic_api: 153 url: data/openconfig-network-instance:network-instances/network-instance=Vlan100 154 method: "PUT" 155 body: {"openconfig-network-instance:network-instance": [{"name": "Vlan100","config": {"name": "Vlan100"}}]} 156 status_code: 204 157 - name: Perform GET operation to view VLAN network instance 158 dellemc.enterprise_sonic.sonic_api: 159 url: data/openconfig-network-instance:network-instances/network-instance=Vlan100 160 method: "GET" 161 status_code: 200 162 register: api_op 163 164**Configuration using network resource modules** 165 166***sonic_resource_modules.yaml*** 167 168 --- 169 170 - name: VLANs, Layer 2 and Layer 3 interfaces configuration using Enterprise SONiC resource modules 171 hosts: sonic_switches 172 gather_facts: no 173 connection: httpapi 174 tasks: 175 - name: Configure VLANs 176 dellemc.enterprise_sonic.sonic_vlans: 177 config: 178 - vlan_id: 701 179 - vlan_id: 702 180 - vlan_id: 703 181 - vlan_id: 704 182 state: merged 183 register: sonic_vlans_output 184 - name: Configure Layer 2 interfaces 185 dellemc.enterprise_sonic.sonic_l2_interfaces: 186 config: 187 - name: Eth1/2 188 access: 189 vlan: 701 190 trunk: 191 allowed_vlans: 192 - vlan: 702 193 - vlan: 703 194 state: merged 195 register: sonic_l2_interfaces_output 196 - name: Configure Layer 3 interfaces 197 dellemc.enterprise_sonic.sonic_l3_interfaces: 198 config: 199 - name: Eth1/3 200 ipv4: 201 - address: 8.1.1.1/16 202 ipv6: 203 - address: 3333::1/16 204 state: merged 205 register: sonic_l3_interfaces_output 206 207***host_vars/sonic_sw1.yaml*** 208 209 hostname: sonic_sw1 210 211 # Common parameters for connection type httpapi or network_cli: 212 ansible_user: xxxx 213 ansible_pass: xxxx 214 ansible_network_os: dellemc.enterprise_sonic.sonic 215 216 # Additional parameters for connection type httpapi: 217 ansible_httpapi_use_ssl: true 218 ansible_httpapi_validate_certs: false 219 220***inventory.yaml*** 221 222 [sonic_sw1] 223 sonic_sw1 ansible_host=100.104.28.119 224 225 [sonic_sw2] 226 sonic_sw2 ansible_host=100.104.28.120 227 228 [sonic_switches:children] 229 sonic_sw1 230 sonic_sw2 231 232Releasing, Versioning and Deprecation 233------------------------------------- 234 235This collection follows [Semantic Versioning](https://semver.org/). More details on versioning can be found [in the Ansible docs](https://docs.ansible.com/ansible/latest/dev_guide/developing_collections.html#collection-versions). 236 237We plan to regularly release new minor or bugfix versions once new features or bugfixes have been implemented. 238 239Enterprise SONiC Ansible Modules deprecation cycle is aligned with [Ansible](https://docs.ansible.com/ansible/latest/dev_guide/module_lifecycle.html). 240 241Code of Conduct 242--------------- 243 244This repository adheres to the [Ansible Community code of conduct](https://docs.ansible.com/ansible/latest/community/code_of_conduct.html) 245 246(c) 2020-2021 Dell Inc. or its subsidiaries. All Rights Reserved. 247