Kubernetes Deployment

This page is for operators deploying the HELM AI Kernel runtime with the repository-owned Kubernetes Helm chart. The outcome is a chart render, a production-safe value set, and a smoke path for health, receipts, and evidence persistence.

Audience

Use this page if you operate Kubernetes and need to run HELM AI Kernel as a self-hosted execution boundary with durable receipts, signing keys, and optional ingress.

Outcome

After this page you should be able to lint the chart, render manifests, provide production signing and API-key material, install the chart, and smoke health plus receipt persistence.

Source Truth

The chart source is deploy/helm-chart. Runtime container wiring is in deploy/helm-chart/templates/deployment.yaml, values are in deploy/helm-chart/values.yaml, and chart-level production notes live in deploy/helm-chart/README.md (protected staff doc).

Deployment Topology

flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        Values["values.yaml"]
        ControlPlane["controlplane source"]
        Mounted["ConfigMap/Secret mounted file"]
        PVC["persistent /data PVC"]
        Pod["helm-ai-kernel serve pod"]
        Service["ClusterIP service"]
        Ingress["optional ingress TLS"]
        Metrics["metrics port / ServiceMonitor"]
    end

    subgraph Evaluation["2. Evaluation & Policy Plane"]
        Source["policy.source config"]
        CRD["HelmPolicyBundle CRD"]
        Snapshot["verified EffectivePolicySnapshot"]
    end

    subgraph Execution["3. Execution & Verdict Plane"]
        Runtime["runtime reconciler"]
    end

    subgraph Ledger["4. Tamper-Evident Ledger Plane"]
        Secrets["signing and API-key Secrets"]
    end

    %% Operational Flow Edges
    Values --> Source
    Source --> Runtime
    ControlPlane --> Runtime
    CRD --> Runtime
    Mounted --> Runtime
    Runtime --> Snapshot
    Values --> Secrets
    Values --> PVC
    Snapshot --> Pod
    Secrets --> Pod
    PVC --> Pod
    Pod --> Service
    Service --> Ingress
    Pod --> Metrics

    %% Premium Styling Rules
    style Source fill:#2d3748,stroke:#4a5568,stroke-width:2px,color:#fff
    style Runtime fill:#3182ce,stroke:#2b6cb0,stroke-width:2px,color:#fff
    style CRD fill:#2d3748,stroke:#4a5568,stroke-width:2px,color:#fff
    style Snapshot fill:#2d3748,stroke:#4a5568,stroke-width:2px,color:#fff
    style Secrets fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff

flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        Values["values.yaml"]
        ControlPlane["controlplane source"]
        Mounted["ConfigMap/Secret mounted file"]
        PVC["persistent /data PVC"]
        Pod["helm-ai-kernel serve pod"]
        Service["ClusterIP service"]
        Ingress["optional ingress TLS"]
        Metrics["metrics port / ServiceMonitor"]
    end

    subgraph Evaluation["2. Evaluation & Policy Plane"]
        Source["policy.source config"]
        CRD["HelmPolicyBundle CRD"]
        Snapshot["verified EffectivePolicySnapshot"]
    end

    subgraph Execution["3. Execution & Verdict Plane"]
        Runtime["runtime reconciler"]
    end

    subgraph Ledger["4. Tamper-Evident Ledger Plane"]
        Secrets["signing and API-key Secrets"]
    end

    %% Operational Flow Edges
    Values --> Source
    Source --> Runtime
    ControlPlane --> Runtime
    CRD --> Runtime
    Mounted --> Runtime
    Runtime --> Snapshot
    Values --> Secrets
    Values --> PVC
    Snapshot --> Pod
    Secrets --> Pod
    PVC --> Pod
    Pod --> Service
    Service --> Ingress
    Pod --> Metrics

    %% Premium Styling Rules
    style Source fill:#2d3748,stroke:#4a5568,stroke-width:2px,color:#fff
    style Runtime fill:#3182ce,stroke:#2b6cb0,stroke-width:2px,color:#fff
    style CRD fill:#2d3748,stroke:#4a5568,stroke-width:2px,color:#fff
    style Snapshot fill:#2d3748,stroke:#4a5568,stroke-width:2px,color:#fff
    style Secrets fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff

Validate The Chart

make helm-chart-smoke
helm lint deploy/helm-chart
helm template helm-ai-kernel deploy/helm-chart

Expected output: lint succeeds, helm template emits Deployment, Service, ConfigMap, Secret, PVC, and optional ServiceMonitor manifests, and make helm-chart-smoke completes without rendering a production chart that lacks signing or API key material.

Policy Authority Boundary

The chart does not make Kubernetes objects the HELM execution authority. It deploys the runtime and configures a policy.source backend. The runtime reconciler owns policy truth: it reads the active head, loads the canonical bundle, verifies the expected hash and signature/provenance, compiles a snapshot, validates it, then atomically swaps the per-scope EffectivePolicySnapshot.

POST /internal/policy/reconcile is a wake-up hint protected by service auth. It does not accept policy bytes and does not directly install policy. Lost hints are recovered by helm.policy.source.pollInterval.

Production Install Skeleton

helm install helm-ai-kernel deploy/helm-chart \
  --set helm.production=true \
  --set helm.signing.key=<64-char-ed25519-seed-hex> \
  --set helm.auth.adminAPIKey=<admin-api-key> \
  --set helm.auth.serviceAPIKey=<service-api-key> \
  --set persistence.enabled=true

For production, prefer existing Kubernetes Secrets over inline values:

kubectl create secret generic helm-signing \
  --from-literal=signing-key=<64-char-ed25519-seed-hex>

kubectl create secret generic helm-auth \
  --from-literal=HELM_ADMIN_API_KEY=<admin-api-key> \
  --from-literal=HELM_SERVICE_API_KEY=<service-api-key>

kubectl create secret generic helm-policy-trust \
  --from-literal=HELM_POLICY_TRUST_PUBLIC_KEY=<64-char-ed25519-public-key-hex>

helm upgrade --install helm-ai-kernel deploy/helm-chart \
  --set helm.production=true \
  --set helm.policy.source.kind=controlplane \
  --set helm.policy.source.controlplane.url=https://helm-controlplane.example.internal \
  --set helm.policy.signature.required=true \
  --set helm.policy.signature.existingSecret=helm-policy-trust \
  --set helm.signing.existingSecret=helm-signing \
  --set helm.auth.existingSecret=helm-auth

Values That Control Runtime Behavior

Smoke Checks

kubectl rollout status deploy/helm-ai-kernel
kubectl port-forward svc/helm-ai-kernel 8080:8080
curl -fsS http://127.0.0.1:8080/health

Then run a governed request through the public API or OpenAI-compatible proxy and verify that receipts persist after pod restart when persistence.enabled=true.

Troubleshooting

Not Covered

This page documents the repository-owned HELM AI Kernel chart only. Managed deployment, tenant migrations, SSO, SIEM, and retention controls belong to the HELM AI Enterprise docs.