Module 1 · SONiC Architecture & Operating Model

Build an Architecture Map

60 minLabCorrelationObservationVirtualOpen-source

A correlation capstone for Module 1: for a small set of objects, build a single map that connects command → database → service → Linux representation → hardware-facing state. You end the module holding the whole system in one table.

Safety: Safe

Non-disruptive. Safe to run in the virtual lab.

This lab only reads state (plus an optional reversible static route). No disruptive actions.

The five columns you will correlate

  Command ─▶ Database ─▶ Service ─▶ Linux repr ─▶ Hardware-facing state
  (show/config) (CONFIG/APPL/ASIC/STATE)  (container/daemon)  (netdev/proc)  (ASIC_DB/counters)

Objective

• Correlate a single object across all five architectural columns.
• Do it for two different object types, including one protocol-learned route (different on-ramp).
• Produce a reusable architecture map that becomes your Module 1 reference.

Starting state

• SONiC-VS reachable; host bash + sonic-db-cli available.
• Objects to trace chosen: (a) a configured interface IP, (b) a learned/static route.

Prerequisites: Lessons 1.1–1.5 and Labs 1.2–1.4 complete. · A running BGP session or at least one learned route available (or note its absence).

Tasks

1
Set up the map template
Create a table with columns: Object | Command | Database(s) | Service/Container | Linux representation | Hardware-facing state. You will fill one row per object.
Expected:
- An empty five-column table ready to populate.
What happened internally: The template forces you to answer the five 'where does this live?' questions for every object — the core Module 1 skill.
2
Row 1 — a configured interface (front-panel port)
SONiC CLI
```
show interfaces status Ethernet0
```
SONiC DB
```
sonic-db-cli CONFIG_DB HGETALL "PORT|Ethernet0"
```
Linux
```
ip link show Ethernet0
```
SONiC DB
```
sonic-db-cli ASIC_DB SCAN 0 MATCH "*PORT*" COUNT 100
```
Expected:
- Filled row: command = show interfaces status; DB = CONFIG_DB PORT + STATE_DB; service = swss/syncd; Linux = Ethernet0 netdev; hardware-facing = SAI port object in ASIC_DB.
What happened internally: This anchors the configured path (CONFIG_DB entry) against its observed and hardware-facing forms.
3
Row 2 — a protocol-learned route (different on-ramp)
Trace a BGP-learned route. Note that it is NOT in CONFIG_DB — it enters via FRR → fpmsyncd → APPL_DB.
FRR / vtysh
```
docker exec -it bgp vtysh -c 'show ip route'
```
SONiC DBlearned route enters here, not CONFIG_DB
```
sonic-db-cli APPL_DB SCAN 0 MATCH "ROUTE_TABLE:*" COUNT 100
```
SONiC DB
```
sonic-db-cli ASIC_DB SCAN 0 MATCH "*ROUTE_ENTRY*" COUNT 100
```
Expected:
- Filled row: command = vtysh show ip route; DB = APPL_DB ROUTE_TABLE (NOT CONFIG_DB) → ASIC_DB route entry; service = bgp/fpmsyncd → swss/syncd; Linux = kernel route (if installed); hardware-facing = SAI route entry.
What happened internally: This row proves the second on-ramp from Lesson 1.5: learned state bypasses CONFIG_DB. If you looked for it in CONFIG_DB you would wrongly call it 'unconfigured'.
4
Correlate observed state and counters (the upward flow)
SONiC CLI
```
show interfaces counters
```
SONiC DB
```
sonic-db-cli STATE_DB HGETALL "PORT_TABLE|Ethernet0"
```
Expected:
- Add an 'observed' note to each row: STATE_DB/COUNTERS_DB values that traveled UP from hardware.
What happened internally: Completes the picture: intent flows down, observed state flows up. Your map should show both directions.
5
Write the one-paragraph synthesis
In your own words, describe how a single command becomes forwarding behavior, and name the one hop you would check first if it did not.
Expected:
- A short synthesis paragraph attached to the map.
What happened internally: Articulating the flow from memory is the assessment for Module 1 — it is the mental model every later module builds on.

Troubleshooting branches

If: No learned routes exist to trace

Then: Use a static route via config route add instead, and note that a static route DOES originate in CONFIG_DB — contrast it with the learned path in your map.

If: ASIC_DB SCAN returns overwhelming output

Then: Tighten the MATCH pattern and raise COUNT modestly; never fall back to KEYS *.

Cleanup / rollback

No changes are required for this observation/correlation lab.
If you added a static route for the alternative, remove it (config route del).

Lab evidence checklist

☐ Completed five-column map with at least two object rows.
☐ One row is a protocol-learned route shown to bypass CONFIG_DB.
☐ Observed-state/counters annotations showing the upward flow.
☐ A one-paragraph synthesis of command → forwarding.

Reflection

Which single column, if you could only inspect one, tells you the most about whether forwarding will work — and why is it still not sufficient alone?
How does the learned-route row change where you would start troubleshooting versus the configured-interface row?

Lab notes & observations