ipspace · ipspace · Aug 1, 2026 · Jul 22, 2026 · Jul 22, 2026 · Jul 22, 2026
diff --git a/docs/caveats.md b/docs/caveats.md
@@ -650,14 +650,23 @@ See also [](caveats-sros) caveats for further details.
 * _netlab_ RIPv2/RIPng template implements route redistribution, but only for static and connected prefixes
 * The device role on nodes with a loopback interface is automatically changed to **router** (contrary to most other network devices, OpenBSD does not allow you to reach non-connected IP addresses unless the IPv4/IPv6 forwarding is enabled).
 
-(caveats-sonic)=
-## Sonic
-
-* Sonic implementation was tested with Azure sonic-vs VM image (release 2023-11) with FRR running in a container. Other Sonic distributions might use different approaches that would require significant modifications to the configuration deployment process.
-* BGP is the only routing protocol running on Azure Sonic. The choice is hardcoded in FRR compilation flags.
-* You cannot use IBGP as there's no IGP protocol to resolve IBGP next hops, unless you believe in running IBGP over EBGP.
-* The Azure Sonic VM image has to be started with a preconfigured BGP AS number (specified in **config_db.json**); otherwise, it does not start the FRR container. That BGP process is removed during the initial BGP configuration and replaced with the actual BGP AS number specified in the lab topology.
-* _netlab_ configures BGP on Sonic through vtysh, not through **config_db**.
+(caveats-sonic-vm)=
+## SONiC Virtual Machine
+
+* SONiC implementation was tested with Azure `sonic-vs` VM image (release 2023-11) with FRR running in a container. Other SONiC distributions might use different approaches that would require significant modifications to the configuration deployment process.
+* BGP is the only routing protocol running on Azure SONiC. The choice is hardcoded in FRR compilation flags.
+* You cannot use IBGP, as there's no IGP protocol to resolve IBGP next hops, unless you believe in running IBGP over EBGP.
+* The Azure SONiC VM image has to be started with a preconfigured BGP AS number (specified in **config_db.json**); otherwise, it does not start the FRR container. That BGP process is removed during the initial BGP configuration and replaced with the actual BGP AS number specified in the lab topology.
+* _netlab_ configures BGP on SONiC through vtysh, not through **config_db**.
+
+(caveats-sonic-clab)=
+## SONiC Container
+
+The `sonic` device also runs under *containerlab* with the community `docker-sonic-vs` image; see [](build-sonic-container) for how to obtain it and how the two deployments differ.
+
+* Configuration is deployed with **docker exec** commands, not over an SSH session.
+* `docker-sonic-vs` ships `sshd` but does not start it.
+* `srv6` is control-plane and kernel-plane only: the locator and End/End.X SIDs are advertised in the IS-IS LSDB and installed as kernel `seg6local` routes, but the end-to-end SRv6 datapath does not resolve -- the same open item as FRR/IS-IS SRv6 on other platforms.
 
 (caveats-vyos)=
 ## VyOS

diff --git a/docs/labs/sonic.md b/docs/labs/sonic.md
@@ -1,21 +1,78 @@
 (build-sonic)=
-# Building a Sonic Vagrant Libvirt Box
+# Preparing a SONiC Box or Container
 
-You can use the **netlab libvirt package** command to build a Sonic Vagrant box for a Sonic virtual machine:
+_netlab_ supports SONiC running in a VM or in a container. Unfortunately, there's no ready-to-use Vagrant box or Docker container that you could pull down from a public registry; you have to [build the box](build-sonic-box) or [download and install the container](build-sonic-container) manually.
 
