README
¶
vikasa-infra
Deploys and secures the NATS/JetStream infrastructure for Vikasa — the clusters, streams, and accounts, plus the security around them: mTLS, NATS JWT/nkey identity, cert-manager PKI, secrets, and each cabinet's NATS leaf + scoped credentials (GitOps overlays + runbooks). That's its whole scope — it does not deploy the collector or deal with the models.
Part of a three-repo split. This repo provisions and secures the NATS/JetStream platform the telemetry flows through — it does not deploy the collector, and has nothing to do with the models vocabulary.
openits-models— the standard ("openconfig for ITS"): YANG-sourced, vendor-neutral telemetry + control vocabulary. Not avikasa-infraconcern.vikasa-collector— reference collector: the cabinet poller translates native SNMP/NTCIP into the OpenITS vocabulary and pushes telemetry into JetStream (plus central-side components). Not deployed by this repo.vikasa-infra— this repo: provisions and secures the NATS/JetStream clusters, PKI, secrets, GitOps overlays, and the cabinet (Pi) base install.
flowchart LR
models["<b>openits-models</b><br/>the standard (vocabulary)"]
collector["<b>vikasa-collector</b><br/>collector — in the cabinet"]
js["NATS / JetStream"]
infra["<b>vikasa-infra</b><br/>(this repo)"]
models -->|"native → OpenITS"| collector
collector -->|"pushes telemetry"| js
infra -->|"provisions + secures"| js
Start here:
docs/README.md— the documentation index (map of every doc).docs/CONCEPTS.md— the five-minute, diagram-led overview (start here if you want the executive/stakeholder picture).docs/ARCHITECTURE.md— the north-star design and the A–E sub-project decomposition.docs/scaling-profiles.md·docs/capacity-model.md— how to size a deployment (profiles, partitions, nodes, retention).
Development
make test # unit tests (includes golden-tree byte comparisons)
make integration # embedded-NATS end-to-end tests (DMZ data path)
make lint # go vet + gofmt check
make golden # regenerate goldens after an intentional output change
Golden tests byte-compare cmd/gen's full output tree against
cmd/gen/testdata/golden-*. When you change generated output on purpose, run
make golden (sets UPDATE_GOLDEN=1) and review the git diff — the diff
is the review artifact.
License
Apache License 2.0 — see LICENSE.
Security
See SECURITY.md for how to report vulnerabilities privately.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
credhealth
command
Command credhealth scans a minted credential bundle (see cmd/issue) and reports each time-bound artifact's expiry status, exiting non-zero when anything is expired, expiring, or unreadable.
|
Command credhealth scans a minted credential bundle (see cmd/issue) and reports each time-bound artifact's expiry status, exiting non-zero when anything is expired, expiring, or unreadable. |
|
gen
command
Package main is the vikasa-infra code generator CLI.
|
Package main is the vikasa-infra code generator CLI. |
|
issue
command
Command issue mints the NATS operator + account trust chain from a topology spec (via the B1 account model) into a local, gitignored credentials dir.
|
Command issue mints the NATS operator + account trust chain from a topology spec (via the B1 account model) into a local, gitignored credentials dir. |
|
internal
|
|
|
accounts
Package accounts builds the NATS account topology + ACL model (the identity and authorization system of record, per architecture §8) from the topology.
|
Package accounts builds the NATS account topology + ACL model (the identity and authorization system of record, per architecture §8) from the topology. |
|
credhealth
Package credhealth scans a minted credential bundle and classifies each time-bound artifact (JWTs + X.509 certs) by expiry.
|
Package credhealth scans a minted credential bundle and classifies each time-bound artifact (JWTs + X.509 certs) by expiry. |
|
fleet
Package fleet loads the cabinet inventory — the operational list of cabinets and the partition each sources into.
|
Package fleet loads the cabinet inventory — the operational list of cabinets and the partition each sources into. |
|
issuance
Package issuance mints the NATS operator + account trust chain from the B1 account model (operator keypair + JWT, per-account keypairs + operator-signed account JWTs), writing a resolver-ready credential bundle.
|
Package issuance mints the NATS operator + account trust chain from the B1 account model (operator keypair + JWT, per-account keypairs + operator-signed account JWTs), writing a resolver-ready credential bundle. |
|
naming
Package naming owns the NATS naming and subject-space conventions shared by planning, account modelling, and credential issuance.
|
Package naming owns the NATS naming and subject-space conventions shared by planning, account modelling, and credential issuance. |
|
pki
Package pki issues X.509 client certificates for cabinet transport mTLS.
|
Package pki issues X.509 client certificates for cabinet transport mTLS. |
|
plan
Package plan defines the substrate-independent intermediate representation (IR) for a Vikasa infrastructure deployment.
|
Package plan defines the substrate-independent intermediate representation (IR) for a Vikasa infrastructure deployment. |
|
render
Package render contains substrate-specific renderers that materialize a substrate-independent plan.Plan into named file contents.
|
Package render contains substrate-specific renderers that materialize a substrate-independent plan.Plan into named file contents. |
|
topology
Package topology is the hand-written topology model for vikasa-infra.
|
Package topology is the hand-written topology model for vikasa-infra. |
Click to show internal directories.
Click to hide internal directories.