mirror of
https://github.com/dtzp555-max/aci-sim.git
synced 2026-07-21 21:15:12 +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>
91 lines
3.9 KiB
Markdown
91 lines
3.9 KiB
Markdown
# Contributing to aci-sim
|
|
|
|
Thanks for considering a contribution. This project is a REST simulator, not
|
|
a production service, so the bar is: does it faithfully match real APIC/NDO
|
|
behavior, and does the test suite stay green.
|
|
|
|
## Dev setup
|
|
|
|
```bash
|
|
git clone https://github.com/dtzp555-max/aci-sim.git
|
|
cd aci-sim
|
|
python -m venv .venv
|
|
source .venv/bin/activate # Windows: .venv\Scripts\activate
|
|
pip install -e '.[dev]' # installs aci_sim + fastapi/uvicorn/pydantic/pyyaml + httpx/pytest
|
|
```
|
|
|
|
## Running the tests
|
|
|
|
```bash
|
|
.venv/bin/python -m pytest -q
|
|
```
|
|
|
|
The suite currently has **888 tests** and must stay green. If you add a
|
|
feature or fix a bug, add or extend tests under `tests/` in the same PR —
|
|
most existing tests are organized by PR/feature (`tests/test_pr*.py`,
|
|
`tests/test_<feature>.py`); follow that convention for new ones.
|
|
|
|
`tests/verify_autoaci.py` (run via `scripts/verify.sh`) is a separate
|
|
verification harness that replays real ACI/NDO query patterns end-to-end
|
|
against a *running* sim instance — it's not part of the plain `pytest`
|
|
collection and isn't required for a normal PR, but it's worth running if
|
|
your change touches the query engine or the write path.
|
|
|
|
## Linting (informational only)
|
|
|
|
There's a `ruff` config in `pyproject.toml` (`[tool.ruff]`), and CI runs
|
|
`ruff check .` — but as a **non-blocking** job (see
|
|
`.github/workflows/ci.yml`'s `lint` job). There's a pre-existing baseline of
|
|
lint findings in the repo today; you don't need to fix unrelated ones in
|
|
your PR, but please don't add new ones in the code you touch.
|
|
|
|
```bash
|
|
.venv/bin/ruff check .
|
|
```
|
|
|
|
## `topology.yaml` drives everything
|
|
|
|
`topology.yaml` is the single source of truth for the whole simulated
|
|
fabric — sites, nodes, tenants, VRFs/BDs/EPGs, contracts, L3Outs, ISN,
|
|
seeded faults, and access-policy defaults. Every plane (both sites' APIC
|
|
stores and the NDO model) is derived from the *same* `Topology` object at
|
|
build time (`aci_sim/build/orchestrator.py`, `aci_sim/ndo/model.py`), which
|
|
is what keeps tenant/VRF/BD names and IDs consistent between a site's APIC
|
|
and NDO's view of it. If you're adding a new object or knob:
|
|
|
|
1. Add the field to `aci_sim/topology/schema.py` (Pydantic v2) — optional,
|
|
with a default that reproduces the pre-existing hardcoded behavior, so
|
|
existing `topology.yaml` files keep validating and building
|
|
byte-identical output.
|
|
2. Wire it into the relevant builder(s) under `aci_sim/build/`.
|
|
3. If it should show up in NDO's view too, wire it into `aci_sim/ndo/model.py`.
|
|
4. Run `aci-sim validate` against the repo's own `topology.yaml` and against
|
|
`aci-sim new`-generated topologies to confirm nothing regressed.
|
|
|
|
See `docs/DESIGN.md` for the module map and the design rationale behind
|
|
past additions, and `docs/CONTRACT.md` for the exact REST behavior contract
|
|
(error envelopes, query semantics, the object catalog) new code needs to
|
|
match.
|
|
|
|
## What PRs should (and shouldn't) do
|
|
|
|
- Keep `pytest -q` green — this is the actual acceptance bar, not a
|
|
suggestion.
|
|
- Prefer additive, backward-compatible changes to `topology.yaml`'s schema
|
|
(new optional fields with safe defaults) over changes that would break an
|
|
existing topology file.
|
|
- Match the existing code style — small, single-purpose builder functions,
|
|
docstrings that explain *why* (not just what), and tests that assert on
|
|
the exact REST response shape, not just "it didn't crash."
|
|
- **Do not reintroduce any real/customer data** — hostnames, IPs, tenant or
|
|
site names, credentials, or anything else identifying a real deployment.
|
|
This repo only uses generic placeholders (`LAB0`/`LAB1`/`LAB2`,
|
|
`App1`-`App5`, `MS-TN1`/`SF-TN1`, `10.192.x`/`10.10.x`, and similar) —
|
|
keep new examples, tests, and docs consistent with that convention.
|
|
|
|
## Filing issues
|
|
|
|
Bug reports are most useful with: the exact request (method + path + body)
|
|
that produced the wrong behavior, what you expected (ideally referencing
|
|
real APIC/NDO documented behavior), and what the sim actually returned.
|