-* Download the **sonic-vs.img.gz** image from Azure or [sonic.software](https://sonic.software/) into an empty directory.
+(build-sonic-box)=
+## Building a SONiC Vagrant Box
+
+You can use the **netlab libvirt package** command to build a SONiC Vagrant box for a SONiC virtual machine:
+
+* Download the **sonic-vs.img.gz** image from Azure or [SONiC.software](https://SONiC.software/) into an empty directory.
 * Unzip image with **gunzip _gz-file-name_**.
 * Execute **netlab libvirt package sonic _img-file-name_** and follow the instructions
 
 ```{warning}
-If you're using a *‌netlab* release older than 1.8.2, or if you're using a Linux distribution other than Ubuntu, please [read the box-building caveats first](libvirt-box-caveats.md).
+If you're using a Linux distribution other than Ubuntu, please [read the box-building caveats first](libvirt-box-caveats.md).
 ```
 
-## Initial Device Configuration
+### Initial Device Configuration
 
 During the box-building process, you might have to disable ZTP or clean up the initial configuration database. The **netlab libvirt config sonic** command displays the build recipe:
 
 ```{eval-rst}
 .. include:: sonic.txt
    :literal:
 ```
+
+(build-sonic-container)=
+## Downloading and Installing SONiC containers
+
+SONiC also runs under *containerlab* using the community `docker-sonic-vs` container. The container is published as
+a build artifact of the [sonic-buildimage](https://github.com/sonic-net/sonic-buildimage) project, so you either download a build or make one.
+
+### Download a Published Build
+
+The SONiC container image is published as an artifact of the SONiC Azure build pipelines. From <https://sonic-build.azurewebsites.net/ui/sonic/pipelines>:
+
+* Scroll to the bottom of the pipeline list, where the **vs** platform is listed;
+* Pick a branch (for example `202405`) and open **Build History**;
+* Choose the latest build whose *Result* is successful and open **Artifacts**;
+* Open the artifact, scroll to **target/docker-sonic-vs.gz**, and download it.
+
+*containerlab* documents the same path for its
+[`sonic-vs` kind](https://containerlab.dev/manual/kinds/sonic-vs/), which uses this image. [sonic.software](https://SONiC.software/) is an unofficial index that is sometimes offered as an alternative, but it carries SONiC *installation* images (`sonic-vs.img`, used for the Vagrant box
+above) rather than the container artifact.
+
+After downloading the container, unpack and load it:
+
+```
+gunzip docker-sonic-vs.gz
+docker load -i docker-sonic-vs
+```
+
+Check the tag `docker load` restored with **docker images**; retag it to `docker-sonic-vs:latest` if necessary.
+
+### Build a SONiC Container
+
+Use this process in an empty directory to build a SONiC container from the `sonic-buildimage` repository:
+
+```
+git clone --recurse-submodules https://github.com/sonic-net/sonic-buildimage.git
+cd sonic-buildimage
+make init
+make configure PLATFORM=vs
+make target/docker-sonic-vs.gz
+docker load -i target/docker-sonic-vs.gz
+```
+
+The device definition expects the image to be tagged **`docker-sonic-vs:latest`**; override
+`defaults.devices.sonic.clab.image` in your topology if yours is tagged differently.
+
+### How SONiC Container Works
+
+`docker-sonic-vs` is a single monolithic container running FRR (`vtysh`) (unlike the VM, which runs FRR in a nested `bgp` container). The container does not start the SSH daemon; *netlab* pushes device configuration and runs validation with **docker exec** commands.
+
+The device inherits from the `frr` device and uses FRR control-plane configuration templates.
+
+See the [SONiC caveats](caveats-sonic-clab) for what is and is not supported.
diff --git a/docs/platforms.md b/docs/platforms.md
@@ -47,7 +47,7 @@
 | Nokia SR OS [❗](caveats-sros)    | sros    | best effort[^SROSBE]   |
 | Nokia SR-SIM [❗](caveats-srsim)  | srsim   | full          |
 | OpenBSD [❗](caveats-openbsd)     | openbsd | best effort   |
-| Sonic [❗](caveats-sonic)         | sonic   | minimal       |
+| SONiC [❗](caveats-sonic-vm) | sonic   | minimal       |
 | VyOS 1.4 [❗](caveats-vyos)       | vyos    | full          |
 
 [^SROSBE]: With the launch of the Nokia SR SIM, we stopped running integration tests for the SR-OS VM, assuming the behavior of the two products would be nearly identical.
@@ -144,7 +144,7 @@ You cannot use all supported network devices with all virtualization providers.
 | Nokia SR OS         |  ❌  |  ✅  |
 | Nokia SR-SIM        |  ❌  |  ✅  |
 | OpenBSD             |  [✅](build-openbsd)  |  [✅](clab-vrnetlab)  |
-| Sonic               |  [✅](build-sonic)  |  ❌  |
+| SONiC               | [✅](build-sonic-box) | [✅](build-sonic-container) |
 | VyOS                |  ✅  |  ✅[❗](caveats-vyos)  |
 
 **Note:**
@@ -211,6 +211,7 @@ Ansible playbooks included with **netlab** can deploy and collect device configu
 | Nokia SR OS[^SROS]    | ✅ | ✅ |
 | OpenBSD               | ✅ | ❌  |
 | Sonic                 | ✅ | ✅ |
+| Sonic (containerlab)  | ✅ | ✅ |
 | VyOS                  | ✅ | ✅ |
 
 **Note:** *netlab* can deploy daemon configurations, but cannot collect them. Use the **netlab initial -o** command to create daemon configuration files in a custom directory.
@@ -236,6 +237,7 @@ _netlab_ uses Ansible playbooks and device-specific task lists to deploy device
 | Junos cRPD | clab | **bash** scripts[^cRBS] |
 | KinD   | clab     | **bash** scripts copied into and executed in containers |
 | linux  | clab     | host- or container-side **bash** scripts[^LBS] |
+| Sonic (containerlab) | clab | **bash** or **vtysh** scripts[^FRRBV] over **docker exec** |
 
 [^FRRBV]: Configurations starting with a *shebang* are assumed to be Linux scripts; all other configurations are assumed to be **vtysh** scripts and get a `#!/usr/bin/vtysh -f` shebang prepended to them.
 
@@ -297,6 +299,7 @@ The following system-wide features are configured on supported network operating
 | Nokia SR OS[^SROS]       | ✅  | ✅  | ✅  | ✅  | ✅  |
 | OpenBSD                  | ✅  | ✅  |  ❌  | ✅  | ✅  |
 | Sonic                    | ✅  | ✅  |  ❌  | ✅  | ✅  |
+| Sonic (containerlab)     | ✅  | ✅  |  ❌  | ✅  | ✅  |
 | VyOS                     | ✅  | ✅  | ✅  | ✅  | ✅  |
 
 [^HIF]: Some Linux-based devices can also use interface names in host names. See [/etc/hosts file on Linux](linux-hosts) for more details.
@@ -328,6 +331,7 @@ The following interface parameters are configured on supported network operating
 | Nokia SR OS[^SROS]    | ✅  |  ❌  | ✅  | ✅  |
 | OpenBSD               | ✅  |  ❌  | ✅  |  ❌  |
 | Sonic                 | ✅  | ✅  | ✅  | ✅  |
+| Sonic (containerlab)  | ✅  | ✅  | ✅  | ✅  |
 | VyOS                  | ✅  |  ❌  | ✅  | ✅  |
 
 (platform-initial-addresses)=
@@ -358,6 +362,7 @@ The following interface addresses are supported on various platforms; most daemo
 | Nokia SR OS[^SROS]    | ✅  | ✅  | ✅  |  ❌  |
 | OpenBSD               | ✅  | ✅  |  ❌  |  ❌  |
 | Sonic                 | ✅  | ✅  | ✅  |  ❌  |
+| Sonic (containerlab)  | ✅  | ✅  | ✅  |  ❌  |
 | VyOS                  | ✅  | ✅  | ✅  |  ❌  |
 
 ```{tip}
@@ -404,6 +409,7 @@ Routing protocol [configuration modules](module-reference.md) are supported on t
 | Nokia SR OS[^SROS]    | ✅   |  ✅   |   ❌  | ✅  | ✅  |
 | OpenBSD               | ✅   |   ❌   |   ❌  | ✅   | ✅   |
 | Sonic                 |  ❌   |   ❌   |   ❌  | ✅  |   ❌  |
+| Sonic (containerlab)  | ✅   |  ✅   |   ❌  | ✅  |  ✅  |
 | VyOS                  | ✅   |  ✅   |   ❌  | ✅  |   ❌  |
 
 These devices support additional control-plane protocols or BGP address families:
@@ -431,6 +437,7 @@ These devices support additional control-plane protocols or BGP address families
 | Mikrotik RouterOS 7   | ✅  |  ❌  | ✅  |  ❌  |
 | Nokia SR Linux        | ✅  | ✅  | ✅  | ✅  |
 | Nokia SR OS[^SROS]    | ✅  | ✅  | ✅  | ✅  |
+| Sonic (containerlab)  | ✅  | ✅  | ✅  | ✅  |
 | VyOS                  | ✅  | ✅  | ✅  |  ❌  |
 
 **Notes:**
@@ -450,6 +457,7 @@ The layer-2 control plane [configuration modules](module-reference.md) are suppo
 | dnsmasq                   | ❌  | ✅ |
 | FRR                       | ✅ | ✅ |
 | Linux                     | ❌  | ✅ |
+| Sonic (containerlab)      | ❌  | ✅ |
 
 (platform-dataplane-support)=
 The data plane [configuration modules](module-reference.md) are supported on these devices[^NSM]:
@@ -482,6 +490,7 @@ The data plane [configuration modules](module-reference.md) are supported on the
 | Nokia SR Linux        | ✅ | ✅ | ✅ | ✅ | ✅ |  ❌ |
 | Nokia SR OS[^SROS]    | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
 | OpenBSD               | ✅ | ❌ | ✅ | ❌  | ❌ |
+| Sonic (containerlab)  | ✅ | ✅ | ✅ | ✅ | ✅ | ✅[❗](caveats-sonic-clab) |
 | VyOS                  | ✅ | ✅ | ✅ | ✅ |  ❌ |  ❌ |
 
 (platform-services-support)=
@@ -525,6 +534,7 @@ Core *netlab* functionality and all multi-protocol routing protocol configuratio
 | Nokia SR OS[^SROS]    | ✅ | ✅ | ❌ | ✅ | ✅ |
 | OpenBSD               | ✅ | ❌ | ❌ | ✅ | ❌ |
 | Sonic                 |  ❌ | ❌ | ❌ | ✅ | ❌ |
+| Sonic (containerlab)  | ✅ | ✅ | ❌ | ✅ | ✅ |
 | VyOS                  | ✅ | ✅ | ❌ | ✅ | ❌ |
 
 (platform-unknown)=

diff --git a/docs/release/26.08.md b/docs/release/26.08.md
@@ -9,8 +9,6 @@
 (release-26.08)=
 ## New Functionality
 
-* Something new
-
 **Minor improvements**
 
 * Something new
@@ -21,6 +19,9 @@
 Arista EOS:
 * Something new
 
+SONiC:
+* SONiC can run under *containerlab* with the community `docker-sonic-vs` container ([details](build-sonic-container), [caveats](caveats-sonic-clab)).
+
 (release-26.08-device-fixes)=
 ## Fixes in Device Settings and Configuration Templates
 

diff --git a/netsim/ansible/tasks/deploy-config/sonic-clab.yml b/netsim/ansible/tasks/deploy-config/sonic-clab.yml
@@ -0,0 +1,22 @@
+# SONiC (containerlab, docker-sonic-vs) config deploy.
+#
+# Reached over Ansible's 'docker' connection plugin (ansible_connection: docker in
+# sonic.yml), so 'command'/'shell' here already execute *inside* the node container --
+# no docker exec wrapping needed.
+#
+# SONiC config is either a bash script of 'config' CLI commands (initial: starts with
+# #!/bin/bash) or an FRR vtysh config (routing modules), same convention as the package
+# 'frr'/'sonic' devices.
+- template:
+    src: "{{ config_template }}"
+    dest: /tmp/config.sh
+
+- set_fact: deployed_config={{ lookup('template',config_template) }}
+
+- name: "run /tmp/config.sh to deploy {{ netsim_action }} config from {{ config_template }}"
+  command: bash /tmp/config.sh
+  when: not ansible_check_mode and ("#!/bin/bash" in deployed_config or "#!/bin/sh" in deployed_config)
+
+- name: "run vtysh -f to deploy {{ netsim_action }} config from {{ config_template }}"
+  command: vtysh -f /tmp/config.sh
+  when: not ansible_check_mode and not ("#!/bin/bash" in deployed_config or "#!/bin/sh" in deployed_config)
diff --git a/netsim/ansible/tasks/readiness-check/sonic_clab.yml b/netsim/ansible/tasks/readiness-check/sonic_clab.yml
@@ -0,0 +1,9 @@
+# Wait for docker-sonic-vs's vtysh (and the underlying config_db redis) to answer before we try
+# to push any configuration. Reached over the 'docker' connection plugin -- no SSH involved.
+- name: Wait for SONiC vtysh to become ready
+  command: vtysh -c 'show version'
+  register: sonic_ready
+  until: sonic_ready.rc == 0
+  retries: 40
+  delay: 3
+  changed_when: false
diff --git a/netsim/ansible/templates/bgp/sonic-clab.j2 b/netsim/ansible/templates/bgp/sonic-clab.j2
@@ -0,0 +1,12 @@
+{#
+  SONiC BGP, container deployment.
+
+  The VM template (bgp/sonic.j2) opens with a "no router bgp" reset. docker-sonic-vs starts with no
+  BGP process at all, and vtysh rejects that line with rc 13 ("Failure to communicate[13] to bgpd,
+  line: no router bgp" / "% No BGP process is configured"), which fails the whole config deploy.
+
+  Before the device was parented to FRR the container had no bgp template of its own and fell
+  through to bgp/frr.j2. This file keeps that behaviour now that bgp/sonic.j2 would otherwise be
+  selected by the <device>.j2 lookup.
+#}
+{% include "frr.j2" +%}