Deployment

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

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 Charts (charts/)

Webhook deployments are normally provisioned automatically: when a WebhookSource CR is created, the API server's WebhookSourceWatcher reconciles a Deployment + Service + Ingress for that source using the same image tag as the running API pod. The standalone ai-agents-webhook chart is available for manual deployments.

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-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-*)
├── releases/            # Flux HelmRelease objects for the three charts
├── 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 shared workspace PVC is ReadWriteMany (or ReadWriteOnce in single-replica setups). 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 three 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 three HelmReleases plus the kustomization at k8s/overlays/production. Image automation watches the latest tag in GHCR and rolls deployments forward when image.yml publishes a new tag.

CI/CD Workflows (.github/workflows/)

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