Helm Charts

MazeVault Helm Chart Configuration Reference

Document Version: 1.0.45
Last Updated: 2026-10-28
License Tier: Enterprise

---

1. Overview

MazeVault publishes the customer Helm chart as an OCI artifact in the MazeVault Harbor with every release vX.Y.Z (chart version X.Y.Z):

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

Log in with the robot account you received from MazeVault (quote it, the name contains $) and pin an explicit chart version:

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

Start from the chart's default values (helm show values …) or the Azure example in the chart's examples/values-azure.yaml, and keep customer-specific overrides in your own values file or GitOps repository. The chart README (helm show readme …) describes the Key Vault secrets, ingress routes and an Argo CD example.

Installations of v1.0.60 and older were distributed through GHCR (ghcr.io/mazevault); new releases are only in Harbor.

Image Tag Strategy and Pull Preflight

• Prefer explicit release tags (for example v1.0.44) instead of latest for production rollouts.
• Run a pull preflight before Helm upgrades so image availability is validated before deployment starts.

# Isolated Docker auth context to avoid local credential side effects
TMP_DOCKER_CFG=$(mktemp -d)
DOCKER_CONFIG="$TMP_DOCKER_CFG" docker login registry.mazevault.com -u 'robot$mazevault+yourcompany'

# Verify the release tags resolve in Harbor
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. Values Reference

Global Settings

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"   # required while frontend.enabled
  ingress:
    enabled: true
    appHost: mazevault.example.com
    docsHost: docs.mazevault.example.com

bffSharedSecret is required

The web interface server (BFF) and the backend share a secret. Create it in the Key Vault (openssl rand -base64 48 | tr -d '\n/+=') and set global.keyVault.secretKeys.bffSharedSecret to the secret's name. While frontend.enabled is true, the chart does not render without it. With keyVault.enabled=false, the pre-created runtime secret must contain the key BFF_SHARED_SECRET. If the key is missing from the runtime secret, only the new frontend pod fails to start (the previous one keeps serving); the backend, agents and gateways keep running. A backend that started without the key keeps running without it after you add it (the environment is read at pod start), so sign-ins fail with 401 until you restart it: kubectl rollout restart deployment/<release>-backend -n <namespace>.

Backend (API Server)

backend:
  replicaCount: 1                            # Keep single-writer backend semantics
  image:
    repository: "registry.mazevault.com/mazevault/mazevault-backend"
    tag: "v1.0.44"                          # Prefer pinned release tags in customer environments

  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
    # Client IP is read from X-Forwarded-For only from these peers. The default is the private ranges
    # (127.0.0.1/32,::1/128,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16,fc00::/7).
    # Set it to the pod CIDR of your ingress controller when that is not a private range.
    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"

  # Database and Redis runtime credentials are projected through the generated 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 (Web Interface)

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

  service:
    port: 80                                 # the container listens on 3000

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

  urls:
    docs: "https://docs.mazevault.example.com"   # NUXT_PUBLIC_DOCS_URL, default https://<docsHost>

The web interface is a Nuxt application with a built-in server (BFF) listening on container port 3000 (the Service port stays 80). It no longer proxies /api, so the ingress is required and must route /api, /swagger and /health to the backend and / to the frontend (see Ingress below). The BFF reaches the backend over plain HTTP through the backend Service. The frontend-nginx ConfigMap and frontend.urls.domain no longer exist. The chart sets these runtime variables on the frontend (see Environment Variables):

Variable	Value in the chart
NUXT_CORE_API_URL	http://<release>-backend:<backend.service.port>
NUXT_BFF_SECRET	from the Key Vault secret bffSharedSecret
NUXT_PUBLIC_ORIGIN	backend.urls.frontend, otherwise https://<appHost> (must equal the browser address exactly)
NUXT_PUBLIC_DOCS_URL	frontend.urls.docs, otherwise https://<docsHost>

Use frontend.config and frontend.extraEnv for additional NUXT_* settings. NODE_EXTRA_CA_CERTS is needed only if you point NUXT_CORE_API_URL at an HTTPS backend (set it through frontend.extraEnv and mount the 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      # optional

The chart creates the routes for appHost itself:

Path	Service
/api	backend
/swagger	backend
/health	backend
/	frontend (web interface)

The documentation (docsHost) and OCSP responder (ocspHost) are published on their own hosts. If you use your own ingress instead of the chart's, it must contain the same routes.

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. Environment-Specific Examples

Production

# 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. Upgrade Procedure

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

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

# Perform upgrade (pinned version)
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

Related

• Azure AKS Deployment — AKS cluster setup
• System Requirements — Resource sizing
• Monitoring — Monitoring configuration