> ## Documentation Index > Fetch the complete documentation index at: https://docs.acornops.dev/llms.txt > Use this file to discover all available pages before exploring further. # Deployment reference > Detailed Kubernetes, VM Compose, target-agent, and production deployment behavior 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: ```bash theme={null} 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: ```yaml theme={null} 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: ```yaml theme={null} 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: ```yaml theme={null} 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: ```bash theme={null} export ACORNOPS_PLATFORM_VERSION="" 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](https://github.com/acornops/acornops-deployment/blob/main/release/stack-versions.yaml). ### 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: ```bash theme={null} 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](/use/connect-kubernetes) for registration, AgentK installation, scope, and verification. ## VM targets Connecting a Linux VM target is also a workspace task. Follow [Connect a Linux VM](/use/connect-vm) for registration, AgentV installation, diagnostics, and bounded write behavior. ## Validation Complete the [production readiness checklist](/deploy/production-readiness) before handing the deployment to workspace users.