Configuration Guide

Overview

The CDN Manager is deployed via Helm chart with configuration supplied through values.yaml files. This guide explains the configuration structure, how to apply changes, and provides a reference for all configurable options.

Configuration Files

The installation ISO provides three configuration files at /mnt/esb3027/:

You only need to specify fields that differ from the defaults. Helm applies configuration hierarchically — values from your file override the chart’s built-in defaults, and any key you omit retains its default value.

Lab Configuration (values-lab.yaml)

values-lab.yaml is the recommended starting point for single-node lab, acceptance testing, and demonstration deployments. It pre-configures settings appropriate for a constrained single-node environment:

• Single Kafka controller replica (the default 3 replicas require 3 separate nodes to satisfy pod anti-affinity rules)
• Single Zitadel replica
• Self-signed TLS by default, with real certificate configuration commented out for reference
• Minimal resource requests suited to a single node

Copy the file to a writable location and edit it before deploying:

cp /mnt/esb3027/values-lab.yaml ~/values.yaml

The minimum required changes are:

1. Set global.hosts.manager[0].host to your node’s hostname or IP address
2. Set zitadel.zitadel.configmapConfig.ExternalDomain to the same value

These two values must match exactly or authentication will fail due to CORS policy violations. See Global Settings for details.

Production Configuration (values-production.yaml)

values-production.yaml is the recommended starting point for multi-node production deployments across a minimum three-node cluster. It pre-configures settings appropriate for a high-availability environment:

• Three Zitadel replicas spread across nodes for HA
• Production-grade resource requests and limits for all major components
• Kafka with a dedicated single-replica StorageClass (avoiding unnecessary triple-redundancy on top of Kafka’s own quorum)
• Manager HPA configured to scale between 3 and 8 replicas
• TLS certificate configuration with clearly marked placeholders

Copy the file to a writable location and edit it before deploying:

cp /mnt/esb3027/values-production.yaml ~/values.yaml

The minimum required changes before deploying are:

1. Set global.hosts.manager[0].host to your primary manager hostname
2. Set zitadel.zitadel.configmapConfig.ExternalDomain to the same hostname
3. Replace the placeholder TLS certificate and key in the ingress.secrets section, and update the secretName values in mibFrontend.ingress.extraTls and zitadel.ingress.tls to match
4. Update global.hosts.routers with your CDN Director instances

See TLS Configuration and Global Settings for full details.

Hardware requirements: For per-node hardware specifications, refer to the System Requirements Guide. The System Requirements Guide is the authoritative source — the hardware comments in the header of values-production.yaml may not reflect the current requirements.

Complete Reference (values.yaml)

The full default values file at /mnt/esb3027/values.yaml documents every configurable option with its default value and inline comments. Use this as a reference when looking up available settings or understanding what the environment-specific files override.

Note: values.yaml is not intended to be used directly as your deployment configuration. Use values-lab.yaml or values-production.yaml as your starting point instead.

Configuration Merging

Helm merges configuration files from left to right, with later files overriding earlier values. This allows you to split your configuration into multiple files — for example, keeping TLS certificates separate from the main configuration:

# Multiple files merged left-to-right
helm install acd-manager /mnt/esb3027/charts/acd-manager \
  --values ~/values.yaml \
  --values ~/values-tls.yaml

Individual Value Overrides

For temporary changes, you can override individual values with --set:

helm upgrade acd-manager /mnt/esb3027/helm/charts/acd-manager \
  --values ~/values.yaml \
  --set manager.logLevel=debug

Note: Using --set is discouraged for permanent changes, as the same arguments must be specified for every Helm operation.

Applying Configuration

Initial Installation

helm install acd-manager /mnt/esb3027/charts/acd-manager \
  --values ~/values.yaml

Updating Configuration

helm upgrade acd-manager /mnt/esb3027/helm/charts/acd-manager \
  --values ~/values.yaml

Dry Run

Before applying changes, validate the configuration with a dry run:

helm upgrade acd-manager /mnt/esb3027/helm/charts/acd-manager \
  --values ~/values.yaml \
  --dry-run

Rollback

If an upgrade fails, rollback to the previous revision:

# View revision history
helm history acd-manager

# Rollback to previous revision
helm rollback acd-manager

# Rollback to specific revision
helm rollback acd-manager <revision_number>

Note: Rollback reverts the Helm release but does not modify your values.yaml file. You must manually revert configuration file changes.

Force Reinstall

If an upgrade fails and rollback is not sufficient, you can perform a clean reinstall:

helm uninstall acd-manager
helm install acd-manager /mnt/esb3027/charts/acd-manager \
  --values ~/values.yaml

Warning: This is service-affecting as all pods will be destroyed and recreated.

Configuration Reference

Global Settings

The global section contains cluster-wide settings. The most critical configuration is global.hosts.

global:
  hosts:
    manager:
      - host: manager.local
    routers:
      - name: default
        address: 127.0.0.1
    edns_proxy: []
    geoip: []

Important: The first entry in global.hosts.manager must match zitadel.zitadel.ExternalDomain exactly. Zitadel enforces CORS protection, and authentication will fail if these do not match.

Manager Configuration

Core Manager API server settings:

Manager Resources

The chart supports both resource presets and explicit resource specifications:

Note: For production workloads, explicitly set manager.resources rather than using presets.

Manager Datastore

manager:
  datastore:
    type: redis
    namespace: "cdn_manager_ds"
    default_ttl: ""
    compression: zstd

