Helm Charts¶

Referenční příručka konfigurace Helm chartů MazeVault

Verze dokumentu: 1.0.46
Poslední aktualizace: 2026-10-28
Licenční úroveň: Enterprise

1. Přehled¶

MazeVault publikuje customer Helm chart jako OCI artefakt v MazeVault Harboru s každým releasem vX.Y.Z (verze chartu X.Y.Z):

oci://registry.mazevault.com/mazevault/mazevault-customer

Přihlaste se robot účtem, který jste dostali od MazeVault (jméno obsahuje $, proto ho dejte do uvozovek), a vždy pinujte explicitní verzi chartu:

helm registry login registry.mazevault.com -u 'robot$mazevault+yourcompany'

helm show chart oci://registry.mazevault.com/mazevault/mazevault-customer --version X.Y.Z

helm upgrade --install mazevault oci://registry.mazevault.com/mazevault/mazevault-customer \
  --version X.Y.Z \
  -n mazevault \
  --create-namespace \
  -f values.customer.yaml

Začněte z výchozích hodnot chartu (helm show values …) nebo z příkladu pro Azure v examples/values-azure.yaml v chartu a zákaznické hodnoty držte ve vlastním values souboru nebo GitOps repozitáři. README chartu (helm show readme …) popisuje Key Vault secrety, routy pro ingress a příklad pro Argo CD.

Instalace v1.0.60 a starší se distribuovaly přes GHCR (ghcr.io/mazevault); nové releasy jsou jen v Harboru.

Strategie tagů image a pull preflight¶

Pro produkční nasazení preferujte explicitní release tagy (například v1.0.44) místo latest.
Před Helm upgradem spusťte pull preflight, aby byla dostupnost image ověřena ještě před samotným nasazením.

# Izolovaný Docker auth context bez vedlejších efektů lokálních přihlášení
TMP_DOCKER_CFG=$(mktemp -d)
DOCKER_CONFIG="$TMP_DOCKER_CFG" docker login registry.mazevault.com -u 'robot$mazevault+yourcompany'

# Ověření, že release tagy v Harboru existují
for img in mazevault-backend mazevault-frontend mazevault-docs mazevault-ocsp; do
  DOCKER_CONFIG="$TMP_DOCKER_CFG" docker manifest inspect "registry.mazevault.com/mazevault/${img}:vX.Y.Z" >/dev/null
done

rm -rf "$TMP_DOCKER_CFG"

2. Reference hodnot (Values)¶

Globální nastavení¶

global:
  environment: "customer"
  rolloutNonce: ""
  workloadIdentity:
    enabled: true
    clientId: ""
  keyVault:
    enabled: true
    secretStore:
      vaultUrl: https://__SET_KEYVAULT_NAME__.vault.azure.net
      tenantId: ""
    secretKeys:
      bffSharedSecret: "mazevault-bff-shared-secret"   # povinné, dokud je frontend.enabled
  ingress:
    enabled: true
    appHost: mazevault.example.com
    docsHost: docs.mazevault.example.com

bffSharedSecret je povinný

Server webového rozhraní (BFF) a backend sdílejí tajemství. Vytvořte ho v Key Vaultu (openssl rand -base64 48 | tr -d '\n/+=') a do global.keyVault.secretKeys.bffSharedSecret zadejte jeho název. Dokud je frontend.enabled pravda, chart se bez něj nevykreslí. Při keyVault.enabled=false musí předem vytvořený runtime secret obsahovat klíč BFF_SHARED_SECRET. Když klíč v runtime secretu chybí, nenastartuje jen nový pod frontendu (předchozí dál obsluhuje); backend, agenti i gatewaye běží dál. Backend, který nastartoval bez klíče, ho po doplnění nemá (prostředí se čte při startu podu), takže přihlášení končí chybou 401, dokud ho nerestartujete: kubectl rollout restart deployment/<release>-backend -n <namespace>.

Backend (API Server)¶

