Skip to content

    Kubernetes (Helm)

    Kubernetes (Helm)

    Section titled “Kubernetes (Helm)”

    The server ships a Helm chart, published as an OCI artifact and also available in the repository under charts/kokoro-server.

    Prerequisites

    Section titled “Prerequisites”
    • A Kubernetes cluster with GPU nodes and the NVIDIA device plugin / GPU Operator, so nvidia.com/gpu is schedulable.
    • Helm 3.8+ (OCI support).

    Install

    Section titled “Install”
    Terminal window
    helm install kokoro \
      oci://ghcr.io/forgeguard-ai/charts/kokoro-server --version 1.1.0

    Pin --version to a released chart version for reproducible deployments.

    Health probes

    Section titled “Health probes”

    The chart wires the server’s health contract into probes so pods receive traffic only after warmup and are not restarted during it:

    • startupProbe → GET /ready (allows a long cold-load window).
    • readinessProbe → GET /ready.
    • livenessProbe → GET /health.

    See Health and readiness.

    Key values

    Section titled “Key values”

    Configuration lives under the kokoroTTS key (and a few top-level keys). Defaults:

    ValueDefaultPurpose
    kokoroTTS.repositoryghcr.io/forgeguard-ai/kokoro-serverImage repository.
    kokoroTTS.tag""Image tag; empty resolves to the chart appVersion (a pinned release).
    kokoroTTS.replicaCount1Replicas (ignored when autoscaling is enabled).
    kokoroTTS.port8880Container/service port.
    kokoroTTS.resources.limits.nvidia.com/gpu1GPUs requested/limited per pod.
    kokoroTTS.apiKey.enabledfalseInject API_KEY from an existing Secret.
    kokoroTTS.apiKey.existingSecret / .secretKey"" / api-keySecret name and key holding the bearer token.
    kokoroTTS.extraEnv[]Extra environment variables (name/value pairs).
    service.typeClusterIPService type.
    ingress.enabledfalseEnable an Ingress (class, hosts, and TLS are configurable).
    autoscaling.enabledfalseEnable an HPA (minReplicas/maxReplicas/CPU target).
    podSecurityContext / securityContextnon-root uid 1001, drop ALL caps, no privilege escalationHardened defaults.

    Set the full env reference from Environment variables through kokoroTTS.extraEnv.

    Authentication from a Secret

    Section titled “Authentication from a Secret”
    Terminal window
    kubectl create secret generic kokoro-auth --from-literal=api-key=REPLACE_ME
    

    helm install kokoro oci://ghcr.io/forgeguard-ai/charts/kokoro-server \
      --version 1.1.0 \
      --set kokoroTTS.apiKey.enabled=true \
      --set kokoroTTS.apiKey.existingSecret=kokoro-auth

    Ingress and TLS

    Section titled “Ingress and TLS”

    For public exposure, enable ingress and terminate TLS at the ingress with a CA-issued certificate (for example via cert-manager) rather than the server’s self-signed certificate. An example values file for AKS with cert-manager and external-dns is provided under charts/kokoro-server/examples/.

    Persistence

    Section titled “Persistence”

    The chart does not provision a volume for OUTPUT_DIR by default, so generated audio is ephemeral and lost on pod restart. If you need durable output (or a persisted TLS certificate), add your own volume and set OUTPUT_DIR accordingly through extraEnv and a pod spec override. For most API workloads, ephemeral output is fine — audio is streamed back to the client.

    Upgrades and the chart rename

    Section titled “Upgrades and the chart rename”

    The chart was renamed from kokoro-fastapi to kokoro-server in 1.1.0 and its selector labels changed. When migrating from the old chart, helm uninstall the old release and install this chart fresh rather than upgrading in place. See Upgrades.