How to use The Ansible server in GNS3 SONiC DataCenter v2.1.0

Robert Strakulski
Updated

[stordis-toc]

Introduction

Welcome to the STORDIS Ansible server guide.

In this guide, we will show you how to use the Ansible server available in the GNS3 SONiC DataCenter project. The Ansible server is used for automation, configuration management, and validation of the SONiC fabric.

Prerequisites

  • Running GNS3 project containing the Spine-Leaf topology. You can download it HERE by filling out the form.
  • Access to the management server (Ubuntu with Ansible installed)
  • Basic knowledge of Ansible
  • Established connectivity to SONiC nodes

Ansible Server Overview

The project includes a preconfigured Ubuntu Server that acts as an Ansible control node.

Key components:

  • Ansible Engine – used for automation and configuration
  • Interactive Menu (app_ansible.sh) – a text-based interface to easily run playbooks without typing long commands
  • Inventory – predefined list of SONiC devices (Leaf/Spine topology)
  • Playbooks – ready-to-use automation scripts

Main directory structure:

STORDIS-DataCenter/
└── ansible_configuration
    ├── ansible-venv                                 # Python Virtual environment
    └── conf_ansible                                 # Main Ansible configuration directory
        ├── ansible.cfg                              # Ansible configuration file
        ├── ansible_devices_backups                  # Directory for backups of devices
        ├── app_ansible.sh                           # Interactive TUI script for network operations
        ├── inventory
        |   ├── hosts # list of all devices
        |   └── group_vars
        |       ├── all                              # Encrypted hash file with credentials to 'all' devices
        |       ├── sonic_api.yaml                   # RESTCONF connection variables
        |       └── sonic_ssh.yaml                   # SSH connection variables
        └── playbooks
            └── playbooks_yaml_files                 # Directory containing Ansible playbooks

Access to Ubuntu Server

Log in to the management server:

Credentials:

  • Login: administrator
  • Passwd: ZAQ2wsx
  • ansible_vault_passwd: ZAQ2wsx
ssh administrator@<IP_Addr>

Note Server on ens3 interface have static address on, so You need to change it manually on /etc/netplan/50-cloud-init.yaml if needed

After that You will need to ZTP configuration files to IP in files are like the same You configured

path

/var/www/html/sonic/ztp.json

and DHCP server configuration

path

/etc/dhcp/dhcpd.conf

Activate Ansible Enviroment

In Project Dictonary proceed to activate the virtual environment

administrator@ubusrv2404:~/SONiC_DC$ source venv/bin/activate
(venv) administrator@ubusrv2404:~/SONiC_DC$

Example:

 

The Interactive Automation Menu (app_ansible.sh)

To simplify Day-1 and Day-2 operations, the platform features a built-in interactive bash script located at ~/STORDIS-DataCenter/conf_ansible/app_ansible.sh.

 

This script acts as a wrapper for Ansible. It automatically validates and handles the virtual environment activation, fetches available hosts, and provides a clear, categorized text menu for executing playbooks.

 

How to run it

You don't need to manually activate the venv to use it. Just enter the conf_ansible directory and execute the script:

administrator@ubusrv2404:~$ cd STORDIS-DataCenter/conf_ansible/
administrator@ubusrv2404:~/STORDIS-DataCenter/conf_ansible$ ./app_ansible.sh

You will see this in Your CLI:
 

Menu Structure & Features

When launched, the script presents a master dashboard categorized into operational areas:

Add Configuration: Sub-menu for deploying new network states (VLANs, IPs, PortChannels, Static Routes).

Delete Configuration: Sub-menu to safely tear down existing infrastructure parameters (VLANs, IPs, PortChannels, Static Routes).

Show Information: Runs operational tasks to gather live facts from switches (VLAN status, interfaces, routing tables).

[no]shutdown an interface: Fast administrative interface state toggling.

Verification: Diagnostic tools like mass connectivity tests and traceroutes.

Save Config: Commits the current running configuration to the startup memory (write_memory.yaml) so changes persist after a switch restart.

Backup: Generates and exports configuration backups (backup.yaml).

Important: The backup playbook does not automatically save the running configuration before creating the backup. If you want to backup your latest changes, you must run Save Config first.

Reboot: Reboots the selected target devices (reboot.yaml). You will be prompted to choose which specific host or group of switches should be restarted