backend:
  replicaCount: 1                            # Zachovat single-writer semantiku backendu
  image:
    repository: "registry.mazevault.com/mazevault/mazevault-backend"
    tag: "v1.0.44"                          # V zákaznickém prostředí preferujte pinned release tagy

  resources:
    requests:
      cpu: "500m"
      memory: "1Gi"
    limits:
      cpu: "2000m"
      memory: "4Gi"

  config:
    MAZEVAULT_CUSTOMER_NAME: __SET_CUSTOMER_NAME__
    MAZEVAULT_CUSTOMER_EMAIL: __SET_CUSTOMER_EMAIL__
    MAZEVAULT_COMPANY_ID: __SET_COMPANY_ID__
    MAZEVAULT_ENV: production
    LOG_LEVEL: info
    # IP klienta se z X-Forwarded-For čte jen od těchto peerů. Výchozí jsou privátní rozsahy
    # (127.0.0.1/32,::1/128,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16,fc00::/7).
    # Pokud pody ingress controlleru nejsou v privátním rozsahu, nastavte jejich CIDR.
    TRUSTED_PROXIES: "127.0.0.1/32,::1/128,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16,fc00::/7"

  # Databázové a Redis runtime přihlašovací údaje se promítají přes generovaný runtime secret.

  # Health probes
  livenessProbe:
    httpGet:
      path: /api/v1/health
      port: 8080
    initialDelaySeconds: 30
    periodSeconds: 30

  readinessProbe:
    httpGet:
      path: /api/v1/health
      port: 8080
    initialDelaySeconds: 10
    periodSeconds: 10

Frontend (Webové rozhraní)¶

frontend:
  replicaCount: 1
  image:
    repository: "registry.mazevault.com/mazevault/mazevault-frontend"
    tag: "v1.0.44"

  service:
    port: 80                                 # kontejner naslouchá na 3000

  resources:
    requests:
      cpu: "100m"
      memory: "128Mi"
    limits:
      cpu: "300m"
      memory: "256Mi"

  urls:
    docs: "https://docs.mazevault.example.com"   # NUXT_PUBLIC_DOCS_URL, výchozí https://<docsHost>

Webové rozhraní je aplikace Nuxt s vestavěným serverem (BFF) naslouchajícím na portu kontejneru 3000 (port Service zůstává 80). Už neproxuje /api, takže ingress je povinný a musí směrovat /api, /swagger a /health na backend a / na frontend (viz Ingress níže). BFF komunikuje s backendem přes obyčejné HTTP skrze Service backendu. ConfigMap frontend-nginx a frontend.urls.domain už neexistují. Chart nastavuje frontendu tyto runtime proměnné (viz Proměnné prostředí):

Proměnná	Hodnota v chartu
`NUXT_CORE_API_URL`	`http://<release>-backend:<backend.service.port>`
`NUXT_BFF_SECRET`	z tajemství Key Vault `bffSharedSecret`
`NUXT_PUBLIC_ORIGIN`	`backend.urls.frontend`, jinak `https://<appHost>` (musí přesně odpovídat adrese v prohlížeči)
`NUXT_PUBLIC_DOCS_URL`	`frontend.urls.docs`, jinak `https://<docsHost>`

Další nastavení NUXT_* zadejte přes frontend.config a frontend.extraEnv. NODE_EXTRA_CA_CERTS je potřeba jen tehdy, když NUXT_CORE_API_URL ukazuje na HTTPS backend (nastavte ho přes frontend.extraEnv a připojte CA).

OCSP Responder¶

ocsp:
  enabled: true
  replicas: 1
  image:
    repository: "mazevault-ocsp"
    tag: "1.8.0"

  resources:
    requests:
      cpu: "200m"
      memory: "256Mi"
    limits:
      cpu: "1000m"
      memory: "1Gi"

  autoscaling:
    enabled: true
    minReplicas: 1
    maxReplicas: 5
    targetCPUUtilizationPercentage: 70

Ingress¶

