Runbook: Primary lokálně + Azure Gateway¶

Provozní runbook pro ověřenou hybridní topologii: local Primary + AKS Gateway

Verze dokumentu: 1.0.0
Poslední aktualizace: 2026-04-13
Licenční úroveň: Enterprise+

1. Rozsah¶

Tento runbook popisuje přesný model nasazení, kde:

Primary backend běží lokálně (Docker Compose)
Gateway běží v Azure AKS (MAZEVAULT_MODE=gateway)
Bootstrap a provoz gateway jsou řízené Primary serverem
Azure používá Managed Identity + Workload Identity pro Key Vault secrets

2. Kritické chování: lokální vs Azure¶

docker compose -f docker-compose.yml up --build rebuilduje a spouští pouze lokální kontejnery.

Azure se tím neaktualizuje.

Pro promítnutí změn do Azure gateway je nutné:

Build + push image do ACR
Aplikace manifestů/Helm hodnot do AKS
Rollout restart a ověření běhu podu

3. Povinná Entra callback adresa¶

V Entra App Registration pro MazeVault SSO použijte:

https://<BACKEND_NEBO_PUBLIC_API_HOST>/api/v1/auth/sso/entra/callback

Použití /auth/entra/callback v této architektuře vede k redirect mismatch.

4. Bootstrap token z Primary¶

TOKEN=$(curl -sk -X POST https://PRIMARY_URL/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@mazevault.com","password":"VAŠE_HESLO"}' | jq -r '.token')

curl -sk -X POST https://PRIMARY_URL/api/v1/gateways/bootstrap \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"azure-gateway-gwc-01"}'

Vrácený token uložte jako GATEWAY_BOOTSTRAP_TOKEN.

5. Build a publikace gateway image¶

docker build -t acrmzvtest.azurecr.io/mazevault-backend:latest \
  -f maze-core/backend/Dockerfile \
  maze-core/backend

docker push acrmzvtest.azurecr.io/mazevault-backend:latest

6. Managed Identity + Workload Identity (povinné)¶

6.1 Zapnutí AKS OIDC + workload identity¶

az aks update \
  --resource-group rg-mazevault-<env> \
  --name aks-mazevault-<env> \
  --enable-oidc-issuer \
  --enable-workload-identity

6.2 Subject federované identity musí přesně odpovídat service accountu¶

Gateway service account v tomto nasazení:

system:serviceaccount:mazevault:mazevault-gateway-sa

Vytvoření/aktualizace federovaného cred:

az identity federated-credential create \
  --identity-name id-mazevault-<env>-<region> \
  --resource-group rg-mazevault-<env> \
  --name fic-mazevault-gateway-sa \
  --issuer <AKS_OIDC_ISSUER_URL> \
  --subject system:serviceaccount:mazevault:mazevault-gateway-sa \
  --audiences api://AzureADTokenExchange

Pokud subject nesouhlasí, mount v podu selže s AADSTS700213.

7. Metoda dodání secretů z Key Vault¶

Použijte Secrets Store CSI Driver + SecretProviderClass pro runtime secrets gateway.

kubectl apply -f maze-core/deploy/k8s/azure-test/gateway-secrets-provider.yaml
kubectl apply -f maze-core/deploy/k8s/azure-test/gateway-deployment.yaml
kubectl rollout restart deployment/mazevault-gateway-npr -n mazevault
kubectl rollout status deployment/mazevault-gateway-npr -n mazevault --timeout=300s

Ověření synchronizace:

kubectl get secretproviderclass -n mazevault
kubectl get secretproviderclasspodstatus -n mazevault
kubectl get secret mazevault-gateway-config -n mazevault

8. Service Principal pro provisioning (Terraform/CI)¶

Použijte dedikovaný Service Principal pouze pro provisioning infrastruktury.

Požadované minimální role na subscription nebo resource-group scope:

Contributor
User Access Administrator

Požadované registrace providerů (jednorázově na subscription):

az provider register --namespace Microsoft.ContainerService --wait
az provider register --namespace Microsoft.KeyVault --wait
az provider register --namespace Microsoft.DBforPostgreSQL --wait
az provider register --namespace Microsoft.Cache --wait
az provider register --namespace Microsoft.ContainerRegistry --wait
az provider register --namespace Microsoft.ManagedIdentity --wait

8.1 OBO uživatel RBAC (povinné pro Azure discovery)¶

Pro uživatele přihlášené přes Entra SSO (OBO) přiřaďte:

Reader na každé subscription, která má být viditelná v discovery
Key Vault Secrets User (nebo Secrets Officer pro scénáře zápisu) na cílovém Project Key Vault

Příklad:

az role assignment create \
  --role "Reader" \
  --assignee <user-object-id-nebo-upn> \
  --scope /subscriptions/<subscription-id>

az role assignment create \
  --role "Key Vault Secrets User" \
  --assignee <user-object-id-nebo-upn> \
  --scope /subscriptions/<subscription-id>/resourceGroups/<rg>/providers/Microsoft.KeyVault/vaults/<vault-name>

Bez role Reader na subscription může OBO discovery endpoint vracet HTTP 200, ale s nulovým seznamem subscriptions.

9. Ověření po nasazení¶

kubectl get pods -n mazevault -l app=mazevault-gateway
kubectl logs -n mazevault deploy/mazevault-gateway-npr --tail=120

Očekávané chování:

Gateway startuje v gateway mode
Lokální license onboarding se přeskočí
Polling na primary tasks endpoint vrací HTTP 200

10. Rychlá mapa troubleshootingu¶

AADSTS700213: subject federované identity neodpovídá (mazevault-gateway-sa vs jiný SA)
401 na gateway tasks: ověřte kompatibilitu gateway token middleware a hlaviček
chybějící gateway_write_queues: aplikujte migraci 000111_gateway_write_queues
šum ze stale gateway health: odstraňte staré gateway záznamy v primary DB a ponechte jeden aktivní gateway
timeout ManagedIdentityCredential na 169.254.169.254 z lokálního Primary: očekávané při testu MI z Dockeru na localhostu (bez IMDS)
automatický fallback integračního testu/sync z lokálního Primary na Azure gateway: v aktuální verzi není dostupný