open/ms-ai-architect
1
0
Fork 0
Code Issues Releases 4 Activity

feat(ultraplan-local): v1.6.0 — /ultraresearch-local deep research command

Browse source 
Add /ultraresearch-local for structured research combining local codebase
analysis with external knowledge via parallel agent swarms. Produces research
briefs with triangulation, confidence ratings, and source quality assessment.

New command: /ultraresearch-local with modes --quick, --local, --external, --fg.
New agents: research-orchestrator (opus), docs-researcher, community-researcher,
security-researcher, contrarian-researcher, gemini-bridge (all sonnet).
New template: research-brief-template.md.

Integration: --research flag in /ultraplan-local accepts pre-built research
briefs (up to 3), enriches the interview and exploration phases. Planning
orchestrator cross-references brief findings during synthesis.

Design principle: Context Engineering — right information to right agent at
right time. Research briefs are structured artifacts in the pipeline:
ultraresearch → brief → ultraplan --research → plan → ultraexecute.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Kjell Tore Guttormsen 2026-04-08 08:58:35 +02:00
commit baa2d0220b
488 changed files with 213221 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

436
skills/ms-ai-engineering/references/api-management/multi-region-ai-gateway-design.md Normal file
View file

@ -0,0 +1,436 @@
# Multi-Region AI Gateway Architecture
**Last updated:** 2026-02
**Status:** GA
**Category:** API Management & AI Gateway
---
## Introduksjon
Organisasjoner som bygger AI-drevne tjenester med Azure OpenAI og andre LLM-tjenester trenger en gateway-arkitektur som tåler regionale feil, minimerer latens for geografisk distribuerte brukere, og overholder krav til dataresidency. Azure API Management (APIM) med multi-region deployment gir nettopp denne kapabiliteten, og er den anbefalte tilnærmingen for enterprise AI-workloads.
For norsk offentlig sektor er multi-region-design spesielt relevant: mange organisasjoner har krav om at data skal behandles innenfor EØS, men ønsker samtidig redundans og lav latens. APIM Premium-tier støtter multi-region gateways med én kontrollplan, noe som forenkler administrasjon og gir automatisk failover mellom regioner. Denne referansen dekker alle aspekter ved design, deploy og drift av en geografisk distribuert AI-gateway.
En vellykket multi-region AI-gateway-arkitektur balanserer tre hensyn: pålitelighet (at tjenesten overlever regionale feil), ytelse (at brukere opplever lav latens uavhengig av lokasjon), og compliance (at data behandles i henhold til regulatoriske krav). API Management løser alle tre gjennom innebygd FQDN-routing, regionale gateways og policy-basert trafikkhåndtering.
---
## Global APIM Distribution
### Multi-Region Deployment Architecture
APIM Premium-tier støtter replikering av gateway-komponenten til flere Azure-regioner. Kontrollplanet (management plane) og utviklerportalen forblir i primærregionen, mens gateway-trafikk håndteres lokalt i hver region.
| Komponent | Distribusjon | Merknader |
|-----------|-------------|-----------|
| Management plane | Kun primærregion | API-definisjoner, policyer, brukerhåndtering |
| Developer portal | Kun primærregion | Brukerregistrering, API-dokumentasjon |
| Gateway | Alle konfigurerte regioner | Håndterer API-trafikk, policy-kjøring |
| Policy-konfigurasjon | Synkronisert (< 10 sek) | Automatisk propagering til alle regioner |
### Deployment via Azure Portal
```
1. Naviger til APIM-instansen → Locations
2. Klikk "+ Add" → Velg region (f.eks. North Europe)
3. Konfigurer antall scale units
4. Aktiver availability zones (anbefalt)
5. Konfigurer VNet/subnet hvis nettverksintegrert
6. Klikk "Add" → gjenta for flere regioner
7. Klikk "Save" for å starte deployment
```
### Bicep-template for Multi-Region APIM
```bicep
resource apim 'Microsoft.ApiManagement/service@2023-09-01-preview' = {
name: 'ai-gateway-apim'
location: 'westeurope'
sku: {
name: 'Premium'
capacity: 2
}
properties: {
publisherEmail: 'admin@example.com'
publisherName: 'AI Gateway'
additionalLocations: [
{
location: 'northeurope'
sku: {
name: 'Premium'
capacity: 1
}
zones: ['1', '2', '3']
}
{
location: 'swedencentral'
sku: {
name: 'Premium'
capacity: 1
}
zones: ['1', '2', '3']
}
]
}
}
```
### Regional DNS-mønster
Hver region får et eget DNS-endepunkt:
| Region | URL-mønster |
|--------|------------|
| Primary (West Europe) | `https://ai-gateway-apim.azure-api.net` |
| West Europe (regional) | `https://ai-gateway-apim-westeurope-01.regional.azure-api.net` |
| North Europe (regional) | `https://ai-gateway-apim-northeurope-01.regional.azure-api.net` |
| Sweden Central (regional) | `https://ai-gateway-apim-swedencentral-01.regional.azure-api.net` |
---
## Region-Aware Routing
### Innebygd Latency-basert Routing
APIM tilbyr automatisk FQDN-basert routing som sender trafikk til gatewayen med lavest latens. Dette er standard oppførsel for multi-region deployments og krever ingen ekstra konfigurasjon.
```
Klient → DNS-oppslag (ai-gateway-apim.azure-api.net)
→ Latency-basert resolving → Nærmeste gateway
→ Lokal policy-kjøring → Backend-kall
```
### Routing til Regionale Backend-tjenester
For å utnytte geografisk distribusjon fullt ut, bør Azure OpenAI-instanser deployes i samme regioner som APIM-gateways. Bruk `context.Deployment.Region` for å rute til lokale backends:
```xml
<policies>
<inbound>
<base />
<choose>
<when condition="@("West Europe".Equals(context.Deployment.Region,
StringComparison.OrdinalIgnoreCase))">
<set-backend-service backend-id="aoai-westeurope" />
</when>
<when condition="@("North Europe".Equals(context.Deployment.Region,
StringComparison.OrdinalIgnoreCase))">
<set-backend-service backend-id="aoai-northeurope" />
</when>
<when condition="@("Sweden Central".Equals(context.Deployment.Region,
StringComparison.OrdinalIgnoreCase))">
<set-backend-service backend-id="aoai-swedencentral" />
</when>
<otherwise>
<set-backend-service backend-id="aoai-westeurope" />
</otherwise>
</choose>
</inbound>
<backend>
<base />
</backend>
<outbound>
<base />
</outbound>
<on-error>
<base />
</on-error>
</policies>
```
### Backend Pool med Priority-basert Load Balancing
Kombinér regionale backends med priority groups for automatisk failover:
```bicep
resource backendPool 'Microsoft.ApiManagement/service/backends@2023-09-01-preview' = {
name: 'ai-gateway-apim/aoai-pool-westeurope'
properties: {
description: 'West Europe pool med failover til North Europe'
type: 'Pool'
pool: {
services: [
{
id: '/subscriptions/.../backends/aoai-westeurope'
priority: 1
weight: 1
}
{
id: '/subscriptions/.../backends/aoai-northeurope'
priority: 2
weight: 1
}
]
}
}
}
```
### Egendefinert Routing med Azure Traffic Manager
For scenarier der innebygd routing ikke er tilstrekkelig:
```
1. Opprett Azure Traffic Manager-profil
2. Konfigurer APIM regionale endepunkter som endpoints
3. Bruk Geographic routing for data residency
4. Konfigurer health probe mot /status-0123456789abcdef
5. Pek custom domain mot Traffic Manager
```
| Routing-metode | Bruksområde |
|---------------|------------|
| Geographic | Data residency-krav (EØS-region) |
| Performance | Lavest latens for sluttbrukere |
| Priority | DR-scenarier med primær/sekundær |
| Weighted | Gradvis migrering mellom regioner |
---
## Latency Optimization
### Strategier for Lav Latens
| Strategi | Beskrivelse | Latensreduksjon |
|----------|-------------|-----------------|
| Co-lokalisering | APIM gateway + Azure OpenAI i samme region | Eliminerer cross-region latens |
| Semantic caching | Cacher tidligere LLM-completions | 50-90% for gjentatte prompts |
| Private endpoints | Direkte nettverksforbindelse uten offentlig internett | 10-30ms reduksjon |
| Connection pooling | Gjenbruk av TCP-forbindelser | 50-100ms per request |
| Regional DNS | Innebygd FQDN med latency-based routing | Automatisk optimal ruting |
### Semantic Caching med Azure Managed Redis
```xml
<inbound>
<base />
<llm-semantic-cache-lookup
score-threshold="0.9"
embeddings-backend-id="embedding-backend"
embeddings-backend-auth="system-assigned" />
</inbound>
<outbound>
<base />
<llm-semantic-cache-store duration="3600" />
</outbound>
```
### Måling av Regional Latens
Bruk `llm-emit-token-metric` med regiondimensjon for å spore latens per region:
```xml
<llm-emit-token-metric namespace="ai-gateway-metrics">
<dimension name="Region" value="@(context.Deployment.Region)" />
<dimension name="API" value="@(context.Api.Name)" />
<dimension name="Backend" value="@(context.Request.Url.Host)" />
</llm-emit-token-metric>
```
---
## Data Residency Compliance
### EØS Data Residency-krav
For norsk offentlig sektor med krav om databehandling innenfor EØS:
| Krav | APIM-implementasjon |
|------|---------------------|
| Data-at-rest i EØS | Deploy APIM primærregion i West Europe/North Europe |
| Data-in-transit i EØS | Private endpoints + VNet-isolasjon |
| Ingen cross-geopolitical failover | Separate gateways per geopolitisk grense |
| Logging i EØS | Log Analytics workspace i EØS-region |
| Nøkkelhåndtering i EØS | Azure Key Vault i EØS-region |
### Viktige Advarsler
**Ikke** implementer en enhetlig gateway på tvers av geopolitiske regioner når data residency er påkrevd:
```
RIKTIG:
Gateway (West Europe) → Azure OpenAI (West Europe)
Gateway (North Europe) → Azure OpenAI (North Europe)
Separate FQDN per region
FEIL:
Gateway (West Europe) → Azure OpenAI (East US) ← Bryter data residency
Enhetlig gateway med failover til US-region ← Bryter data residency
```
### Azure OpenAI Deployment Types og Data Residency
| Deployment Type | Data Residency | Egnet for offentlig sektor? |
|----------------|---------------|---------------------------|
| Standard | Data i angitt region | Ja, med EØS-region |
| Provisioned (PTU) | Data i angitt region | Ja, med EØS-region |
| Data Zone Standard | Data innenfor Azure data zone | Ja, med European data zone |
| Global Standard | Data kan prosesseres i enhver region | Nei, ikke for data residency-krav |
### Policy for Data Residency Enforcement
```xml
<inbound>
<base />
<!-- Blokkér requests som kan rutes utenfor EØS -->
<choose>
<when condition="@(!new[] { "West Europe", "North Europe",
"Sweden Central", "France Central", "Germany West Central" }
.Contains(context.Deployment.Region))">
<return-response>
<set-status code="403" reason="Forbidden" />
<set-body>Data residency violation: Request routed outside EEA</set-body>
</return-response>
</when>
</choose>
</inbound>
```
---
## Cross-Region Failover
### Automatisk Failover med Innebygd FQDN
Ved standard multi-region deployment håndterer APIM failover automatisk:
```
1. Gateway i Region A svarer ikke
2. DNS TTL utløper (typisk 5-10 minutter)
3. Trafikk rutes til Region B (lavest latens blant aktive)
4. Klienter MÅ respektere DNS TTL
5. Retry-logikk i klient håndterer overgangsperiode
```
### Disable/Enable Regional Gateway
For planlagt vedlikehold eller DR-testing:
```bash
# Deaktiver gateway i North Europe
az apim update \
--name ai-gateway-apim \
--resource-group rg-apim \
--set additionalLocations[location="North Europe"].disableGateway=true
# Verifiser status
az apim show \
--name ai-gateway-apim \
--resource-group rg-apim \
--query "additionalLocations[].{Location:location,Disabled:disableGateway,Url:gatewayRegionalUrl}" \
--output table
# Reaktiver etter vedlikehold
az apim update \
--name ai-gateway-apim \
--resource-group rg-apim \
--set additionalLocations[location="North Europe"].disableGateway=false
```
### Active-Active med Active-Passive Azure OpenAI
For maksimal pålitelighet, kombinér active-active gateway med active-passive backend:
```
Region A (Active):
APIM Gateway → PTU Azure OpenAI (Priority 1)
→ Standard Azure OpenAI (Priority 2, failover)
Region B (Active):
APIM Gateway → PTU Azure OpenAI (Priority 1)
→ Standard Azure OpenAI (Priority 2, failover)
Cross-region failover:
Region A feil → All trafikk til Region B
Region A PTU throttled → Standard deployment i Region A
```
### Circuit Breaker for Backend Failover
```bicep
resource backend 'Microsoft.ApiManagement/service/backends@2023-09-01-preview' = {
name: 'ai-gateway-apim/aoai-westeurope'
properties: {
url: 'https://aoai-westeurope.openai.azure.com'
protocol: 'http'
circuitBreaker: {
rules: [
{
failureCondition: {
count: 3
errorReasons: ['Server errors']
interval: 'PT1M'
statusCodeRanges: [
{ min: 429, max: 429 }
{ min: 500, max: 599 }
]
}
name: 'aoai-breaker'
tripDuration: 'PT30S'
acceptRetryAfter: true
}
]
}
}
}
```
### Kapasitetsplanlegging for Failover
Ved failover må gjenværende regioner absorbere all trafikk:
| Scenario | Region A Kapasitet | Region B Kapasitet | Nødvendig overprovisionering |
|----------|-------------------|-------------------|-----------------------------|
| 2 regioner, active-active | 100% normal load | 100% normal load | Hver region: 2x normal |
| 2 regioner, active-passive | 100% normal load | 0% (standby) | Passiv region: 1x normal |
| 3 regioner, active-active | 33% normal load | 33% normal load | Hver region: 1.5x normal |
Bruk [Azure OpenAI Capacity Calculator](https://oai.azure.com/portal/calculator) for PTU-kapasitetsplanlegging.
---
## Nettverksarkitektur
### Internal VNet Mode — Multi-Region
For scenarier med intern VNet-modus (typisk for offentlig sektor):
```
Klient → Azure Front Door (WAF) → Private Endpoint → APIM Gateway (Region A)
→ APIM Gateway (Region B)
→ Egenhåndtert routing (Load Balancer/Traffic Manager)
```
**Viktig:** I internal VNet-modus håndterer APIM IKKE automatisk routing mellom regionale gateways. Organisasjonen må selv implementere routing via Azure Front Door, Traffic Manager, eller en annen load balancer.
### VNet Krav per Region
Hver region krever eget VNet med nødvendige NSG-regler:
| Port | Retning | Formål |
|------|---------|--------|
| 3443 | Inbound | Management traffic |
| 443 | Inbound | Client traffic (HTTPS) |
| 1433 | Outbound | Azure SQL (primærregion) — påkrevd fra alle regioner |
| 443 | Outbound | Azure Storage, Azure Monitor, Key Vault |
---
## Referanser
- [Deploy an Azure API Management instance to multiple Azure regions](https://learn.microsoft.com/en-us/azure/api-management/api-management-howto-deploy-multi-region) — Offisiell guide for multi-region deployment
- [Use a gateway in front of multiple Azure OpenAI deployments or instances](https://learn.microsoft.com/en-us/azure/architecture/ai-ml/guide/azure-openai-gateway-multi-backend) — Arkitekturmønstre for AI gateway
- [AI gateway in Azure API Management](https://learn.microsoft.com/en-us/azure/api-management/genai-gateway-capabilities) — Oversikt over AI gateway-kapabiliteter
- [Access Azure OpenAI through a gateway](https://learn.microsoft.com/en-us/azure/architecture/ai-ml/guide/azure-openai-gateway-guide) — Well-Architected Framework-veiledning
- [Azure OpenAI deployment types](https://learn.microsoft.com/en-us/azure/ai-foundry/foundry-models/concepts/deployment-types) — Deployment types og data residency
---
## For Cosmo
- **Bruk denne referansen** når kunder trenger en AI-gateway som dekker flere Azure-regioner, eller når data residency og failover er sentrale krav.
- For norsk offentlig sektor: Anbefal alltid EØS-regioner (West Europe, North Europe, Sweden Central) og advar eksplisitt mot Global Standard deployments som kan prosessere data utenfor EØS.
- Husk at rate-limiting policyer (rate-limit, llm-token-limit) teller separat per regional gateway — dette betyr at en 1000 TPM-grense gjelder per region, ikke totalt.
- Start enkelt med to EØS-regioner (West Europe + North Europe) og vurder tredje region (Sweden Central) kun ved behov for høyere tilgjengelighet.
- Kombiner alltid multi-region gateway med circuit breaker og backend pools for å sikre automatisk failover uten manuell intervensjon.