global:
  ingress:
    enabled: true
    className: "nginx"
    annotations:
      nginx.ingress.kubernetes.io/ssl-redirect: "true"
      nginx.ingress.kubernetes.io/proxy-body-size: "50m"
      nginx.ingress.kubernetes.io/proxy-read-timeout: "300"
      nginx.ingress.kubernetes.io/proxy-send-timeout: "300"
    appHost: vault.example.com
    docsHost: docs.vault.example.com
    ocspHost: ocsp.vault.example.com      # volitelné

Chart pro appHost vytvoří tyto trasy sám:

Cesta	Služba
`/api`	backend
`/swagger`	backend
`/health`	backend
`/`	frontend (webové rozhraní)

Dokumentace (docsHost) a OCSP responder (ocspHost) se publikují na vlastních hostech. Pokud místo ingressu z chartu používáte vlastní, musí obsahovat stejné trasy.

Monitoring¶

monitoring:
  serviceMonitor:
    enabled: true                            # Requires Prometheus Operator
    interval: 30s
    labels:
      release: prometheus

  prometheusRules:
    enabled: true
    rules:
      - alert: MazeVaultBackendDown
        expr: up{job="mazevault-backend"} == 0
        for: 5m
        labels:
          severity: critical
      - alert: MazeVaultHighErrorRate
        expr: rate(http_requests_total{status=~"5.."}[5m]) > 0.1
        for: 10m
        labels:
          severity: warning

3. Příklady pro jednotlivá prostředí¶

Produkce¶

# values-production.yaml
global:
  domain: "vault.company.com"
  tls:
    enabled: true

backend:
  replicas: 1
  resources:
    requests:
      cpu: "1000m"
      memory: "2Gi"
    limits:
      cpu: "4000m"
      memory: "8Gi"
  env:
    LOG_LEVEL: "warn"

frontend:
  replicas: 3
  autoscaling:
    enabled: true
    minReplicas: 3

monitoring:
  serviceMonitor:
    enabled: true

Staging¶

# values-staging.yaml
global:
  domain: "vault-staging.company.com"

backend:
  resources:
    requests:
      cpu: "500m"
      memory: "1Gi"
    limits:
      cpu: "2000m"
      memory: "4Gi"

frontend:
  replicas: 1
  autoscaling:
    enabled: false

4. Postup aktualizace¶

# Kontrola cílové verze chartu
helm show chart oci://registry.mazevault.com/mazevault/mazevault-customer --version X.Y.Z

# Kontrola změn
helm diff upgrade mazevault oci://registry.mazevault.com/mazevault/mazevault-customer \
  --version X.Y.Z \
  -n mazevault -f values-production.yaml

# Provedení upgrade (pin verze)
helm upgrade --install mazevault oci://registry.mazevault.com/mazevault/mazevault-customer \
  --version X.Y.Z \
  -n mazevault -f values-production.yaml \
  --wait --timeout 10m

# Verify
kubectl get pods -n mazevault
kubectl exec -n mazevault deploy/mazevault-backend -- \
  wget -qO- http://localhost:8080/api/v1/health

5. Partner Onboarding Checklist (zkrácená verze)¶

Při onboarding partnera i před každým customer release ověřte minimálně následující body:

Verze a kompatibilita: chart verze odpovídá release (vX.Y.Z -> X.Y.Z), CI/CD používá pinned verzi.
ENV a secrets: povinné hodnoty jsou vyplněné, secret-only hodnoty nejsou v plaintext values.
AKS/ESO/Ingress: externí secret management a ingress/TLS model odpovídají prostředí.
Upgrade/rollback: partner má ověřený upgrade příkaz a rollback postup (helm rollback).
Smoke test: health endpoint, pody, ingress a externalsecret zdroje jsou po nasazení v pořádku.
Security: partner ověřuje původ artefaktů a checksum/signature dle interní politiky.

Detailní checklist pro release maintainery a partner handover je v monorepu MazeVault v souboru product/release/CUSTOMER_RELEASE_CHECKLIST.md.

Související¶

Nasazení na Azure AKS — Nastavení clusteru AKS
Systémové požadavky — Dimenzování prostředků
Monitoring — Konfigurace monitoringu