Deployment reference

AcornOps deployment has two independent steps: deploy the central platform, then connect each Kubernetes cluster or Linux VM with an outbound agent. Starter automation is part of current-version control-plane workspace provisioning in every environment. It is independent of optional local target fixtures such as SEED_DEVELOPMENT_DATA; each new workspace receives the final starter bundle once, with no startup upgrade or repair pass.

Kubernetes

Use the acornops-platform Helm chart to deploy the central platform into a Kubernetes cluster. The chart deploys:

management console,
control plane,
execution engine,
LLM gateway,
optional platform admin console when explicitly enabled,
database migration Jobs.

Postgres and Redis are operator-provided. The chart references an existing Kubernetes Secret instead of templating secret values into Helm values.

Required platform inputs

Prepare these inputs before installing the chart:

Input	Notes
Public API host	Operator-owned host for API routes, such as `api.example.com`.
Console host	Operator-owned host for the management console, such as `console.example.com`.
TLS secret	Referenced by the ingress configuration.
External Postgres	Used by control plane and LLM gateway.
External Redis	Used by control plane, execution engine, and LLM gateway.
Existing secret	Defaults to `acornops-platform-secrets`.
OIDC client	Redirects back to the control plane callback route.
External integration service token	Required when enabling the registered external integration client account-link flow.
Provider credential plan	Configure a write-only workspace credential after installation, or enable the platform admin console and configure an optional platform default.
Internal TLS Secrets	Optional. Required only when `internalTransport.tls.enabled=true`.

Review these value groups before installing or upgrading:

Area	Values
Public hosts	`platform.publicUrl`, `platform.consoleUrl`, `exposure.ingress.apiHost`, `exposure.ingress.consoleHost`
Workspace-user access	`userAccess.oidc.`, `userAccess.password.`, `userAccess.session.*`
Platform-admin access	`platformAdminAccess.*`
Workspace roles	`workspaceRoles.enabledBuiltIns`, `workspaceRoles.customTemplates`
Run policy and target connectivity	`ai.`, `assistantRuntime.`, `agentGateway.*`
Reasoning summaries	`ai.reasoningSummariesEnabled`, `ai.allowedReasoningSummaryModes`, `ai.allowedReasoningEfforts`
Gateway controls	`components.llmGateway.auth.`, `components.llmGateway.mcpEgress.`, `components.llmGateway.rateLimits.*`
Internal transport TLS	`internalTransport.tls.*`
Network egress	`networkPolicies.postgres.to`, `networkPolicies.redis.to`, `networkPolicies.vault.to`, `networkPolicies.extraEgress.*`

Internal service TLS

The chart can harden control-plane, execution-engine, and LLM gateway traffic with operator-supplied HTTPS/mTLS. It is disabled by default. AcornOps does not generate or chart-manage the CA or certificates. Create a CA Secret and one TLS Secret per service:

kubectl -n acornops-platform create secret generic acornops-internal-ca \
  --from-file=ca.crt=./ca.crt

kubectl -n acornops-platform create secret tls control-plane-internal-tls \
  --cert=./control-plane.crt \
  --key=./control-plane.key

kubectl -n acornops-platform create secret tls execution-engine-internal-tls \
  --cert=./execution-engine.crt \
  --key=./execution-engine.key

kubectl -n acornops-platform create secret tls llm-gateway-internal-tls \
  --cert=./llm-gateway.crt \
  --key=./llm-gateway.key

Then set:

internalTransport:
  tls:
    enabled: true
    ca:
      secretName: acornops-internal-ca
    certificates:
      controlPlane:
        secretName: control-plane-internal-tls
      executionEngine:
        secretName: execution-engine-internal-tls
      llmGateway:
        secretName: llm-gateway-internal-tls

Certificates should include SANs for the rendered service DNS names. For the default release name and namespace shown in this guide, the control-plane DNS name is acornops-platform-control-plane.acornops-platform.svc. If you use a different release name or namespace, render the chart and use the service DNS names from your deployment. Public ingress stays on the control-plane HTTP service port. Existing bearer tokens and run-scoped JWT checks remain required. cert-manager can create the same Secrets, but it is optional. A representative control-plane certificate looks like this:

apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: control-plane-internal-tls
  namespace: acornops-platform
spec:
  secretName: control-plane-internal-tls
  issuerRef:
    name: acornops-internal-ca-issuer
    kind: Issuer
  dnsNames:
    - acornops-platform-control-plane.acornops-platform.svc
  usages:
    - server auth
    - client auth

