threadlight-citadel-hub

Files (9)

• PROVENANCE.md
• README.md
• SKILL.md
• customer-checklist.md · references/
• live-audit-notes.md · references/
• enterprise-baseline.env · references/profiles/
• pilot-quickstart.env · references/profiles/
• vnet-isolated-spoke-aware.env · references/profiles/
• upstream-pin.md · references/

SKILL.md (first lines)

# Citadel Hub Deploy — Layer 1 Governance Hub

> **Status:** Public Preview wrapper around the
> [Azure-Samples / ai-hub-gateway-solution-accelerator] branch
> `citadel-v1` (MIT). The accelerator is the canonical source; this skill
> never forks or vendors its Bicep — it pins to a known-good commit, ships
> 3 curated AZD env profiles, and wires the deployment into the
> Threadlight conventions (tenant isolation, MCAPS pilot tagging,
> spoke-aware networking).
>
> **Pinned upstream:** `63f0f812474e713916dc909494d655246783a1d9`;
> see [`references/upstream-pin.md`](references/upstream-pin.md).
> **Validation boundary:** the current pin is build-validated and was
> live-deployed with the lean pilot overlay on 2026-08-19. Core APIM model
> discovery and chat succeeded. Positive client-credentials JWT validation
> remains unverified because the validation tenant's Conditional Access policy
> blocked workload token issuance; see
> [`references/live-audit-notes.md`](references/live-audit-notes.md).

[Azure-Samples / ai-hub-gateway-solution-accelerator]: https://github.com/Azure-Samples/ai-hub-gateway-solution-accelerator/tree/citadel-v1

---

## 1. Why this matters

Most "Foundry pilot" decks stop at "deploy a Foundry account, run an
agent". That works for **one** team and **one** use case. The moment a
second team needs the same model, you hit five hard problems:

1. **Cost attribution.** Whose subscription pays for which call?
2. **Quota fairness.** One team's batch run starves another's chat.
3. **Policy uniformity.** PII redaction, content safety, model
   allow-lists — defined once, enforced everywhere.
4. **Auditability.** Who called what model, when, with which prompt?
5. **Backend abstraction.** Switching a model from PTU → PayAsYouGo
   shouldn't require every spoke to re-deploy.

The Citadel Governance Hub is the AI Apps GBB reference design that
solves all five at the platform level. APIM in front of every model
backend, Cosmos for usage telemetry, Logic App for billing aggregation,
Event Hub for streaming events, and a **per-team Access Contract**
(APIM Product) that gives each spoke its own subscription key, scope,
and policy bundle.

Without this you end up with N spoke projects each negotiating their
own Foundry quota and their own PII policy — and your CISO finds out
on day 91.

```
   ┌──────────────────────────────────────────────────────────┐
   │   Layer 1 — Governance Hub (this skill deploys it)        │
   │                                                           │
   │  ┌────────────┐    ┌──────────┐    ┌──────────────────┐  │
   │  │ APIM v2    │ ←→ │ Cosmos   │ ←→ │ Foundry (×N)     │  │
   │  │ AI Gateway │    │ Usage DB │    │ Multi-region     │  │
   │  └────────────┘    └──────────┘    └──────────────────┘  │
   │       ↑                  ↑                                │
   │       │                  │                                │
   │  ┌────┴───┐   ┌──────────┴────┐                          │
   │  │ Event  │   │ Logic App     │                          │
   │  │ Hub    │   │ Usage         │                          │
   │  └────────┘   │ Aggregation   │                          │
   │               └───────────────┘                          │
   └──────────────────────────────────────────────────────────┘
            ↑                          ↑                ↑
            │ per-team access contract │                │
            │ (APIM Product + sub key) │                │
   ┌────────┴──────┐         ┌─────────┴─────┐  ┌──────┴────┐
   │ Spoke project │         │ Spoke project │  │ Foundry   │
   │  team A       │         │   team B      │  │ Workspace │
   │ (use citadel- │         │ (use citadel- │  │ (use      │
   │  spoke-onbrd) │         │  spoke-onbrd) │  │  spoke…)  │
   └───────────────┘         └───────────────┘  └───────────┘
```

---

## 2. What `threadlight-citadel-hub` does (and what it doesn't)

### Does

- Captures the upstream `azd` template at a **pinned SHA** (see
  `references/upstream-pin.md`); never silently rolls forward.
- Wraps the deployment in a **tenant-isolated, assertion-gated** workflow
  (see `threadlight-tenant-isolation`).
- Ships **3 curated AZD environment profiles** in `references/profiles/`:
  - `pilot-quickstart.env` — Developer SKU, lean optional-service overlay
  - `enterprise-baseline.env` — Standard v2, production-grade, BYO Log Analytics
  - `vnet-isolated-spoke-aware.env` — BYO VNet + DNS, pre-wired for
    `microsoft-foundry` spokes
- Documents the current **12-scenario upstream validation sequence** and
  the four-notebook strongly recommended baseline.
- Documents the **post-deploy hand-off** to `threadlight-citadel-spoke`
  (per-team access contracts) and `threadlight-govern` (in-process governance).

### Doesn't

- **Doesn't fork or vendor** the upstream Bicep. The deployment uses a
  detached Git checkout at the exact pinned SHA. `azd init` cannot pin a
  commit when given `--branch`, so branch-based initialization is forbidden.
- **Doesn't onboard spokes.** That's `threadlight-citadel-spoke` — a
  single `az deployment sub create` against
  `bicep/infra/citadel-access-contracts/main.bicep`.
- **Doesn't add in-process governance.** That's `threadlight-govern` — runs
  inside the agent process, before/after every tool call.
- **Doesn't manage post-deploy upgrades.** The
  `bicep/infra/apim-gateway-upgrade/` flow (StandardV2 → newer SKUs,
  policy fragment refresh) is upstream-owned.
- **Doesn't onboard LLM backends.** That's the
  `validation/llm-backend-onboarding-runner.ipynb` notebook upstream.

| Want to do this | Use this skill instead |
|---|---|
| Wire your agent project into a deployed hub | `threadlight-citadel-spoke` |
| Add per-tool-call governance inside MAF/Foundry agents | `threadlight-govern` |
| Deploy a single-resource Foundry inside a private VNet (no APIM) | `microsoft-foundry` |
| Switch tenants, isolate az/azd config dirs | `threadlight-tenant-isolation` |
| Apply MCAPS pilot tagging conventions (`SecurityControl: Ignore`, `AZURE_TAGS`) | `threadlight-deploy/references/azd-modules` |
| Get App Insights traces from the deployed hub into your spoke | `threadlight-deploy/references/observability` |

From aiappsgbb/threadlight-skills, MIT.

More from aiappsgbb/threadlight-skills