Kubernetes & OpenShift

For production workloads, Alquimia Platform runs as a Kubernetes workload with separate master and worker deployments. This separates request intake from execution, lets you scale each role independently, and supports Vault-backed dynamic credentials and SPIFFE workload identity.

Deployment topology

                         Ingress / Load balancer
                                  │
                                  ▼
              ┌─────────────────────────────────────┐
              │  alquimia-runtime master (1 replica)│
              │  (HTTP API + registry management)   │
              └─────────────────┬───────────────────┘
                                │ CloudEvents
                                ▼
              ┌─────────────────────────────────────┐
              │  Kafka / event bus                    │
              └─────────────────┬───────────────────┘
                                │ CloudEvents
                                ▼
              ┌─────────────────────────────────────┐
              │  alquimia-runtime worker replicas   │
              │  (agent execution via alquimia-core)│
              └─────────────────┬───────────────────┘
                                │
        ┌───────────────────────┼───────────────────────┐
        ▼                       ▼                       ▼
   PostgreSQL                Redis                   Qdrant
  (persistence)           (state/cache)          (vectors/RAG)

Roles

Role	Responsibility	Scaling driver
Master	Accepts HTTP requests, manages registry, publishes events	Fixed at exactly 1 replica (Recreate strategy)
Worker	Consumes events and executes agents	Inference throughput, up to the alquimia.events partition count (6)

Workers are stateless. You can add replicas to increase throughput without changing the master deployment, up to the number of partitions on alquimia.events; extra workers stay idle.

The master is the single writer of the TinyDB registry (protected by a Redis Redlock). Run exactly one master replica with the Recreate deployment strategy; do not scale or autoscale it.

Deployment overlays

The runtime repository provides overlays for different environments:

Overlay	Use
kubernetes	Vanilla Kubernetes without admission policies.
production	Vanilla Kubernetes with Kyverno admission policies in Enforce mode (image signature verification and pod security).
openshift	OpenShift / ROSA; uses OpenShift’s built-in security constraints (SCCs).
spire-openshift	Deploys the SPIRE manifests (k8s/spire) with the agent patches OpenShift needs; used for SPIFFE workload identity, separately from the runtime overlay.

Choose the overlay that matches your cluster’s tooling and compliance needs.

Caution

In the kubernetes and production overlays the master registry lives on an emptyDir volume, and the s3-sync sidecar mirrors it to S3 (rclone sync from local to S3) without restoring it first. In runtime ≤ 0.5.4, a master restart therefore mirrors an empty registry over the S3 backup. Mount a PersistentVolumeClaim for the master registry, or back up the S3 registry prefix before any master restart.

Security considerations

• Use projected service-account tokens (audience vault) and the Kubernetes Vault auth method for runtime services. Set both VAULT_K8S_ROLE (runtime) and VAULT_AUTH_ROLE (alquimia-core secret resolver); static VAULT_TOKEN and the alquimia-vault Secret are no longer used.
• Use SPIFFE/SPIRE and the JWT Vault auth method for per-agentspace agent identities.
• Enable image signature verification in production overlays.
• Store sensitive values in Vault, not in ConfigMaps or environment variables.

Network policies

Runtime masters and workers need egress to the blob store. Starting with runtime 0.5.4, the local reference stack uses Alarik on TCP 8080. Allow egress to pods labelled app.kubernetes.io/name: alarik on that port:

apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: allow-to-alarik
spec:
  podSelector:
    matchLabels:
      app.kubernetes.io/name: alquimia-runtime
  policyTypes:
    - Egress
  egress:
    - to:
        - podSelector:
            matchLabels:
              app.kubernetes.io/name: alarik
      ports:
        - protocol: TCP
          port: 8080

If you are upgrading from an older deployment that still uses MinIO, keep the legacy rule for TCP 9000 until the migration to Alarik is complete.

Before deploying

1. Provision a PostgreSQL database, Redis cache, Qdrant vector store, Kafka cluster, and object store. Size PostgreSQL max_connections for the runtime’s per-process pools (see Runtime configuration).
2. Set up Vault with the required auth methods, policies, and secrets.
3. Prepare image-signing verification if using the production overlay.
4. Create namespace, service accounts, and network policies.
5. Configure ingress or load balancer for the master API.

Tip

For exact manifests, secret setup, and Vault configuration, see the Runtime configuration reference.

Next steps

• Configuration — configure the runtime for your cluster.
• Scaling & production — tune throughput and reliability.
• Vault policies — set up Vault for dynamic credentials.