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