Create equivalent certificates for execution-engine and llm-gateway with their rendered service DNS names. Restart affected pods after CA or leaf certificate rotation unless an operator-managed reloader handles restarts.

Workspace roles

Configure deployment-supported workspace roles with workspaceRoles in chart values:

workspaceRoles:
  enabledBuiltIns:
    - owner
    - admin
    - operator
    - viewer
    - auditor
  customTemplates:
    - key: incident_responder
      displayName: Incident Responder
      description: Can run read-only diagnostics, inspect logs, and cancel runs.
      capabilities:
        - read_workspace_data
        - read_members
        - create_sessions
        - create_read_only_runs
        - read_target_logs
        - cancel_runs
      sortOrder: 300

If enabledBuiltIns is omitted, all built-ins are enabled. If it is provided, it must include owner. Custom roles may only use supported workspace capabilities and cannot include owner-only governance capabilities. Every workspace inherits the same catalog. Example install:

export ACORNOPS_PLATFORM_VERSION="<version-from-stack-versions.yaml>"

helm upgrade --install acornops-platform oci://ghcr.io/acornops/charts/acornops-platform \
  --version "${ACORNOPS_PLATFORM_VERSION}" \
  --namespace acornops-platform \
  --create-namespace \
  --values values.prod.yaml

Resolve the version from the acornopsPlatform entry in the stack-versions.yaml release matrix.

Production exposure

Expose only the management console and control-plane public routes:

https://console.example.com/
https://api.example.com/api/v1
wss://api.example.com/api/v1/agent/connect

Keep execution engine and LLM gateway private to the platform network. Ingress ownership and NetworkPolicy authorization are independent. exposure.ingress.enabled controls whether the chart renders an Ingress; it does not authorize packets. When networkPolicies.enabled=true, configure networkPolicies.ingressController.from with the exact namespace and pod selectors allowed to reach the management console and control plane. An empty list fails closed and allows no ingress-controller source through the chart’s default-deny policy. This applies equally when an external controller or GitOps system owns the Ingress resource.

Replicas

The chart defaults to multiple replicas for stateless or Redis-coordinated services where supported:

Component	Default posture
Management console	Multiple replicas
Control plane	Multiple replicas with Redis-backed agent routing and renewed scheduler leases
Execution engine	Multiple replicas with Redis-backed run reservation
LLM gateway	Multiple replicas with external Postgres and Redis

During a control-plane rollout, connected agents reconnect to an available pod. Commands that are active during the rollout can fail or time out and should be retried.

VM Compose

Use the VM Compose stack for a single-machine central platform installation. This path is useful for smaller environments and production-style testing with separate Kubernetes clusters and VM targets. Typical flow:

cp env/vm/.env.example env/vm/.env.prod
task prod-up

Before starting the stack:

Generate unique internal service tokens and encryption keys.
Set production hostnames and OIDC settings.
Keep TRUST_PROXY=1 when the edge proxy owns TLS and forwarded host headers.
Point database and Redis settings at durable services.
Review JWKS readiness, request-size, rate-limit, and MCP egress variables.
Pin all image references from the vm-prod-v1 release matrix instead of using mutable or independently selected tags.
Confirm the reverse proxy terminates TLS for the console and API hosts.

Database init jobs run before services start. Treat init failures as deployment blockers.

Greenfield database epoch

This version is not a rolling database upgrade. Back up if needed, then drop and recreate the external control-plane and gateway databases before installing the complete pinned stack matrix. Pre-release data is not preserved, and mixed gateway, control-plane, or execution-engine versions are unsupported.

Kubernetes clusters

Connecting a Kubernetes target is a workspace task performed after the central platform is ready. Follow Connect a Kubernetes cluster for registration, AgentK installation, scope, and verification.

VM targets

Connecting a Linux VM target is also a workspace task. Follow Connect a Linux VM for registration, AgentV installation, diagnostics, and bounded write behavior.

Validation

Complete the production readiness checklist before handing the deployment to workspace users.

Start here

Install

Configure

Govern

Operate

Deployment reference

Kubernetes

Required platform inputs

Internal service TLS

Workspace roles

Production exposure

Replicas

VM Compose

Greenfield database epoch

Kubernetes clusters

VM targets

Validation

​Kubernetes

​Required platform inputs

​Internal service TLS

​Workspace roles

​Production exposure

​Replicas

​VM Compose

​Greenfield database epoch

​Kubernetes clusters

​VM targets

​Validation

Kubernetes

Required platform inputs

Internal service TLS

Workspace roles

Production exposure

Replicas

VM Compose

Greenfield database epoch

Kubernetes clusters

VM targets

Validation