SONiC KVM Virtual Testbed
Deploy a local sonic-mgmt KVM testbed with cEOS neighbors on a single machine.
Architecture
CODEBLOCK0
Management network: br1 bridge, 10.250.0.0/24 (host at .1).
Supported Topologies
| Testbed Name | Topo | DUT | VM Base | Neighbors (raw → converged) |
|---|
| INLINECODE3 | t0 | vlab-01 | VM0100 | 4 → 1 cEOS |
| INLINECODE4 |
t1-lag | vlab-03 | VM0104 | 24 → 2 cEOS |
Use use_converged_peers: true in vtestbed.yaml to reduce cEOS containers via multi-VRF convergence (requires PR #22399 in master branch).
Prerequisites
- - Ubuntu 20.04/22.04/24.04, KVM enabled (
kvm-ok) - 30GB+ RAM (for single topo) or 20GB+ with reduced VM memory
- Docker installed, user in
docker, kvm, libvirt groups - Built
sonic-vs.img.gz from sonic-buildimage - cEOS image file (e.g.,
cEOS64-lab-4.32.5M.tar.xz) - INLINECODE12 installed on host
Deploy Procedure
1. Initial Setup (one-time)
CODEBLOCK1
2. Configure Credentials and Settings
See references/credentials.md for all config files.
Critical files (these reset on git operations — automate fixes in a script):
| File | Key Setting | Why |
|---|
| INLINECODE13 | INLINECODE14 | Host SSH access |
| INLINECODE15 |
sonic_login: "<dut_user>" | DUT SSH user (matches sonic-vs build user) |
|
group_vars/all/ceos.yml |
skip_ceos_image_downloading: true | Use local cEOS image |
|
group_vars/vm_host/main.yml |
max_fp_num: 127 | Default 4 is too low for T0/T1 |
|
veos_vtb |
ansible_user: <your_user> | Inventory host user |
|
veos | Comment out
STR-ACS-SERV-01 | Avoid dual-host conflict |
|
vars/docker_registry.yml | Remove
:443 from host |
:443 causes docker pull to hang |
|
vtestbed.yaml |
use_converged_peers: true | Enable multi-VRF convergence |
Create a fix script to re-apply all settings. Run it before EVERY testbed operation.
3. Deploy Topology
CODEBLOCK2
Duration: ~15-20 minutes (VM boot + cEOS startup).
4. Post-Deploy DUT Setup
After add-topo, the DUT boots with the build user. The multi_passwd_ssh plugin expects admin:
CODEBLOCK3
5. Deploy Minigraph
CODEBLOCK4
Duration: ~5-10 minutes.
6. Verify
CODEBLOCK5
Expected BGP state with converged peers:
- - T0: ARISTA01T1 Established (6400 prefixes), ARISTA02-04T1 Active (normal — VRF peers without physical port-channels)
- T1-LAG: 17/24 sessions up (all T0 + 1 T2 spine; remaining T2 spines Active)
7. Run Tests
CODEBLOCK6
Teardown
CODEBLOCK7
Duration: ~12-15 minutes.
Critical Gotchas
- 1. Config files revert during git and testbed operations — run fix script before EVERY command
- Remove
.bak files before add-topo — stale backups cause KeyError in converger docker import for cEOS (not docker load):443 in dockerregistryhost silently hangs docker pullsmax_fp_num: 4 is too low — set to 127br1 bridge is not persistent across reboots — add netplan config- Non-admin builds: sonic-vs uses the build machine's username, not INLINECODE41
use_converged_peers: true requires master branch (PR #22399) for auto-convergence
Troubleshooting
See references/troubleshooting.md for detailed diagnosis of common failures.
SONiC KVM 虚拟测试床
在单台机器上部署包含 cEOS 邻居的本地 sonic-mgmt KVM 测试床。
架构
宿主机 (KVM + Docker)
├── vlab-XX (运行 sonic-vs 的 KVM 虚拟机) — 被测设备
├── ceosvmsX-YVMZZ (Docker) — cEOS 邻居
├── ptf_vmsX-Y (Docker) — PTF 测试流量生成器
└── sonic-mgmt (Docker) — Ansible + pytest 框架
管理网络：br1 桥接，10.250.0.0/24（宿主机位于 .1）。
支持的拓扑
| 测试床名称 | 拓扑 | 被测设备 | 虚拟机基础 | 邻居（原始 → 收敛后） |
|---|
| vms-kvm-t0 | t0 | vlab-01 | VM0100 | 4 → 1 个 cEOS |
| vms-kvm-t1-lag |
t1-lag | vlab-03 | VM0104 | 24 → 2 个 cEOS |
在 vtestbed.yaml 中使用 useconvergedpeers: true 可通过多 VRF 收敛减少 cEOS 容器（需要 master 分支的 PR #22399）。
前提条件
- - Ubuntu 20.04/22.04/24.04，已启用 KVM（kvm-ok）
- 30GB+ 内存（单拓扑）或 20GB+（减少虚拟机内存）
- 已安装 Docker，用户属于 docker、kvm、libvirt 组
- 从 sonic-buildimage 构建的 sonic-vs.img.gz
- cEOS 镜像文件（例如 cEOS64-lab-4.32.5M.tar.xz）
- 宿主机已安装 sshpass
部署流程
1. 初始设置（一次性）
bash
克隆仓库
git clone https://github.com/sonic-net/sonic-mgmt.git ~/sonic-mgmt
cd ~/sonic-mgmt && git checkout master # 自动收敛需要 PR #22399
准备镜像
mkdir -p ~/veos-vm/images ~/sonic-vm/images
gunzip -k sonic-vs.img.gz
cp sonic-vs.img ~/veos-vm/images/ && cp sonic-vs.img ~/sonic-vm/images/
导入 cEOS（使用 docker import，而非 docker load）
xz -d cEOS64-lab-4.32.5M.tar.xz
docker import cEOS64-lab-4.32.5M.tar ceosimage:4.32.5M
管理桥接
cd ~/sonic-mgmt/ansible && sudo ./setup-management-network.sh
debian:jessie 依赖
docker pull publicmirror.azurecr.io/debian:jessie
docker tag publicmirror.azurecr.io/debian:jessie debian:jessie
sonic-mgmt 容器
./setup-container.sh -n sonic-mgmt -d /data
创建密码文件
echo abc > ~/sonic-mgmt/ansible/password.txt
2. 配置凭据和设置
所有配置文件详见 references/credentials.md。
关键文件（这些文件会在 git 操作后重置——建议编写脚本自动修复）：
| 文件 | 关键设置 | 原因 |
|---|
| groupvars/vmhost/creds.yml | vmhostuser: <youruser> | 宿主机 SSH 访问 |
| groupvars/all/creds.yml |
sonic
login: user> | 被测设备 SSH 用户（需与 sonic-vs 构建用户一致） |
| groupvars/all/ceos.yml | skipceosimagedownloading: true | 使用本地 cEOS 镜像 |
| groupvars/vmhost/main.yml | maxfpnum: 127 | 默认值 4 对 T0/T1 拓扑过低 |
| veosvtb | ansibleuser: | 清单主机用户 |
| veos | 注释掉 STR-ACS-SERV-01 | 避免双主机冲突 |
| vars/docker_registry.yml | 从主机名中移除 :443 | :443 会导致 docker pull 挂起 |
| vtestbed.yaml | useconvergedpeers: true | 启用多 VRF 收敛 |
创建修复脚本以重新应用所有设置。每次测试床操作前都必须运行。
3. 部署拓扑
bash
修复配置 + 删除旧的 .bak 文件
bash fix-configs.sh
rm -f vars/topo_.yml.bak
在 sonic-mgmt 容器内：
./testbed-cli.sh -t vtestbed.yaml add-topo password.txt
耗时：约 15-20 分钟（虚拟机启动 + cEOS 启动）。
4. 部署后被测设备设置
add-topo 完成后，被测设备以构建用户身份启动。multipasswdssh 插件期望使用 admin 用户：
bash
以构建用户身份 SSH 到被测设备
ssh user>@IP>
创建 admin 用户
sudo useradd -m -s /bin/bash -G sudo,docker admin
echo admin:password | sudo chpasswd
sudo bash -c echo admin ALL=(ALL) NOPASSWD:ALL > /etc/sudoers.d/admin
修复 Docker 套接字权限
sudo chmod 666 /var/run/docker.sock
5. 部署 Minigraph
bash
再次修复配置 + 删除 .bak 文件（它们会恢复！）
bash fix-configs.sh
rm -f vars/topo_.yml.bak
./testbed-cli.sh -t vtestbed.yaml deploy-mg NAME> veos
vtb password.txt
耗时：约 5-10 分钟。
6. 验证
bash
检查容器
docker ps | grep -E ceos|ptf
检查 BGP（deploy-mg 后使用 admin 用户）
sshpass -p password ssh admin@
show ip bgp summary
使用收敛邻居时的预期 BGP 状态：
- - T0：ARISTA01T1 已建立（6400 条前缀），ARISTA02-04T1 处于活跃状态（正常——VRF 对等体无物理端口通道）
- T1-LAG：17/24 个会话已建立（所有 T0 + 1 个 T2 骨干；其余 T2 骨干处于活跃状态）
7. 运行测试
bash
cd /data/sonic-mgmt/tests
./runtests.sh -n NAME> -d NAME> -c path> \
-f vtestbed.yaml -i ../ansible/veos_vtb
拆除
bash
bash fix-configs.sh
rm -f vars/topo_.yml.bak
./testbed-cli.sh -t vtestbed.yaml remove-topo password.txt
耗时：约 12-15 分钟。
关键注意事项
- 1. 配置文件在 git 和测试床操作期间会恢复——每次命令前运行修复脚本
- 在 add-topo 前删除 .bak 文件——过期的备份会导致收敛器出现 KeyError
- cEOS 使用 docker import（而非 docker load）
- dockerregistryhost 中的 :443 会静默导致 docker pull 挂起
- maxfpnum: 4 过低——设置为 127
- br1 桥接在重启后不持久——添加 netplan 配置
- 非 admin 构建：sonic-vs 使用构建机器的用户名，而非 admin
- useconvergedpeers: true 需要 master 分支（PR #22399）才能自动收敛
故障排除
常见故障的详细诊断请参见 references/troubleshooting.md。
