Deployment

Kubernetes deployment guide for ai-agents. The runtime is delivered as a single Helm chart (ai-agents-main) plus shared infra (CRDs, RBAC, secrets) installed via FluxCD.

For the top-level architecture (building blocks, deployment view, RAD conformance) see the Software Architecture Document.

Prerequisites

• Kubernetes cluster with FluxCD
• Traefik ingress controller
• Authelia identity provider
• External Secrets Operator (or SOPS-encrypted secrets)
• Longhorn storage (for the workspace + uploads PVC)

Namespace

All workloads run in ai-agents.

apiVersion: v1
kind: Namespace
metadata:
  name: ai-agents

Helm Chart (charts/ai-agents-main)

A single chart deploys everything. The former ai-agents-processor and ai-agents-webhook charts were removed — the operator runs inside the API process (ENABLE_OPERATOR) and webhook pods run the API image in MODE=webhook.

Webhook deployments are provisioned automatically: when a WebhookSource CR is created, the API server's WebhookSourceWatcher reconciles a Deployment + Service + Ingress for that source using the running API image tag (MODE=webhook), and tears them down via a finalizer when the CR is deleted.

CRDs and Cluster Infra (k8s/infra/)

CRDs live in k8s/infra/ and are installed cluster-wide ahead of the workloads:

k8s/infra/
├── crd-inferencerequest.yaml
├── crd-aimodel.yaml
├── crd-aiagent.yaml
├── crd-aiconfig.yaml
├── crd-aiinstruction.yaml
├── crd-aitool.yaml
├── crd-aimcpserver.yaml
├── crd-aiskill.yaml
├── crd-aiexecutor.yaml
├── crd-webhooksource.yaml
├── externalsecret-*.yaml
├── secretstore.yaml
└── networkpolicy-*.yaml

CRD group/version: labrats.work/v1alpha1.

Kustomize Layout (k8s/)

k8s/
├── base/                # Base ai-agents-main resources (Deployment-style)
├── infra/               # CRDs, ExternalSecrets, SecretStore, NetworkPolicies
├── instructions/        # AiInstruction CRs (global-* and local-*)
├── policies/            # OPA/Kyverno-style policy manifests
├── releases/            # Flux HelmRelease (helmrelease-main.yaml)
├── envs/
│   ├── dev/
│   └── prod/
└── overlays/
    └── production/

Shipped instructions:

Required Secrets

The API server reads the following keys from the deployment-level Secret (managed via External Secrets Operator or SOPS):

Backend credential secrets are optional and referenced per-model by AiModel.spec.credentialsRef (used only by the claude executor). Caller identity flows via the IR apiKeyRef (an API-key Secret); GitHub uses the App credentials in github-app-credentials. There is no AiAccount pool (removed in spec 0003).

Configuration (env vars)

Each process reads from src/config.ts:

Ingress

The unified deployment uses two Ingresses, split by auth requirement:

Public (ai-agents-public)

No middleware. Used by external services and probes.

Protected (ai-agents-protected)

Authelia ForwardAuth via:

traefik.ingress.kubernetes.io/router.middlewares: authelia-authelia@kubernetescrd

The cross-namespace middleware reference requires allowCrossNamespace: true on Traefik's Kubernetes CRD provider.

Network Policies

Strict pod-to-pod and egress rules:

• API pod ingress: Traefik, App pod, plus client namespaces (e.g. github-ai-agents, reader-ai-agents).
• API pod egress: K8s API (CRDs/Jobs/Secrets), DNS, HTTPS (OIDC, GitHub, callbacks).
• App pod ingress: Traefik only.
• App pod egress: API pod, DNS.
• Executor Jobs: egress to the K8s API (credential write-back), DNS, HTTPS to the AI provider, plus optional GitHub.

Storage

The workspace PVC is ReadWriteOnce (the API runs single-replica with strategy: Recreate); the separate uploads PVC is ReadWriteMany so the API mounts it read-write while executor Jobs mount it read-only. Layout:

/workspace/
├── .accounts/    # Account credential files (legacy path)
├── jobs/         # Per-job workspaces (ephemeral, cleanup CronJob below)
└── uploads/      # PDF and workspace uploads — mounted into Executor Jobs read-only

UPLOADS_PVC_NAME is mounted into every executor Job at /uploads.

An optional models-cache PVC (pvc-models-cache.yaml) can be mounted at /models on executor Jobs for local inference providers. When AiConfig.spec.providers[provider].modelUrl is set, the job executor adds an init container that downloads the GGUF model to the cache PVC (only if not already present). This avoids re-downloading large models for each job.

CronJobs

Shipped from ai-agents-main:

Health Probes

All processes expose the same liveness/readiness contract:

• Liveness: GET /health → 200 {"status":"ok"}
• Readiness: GET /ready → 200 {"status":"ok"}

Probes have no external dependencies — they confirm the process is up. Operator readiness is implicit (the informer caches populate at boot).

Security Context

Standard hardened defaults:

securityContext:
  runAsNonRoot: true
  runAsUser: 1001
  runAsGroup: 1001
  fsGroup: 1001
  allowPrivilegeEscalation: false
  privileged: false
  capabilities: { drop: [ALL] }

FluxCD Integration

The flux repo (labrats.work.hetzner.cluster.flux) references the ai-agents-main HelmRelease plus the kustomization at k8s/overlays/production. Image automation rolls deployments forward via Flux ImagePolicy ranges (dev loose >=0.0.0, prod strict) — never a :latest tag — when image.yml publishes a new semver tag.

CI/CD Workflows (.github/workflows/)

All workflows run on k8s-hetzner-arc self-hosted runners; images push to ghcr.io/labrats-work/.