avd-opsConcepts
- Built on my own time for research and learning. Not affiliated with, endorsed by or supported by my employer or Microsoft.
- Don't run any of it in production or against tenants that matter. Test in a dedicated lab subscription and tenant first.
- Provided "as is", without warranty of any kind, under each repo's license. You use it at your own risk and own the Azure charges it incurs.
- Contributions and forks are welcome and encouraged. See Contribute.
The repos share a handful of ideas. Each is explained in full in the repo that owns it; this page is the short version with the links.
Three questions, three repos, and a layer on top
Each repo answers one question (family roles):
| Question | Repo |
|---|---|
| How it's built and changed from here | avd-landing-zone |
| What is there now | avd-current-state |
| What it should be, and why | avd-assess |
On top of those sits an intelligence and abstraction layer: avd-second-brain is the why over the environment's whole life, and avd-swarm is the how of operating it.
Dependencies point down, never up: avd-landing-zone and avd-current-state are a self-contained pair that keeps working with no second brain and no avd-swarm.
Contracts, not shared code
The repos pass versioned, redacted files to each other instead of importing each other's code. Each format has a number (C6 knowledge, C11 current-state facts, C14 target state, C15 the fact register and so on) and one JSON Schema. avd-second-brain holds the registry, and repos that read a format keep a byte-identical copy pinned to a commit. See contracts.
The brain thinks, the swarm acts
avd-second-brain never holds a write credential. Every change to an estate is a plan that avd-swarm proposes, a person approves in a GitHub environment, and a governance gate checks against live state. One layered kill switch stops it, and only the owner resets it. See decision 0003 and avd-swarm's governance.
Tenant data stays with the tenant
Collectors and validators read an estate; what leaves it is redacted: counts, public values and pseudonyms, never names or IDs. A customer's estate vault lives in that customer's private repo. None of the public repos holds tenant data.
Read first, change with approval
Scripts and agents read freely. Anything that creates, changes or deletes cloud resources runs only after a person approves it, and every sandbox run comes with a cost estimate and a teardown.
Keep the last copy, stop the meter
Teardown removes what a redeploy recreates and keeps the data. Logs and teardown proof go to one run
store outside the deployment, kept by default (-TeardownLogs Keep), and deleting data with no
checked copy elsewhere needs -DiscardLastCopy, which -Force never implies
(never delete the last copy,
avd-second-brain decision 0016).
Anything that bills by time is removed, stopped or scheduled at the end of a run unless you opt in
with -KeepRunning <until>, and recurring commitments such as licenses and Marketplace offers are
recorded with their cancel windows, never bought by a script
(never leave the meter running,
decision 0017).
Your own copies go to a separate
private companion repo.
Knowledge capture
Each repo records what a change taught in a knowledge base in the shared format, or says why there's nothing to record, and a pull request check asks for it. The format comes from the 2ndbrain template; the AVD lessons live in avd-second-brain's knowledge base. These docs use the same format.
What's out of scope
The repos use Bicep, PowerShell and native Azure, Entra and Microsoft 365 tooling only. Asks outside that lane are referred elsewhere by avd-second-brain's lane rules (decision 0012).