Workflow

Choose an action from the menu: (e.g., type 1 for Add Configuration, then 1 for Add VLAN). The script dynamically extracts and prints out all available hostnames from your inventory/hosts file.

You will be prompted to target specific nodes: Enter target host(s) (or group, e.g., spine-1 or leaf-*, to use on every device type <all>) [--limit]:

Type your target: (e.g., leaf-1, spine-*, or all).

Provide the Ansible Vault password: (Look into point above HERE for credentials) when requested to unlock the switch credentials and execute the task safely.

=====================================
    SONiC Ansible Configuration Menu
=====================================
1) Add Configuration          6) Save Config
2) Delete Configuration       7) backup
3) Show Information           8) Reboot
4) [no]shutdown an interface  9) Exit
5) Verification
What do you want to do? 1

=== ADD CONFIGURATION ===
1) Add VLAN                    4) Create Portchannel
2) Add IP to Interface         5) Create Static Route
3) Add Members to Portchannel  6) Back to Main Menu
Choose an option:

End of work in app

You can easily leave application menu by entering option 9 in main menu

=====================================
    SONiC Ansible Configuration Menu
=====================================
1) Add Configuration          6) Save Config
2) Delete Configuration       7) backup
3) Show Information           8) Reboot
4) [no]shutdown an interface  9) Exit
5) Verification
What do you want to do? 9
Happy Networking!
administrator@ubusrv2404:~/STORDIS-DataCenter/conf_ansible$

 

Server configuration

Available Automation Use Cases

The Ansible server includes a set of ready-to-use playbooks that demonstrate common SONiC DataCenter operations. These can be used both for automation and as reference examples for building your own workflows.

How to use Playbook?

  1. You need to be in the same ansible_configuration dictonary - You need to use command in the same path where ansible.cfg file is

  2. Use command like below:

    # to use playbook on all hosts in inventory
ansible-playbook -i inventory/hosts playbooks/<playbook.yaml> --ask-vault-pass

Example:

(ansible-venv) administrator@ubusrv2404:~/STORDIS-DataCenter/conf_ansible$ ansible-playbook -i inventory/hosts playbooks/test_connection.yaml --ask-vault-pass
Vault password:
PLAY [SONiC Connectivity Check via SSH] ****************************************

TASK [Execute Ping from Switch to Server] **************************************
[WARNING]: Deprecation warnings can be disabled by setting `deprecation_warnings=False` in ansible.cfg.
ok: [leaf-1]
ok: [spine-2]
ok: [spine-1]
ok: [leaf-3]
ok: [leaf-2]
ok: [leaf-4]
ok: [access-2]
ok: [access-1]
ok: [access-3]
ok: [access-4]

TASK [Display Raw Output (for debugging)] **************************************
(...)

TASK [Final Result Summary] ****************************************************
(...)
TASK [Handle Critical Failure] *************************************************
(...)
PLAY RECAP *********************************************************************
leaf-1                     : ok=3    changed=0    unreachable=0    failed=0    skipped=1    rescued=0    ignored=0
leaf-2                     : ok=3    changed=0    unreachable=0    failed=0    skipped=1    rescued=0    ignored=0
leaf-3                     : ok=3    changed=0    unreachable=0    failed=0    skipped=1    rescued=0    ignored=0
leaf-4                     : ok=3    changed=0    unreachable=0    failed=0    skipped=1    rescued=0    ignored=0
spine-1                    : ok=3    changed=0    unreachable=0    failed=0    skipped=1    rescued=0    ignored=0
spine-2                    : ok=3    changed=0    unreachable=0    failed=0    skipped=1    rescued=0    ignored=0
access-1                   : ok=3    changed=0    unreachable=0    failed=0    skipped=1    rescued=0    ignored=0
access-2                   : ok=3    changed=0    unreachable=0    failed=0    skipped=1    rescued=0    ignored=0
access-3                   : ok=3    changed=0    unreachable=0    failed=0    skipped=1    rescued=0    ignored=0
access-4                   : ok=3    changed=0    unreachable=0    failed=0    skipped=1    rescued=0    ignored=0

Note:

If You want to use playbook on singular host please use --limit flag in the end of command e.g.

