threadlight-citadel-spoke

Files (6)

• PROVENANCE.md
• SKILL.md
• __init__.py · references/python/
• access_contract_probe.py · references/python/
• upstream-pin.md · references/
• manual_consumer_prompt.md · test-fixture/

SKILL.md (first lines)

# Citadel Spoke Onboarding — Reference Guide

How to connect a GenAI application or Microsoft Foundry project to an
**existing** AI Citadel Governance Hub. Controls cover the traffic actually routed
through the gateway, not every agent action or a compliance certification.

> **Threadlight integration**: This skill is the **opt-in Phase 7** of
> `threadlight-deploy`. It runs ONLY when SPEC § 11b sets
> `governance_hub.required: yes` (the SPEC field is generic; the AI
> Citadel hub is one reference implementation). The base agent deploy
> (Phase 5 + 6) lands in the customer's tenant first; this skill
> onboards it as a hub spoke afterwards as an additive step. Read
> SPEC § 11b for the per-process governance posture (hub endpoint,
> access contracts, JWT requirements, secret wiring).
>
> **Threadlight pilots MUST use Option B (Foundry Connection)** — see
> `Consuming the Gateway from Your App` below. Option A (Key Vault
> secret pull) violates the keyless-by-mandate posture: it requires
> the agent to hold an APIM subscription key and read it from KV at
> runtime. Option B threads the call through a Foundry APIM connection
> so the agent does not retrieve the subscription key. The pinned connection
> uses `authType: ApiKey`; this is **not end-to-end keyless**. Caller-to-Foundry
> Entra authentication, connection-managed secret custody and downstream APIM
> authentication are separate boundaries. JWT requires its own approved setup
> and positive/negative runtime evidence; no MI-to-APIM JWT flow is implied.
> If a customer insists on
> Option A for a non-threadlight reason, document the deviation in
> SPEC § 11b explicitly.

> **Source:** [exact hub/spoke revision](https://github.com/Azure-Samples/ai-hub-gateway-solution-accelerator/tree/63f0f812474e713916dc909494d655246783a1d9).
> The [pin record](references/upstream-pin.md) separates source comparison from
> live compatibility. `citadel-v1` is a freshness signal, not a deployment input.
> **Quick link:** <https://aka.ms/ai-hub-gateway>

---

## Key Concepts

| Term | Meaning |
|------|---------|
| **Citadel Governance Hub** | Central control plane with Azure API Management (APIM) acting as the unified AI gateway. Already deployed — not your concern here. |
| **Spoke** | An isolated workload environment (Foundry project, Container App, Function, etc.) that consumes AI services **through** the hub gateway. |
| **Access Contract** | A Bicep parameter file (`.bicepparam`) + optional policy XML declaring what AI services a spoke needs, with what policies. Deployed as IaC. |
| **Foundry Connection** | An APIM-type connection inside an Azure AI Foundry project that routes model calls through the Citadel gateway. |
| **Service Code** | Short acronym mapping a category of AI services to APIM API IDs (e.g. `LLM`, `DOC`, `SRCH`, `OAIRT`). |

---

## What Gets Created Per Access Contract

| Resource | Naming Pattern | Description |
|----------|----------------|-------------|
| **APIM Product** | `{code}-{BU}-{UseCase}-{ENV}` | One per service code, with attached APIs and policies |
| **APIM Subscription** | `{product}-SUB-01` | Subscription with API key |
| **Key Vault Secrets** (optional) | `{secretName}` | Endpoint URL + API key stored in KV |
| **Foundry Connection** (optional) | `{prefix}-{code}` | APIM connection for Foundry agents |

---

## Prerequisites (Spoke Side)

| Requirement | Details |
|-------------|---------|
| Running Citadel Hub | APIM deployed with published APIs matching your `apiNameMapping` |
| Azure CLI + Bicep | Latest version with `az deployment sub create` support |
| Permissions | `API Management Service Contributor` on APIM RG, `Key Vault Secrets Officer` on target KV (if used), `Contributor` on Foundry RG (if using Foundry connections) |
| Foundry Project | Must exist if you want APIM connections inside Foundry |

Before any operator Azure call, apply
[`threadlight-tenant-isolation`](../threadlight-tenant-isolation/SKILL.md): paired isolated
CLI/AZD context and the approved exact tenant/subscription. Assert the target
immediately before writes. Read-only inventory grants no repair authority.

---

## Step-by-Step: Create an Access Contract

### 1. Scaffold the Contract Folder

Materialize the exact reviewed hub revision, then follow
`contracts/<businessunit-usecasename>/<environment>/`. Do not overwrite an existing
checkout, deployed contract or policy to align a pin.

```bash
PINNED_SHA="63f0f812474e713916dc909494d655246783a1d9"
git clone --filter=blob:none --no-checkout https://github.com/Azure-Samples/ai-hub-gateway-solution-accelerator.git
cd ai-hub-gateway-solution-accelerator
git fetch --depth 1 origin "$PINNED_SHA"
git checkout --detach "$PINNED_SHA"
test "$(git rev-parse HEAD)" = "$PINNED_SHA"
cd bicep/infra/citadel-access-contracts

# Create contract folder
mkdir -p contracts/myteam-myagent/dev
cd contracts/myteam-myagent/dev

# Copy templates
cp ../../../main.bicepparam main.bicepparam
cp ../../../policies/default-ai-product-policy.xml ai-product-policy.xml
```

> 📂 Full contract folder structure and module reference:
> [citadel-access-contracts/](https://github.com/Azure-Samples/ai-hub-gateway-solution-accelerator/tree/citadel-v1/bicep/infra/citadel-access-contracts)
>
> ⚠️ Sample contracts were removed from the repo. Use `main.bicepparam` as your template base.
> Review `allowedModels` explicitly: this revision's default LLM policy allows
> `gpt-4.1,gpt-5.4-mini`, unlike the older policy's broader list. Existing
> approved policies are not replaced automatically. Leave optional key rotation
> and additional-gateway settings disabled unless separately approved.

### 2. Configure the Parameter File

Edit `main.bicepparam`:

```bicep
using '../../../main.bicep'

// ── Hub coordinates (get these from your platform team) ──
param apim = {

From aiappsgbb/threadlight-skills, MIT.

More from aiappsgbb/threadlight-skills