Manager Discovery

manager:
  discovery: []
  # Example:
  # - namespace: "other"
  #   hosts:
  #     - other-host1
  #     - other-host2
  #   pattern: "other-.*"

Manager Tuning

manager:
  tuning:
    enable_cache_control: true
    cache_control_max_age: "5m"
    cache_control_miss_max_age: ""

Manager Container Arguments

manager:
  args:
    - --config-file=/etc/manager/config.toml
    - http-server

Gateway Configuration

NGinx Gateway settings for external Director communication:

MIB Frontend Configuration

Web-based configuration GUI settings:

Confd Configuration

Confd settings for configuration management:

VictoriaMetrics Configuration

Time-series database for metrics:

Ingress Configuration

Traffic exposure settings:

Ingress Extra Paths

The chart includes default extra paths for Confd and GeoIP:

ingress:
  extraPaths:
    - path: /confd
      pathType: Prefix
      backend:
        service:
          name: acd-manager-gateway
          port:
            name: http
    - path: /geoip
      pathType: Prefix
      backend:
        service:
          name: acd-manager-gateway
          port:
            name: http

TLS Certificate Secrets

For production TLS certificates:

ingress:
  secrets:
    - name: manager.local-tls
      key: |-
        -----BEGIN RSA PRIVATE KEY-----
        ...
        -----END RSA PRIVATE KEY-----
      certificate: |-
        -----BEGIN CERTIFICATE-----
        ...
        -----END CERTIFICATE-----
  tls: true

Resource Configuration

Resource Presets

Predefined resource configurations for common deployment sizes:

Note: Limits are calculated as requests plus 50% (except for xlarge/2xlarge and ephemeral-storage).

Custom Resources

Override preset with custom values:

manager:
  resources:
    requests:
      cpu: "300m"
      memory: "512Mi"
    limits:
      cpu: "1"
      memory: "1Gi"

Note:

• CPU values use millicores (1000m = 1 core)
• Memory values use binary SI units (1024Mi = 1GiB)
• Requests represent minimum guaranteed resources
• Limits represent maximum consumable resources

Capacity Planning

When sizing resources:

• Requests determine scheduling (node must have available capacity)
• Limits prevent resource starvation
• Maintain 20-30% cluster headroom for scaling
• Total capacity = sum of all requests × replica count + headroom

Security Contexts

Pod Security Context

manager:
  podSecurityContext:
    enabled: true
    fsGroup: 1001
    fsGroupChangePolicy: Always
    sysctls: []
    supplementalGroups: []

Container Security Context

manager:
  containerSecurityContext:
    enabled: true
    runAsUser: 1001
    runAsGroup: 1001
    runAsNonRoot: true
    readOnlyRootFilesystem: true
    privileged: false
    allowPrivilegeEscalation: false
    capabilities:
      drop: ["ALL"]
    seccompProfile:
      type: "RuntimeDefault"

Health Probes

Probe Types

Default Probe Configuration

Liveness Probe

manager:
  livenessProbe:
    enabled: true
    initialDelaySeconds: 5
    periodSeconds: 30
    timeoutSeconds: 10
    failureThreshold: 5
    successThreshold: 1
    httpGet:
      path: /api/v1/health/alive
      port: http

Readiness Probe

manager:
  readinessProbe:
    enabled: true
    initialDelaySeconds: 5
    periodSeconds: 10
    timeoutSeconds: 7
    failureThreshold: 3
    successThreshold: 1
    httpGet:
      path: /api/v1/health/ready
      port: http

Startup Probe

manager:
  startupProbe:
    enabled: true
    initialDelaySeconds: 0
    periodSeconds: 5
    timeoutSeconds: 3
    failureThreshold: 10
    successThreshold: 1
    httpGet:
      path: /api/v1/health/alive
      port: http

Autoscaling Configuration

Horizontal Pod Autoscaler (HPA)

manager:
  autoscaling:
    hpa:
      enabled: true
      minReplicas: 3
      maxReplicas: 8
      targetCPU: 50
      targetMemory: 80

Network Policy

networkPolicy:
  enabled: true
  allowExternal: true
  allowExternalEgress: true
  addExternalClientAccess: true

Pod Affinity and Anti-Affinity

manager:
  podAffinityPreset: ""
  podAntiAffinityPreset: soft
  nodeAffinityPreset:
    type: ""
    key: ""
    values: []
  affinity: {}

Service Configuration

service:
  type: ClusterIP
  ports:
    http: 80
  annotations:
    service.kubernetes.io/topology-mode: Auto
  externalTrafficPolicy: Cluster
  sessionAffinity: None

Persistence Configuration

persistence:
  enabled: false
  mountPath: /agiletv/manager/data
  storageClass: ""
  accessModes:
    - ReadWriteOnce
  size: 8Gi

RBAC and Service Account

rbac:
  create: false
  rules: []

serviceAccount:
  create: true
  name: ""
  automountServiceAccountToken: true
  annotations: {}

Metrics

metrics:
  enabled: false
  serviceMonitor:
    enabled: false
    namespace: ""
    annotations: {}
    labels: {}
    interval: ""
    scrapeTimeout: ""

Next Steps

After configuration:

1. Installation Guide - Deploy with your configuration
2. Operations Guide - Day-to-day management
3. Performance Tuning Guide - Optimize system performance
4. Architecture Guide - Understand component relationships