(ansible-venv) administrator@ubusrv2404:~/STORDIS-DataCenter/conf_ansible$ ansible-playbook -i inventory/hosts playbooks/test_connection.yaml --limit leaf-1 --ask-vault-pass

SONiC automation playbooks overview

This repository contains a comprehensive suite of Ansible playbooks designed to automate day-to-day operations, configuration changes, and state verification on Edgecore SONiC switches using both the RESTCONF API and network CLI execution paths

VLAN Management

Playbooks related to VLAN operations demonstrate Layer 2 segmentation control:

  • add_vlan.yaml - Demonstrates how to create a VLAN, assign parameters, and enable it.
  • delete_vlan.yaml - Shows how to safely remove a VLAN, including handling cases where the VLAN does not exist.
  • show_vlan.yaml - Retrieves and displays current VLAN configuration from the device.

Layer 3 & Routing Configuration

These playbooks manage IP addressing and routing tables, crucial for building underlay and overlay network boundaries

  • add_IP.yaml – Handles IP address assignment on physical or logical interfaces.
  • delete_IP.yaml – Removes IP addresses from specified interfaces.
  • create_static_route.yaml – Configures static IP routes.
  • delete_static_route.yaml – Safely purges static routes from the routing table.

Link Aggregation (PortChannels)

Automates the bundling of physical interfaces into logical groups for redundancy and bandwidth aggregation:

  • create_portchannel.yaml – Provisions logical PortChannel (LAG) interfaces on the switches.
  • add_members_portchannel.yaml – Binds physical Ethernet interfaces to an existing PortChannel group.
  • delete_portchannel_member.yaml – Removes a specific physical interface from a PortChannel bundle without destroying the logical group.
  • delete_portchannel.yaml – Completely teardowns a PortChannel interface and cleans up its logical references.

Interface Control & Operational State

Playbooks designed for interface state manipulation, physical plant management, and configuration persistence:

  • shutdown.yaml – Safely administrative toggles (up/down) physical interfaces, subinterfaces, or loopbacks.
  • write_memory.yaml – Commits the running-configuration from volatile Redis DB state directly into the startup-config (config_db.json).
  • reboot.yaml – Issues controlled system reload commands to the SONiC operating system.
  • backup.yaml – A passive, zero-downtime backup playbook that securely fetch the active /etc/sonic/config_db.json file over SSH and saves it into a directory (ansible_devices_backups) of Ansible Server

Operational Verification & Troubleshooting

A group of non-intrusive playbooks providing real-time visibility into fabric health, routing states, and path verification:

  • show_int.yaml – Uses CLI execution paths to fetch structural interface statistics and link states.
  • show_ip_int.yaml – Provides a  summary of all IP addresses assigned to physical and logical switch ports.
  • show_ip_route.yaml – Dumps the current IPv4 routing table.
  • show_portchannel.yaml – Displays active LACP/LAG bundling status and member state verification.
  • test_connection.yaml – A multi-purpose validation playbook serving as a baseline health check for SSH keys and API responsiveness.
  • traceroute.yaml – Executes traceroute to provided host.

Automation Architecture and Concepts

The Ansible environment in this project is designed to reflect real-world DataCenter automation practices.

Inventory Structure

The inventory is organized into logical groups:

  • sonic_ssh – devices managed via SSH
  • sonic_api – devices managed via RESTCONF
  • switches – Leaf and Spine topology

This structure allows flexible targeting of automation tasks depending on the protocol and use case.

The tools provides a standardized approach to:

  • Day 0 provisioning (initial setup)
  • Day 1 configuration (service deployment)
  • Repeatable and consistent automation workflows

It separates:

  • Inventory (what to configure)
  • Playbooks (how to configure)
  • Virtual Environment (ansible-venv)

The project uses an isolated Python environment to:

  • Avoid dependency conflicts
  • Ensure consistent Ansible versions
  • Provide a reproducible automation setup

The environment supports ZTP for automatic device onboarding.

This enables:

  • Automatic configuration of new SONiC devices
  • Reduced manual intervention
  • Faster lab and production deployments

Do You have more questions?

If you have any questions, encounter issues, or if any part of the configuration is unclear, please contact STORDIS Technical Support.

Our team will be happy to assist you.

You can reach us via the support portal:

https://support.stordis.com/hc/en-us

For more free resources, visit: https://stordis.com/free-resources/

Comments 0

Articles in this section