mirror of
https://github.com/dtzp555-max/aci-sim.git
synced 2026-07-19 09:46:33 +00:00
taodengandClaude Fable 5
7e9a175ce6
aci-sim is a stateful REST simulator of a 2-site Cisco ACI fabric (per-site APIC + ND/NDO management planes) — for testing ACI automation (Ansible cisco.aci / cisco.mso, aci-py, custom REST clients) and CI gates without real hardware. Highlights: APIC + NDO REST surface served from one in-memory MIT built from a declarative topology.yaml; port mode + sandbox (real per-device IPs on :443) run modes; LLDP/CDP neighbor visibility; NDO->APIC deploy mirror (multi-site templates materialize onto the target sites' APIC stores); real-APIC fvBD default attributes; file-backed state save/restore; an `aci-sim` CLI (validate/show/graph/run/new/init/lldp); and an 888-test suite. History squashed for the public release. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
998 lines
60 KiB
Markdown
998 lines
60 KiB
Markdown
# Changelog
|
||
|
||
All notable changes to this project are documented in this file.
|
||
|
||
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
|
||
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html)
|
||
(pre-1.0: minor bumps may include breaking changes to the sim's behavior).
|
||
|
||
## [0.16.0] - 2026-07-05
|
||
|
||
### Changed
|
||
- **Project renamed `aci-fabric-sim` -> `aci-sim`.** Import package
|
||
`aci_fabric_sim` -> `aci_sim`, PyPI distribution name, GitHub repo, and the
|
||
`aci-sim` CLI entry point are now all unified under one name (previously
|
||
the package and CLI were `aci-sim`/`aci_sim` while the repo/distribution
|
||
metadata still said `aci-fabric-sim` in places). No behavior change —
|
||
every module path under `aci_sim/` and every documented command are
|
||
unchanged; this is a naming-consistency cleanup ahead of the repo going
|
||
public.
|
||
|
||
## [0.15.0] - 2026-07-05
|
||
|
||
### Added
|
||
- **NDO -> APIC deploy mirror.** `POST /mso/api/v1/task` (the deploy/undeploy
|
||
request `cisco.mso.ndo_schema_template_deploy` sends) was a pure
|
||
acknowledgment no-op — it never materialized the deployed schema
|
||
template's VRFs/BDs/ANPs/EPGs/binds into the target sites' APIC stores, so
|
||
a multi-site tenant created purely through NDO never appeared on the APIC
|
||
side. `mirror_template_to_sites()` (`aci_sim/ndo/deploy_mirror.py`) closes
|
||
this gap: given the NDO state, a template name, and a site_id ->
|
||
ApicSiteState map, it walks the owning schema's template plus each
|
||
associated SITE entry (host-based-routing overlay, domain associations,
|
||
static ports) and upserts the equivalent `fvCtx`/`fvBD`/`fvAp`/`fvAEPg` (+
|
||
children) MOs into every target site's `MITStore`, reusing the same
|
||
DN/attribute conventions the boot-time builders and the direct POST-write
|
||
path already use. Also creates a per-site `fvTenant` shadow so the tenant
|
||
itself — not just its child objects — is visible on each target site's
|
||
APIC after an NDO-driven deploy (previously only the site passed via
|
||
`--apic` in ad hoc testing got the tenant; the other site's `fvTenant` was
|
||
missing entirely).
|
||
- **`fvBD` create-time default attributes.** A POSTed BD now carries the
|
||
same default attribute set a real APIC assigns at creation
|
||
(`epMoveDetectMode="garp"`, `hostBasedRouting="no"`, `mtu="9000"`, …)
|
||
instead of only the attributes the caller explicitly set — so
|
||
host-based-routing and EP-move-detection now show up correctly in the
|
||
APIC BD view for a BD created via a plain POST, matching real-APIC
|
||
behavior.
|
||
|
||
## [0.14.0] - 2026-07-05
|
||
|
||
### Added
|
||
- **File-backed state persistence.** New `POST /_sim/save/{name}` and
|
||
`POST /_sim/load/{name}` routes on both the APIC plane
|
||
(`aci_sim/control/admin.py`) and the NDO plane (`aci_sim/ndo/app.py`)
|
||
serialize/restore each plane's store to/from disk under `SIM_STATE_DIR`
|
||
(default `~/.aci-sim/state`) — unlike the existing in-memory
|
||
`snapshot`/`restore`, this state survives a full sim restart.
|
||
`scripts/sim-state.sh {save|restore} <name>` is the whole-fabric wrapper:
|
||
it derives each plane's address the same way `scripts/sandbox-up.sh` does
|
||
and hits every plane's endpoint (both APIC sites + NDO) in one command.
|
||
New module `aci_sim/control/persist.py` implements the serialization: a
|
||
`MITStore` flattens to a JSON list of `{class, attrs}` dicts (MOs stored
|
||
in the MIT are always childless — the parent/child hierarchy lives only
|
||
in the store's own index — so replaying them through `MITStore.add`
|
||
faithfully rebuilds it); `NdoState`'s persisted fields are deep-copied to
|
||
a JSON-friendly dict and reapplied onto the same live object via
|
||
`setattr` (the running NDO app closes over that object's identity, so a
|
||
reload must mutate in place rather than swap in a new instance).
|
||
|
||
## [0.13.2] - 2026-07-04
|
||
|
||
### Fixed
|
||
- **NDO `serviceNodeRef` resolved to a string ref (was a dict).** The
|
||
service-graph -> contract bind path stored `serviceNodeRef` as a dict-form
|
||
ref while every other mirror/lookup path expects the canonical NDO string
|
||
ref shape (`/schemas/{id}/templates/{tmpl}/{category}/{name}`); re-running
|
||
the bind against an already-bound contract was not idempotent because the
|
||
two representations never compared equal. Fixed to resolve/store the
|
||
string form, matching the rest of the NDO ref conventions.
|
||
|
||
## [0.13.1] - 2026-07-04
|
||
|
||
### Fixed
|
||
- **`pip install` was completely broken — now fixed (critical, packaging).** A
|
||
from-scratch clean-venv E2E revealed that `pip install aci-sim` / `pip
|
||
install .` produced an unusable package: (1) **zero runtime dependencies** were
|
||
declared to pip — `pyproject.toml` had `dynamic = ["dependencies"]` with no
|
||
`[tool.setuptools.dynamic]` source, so fastapi/uvicorn/pydantic/pyyaml were
|
||
never installed (the CLI crashed on the first third-party import, `import
|
||
yaml`); and (2) **every subpackage was omitted** — `packages =
|
||
["aci_sim"]` shipped only the top-level module, dropping
|
||
`topology`/`build`/`rest_aci`/`ndo`/`mit`/`runtime`/`query`/`control`. The dev
|
||
workflow (`pip install -e .` + `pip install -r requirements.txt`) masked both.
|
||
Fix: static `[project.dependencies]` (fastapi/uvicorn[standard]/pydantic/pyyaml),
|
||
a `[project.optional-dependencies].dev` extra (httpx/pytest/pytest-asyncio), and
|
||
`[tool.setuptools.packages.find] include = ["aci_sim*"]` to ship every
|
||
subpackage. Verified end-to-end: a fresh venv `pip install .` now yields a
|
||
working `aci-sim` CLI + importable package.
|
||
|
||
## [0.13.0] - 2026-07-04
|
||
|
||
### Added
|
||
- **Admin account in the setup wizard + `aci-sim run` credential enforcement.**
|
||
`aci-sim init`'s new **Step 0: Admin account** prompts for the fabric admin
|
||
username/password (default `admin`/`cisco`) and whether NDO shares the APIC
|
||
account (default yes), writing them into a new topology.yaml `auth:` section
|
||
(`schema.Auth`: `username`/`password` + optional `ndo_username`/`ndo_password`).
|
||
`aci-sim run` resolves these into `SIM_USERNAME`/`SIM_PASSWORD` for the
|
||
supervisor via the new `cli.resolve_admin_credentials()`, so the APIC plane
|
||
then ENFORCES them (`aaaLogin` returns 401 on a username/password mismatch).
|
||
**Precedence** (highest first): an explicit `SIM_USERNAME`/`SIM_PASSWORD`
|
||
already in the environment wins (the CI/override escape hatch), else the
|
||
topology `auth:` section, else `auth.py`'s own `admin`/`cisco` default.
|
||
`aci-sim run` prints a one-line auth-source banner at startup (the username +
|
||
where it came from, never the password).
|
||
- The NDO plane stays **lenient by design** — `/login` and `/api/v1/auth/login`
|
||
accept any credential and never validate the bearer token (cisco.mso/aci-py
|
||
client compatibility). The shared account is recorded/reported but not
|
||
enforced there; a split `ndo_username`/`ndo_password` is informational.
|
||
|
||
### Notes
|
||
- Purely additive / backward-compatible: a topology.yaml with **no** `auth:`
|
||
section still validates (`Topology.auth: Auth | None = None`) and `aci-sim
|
||
run` injects nothing — behavior is identical to 0.12.0.
|
||
- 24 new tests (`tests/test_admin_account.py`) cover the wizard's `auth:`
|
||
output (defaults / custom / split-NDO), `resolve_admin_credentials`
|
||
precedence, `build_run_env_argv` injection + filesystem purity, end-to-end
|
||
`aaaLogin` enforcement of a rotated password (incl. the stale default now
|
||
failing) with NDO still lenient, and no-`auth:` backward-compat.
|
||
|
||
## [0.12.0] - 2026-07-04
|
||
|
||
### Added
|
||
- **LLDP/CDP neighbor fidelity — enriched adjacencies + materialized container MOs + CLI.**
|
||
`lldpAdjEp`/`cdpAdjEp` previously carried only `sysName`/`mgmtIp`; both are now enriched with
|
||
real-APIC-shaped fields — `lldpAdjEp` gains `portIdV` (the NEIGHBOR's own port), `portIdT`,
|
||
`chassisIdT`, `chassisIdV` (a deterministic per-node MAC via new `build/neighbors.py:node_mac`),
|
||
`sysDesc` (`"{model} running {version}"` for a switch neighbor, `"Cisco APIC"` for a controller),
|
||
`capability`, `id`, `ttl`; `cdpAdjEp` gains `devId` (== `sysName`), `portId`, `platId`, `ver`,
|
||
`cap`. Purely additive — `sysName`/`mgmtIp` are unchanged, so every pre-existing consumer
|
||
(autoACI, this repo's own tests) keeps working untouched.
|
||
New container classes `lldpInst`/`lldpIf`/`cdpInst`/`cdpIf` are now materialized (one `*Inst`
|
||
per switch node with any adjacency, one `*If` per adjacency-bearing local port), fixing a bug
|
||
where a deep-root subtree query (`GET /api/mo/topology/pod-1/node-101/sys/lldp/inst.json?
|
||
query-target=subtree&target-subtree-class=lldpAdjEp`) returned `totalCount=0` — the query
|
||
engine's `run_mo_query` short-circuits to `([], 0)` when the root DN has no MO of its own, and
|
||
`.../sys/lldp/inst` previously had none. `/api/class/lldpInst.json`/`lldpIf.json`/`cdpInst.json`/
|
||
`cdpIf.json` now also return real results.
|
||
All three adjacency-construction sites (`build/cabling.py` spine<->leaf links, `build/fabric.py`
|
||
APIC<->leaf attachment, `rest_aci/writes.py`'s dynamic node-registration reaction) now share one
|
||
helper module, `build/neighbors.py` (`add_adjacency`/`add_switch_adjacency` +
|
||
`ensure_lldp_containers`/`ensure_cdp_containers`), so a dynamically-registered node (via POST
|
||
`fabricNodeIdentP` or `/_sim/add-leaf`) gets the identical enriched/materialized treatment a
|
||
boot-time-seeded node gets — verified by `tests/test_lldp_cdp_fidelity.py`'s dynamic-path tests.
|
||
New CLI subcommand `aci-sim lldp [topology] [--site NAME] [--node ID] [--cdp] [--json]` prints a
|
||
`show lldp neighbors`-style grouped table (or CDP with `--cdp`, or structured JSON with `--json`).
|
||
`tests/test_lldp_cdp_fidelity.py` (20 tests): container materialization, the subtree-query
|
||
regression fix, bidirectional `portIdV` consistency across a spine<->leaf link, `cdpAdjEp.devId
|
||
== sysName`, backward-compat field presence, the dynamic-registration path, and the CLI (text/
|
||
`--json`/`--cdp`/a graceful non-existent node id).
|
||
|
||
## [0.11.0] - 2026-07-04
|
||
|
||
### Added
|
||
- **APIC query subscriptions + websocket push-on-change.** Real APIC's subscription mechanism,
|
||
the piece the "Monitoring/observability integration" use case (README §1) needed to move past
|
||
polling-only. `GET /api/class/{cls}.json`, `GET /api/mo/{dn}.json` (+ `/api/node/mo/{dn}` alias),
|
||
and `GET /api/node/class/{...}` all now accept `?subscription=yes`, returning the *unchanged*
|
||
query result plus a top-level `subscriptionId` string (opt-in only — a plain query with no
|
||
`?subscription=yes` is byte-identical to before this feature, no key added, no behavior change).
|
||
`GET /socket<token>` (real APIC's literal path shape, `<token>` = the `APIC-cookie` session
|
||
token) opens a websocket; when a subscribed class or DN/subtree changes via `POST`/`DELETE`,
|
||
a `{"subscriptionId":[...],"imdata":[{<class>:{"attributes":{...,"status":"created|modified|
|
||
deleted","dn":...}}}]}` event pushes over that connection. `GET /api/subscriptionRefresh.json?
|
||
id=<id>` keeps a subscription alive past its 90s TTL (matching real APIC), always 200 even for
|
||
an unknown id. Disconnecting the websocket drops that connection's subscriptions. New module
|
||
`aci_sim/rest_aci/subscriptions.py` (in-memory registry + notify — module-level state,
|
||
same pattern as `auth.py`'s session store); write handlers stay fully synchronous and simply
|
||
call `notify()`, which enqueues onto each live connection's own `asyncio.Queue` — the websocket
|
||
route drains that queue independently, so a write request never awaits network I/O on some
|
||
other client's socket. `tests/test_subscriptions.py` (12 tests): subscribe returns
|
||
`subscriptionId`; a plain query has zero shape change; websocket created/modified/deleted push
|
||
for a subscribed class; an unsubscribed class does not push; DN-scoped subscriptions match
|
||
subtree writes; refresh returns 200 (known and unknown id); an unknown-token websocket is
|
||
rejected; disconnect cleans up subscriptions. See README §10a and `docs/CONTRACT.md` §2a for
|
||
the full contract.
|
||
|
||
## [0.10.0] - 2026-07-04
|
||
|
||
### Added
|
||
- **OOB management gateway — a real MO instead of a discarded value.** Every node already got
|
||
`topSystem.oobMgmtAddr` (the OOB IP), but no gateway was modeled anywhere; `aci-sim init`'s wizard
|
||
even asked for one per site, but discarded the answer (no schema field, no MO — just an
|
||
informational summary line). Real APIC models the OOB address + gateway in the special `mgmt`
|
||
tenant (`uni/tn-mgmt/mgmtp-default/oob-default`, a `mgmtOoB` EPG) with one `mgmtRsOoBStNode` child
|
||
per node. New `Site.oob_gateway: Optional[str]` schema field (optional, default `None`, validated
|
||
as a real IP address) plus a new builder `aci_sim/build/mgmt.py` (registered in
|
||
`build/orchestrator.py`) that emits the minimal faithful scaffolding for every site:
|
||
`fvTenant`(mgmt) → `mgmtMgmtP`(default) → `mgmtOoB`(default) → one `mgmtRsOoBStNode`(tDn,addr,gw)
|
||
per node (switches AND controllers), `addr` = the node's OOB IP + mask (mask from
|
||
`fabric.oob_subnet` if set, else `/24` by default — deliberately not `fabric.oob_pool`'s wider
|
||
`/16`, which spans multiple pods/sites), `gw` = `site.oob_gateway` (empty string, never an invented
|
||
default, when unset).
|
||
- `aci-sim init`'s wizard now WRITES each site's answered OOB gateway into
|
||
`topology_dict["sites"][i]["oob_gateway"]` instead of discarding it; `aci-sim show` surfaces
|
||
`oob_gateway=<value|->` per site.
|
||
- `tests/test_oob_gateway.py` (25 tests): schema default/validation, builder MO shape (mgmtRsOoBStNode
|
||
per node, addr/gw correctness, mask derivation, empty-gw-when-unset), wizard write-through
|
||
(defaults run, custom answers, multi-site per-site gateways), and backward compatibility (repo
|
||
`topology.yaml` builds unchanged, existing `topSystem`/`fabricNode` attrs untouched, new
|
||
mgmt-tenant scaffolding is purely additive).
|
||
|
||
### Changed
|
||
- `docs/CONTRACT.md`: new "Mgmt tenant — OOB management" entry cataloging `fvTenant`(mgmt)/
|
||
`mgmtMgmtP`/`mgmtOoB`/`mgmtRsOoBStNode`.
|
||
- `README.md` §6c (Tier-3 config reference) documents `site.oob_gateway`; §5 `aci-sim show`/
|
||
`aci-sim init` sample output updated to include `oob_gateway=...`.
|
||
|
||
## [0.9.0] - 2026-07-04
|
||
|
||
### Added
|
||
- **`aci-sim graph` — self-contained SVG/HTML topology diagram.** New `aci_sim/graph.py`
|
||
renders the *built* fabric (spines, leaves, border leaves with vPC-pair grouping, per-site
|
||
controllers, and — for multi-site topologies with `isn.enabled: true` — a single ISN cloud node
|
||
with spine→ISN uplinks) as hand-generated, dependency-free SVG: no CDN, no local server, no npm
|
||
build step. `-o FILE.html` wraps the SVG in a minimal inline-CSS HTML shell (double-click to open
|
||
in any browser); `-o FILE.svg` writes raw SVG. Layout is a hand-computed tiered ACI hierarchy
|
||
(spine row → leaf row → border-leaf row → controller row per site, sites placed side by side, ISN
|
||
cloud centered above/between them for multi-site) plus a role→color legend and a title bar
|
||
(fabric name, site count, node count). Purely additive: no change to `topology/schema.py` or any
|
||
`build/*.py` builder — `graph.py` only reads the validated `Topology` model and re-derives the
|
||
same spine×leaf mesh `build/cabling.py::cabling_links()` produces, so the diagram always matches
|
||
the fabric that would actually be built.
|
||
- **Visual language matched to autoACI's topology view** (studied read-only on autoACI's
|
||
`frontend/src/composables/useTopologyStyles.js` + `backend/routers/topology.py`; NOT imported —
|
||
autoACI's implementation is Vue+cytoscape, this is a standalone Python reimplementation of the
|
||
same colors/hierarchy): spine = `#2563eb` blue, leaf/border-leaf = `#16a34a` green, controller =
|
||
`#d97706` amber, ISN cloud = `#475569` slate; rounded-rect nodes with a subtle drop shadow;
|
||
cabling links solid gray, ISN links dashed orange, vPC-peer links dotted slate.
|
||
- Complements `aci-sim show` (text inventory) with a visual counterpart — `show` for machine/human
|
||
text detail, `graph` for at-a-glance topology shape.
|
||
- `tests/test_graph.py` (18 tests): node/link counts against the repo's default 2-site topology,
|
||
ISN-cloud presence for multi-site and absence for a generated 1-site topology, a generated 3-site
|
||
topology rendering all 3 sites, role-color presence, well-formed-XML checks via `xml.etree`, and
|
||
`aci-sim graph` CLI coverage (HTML/SVG output, default paths, missing-file and bad-extension
|
||
errors) — no browser required anywhere in the suite.
|
||
|
||
## [0.8.1] - 2026-07-04
|
||
|
||
### Added
|
||
- **CI gate example + Use Cases docs.** New `examples/ci/`: `assert_mit.py` (a tiny MIT-end-state
|
||
assertion helper — `class:`/`mo:`/`absent:`/`attr:` checks, exit code = failed-check count, works
|
||
against the sim OR a real APIC) and `github-actions-aci-gate.yml` (copy-pasteable start-sim →
|
||
run-automation → assert workflow). README §1 gains a "More applications" table (SDK/provider
|
||
testing, change pre-flight, REST-contract testing, multi-tool interop, monitoring, scale) with
|
||
honest ready/partial/extension status, plus an explicit out-of-scope note.
|
||
|
||
## [0.8.0] - 2026-07-04
|
||
|
||
### Added
|
||
- **`aci-sim init` — interactive APIC-setup-style topology wizard (PR-22).** Modeled on the real APIC
|
||
first-boot setup dialog: prompts each field with a suggested default shown in `[brackets]` (ENTER
|
||
accepts it, or type a custom value), then writes a `topology.yaml` and auto-runs `aci-sim validate` on
|
||
the result. Flow: Step 0 deployment type (`1) Single fabric` / `2) Multi-site` — real APIC's "multi-pod"
|
||
choice is deliberately NOT offered, since this sim builds no true multi-pod fabric); Step 1 per-site
|
||
fields (name, site ID, BGP AS, pod ID, controller count 1-5, APIC OOB mgmt IP, then — if
|
||
controllers > 1 — one prompt per additional controller each suggesting the previous IP + 1 via
|
||
`ipaddress.ip_address(prev) + 1`, mapping to PR-21's `Site.controller_ips`; OOB gateway asked once per
|
||
site; TEP pool/infra VLAN/GIPo pool/OOB subnet/spine-leaf-border counts); Step 2 multi-site-only
|
||
(NDO mgmt IP, ISN OSPF area/MTU); Step 3 summary + confirm + write + auto-validate. Reuses
|
||
`generate_topology()` — the SAME generator `aci-sim new` calls — as a thin interactive front-end; no
|
||
topology-emission logic is duplicated.
|
||
- **Non-interactive wizard modes**: `--defaults` accepts every suggested default without prompting, and is
|
||
also auto-enabled whenever stdin is not a TTY (so `aci-sim init` never hangs in CI/scripts even without
|
||
the flag). `--answers FILE` accepts a YAML or JSON file of pre-filled field-name -> value answers;
|
||
listed fields are used verbatim, unlisted fields still prompt/default as usual — enables fully scripted,
|
||
reproducible topology generation (e.g. `site1_controllers: "3"` to script a specific cluster size).
|
||
- **`generate_topology()` widened (PR-22, additive, backward compatible)**: new optional `site_overrides`
|
||
parameter — a `list[dict]` (one entry per site) shallow-merged onto each auto-derived site definition
|
||
(name/id/apic_host/mgmt_ip/fabric_name/asn/pod/controllers/controller_ips) — lets a caller (the wizard)
|
||
express per-site heterogeneity, including PR-21's `controller_ips`, which the existing flat
|
||
`--controllers`/`--apic-ip-base` flags cannot express per-site. `leaves_per_site`/`spines_per_site`/
|
||
`border_pairs` now also accept a `list[int]` (one count per site) in addition to the pre-existing
|
||
single `int` applied uniformly to every site — needed because the wizard asks spine/leaf/border-pair
|
||
counts per site. Both widenings are fully backward compatible: every pre-PR-22 caller (including
|
||
`aci-sim new` and every existing test) passes a plain `int`/omits `site_overrides`, and gets
|
||
byte-identical output to before.
|
||
|
||
### Changed
|
||
- CLI help/argparse: new `init` subcommand registered alongside `validate`/`show`/`run`/`new`.
|
||
|
||
## [0.7.0] - 2026-07-04
|
||
|
||
### Changed
|
||
- **BREAKING (node counts): `Site.controllers` default 3 → 1 — single-APIC-per-site by design (PR-21).**
|
||
APIC cluster size is irrelevant to Ansible playbook *deployment* testing (a playbook targets exactly one
|
||
APIC endpoint); cluster size only matters for cluster-health/appliance-vector tooling such as autoACI's
|
||
`health_score.py`. `controllers` remains fully configurable, now range-validated **1-5**
|
||
(`Topology.normalize_and_validate`) — set `controllers: 3` on a site to restore the old default /
|
||
exercise multi-controller `infraWiNode`/cluster-health semantics. This changes every site's generated
|
||
`fabricNode`/`topSystem` count (−2 per site at the new default vs. the old one), `fabricLink`/
|
||
`lldpAdjEp`/`cdpAdjEp` counts for the APIC↔leaf attachment, and `infraWiNode` count (`controllers²`).
|
||
All existing test assertions and e2e scripts encoding the old counts were recomputed and updated — see
|
||
`docs/DESIGN.md`'s "PR-21" section for the full before/after accounting.
|
||
- `aci-sim new`'s `--controllers` flag and `generate_topology()`'s `controllers` parameter both default to
|
||
`1` now (was `3`), matching the new `Site.controllers` schema default.
|
||
- The shipped root `topology.yaml`'s commented `# controllers: N` example line now shows the current
|
||
default (`1`) instead of the pre-PR-21 default (`3`); a new commented block shows the
|
||
`controllers: 3` + `controller_ips: [...]` opt-in shape for multi-controller topologies.
|
||
|
||
### Added
|
||
- **`Site.controller_ips: Optional[list[str]]` — explicit per-controller OOB mgmt IPs (PR-21).** When
|
||
set, `controller_ips[i]` is controller `i+1`'s `topSystem.oobMgmtAddr` verbatim (length must equal
|
||
`controllers`, each entry a valid IP — validated). When unset (default), OOB IPs are auto-derived
|
||
**sequentially from `site.mgmt_ip`**: controller 1 = `mgmt_ip`, controller 2 = `mgmt_ip`+1, controller 3
|
||
= `mgmt_ip`+2, etc., via the new `Site.controller_oob_ips()` helper (`topology/schema.py`). Falls back
|
||
to the legacy per-node `oob_ip(pod, cid)` scheme when `mgmt_ip` is also unset, so a topology setting
|
||
neither field keeps byte-identical controller OOB addresses to pre-PR-21. Wired into
|
||
`build/fabric.py`'s controller `topSystem.oobMgmtAddr` and the leaf-side `lldpAdjEp`/`cdpAdjEp.mgmtIp`
|
||
(kept consistent — both read the same per-call derived list). Surfaced in `aci-sim show`/`show --json`
|
||
as `controller_ips`. The sim's REST server still binds to exactly one address per site (`mgmt_ip`,
|
||
controller-1 / the cluster VIP) regardless of `controllers` — it never runs N separate APIC processes;
|
||
`controllers`/`controller_ips` only affect the simulated fabricNode/topSystem/infraWiNode data.
|
||
- README "Configuration" section (§6a) now documents the single-APIC design intent explicitly, and a new
|
||
`docs/DESIGN.md` "PR-21" section covers the full before/after node-count accounting and verification.
|
||
|
||
## [0.6.0] - 2026-07-04
|
||
|
||
### Added
|
||
- **Tier-3 fine-tuning parameters (PR-20) — the last planned param tier.**
|
||
New optional `topology.yaml` fields — all defaulted to pre-existing
|
||
hardcoded behavior (or the real ACI factory default where no prior
|
||
hardcoded value existed), so the existing repo `topology.yaml` validates
|
||
and builds unchanged:
|
||
- `bd.mac` (per-BD, optional) and `fabric.default_bd_mac` (fabric-wide,
|
||
default `"00:22:BD:F8:19:FF"` — the exact literal `build/tenants.py`
|
||
already hardcoded for every BD pre-PR-20) — now threaded into
|
||
`fvBD.mac`, replacing that hardcode. Resolution order: `bd.mac or
|
||
fabric.default_bd_mac`. Byte-identical output when both are unset.
|
||
- `l3out.csw_peer.keepalive`/`.hold` (defaults `60`/`180`, real ACI
|
||
defaults) — threaded into `build/l3out.py`'s `bgpPeerP.keepAliveIntvl`/
|
||
`holdIntvl` (previously not carried on that MO at all). `hold` must
|
||
exceed `keepalive`.
|
||
- `isn.ospf_hello`/`.ospf_dead` (defaults `10`/`40`, real ACI defaults) —
|
||
threaded into `build/underlay.py`'s `ospfIf.helloIntvl`/`deadIntvl`
|
||
(previously not carried on that MO at all). `ospf_dead` must exceed
|
||
`ospf_hello`.
|
||
- `isn.bfd_min_rx`/`.bfd_min_tx`/`.bfd_multiplier` (defaults `50`/`50`/
|
||
`3`, real ACI defaults) — store + range-validate + surface only. This
|
||
sim builds no `bfdIfP`-style MO anywhere (grepped `build/*.py`: zero
|
||
matches for "bfd"), so these are explicitly **store-only**, documented
|
||
as such in `aci-sim show`'s own output.
|
||
- `fabric.oob_subnet` (validate-only; must fall within
|
||
`192.168.0.0/16`) and `fabric.inb_subnet` (store-only; must fall
|
||
within a private RFC1918 range) — `oob_ip()` still derives every
|
||
node's OOB address from `(pod, node_id)` only (documented pre-existing
|
||
limitation, unchanged); this sim has no in-band mgmt MO at all, so
|
||
`inb_subnet` is explicitly store-only.
|
||
- `fabric.default_apic_version` (fabric-wide override; default `None` =
|
||
unchanged behavior) — takes precedence over each site's own
|
||
`site.apic_version` (PR-9/PR-18 lineage, already fully wired and
|
||
already independent of switch-node `Node.version`) in
|
||
`build/fabric.py`'s controller `fabricNode`/`topSystem`/
|
||
`firmwareCtrlrRunning`. **Finding while implementing this PR:**
|
||
`site.apic_version` already drove those MOs independently of switch
|
||
version before this PR — the actual gap closed here is (1) a
|
||
fabric-wide override knob and (2) `aci-sim show` never surfaced
|
||
`apic_version` at all pre-PR-20 (now shown per-site as the resolved
|
||
effective value).
|
||
- `aci-sim new` gained `--isn-ospf-hello`, `--isn-ospf-dead`,
|
||
`--isn-bfd-min-rx`, `--isn-bfd-min-tx`, `--isn-bfd-multiplier`,
|
||
`--default-bd-mac` flags; `aci-sim show` now prints
|
||
`oob_subnet`/`inb_subnet` (labeled store-only)/`default_bd_mac`,
|
||
`default_apic_version` (when set), ISN `ospf_hello`/`ospf_dead`, ISN
|
||
BFD timers (labeled store-only), and each site's effective
|
||
`apic_version`.
|
||
- New tests: `tests/test_pr20_tier3.py` (41 tests). Full suite: 713
|
||
passed (672 pre-existing + 41 new), zero regressions.
|
||
- See `docs/DESIGN.md`'s "PR-20 — Tier-3 fine-tuning parameters" section
|
||
for the full design rationale and an explicit statement of which
|
||
backward-compat verification was performed in this sandboxed
|
||
development environment vs. deferred to the main thread's independent
|
||
production-chain re-run (no SSH access to the hardware test host from
|
||
this environment).
|
||
|
||
## [0.5.0] - 2026-07-04
|
||
|
||
### Added
|
||
- **Tier-2 topology-elasticity parameters (PR-19).** New optional
|
||
`topology.yaml` fields — all defaulted to pre-existing hardcoded behavior,
|
||
so the existing repo `topology.yaml` validates and builds unchanged:
|
||
- `isn.ospf_area` (default `"0.0.0.0"`, accepts dotted-decimal or
|
||
decimal-integer notation) and `isn.mtu` (default `9150`, range
|
||
576-9216) — now threaded into `build/underlay.py`'s `ospfIf`/
|
||
`ospfAdjEp` `area` and `build/interfaces.py`'s dedicated ISN/IPN spine
|
||
uplink `l1PhysIf.mtu`, replacing hardcoded `"0.0.0.0"`/`9216` literals
|
||
at those specific call sites. Ordinary fabric ports keep their existing
|
||
9216 MTU.
|
||
- `access.vmm_domains[]` (default: empty list) — a VMM domain model
|
||
(`vcenter_ip`, `vcenter_dvs`, `vlan_pool`, `datacenter`) that builds a
|
||
`vmmDomP` (+ `vmmCtrlrP`/`vmmUsrAccP` when `vcenter_ip` is set, +
|
||
`infraRsVlanNs` when `vlan_pool` is set) in `build/access.py`. Verified
|
||
(read-only, hardware test host) that this is a **pure addition**: the real
|
||
aci-py `bind_epg_to_vmm_domain` MS-TN1 chain writes an NDO schema
|
||
`domainAssociations` entry referencing the domain by DN string only —
|
||
no existing builder or production chain reads a `vmmDomP`/`vmmCtrlrP`
|
||
object today, hence the empty-list default (unlike `phys_domains`/
|
||
`l3_domains`/`aaeps`, which each seed one entry). See `docs/DESIGN.md`
|
||
PR-19 section for the full verification trail.
|
||
- **Leaf/spine count elasticity bug fix**: `aci-sim new`'s node-ID
|
||
generator (`generate_topology()`) had no guard against
|
||
`--leaves-per-site`/`--spines-per-site` exceeding the node-ID scheme's
|
||
documented ~100-per-site ceiling, or `--border-pairs` pushing the
|
||
border block past the next site's leaf range — all three previously
|
||
produced a `topology.yaml` dict that failed deep inside
|
||
`Topology.normalize_and_validate` with a generic "node ids collide"
|
||
error. Now rejected at generation time with a clear message naming the
|
||
offending flag. Verified: `--leaves-per-site 8 --spines-per-site 4`
|
||
(and `--border-pairs` > 1) validate and build clean; the exact boundary
|
||
(100 leaves/spines, 49 border-pairs at default counts) still works;
|
||
101/50 respectively are cleanly rejected.
|
||
- `isn.peer_mesh: partial` re-examined and kept as a documented
|
||
validate-and-reject (unchanged decision from PR-17/18) — no sensible
|
||
default partition exists without additional per-site config the schema
|
||
doesn't carry.
|
||
- `aci-sim new` gained `--isn-ospf-area`, `--isn-mtu` flags; `aci-sim
|
||
show` now prints ISN enabled/peer_mesh/ospf_area/mtu and any configured
|
||
VMM domains.
|
||
- New tests: `tests/test_pr19_tier2.py` (37 tests) + 6 additions to
|
||
`tests/test_cli.py`.
|
||
|
||
## [0.4.0] - 2026-07-04
|
||
|
||
### Added
|
||
- **Tier-1 fabric configuration parameters (PR-18).** New optional
|
||
`topology.yaml` fields — all defaulted to the pre-existing hardcoded
|
||
behavior, so the existing repo `topology.yaml` validates and builds
|
||
unchanged:
|
||
- `fabric.tep_pool` (default `"10.0.0.0/16"`), `fabric.infra_vlan`
|
||
(default `3967`, range 1-4094), `fabric.gipo_pool` (default
|
||
`"225.0.0.0/15"`) — stored, CIDR/range-validated, and surfaced via
|
||
`aci-sim show`/`aci-sim new`. No builder currently derives a per-node
|
||
address or VLAN attribute from these (see `docs/DESIGN.md` PR-18
|
||
section) — store-only until a future PR wires them into a builder.
|
||
- `site.controllers` (APIC cluster size, default 3) and `site.pod`
|
||
(default 1) already existed and were already fully wired through every
|
||
relevant builder (`fabricNode`/`topSystem`/`infraWiNode`/
|
||
`firmwareCtrlrRunning`/health/endpoints); PR-18 verified this end-to-end
|
||
and added `aci-sim new --controllers N`.
|
||
- Deterministic non-empty node serials: `build/fabric.py`'s new
|
||
`default_serial(site_id, node_id)` (`f"SAL{site_id}{node_id:04d}"`)
|
||
replaces the previous inline `SIM{node.id:08d}` fallback used whenever
|
||
an auto-generated `Node.serial` is empty, so `fabricNode.serial` /
|
||
`fabricNodeIdentP.serial` always carry a real, deterministic serial for
|
||
`cisco.aci.aci_fabric_node` to register against. Explicit YAML
|
||
`serial:` values still override.
|
||
- `aci-sim new` gained `--controllers`, `--tep-pool`, `--infra-vlan`,
|
||
`--gipo-pool` flags; `aci-sim show` now prints each node's resolved
|
||
serial and each site's controller count, plus the fabric-wide
|
||
tep_pool/infra_vlan/gipo_pool.
|
||
- Verified N-site behavior: a 3-site scaffold (`aci-sim new --sites 3`)
|
||
builds with zero node-ID collisions and per-site `infraWiNode` counts
|
||
matching the configured controller count. **Documented limit**: ISN
|
||
inter-site peering and stretched-tenant HOME/REMOTE endpoint placement
|
||
still rely on `Topology.other_site()`, which is 2-site-only semantics
|
||
(pre-existing, not introduced by this PR) — with 3+ sites, ISN is not a
|
||
true full mesh. See README §6a / §8 and `docs/DESIGN.md` PR-18 section.
|
||
- New tests: `tests/test_pr18_tier1.py`.
|
||
|
||
## [0.3.0] - 2026-07-04
|
||
|
||
### Added
|
||
- **`aci-sim` topology CLI (PR-17).** A new console script
|
||
(`aci_sim/cli.py`, `[project.scripts] aci-sim`) that makes
|
||
`topology.yaml` easier to author, validate, preview, and run — purely
|
||
additive: it does not change the topology schema, builders, or NDO/REST
|
||
code, and `topology.yaml` remains the single source of truth. Four
|
||
subcommands:
|
||
- `aci-sim validate [TOPOLOGY]` — runs the same `load_topology()`/Pydantic
|
||
validation the sim already performs at startup, printing a concise
|
||
pass/fail summary (sites, leaves/spines/border-leaves per site, tenant
|
||
count) instead of a raw traceback. This is the CI gate.
|
||
- `aci-sim show [TOPOLOGY]` — prints the **derived** inventory (not just
|
||
an echo of the YAML): per-site APIC host/mgmt IP/ASN/pod/fabric name, a
|
||
table of every node with its derived loopback/OOB IP (via
|
||
`build/fabric.py`'s `loopback_ip`/`oob_ip`), the NDO mgmt IP, and the
|
||
actual host:port each controller will listen on (port mode or sandbox
|
||
mode, read from `runtime/config.py`). `--json` for machine-readable
|
||
output.
|
||
- `aci-sim run [TOPOLOGY]` — a thin wrapper around `python -m
|
||
aci_sim.runtime.supervisor`: validates the topology up front,
|
||
generates self-signed certs on first run (mirrors
|
||
`scripts/gen_certs.sh`), sets `TOPOLOGY_PATH`, passes through
|
||
`SIM_BIND`/`SIM_SANDBOX`/etc. from the environment, and execs the
|
||
supervisor — `scripts/run.sh` is unchanged and keeps working.
|
||
- `aci-sim new` — scaffolds a fresh, minimal, valid `topology.yaml` (to
|
||
stdout or `-o FILE`) from flags (`--sites`, `--leaves-per-site`,
|
||
`--spines-per-site`, `--border-pairs`, `--asn`, `--fabric-name-prefix`,
|
||
`--ndo-ip`, `--apic-ip-base`), using the same node-ID scheme documented
|
||
in `topology/schema.py` (leaves base 101 +200/site, spines base 201
|
||
+200/site, border leaves placed outside both ranges in vPC pairs). The
|
||
generated file always passes `aci-sim validate` and boots.
|
||
- New `tests/test_cli.py` (20 tests): validate positive/negative
|
||
(duplicate node id, bad CIDR), show text + `--json` asserting derived
|
||
IPs for a known node, `new --sites 3 --leaves-per-site 4` round-tripped
|
||
through the real Pydantic model, and `run`'s env/argv construction via
|
||
a pure `build_run_env_argv` helper (no live socket binding in tests).
|
||
- README gets a new "## 5. CLI" section (subsequent sections renumbered
|
||
6-11); `deploy/README.md`/Quickstart note `aci-sim run` as the
|
||
preferred entrypoint alongside `scripts/run.sh`.
|
||
|
||
## [0.2.7] - 2026-07-04
|
||
|
||
### Fixed
|
||
- **NDO site-local BD duplication — mirror vs site-module dedup (PR-16).**
|
||
`aci_sim/ndo/patch.py::_mirror_template_bd_to_sites` (PR-15)
|
||
auto-creates a site-local BD shadow with a full-path STRING `bdRef` the
|
||
moment a template BD is added. Separately, `mso_schema_site_bd.py`'s
|
||
"BD does not exist yet" branch PATCHes `add /sites/{siteId}-{template}/
|
||
bds/-` (the RFC-6902 *append* form) with a DICT-shaped `bdRef`. The
|
||
append branch of `apply_json_patch` never consulted `_find_by_name`/ref
|
||
resolution before appending, and `_find_by_name`'s own ref-lookup only
|
||
recognized the string ref shape — so the two writers never converged on
|
||
one entry, and `sites[].bds[]` ended up with two rows for the same
|
||
template BD (one empty mirror, one carrying the real subnet) —
|
||
confirmed against a reference NDO schema (`App1-Net-LAB0`, Acme
|
||
App1-Net tenant) after `create_tenant`+`create_bd`.
|
||
Fixed by deduping a **nameless site-local shadow** strictly by its
|
||
single IDENTITY ref (`bds`→`bdRef`, `anps`→`anpRef`, `epgs`→`epgRef`,
|
||
`contracts`→`contractRef`; `_IDENTITY_REF_BY_COLLECTION`), resolved in
|
||
both string and dict shapes via a new `_bare_ref_name()` helper. A new
|
||
`_find_shadow_by_identity()` is the append-path dedup; `_find_by_name`'s
|
||
ref-lookup now fires only for nameless items and only over identity
|
||
refs. A NAMED object (a template-level BD add) is matched only by
|
||
name/displayName and always appends.
|
||
IMPORTANT — the first cut of this fix iterated **all** `*Ref` keys
|
||
(including `vrfRef`), which collapsed every template's BDs into a single
|
||
entry because distinct BDs share one `vrfRef` (`vrf-L3_LAB0`); an
|
||
independent full-chain Acme run caught it (`create_bd` failed
|
||
`"Provided BD 'bd-App2-Net-...' does not exist"`). The shipped fix
|
||
restricts ref-matching to identity refs of nameless shadows only —
|
||
guarded by `test_distinct_template_bds_sharing_vrfref_do_not_collapse`.
|
||
Verified end-to-end on real ACI hardware: Acme App1-Net
|
||
`create_tenant.yml`/`create_bd.yml` both `failed=0`; live NDO schema
|
||
`App1-Net-LAB0` shows template BD counts `LAB1-LAB2=6`, `LAB1=14`,
|
||
`LAB2=10` (30, no collapse) and exactly one site-local BD entry per
|
||
template BD (no duplicate). Covers the analogous ANP/contract
|
||
site-mirror paths too — no regression against the PR-12/PR-13 mirror
|
||
suites. 9 tests in `tests/test_pr16_bd_mirror_dedup.py`.
|
||
|
||
## [0.2.6] - 2026-07-04
|
||
|
||
### Added
|
||
- **Domain-qualified `aaaLogin` name + template-BD site mirroring for
|
||
aci-py (PR-15).** Two confirmed sim gaps from a real `aci-py` (pure-Python
|
||
Ansible-to-ACI compiler) run against the hardware sandbox:
|
||
1. **APIC login rejects a domain-qualified login name.** `aci-py` posts
|
||
`POST /api/aaaLogin.json` with `aaaUser.attributes.name =
|
||
"apic:local\admin"` — a valid real-APIC login format
|
||
(`apic:<loginDomain>\<username>`). The sim's `aaaLogin` handler
|
||
(`aci_sim/rest_aci/auth.py`) exact-matched the raw `name`
|
||
attribute against `SIM_USERNAME`, so every domain-qualified login
|
||
401'd even with the correct password — confirmed live against the
|
||
sandbox (`name="apic:local\admin"` -> 401, `name="admin"` -> 200
|
||
before this fix). Added `_bare_username()`, which strips an optional
|
||
`apic:<domain>\` / `<domain>\` prefix before the credential compare,
|
||
so both the plain and domain-qualified forms authenticate identically;
|
||
a wrong username in either form still 401s.
|
||
2. **NDO schema PATCH 400 mid `create_tenant`/`create_bd`.** `aci-py`'s
|
||
`mso_schema_site_bd` shim always PATCHes a site-local BD shadow with
|
||
`op: replace` (never `add`), because real NDO 4.x auto-creates that
|
||
shadow ("BDDelta") the moment a template-level BD is added to a
|
||
template that already has sites attached — a fresh `add` there 409s
|
||
on real hardware, so the shim does a GET-then-replace instead (its own
|
||
docstring documents this real-hardware behavior). The sim never
|
||
mirrored a template BD `add` into `sites[].bds[]` (unlike ANPs/EPGs
|
||
since PR-12 and contracts since PR-13 — the same "auto-mirror on
|
||
template add" pattern, just missing the BD collection), so the
|
||
site-BD `replace` 400'd with `"replace: 'bd-FW_LAB0' not found at
|
||
'/sites/1-LAB1-LAB2/bds/bd-FW_LAB0'"` — confirmed verbatim against a
|
||
real hardware aci-py MS-TN2 run before this fix. Added
|
||
`_mirror_template_bd_to_sites` (`aci_sim/ndo/patch.py`,
|
||
PATCH-time, parallel to `_mirror_template_anp_to_sites` /
|
||
`_mirror_template_contract_to_sites`) and the equivalent boot-time
|
||
mirror in `build_ndo_model` (`aci_sim/ndo/model.py`), so a
|
||
topology.yaml tenant that ships with BDs already configured also
|
||
boots with the site shadow pre-mirrored.
|
||
- VERDICT: both gaps are genuine sim fidelity gaps, not aci-py bugs —
|
||
aci-py's domain-qualified login name and its GET-then-replace
|
||
site-BD shim both mirror documented real-APIC/real-NDO behavior.
|
||
- Confirmed end-to-end on real ACI hardware: aci-py's `live_chain.py`
|
||
driver against `environments/lab-multisite-sim` now reaches
|
||
**MS-TN2: 13/13 steps rc=0** (was 9 ok / 4 fail before this PR — the 4
|
||
failures were exactly the login 401s and the `replace: 'bd-*' not
|
||
found` 400) and **MS-TN1: 11/11 rc=0** (1 skip, no regression).
|
||
- 13 new tests in `tests/test_pr15_acipy_gaps.py` covering both plain and
|
||
domain-qualified (`apic:local\admin` and `local\admin`) aaaLogin forms,
|
||
a domain-qualified wrong-user/wrong-password still-401 check, the
|
||
template-BD-add-mirrors-into-site PATCH behavior (single site, multiple
|
||
sites, idempotency, non-associated-site isolation), the full
|
||
add-then-replace sequence aci-py actually emits, and the boot-time
|
||
mirror for topology.yaml tenants that ship with BDs already configured.
|
||
|
||
## [0.2.5] - 2026-07-04
|
||
|
||
### Added
|
||
- **Classic ND bare `/login` + `/logout` endpoints (aci-py, cisco.nd)
|
||
(PR-14).** aci-py's NDO connector and the `cisco.nd` httpapi plugin POST
|
||
to the classic Nexus Dashboard bare `/login` (body `{userName,
|
||
userPasswd, domain}`, JWT in `token`/`jwttoken`) alongside the newer
|
||
`/api/v1/auth/login`. The sim only had the latter, so aci-py 404'd on
|
||
every NDO login. Mirrored the existing auth handler at bare `/login` +
|
||
`/logout`.
|
||
|
||
## [0.2.4] - 2026-07-04
|
||
|
||
### Added
|
||
- **NDO tenant-policy-template DHCP surface + schema serviceGraphs for
|
||
cisco.mso (PR-13).** Two confirmed sim gaps from a real aci-ansible run
|
||
against ACI hardware, both the last NDO write surfaces blocking the multi-site
|
||
(MS) suite:
|
||
1. **Tenant-policy-template CREATE flow.** `prereq_tenantpol.yml`'s
|
||
`cisco.mso.ndo_template` task (`delegate_to: localhost`) 404'd on
|
||
`GET /api/v1/templates/summaries` — a BARE path with no `/mso` prefix.
|
||
Root cause: `delegate_to: localhost` forces `ansible-mso`'s
|
||
`MSOModule` down its direct-HTTP branch instead of the persistent
|
||
`ansible.netcommon.httpapi` connection every other task on the same
|
||
playbook host uses, and that branch never adds the `/mso` prefix.
|
||
Added a full generalized template store (`POST`/`GET`/`PATCH`/`DELETE
|
||
/templates{,/summaries,/objects,/{id}}`, both bare and `/mso`-prefixed)
|
||
so `ndo_template` can create a tenant-policy template that persists,
|
||
`cisco.mso.ndo_dhcp_relay_policy` (`create_dhcp_relay`) can add a DHCP
|
||
relay policy against it (schema-template EPGs now carry a `uuid` field
|
||
for provider refs — previously absent), and
|
||
`cisco.mso.ndo_schema_template_bd_dhcp_policy` (`bind_dhcp_relay_to_bd`)
|
||
can resolve/bind it to a BD via the new `templates/objects?type=
|
||
dhcpRelay&{uuid|name}=...` cross-template lookup route. Confirmed
|
||
end-to-end on a real hardware run: MS-TN1/MS-TN2 `create_dhcp_relay` +
|
||
`bind_dhcp_relay_to_bd` now reach `failed=0`.
|
||
2. **Schema serviceGraphs surface.** The mso-model role's "Create service
|
||
graph" task (`custom_mso_schema_service_graph.py`, a legacy
|
||
pre-`MSOTemplate`/`MSOSchema` module) bare-subscripts
|
||
`schema_obj.get('sites')[site_idx]['serviceGraphs']` — the
|
||
TEMPLATE-level `serviceGraphs` bare-subscript was already covered by
|
||
PR-11, but the SITE-level sibling was not, hitting `KeyError:
|
||
'serviceGraphs'` on a real hardware MS-TN2 `create_tenant` pass-2 run
|
||
(`-e automate_contract_graph=true`). Added `SITE_TOP_LEVEL_DEFAULTS`
|
||
(`aci_sim/ndo/patch.py`) to backfill `serviceGraphs` (and
|
||
`contracts`, see below) on every schema `sites[]` entry; `GET
|
||
/mso/api/v1/schemas` now returns full nested schema detail (matching
|
||
real NDO) instead of a trimmed `{name}`-only summary, since this same
|
||
legacy module bare-subscripts straight into that response; added
|
||
`GET schemas/service-node-types` and a `tenantId` field on every
|
||
schema template (both required by the same module). Chasing this to
|
||
green on real ACI hardware surfaced a DEEPER gap: once the
|
||
`serviceGraphs` KeyError was fixed, the mso-model role's raw
|
||
`cisco.mso.mso_rest`-driven "Atomic PATCH — bind service-graph
|
||
redirect on ALL fabrics" task addresses a SITE-LOCAL contract by bare
|
||
name (`/sites/{siteId}-{t}/contracts/{c}/serviceGraphRelationship`) —
|
||
the sim never mirrored template-level contracts into
|
||
`sites[].contracts[]` at all (unlike ANPs/EPGs, mirrored since PR-12),
|
||
hitting `PatchError: path segment 'con-Firewall_LAB0' not found in
|
||
list`. Added `_mirror_template_contract_to_sites` (PATCH-time) and the
|
||
equivalent boot-time mirror in `build_ndo_model`. Confirmed end-to-end
|
||
on a real hardware run: MS-TN2 `create_tenant` pass-2 (01b) now reaches
|
||
`failed=0`.
|
||
- 26 new tests in `tests/test_pr13_ndo_dhcp_svcgraph.py` covering the
|
||
bare/mso-prefixed template routes, the full `ndo_template` create→lookup
|
||
round trip, DHCP relay policy add/read via `templates/objects`,
|
||
`bind_dhcp_relay_to_bd`'s full PATCH sequence, site-level `serviceGraphs`
|
||
normalization, the full schema-detail `GET /schemas` shape, and the
|
||
site-local contracts mirroring + atomic redirect PATCH.
|
||
|
||
## [0.2.3] - 2026-07-03
|
||
|
||
### Added
|
||
- **NDO site-local ANP/EPG + static-port schema surface.** PR-11 closed the
|
||
schema write round-trip for template-level objects but left the last
|
||
MS-TN1 gap: `bind_epg_to_static_port`
|
||
(`cisco.mso.mso_schema_site_anp_epg_staticport`) crashed client-side with
|
||
`'NoneType' object has no attribute 'details'`. Two compounding root
|
||
causes, both fixed:
|
||
1. Real NDO stores a self-referencing `anpRef` string on every
|
||
template-level ANP object itself (and `epgRef` on every EPG) —
|
||
confirmed because `ansible-mso`'s `mso_schema_template_anp.py`/
|
||
`_anp_epg.py` explicitly strip it client-side before an idempotency
|
||
comparison (`if "anpRef" in mso.previous: del mso.previous["anpRef"]`
|
||
— dead code unless the server sends one back). `MSOSchema.
|
||
set_site_anp()`/`set_site_anp_epg()` (`ansible-mso`'s
|
||
`module_utils/schema.py`) key their site-local lookup off exactly
|
||
this field; without it the lookup always compares against `None`.
|
||
`normalize_template()` (`aci_sim/ndo/patch.py`) now backfills
|
||
`anpRef`/`epgRef` on every `anps[]`/`epgs[]` entry (takes an optional
|
||
`schema_id` param to build them); `build_ndo_model()`
|
||
(`aci_sim/ndo/model.py`) calls it at boot too.
|
||
2. Real NDO 4.x auto-populates a schema's site-local
|
||
`sites[].anps[].epgs[]` the moment a template-level ANP/EPG is added
|
||
to a template that already has a site attached — the sim never did
|
||
this mirroring, so `set_site_anp()`/`set_site_anp_epg()` always
|
||
returned `None` and the module's own dead-on-4.x fallback path (its
|
||
own source comment: *"Coverage misses this two conditionals when
|
||
testing on 4.x and above"*) crashed instead. `apply_json_patch` now
|
||
auto-mirrors: `add /templates/{t}/anps/-` creates a matching
|
||
`{anpRef, epgs:[]}` site-anp in every associated site; `add
|
||
/templates/{t}/anps/{a}/epgs/-` creates a matching **full-shaped**
|
||
site-EPG `{epgRef, subnets:[], staticPorts:[], staticLeafs:[],
|
||
domainAssociations:[]}` under it. The full child-collection shape is
|
||
mandatory — every sibling `mso_schema_site_anp_epg_*` module
|
||
bare-subscripts its own array (a missing key is a hard `KeyError`,
|
||
not a 4xx): `_domain` reads `domainAssociations`, `_staticleaf` reads
|
||
`staticLeafs`, `_staticport` reads `staticPorts`, `_subnet` reads
|
||
`subnets`. (An earlier iteration that omitted `domainAssociations`
|
||
regressed `bind_epg_to_physical_domain`/`_vmm_domain` on ACI hardware with
|
||
`KeyError: 'domainAssociations'`.) Single source of truth for the
|
||
shape is `SITE_OBJECT_DEFAULTS["epgs"]`, consumed by `_new_site_epg()`
|
||
(mirror path) and `normalize_site()` (backfill path).
|
||
`build_ndo_model()` performs the same mirroring at boot for
|
||
topology-seeded schemas. Both idempotent.
|
||
|
||
`epgRef`'s canonical string form uniquely nests two name segments
|
||
(`/schemas/{id}/templates/{t}/anps/{a}/epgs/{e}`, confirmed against
|
||
`ansible-mso`'s `module_utils/mso.py` `epg_ref()`) — handled by a
|
||
dedicated `_stringify_refs` branch since the existing single-category
|
||
`_REF_NAME_FIELDS` table only fits one name field. `_REF_LOOKUP_KEYS`
|
||
gained `epgRef` so a site-epg (ref-only, no `name` of its own) resolves
|
||
by its bare EPG name the same way site-local bds/anps already did
|
||
(PR-11). Verified end-to-end against a real-hardware multi-site E2E run:
|
||
the full MS-TN1 chain (`create_tenant` → `create_bd` →
|
||
`create_application` → `bind_epg_to_static_port`) now reaches `failed=0`
|
||
on every host, closing the CONTRACT.md §7a "known gap" note. New
|
||
`tests/test_pr12_site_local.py`.
|
||
|
||
## [0.2.2] - 2026-07-03
|
||
|
||
### Added
|
||
- **NDO schema write round-trip (POST/PATCH).** PR-10's schema surface was
|
||
read-only (a static per-tenant seed plus a POST that stored a schema no
|
||
PATCH could reach). PR-11 makes the schema store fully writable, matching
|
||
the exact request sequence every `cisco.mso` schema-object module
|
||
performs (verified against `ansible-mso`'s `plugins/module_utils/mso.py` +
|
||
`schema.py` and confirmed on a real multi-site aci-ansible E2E run against
|
||
ACI hardware): `GET schemas/list-identity` (displayName→id, already existed) →
|
||
`GET schemas/{id}` (already existed) → `PATCH schemas/{id}` with a
|
||
JSON-Patch-shaped op list (`{"op":"add"/"replace"/"remove","path":...,
|
||
"value":...}`). New `aci_sim/ndo/patch.py` implements a general
|
||
applier (`apply_json_patch`) supporting three path-addressing conventions
|
||
cisco.mso modules use: numeric index / `"-"` append (RFC 6902), a *named*
|
||
segment resolved against a `name`/`displayName` field
|
||
(`/templates/LAB1/bds/bd-App1_LAB1`), a *synthetic composite* key
|
||
`"{siteId}-{templateName}"` unique to the top-level `sites[]` array
|
||
(`/sites/1-LAB1/bds/-` — every `mso_schema_site_*` module builds this
|
||
literally), and a *`*Ref`-name* lookup for site-local child objects that
|
||
carry no `name` of their own (`/sites/1-LAB1/bds/bd-App1_LAB1/subnets/-`
|
||
resolves `bd-App1_LAB1` against the site-local BD's `bdRef` string).
|
||
`normalize_template()`/`normalize_site()` backfill every collection-default
|
||
key (`vrfs`/`bds`/`anps.epgs`/`contracts`/`filters`/`externalEpgs`/
|
||
`intersiteL3outs`/`serviceGraphs`/`subnets`/...) real NDO defaults
|
||
server-side but several `cisco.mso` create/add payloads omit — a missing
|
||
key there is a hard crash client-side (`'NoneType' object is not
|
||
iterable`, bare `KeyError`, or `TypeError: sequence item 0: expected str
|
||
instance, dict found` when a sibling module `", ".join()`s a `*Ref` field
|
||
the sim had stored as a dict instead of NDO's canonical string form
|
||
`/schemas/{id}/templates/{tmpl}/{category}/{name}` — all three confirmed
|
||
on real hardware create_tenant/create_bd runs before the fix).
|
||
- **`GET /api/config/class/remoteusers` + `/localusers`.** `cisco.mso.mso_
|
||
tenant`'s tenant-create flow always resolves the tenant's `users` list via
|
||
`lookup_users()`, which on ND platforms falls back to these legacy
|
||
`/api/config/class/*` routes when the modern `/nexus/infra/api/aaa/v4/*`
|
||
endpoints aren't available. The sim only served the modern route's absence
|
||
as a 404, so `nd_request()` had no `"code"`/`"messages"` in the error body
|
||
and aborted with `"ND Error: Unknown error no error code in decoded
|
||
payload"` — verified on a real hardware create_tenant run. Now seeded with a
|
||
local `admin` user in ND's `{"items":[{"spec":{...}}]}` aggregate shape.
|
||
- **Bare `GET /api/v1/sites`.** `cisco.mso.ndo_template`'s TenantPol prereq
|
||
lookup hits this un-prefixed path (no `/mso`); the sim only served the
|
||
`/mso/api/v1/sites` form. Same data, added alongside PR-10's bare
|
||
`/api/v1/tenants`.
|
||
- **`PUT`/`POST /mso/api/v1/tenants{,/{id}}`.** `cisco.mso.mso_tenant`
|
||
updates a tenant in place (`PUT .../tenants/{id}`) whenever the tenant
|
||
already exists in `GET /mso/api/v1/tenants` — true for every tenant this
|
||
sim seeds from the topology. Previously unimplemented (404).
|
||
- **`GET /mso/api/v1/schemas/{id}/validate`, `execute|status/schema/{id}/
|
||
template/{name}`, `POST /mso/api/v1/task`.** The full schema-template
|
||
deploy surface: `cisco.mso.mso_schema_template_deploy` (legacy) validates
|
||
then calls `GET execute|status/schema/.../template/...`; the module
|
||
aci-ansible's `mso-model` role actually invokes,
|
||
`cisco.mso.ndo_schema_template_deploy`, instead validates then `POST
|
||
/mso/api/v1/task` with `{schemaId, templateName, isRedeploy}` — confirmed
|
||
against the collection installed on real ACI hardware (differs from the upstream
|
||
`master`-branch module source). All three were 404 before this PR.
|
||
|
||
### Fixed
|
||
- `GET /mso/api/v1/schemas` / `list-identity` no longer double-lists (or
|
||
silently drops) a schema after it's mutated by `PATCH` — the summary
|
||
projection is now kept in sync in place rather than appended as a
|
||
duplicate "extra" entry.
|
||
|
||
### Verified against a real-hardware E2E run
|
||
MS-TN1 (multi-site tenant) now reaches `failed=0` for `create_tenant`,
|
||
`create_bd`, `create_application`, `bind_epg_to_physical_domain`,
|
||
`bind_epg_to_vmm_domain`, and `bind_epg_to_secure_application`. Remaining
|
||
known gap: `bind_epg_to_static_port` needs site-local ANP/EPG object
|
||
creation (`mso_schema_site_anp`/`_anp_epg`), not implemented in this PR —
|
||
tracked for PR-12 (see docs/CONTRACT.md §7 for the precise failure
|
||
signature).
|
||
|
||
### Tests
|
||
- New `tests/test_pr11_ndo_write.py` (31 tests): `apply_json_patch` op
|
||
semantics (add/replace/remove, index/name/composite-key/ref-name
|
||
resolution, auto-vivification safety), `normalize_template`/
|
||
`normalize_site` collection-default backfilling, `*Ref` dict→string
|
||
normalization, and full schema create→PATCH→GET round-trips through the
|
||
FastAPI routes (including the exact site-local BD + BD-subnet sequence a
|
||
real E2E run exercises).
|
||
|
||
## [0.2.1] - 2026-07-03
|
||
|
||
### Fixed
|
||
- **`/api/node/mo/{dn}` alias (11 E2E failures).** Real APIC serves
|
||
`/api/node/mo/{dn}.json` as a full equivalent of `/api/mo/{dn}.json` (the
|
||
form the APIC GUI's API Inspector and some `cisco.aci` call paths emit).
|
||
The sim only registered `/api/mo/*`, so an alias request fell through to
|
||
FastAPI's default 404 `{"detail":"Not Found"}` — a shape `cisco.aci`
|
||
cannot parse (surfaces as `"APIC Error None: None"`, `status=-1`). GET,
|
||
POST, and DELETE are now all registered on both paths via stacked route
|
||
decorators sharing one handler, so behavior can never drift between the
|
||
canonical and alias forms.
|
||
- **APIC-shaped 400 for unmatched `/api/*` paths.** Any request under
|
||
`/api/*` that doesn't match a real route now returns an APIC error
|
||
envelope (`imdata`/`error`/`code`) instead of FastAPI's `{"detail":...}` —
|
||
real APIC never emits that shape. Implemented as a Starlette 404 exception
|
||
handler scoped to the `/api/*` prefix, so it only fires once routing has
|
||
already failed and can never shadow a real route.
|
||
- **NDO site names now use the fabric name, not the short topology name.**
|
||
`GET /mso/api/v1/sites` previously reported the topology's internal short
|
||
site name (`"LAB1"`/`"LAB2"`); real NDO registers sites under their
|
||
fabric name (`"LAB1-IT-ACI"`/`"LAB2-IT-ACI"`), and `cisco.mso.mso_tenant`
|
||
failed with `"Site 'LAB1-IT-ACI' is not a valid site name"` against the
|
||
short form. Verified against a real-gear `cisco.mso.mso_tenant` run.
|
||
`aci_sim/ndo/model.py`'s site builder now exposes
|
||
`Site.fabric_name` (falling back to the short name if unset); internal
|
||
site-id joins (`tenant.sites`, schema site associations) are unaffected
|
||
since they key off the topology's short name, never the NDO-facing
|
||
display name.
|
||
- **NDO schema `list-identity` + bare `/api/v1/tenants`.** Added
|
||
`GET /mso/api/v1/schemas/list-identity` — the lightweight
|
||
schema-enumeration endpoint every `cisco.mso` schema module calls first to
|
||
resolve a schema `displayName` to its `id` (verified against
|
||
`ansible-mso`'s `plugins/module_utils/mso.py`:
|
||
`query_objs("schemas/list-identity", key="schemas", displayName=schema)`,
|
||
which reads `json["schemas"][]` entries with at least `id` + `displayName`).
|
||
Declared *before* the parameterized `GET /mso/api/v1/schemas/{schema_id}`
|
||
route so `"list-identity"` is never matched as a schema id (previously
|
||
would 404 with `{"detail":"Schema 'list-identity' not found"}`). Also
|
||
added `GET /api/v1/tenants`, backing `cisco.mso.ndo_template`'s tenant
|
||
prereq lookup, returning the same tenant list as the existing
|
||
`/mso/api/v1/tenants`. Both are read-only additions — the schema/template
|
||
*write* surface (`PATCH` deploy) is an intentional follow-up.
|
||
- New regression suite `tests/test_pr10_ansible_gaps.py` (9 tests) covers
|
||
all of the above; `tests/test_ndo.py`'s site-name assertions updated to
|
||
join by fabric name.
|
||
|
||
## [0.2.0] - 2026-07-03
|
||
|
||
### Added
|
||
- Public-release preparation: rewritten README (purpose, architecture, both
|
||
run modes, configuration reference, error-handling contract, known
|
||
limitations), MIT `LICENSE`, this `CHANGELOG.md`, GitHub Actions CI
|
||
(`ci.yml`), a validated `examples/ansible/` playbook set (smoke +
|
||
teardown), and a project-root `CLAUDE.md` release-kit overlay.
|
||
|
||
### Changed
|
||
- Hygiene pass: removed a real internal hostname/username pair from
|
||
`docs/DESIGN.md`'s batch-2/3 verification note and genericized an example
|
||
path in `deploy/aci-sim.service`; no functional/behavioral change.
|
||
|
||
## [0.1.12] - 2026-07-03
|
||
|
||
### Added
|
||
- Ansible `cisco.aci` fidelity: `DELETE /api/mo/{dn}.json` (`state=absent`,
|
||
server-side idempotent), `GET` on a nonexistent-but-well-formed DN now
|
||
returns 200-empty instead of 404 (unblocks `state=present` GET-before-write
|
||
playbooks), `status="deleted"` cascade regression coverage,
|
||
`annotation`/`ownerKey`/`ownerTag`/`nameAlias` passthrough regression
|
||
coverage, and certificate-signature auth in accept-mode (claimed-identity
|
||
trust, no signature verification — documented trust-model caveat).
|
||
|
||
## [0.1.11] - 2026-07-03
|
||
|
||
### Added
|
||
- Default loopback bind (`SIM_BIND`, defaults to `127.0.0.1`) so the
|
||
unauthenticated `/_sim` control plane is never LAN-exposed by accident.
|
||
- Linux sandbox-mode support (`ip addr add/del … dev lo`) alongside the
|
||
existing macOS `lo0 alias` path in `sandbox-up.sh`/`sandbox-down.sh`.
|
||
- Effective-port environment overrides and topology config validation.
|
||
- systemd `--user` unit and launchd plist deployment docs (`deploy/`).
|
||
|
||
## [0.1.10] - 2026-07-03
|
||
|
||
### Added
|
||
- Mutation-killing numeric-comparison test coverage and minimum-row
|
||
assertions on HTTP fault-path tests, closing gaps a mutation-testing pass
|
||
identified in the query engine's comparison operators.
|
||
|
||
## [0.1.9] - 2026-07-03
|
||
|
||
### Fixed
|
||
- `/_sim/reload` now rebuilds against the freshly-loaded `Site` object
|
||
(matched by id, falling back to name) instead of a stale pre-reload
|
||
reference, so topology edits actually take effect.
|
||
- The `fabricNodeIdentP` node-registration reaction now materializes an
|
||
enriched MO set (fabricNode + topSystem + healthInst + fabricLink/
|
||
lldpAdjEp/cdpAdjEp cabling + port inventory), not just a bare fabricNode.
|
||
- `GET /api/node/class/{class}.json` (no DN prefix) now correctly resolves
|
||
as the fabric-wide equivalent of `/api/class/{class}.json`.
|
||
|
||
## [0.1.8] - 2026-07-03
|
||
|
||
### Added
|
||
- Seeded batch-2/3 contract classes: port-channel/vPC member relations
|
||
(`pcAggrIf`, `pcRsMbrIfs`), transceiver/optics inventory (`ethpmFcot`),
|
||
APIC cluster health (`infraWiNode`), zoning-rule/pcTag plumbing
|
||
(`actrlRule`, `fvEpP`), EVPN VPN routes (`bgpVpnRoute`, `bgpPath`), and
|
||
boot-seeded node registration (`fabricNodeIdentP`). Deliberately did NOT
|
||
build `infraNodeIdentP` (no real consumer; a different concept from
|
||
`fabricNodeIdentP` despite the similar name).
|
||
|
||
## [0.1.7] - 2026-07-03
|
||
|
||
### Added
|
||
- Seeded batch-1 previously-catalogued-but-unbuilt contract classes:
|
||
access-policy cluster (`infraAccPortP`/`infraHPortS`/`infraPortBlk`/
|
||
`infraRsAccBaseGrp`/`infraAccBndlGrp`), route-control cluster
|
||
(`rtctrlProfile`/`rtctrlCtxP`/`rtctrlSubjP`/`rtctrlMatchRtDest`/
|
||
`rtctrlSetComm`/`rtctrlSetPref`), static routes (`ipRouteP`/`ipNexthopP`),
|
||
RIB/ARP (`uribv4Route`/`uribv4Nexthop`/`arpAdjEp`), `ospfIf`, and static
|
||
bindings (`fvRsPathAtt`, `vzRsSubjGraphAtt`).
|
||
|
||
## [0.1.6] - 2026-07-03
|
||
|
||
### Fixed
|
||
- Topology-consistency findings: real ports built for L3Out sub-interfaces
|
||
and spine OSPF/ISN uplinks (previously referenced but never built),
|
||
endpoint/APIC port separation on shared leaves, correct multi-site
|
||
endpoint semantics (home-site front-panel attachment vs. remote tunnel-
|
||
learned), BD `unicastRoute` now reflects actual subnet presence, and
|
||
controller health (`healthInst`) seeded for every controller node.
|
||
|
||
## [0.1.5] - 2026-07-03
|
||
|
||
### Fixed
|
||
- Auth is now enforced end-to-end: token validation, credential checking
|
||
against `SIM_USERNAME`/`SIM_PASSWORD`, session expiry
|
||
(`refreshTimeoutSeconds`), and APIC error envelopes (401/403) on every
|
||
query/write route instead of accepting any request.
|
||
|
||
## [0.1.4] - 2026-07-03
|
||
|
||
### Fixed
|
||
- Valid IPv4 derivation for node IDs greater than 255 (previous scheme
|
||
overflowed the last octet). Seeded the `userprofile`/`aaaUserDomain`
|
||
login-probe MO so the CONTRACT §1 subtree query resolves.
|
||
|
||
## [0.1.3] - 2026-07-03
|
||
|
||
### Fixed
|
||
- Write path is now atomic (validate-then-commit): a malformed node
|
||
anywhere in a POST body's tree rejects the whole write with a 400
|
||
envelope and leaves the store untouched. Canonical RN synthesis for
|
||
dn-less children (e.g. `fvBD` → `BD-{name}`) instead of a generic
|
||
`{class}-{name}` guess, avoiding orphan duplicate DNs.
|
||
|
||
## [0.1.2] - 2026-07-03
|
||
|
||
### Fixed
|
||
- Query engine: subtree-scope filtering now applies `query-target-filter`
|
||
to the whole scoped set (root + descendants) rather than pre-filtering
|
||
the root out of scope; `page`/`page-size` parameter validation (400 on
|
||
non-numeric/out-of-range values instead of silent truncation); stricter
|
||
filter-expression parsing (malformed/truncated expressions → 400 instead
|
||
of a 500 or silent no-op).
|
||
|
||
## [0.1.1] - 2026-07-02
|
||
|
||
### Fixed
|
||
- `rsp-subtree=full` nesting (recursive children, not one level).
|
||
- Comparison filter operators (`gt`/`lt`/`ge`/`le`/`bw`) with numeric-vs-
|
||
lexical comparison semantics.
|
||
|
||
## [0.1.0] - 2026-07-01
|
||
|
||
### Added
|
||
- Initial project scaffold: MIT store + query engine (P1/P2), topology
|
||
schema + default `topology.yaml`, fabric/tenant builders (P3/P4), the APIC
|
||
REST app + runtime supervisor + `/_sim` control API (P5), the NDO plane
|
||
(P6), and an end-to-end verification harness (P7) — see `docs/CONTRACT.md`
|
||
and `docs/DESIGN.md` for the full design record.
|