ACP Engine Helm Chart

This chart deploys the ACP platform as independent Kubernetes workloads:

• manager: Next.js Manager web application.
• engine: public /api/v1 entrypoint.
• mcp: public MCP JSON-RPC facade plus internal MCP server management, discovery, routing, proxying, and tool execution.
• auth: authentication, users, realms, memberships, API keys, and themes.
• runtime: flows, prompts, sessions, context, agent config, and routing rules.
• ai: AI chat, AI usage, and AI provider management.
• catalog: private merchant/store Catalog API used by Engine and the merchant-authenticated MCP profile.
• usage: usage records, transaction counting, and usage summaries.
• enrichment: store-scoped enrichment providers, jobs, and usage.
• data: anonymous event ingestion and OpenSearch-backed exploration.
• safezone: global Safe Zone connections and scoped policies.
• optional bundled Redis and OpenSearch data services;
• optional Prometheus, Alertmanager, and Grafana monitoring stack.

Expose Manager for the web UI, the engine for REST API traffic, and the public paths of mcp for MCP JSON-RPC traffic. Other Engine domain services stay internal ClusterIP services.

Install

helm upgrade --install acp-engine ./deployment/helm-chart \
  --namespace acp-engine \
  --create-namespace \
  --set secrets.dbUrl='postgres://user:pass@postgres:5432/acp_engine?sslmode=disable' \
  --set secrets.jwtSecret='change-me' \
  --set secrets.apiKeyEncryptionKey='change-me-32-chars' \
  --set secrets.grafanaAdminPassword='change-me'

Render Locally

helm template acp-engine ./deployment/helm-chart

Images

Set image repositories and tags per service:

services:
  manager:
    image:
      repository: registry.example.com/acp-engine/engine/manager
      tag: "1.0.0"
  engine:
    image:
      repository: registry.example.com/acp-engine/engine
      tag: "1.0.0"
  auth:
    image:
      repository: registry.example.com/acp-engine/auth-service
      tag: "1.0.0"
  mcp:
    image:
      repository: registry.example.com/acp-engine/mcp-service
      tag: "1.0.0"

Secrets

By default, the chart creates a Kubernetes Secret from:

• secrets.dbUrl
• secrets.redisUrl
• secrets.jwtSecret
• secrets.internalServiceSecret
• secrets.mcpSharedSecret
• secrets.apiKeyEncryptionKey

For production, prefer ExternalSecret or sealed secret workflows. If you provide an existing Secret, set:

secrets:
  create: false
  name: acp-engine-secrets

The Secret must contain:

• DB_URL
• REDIS_URL
• JWT_SECRET
• INTERNAL_SERVICE_SECRET
• MCP_SHARED_SECRET
• CATALOG_PAYMENT_VERIFICATION_SECRET
• API_KEY_ENCRYPTION_KEY
• DATA_INTERNAL_TOKEN
• DATA_ANONYMIZATION_SECRET
• SAFE_ZONE_INTERNAL_TOKEN
• ENRICHMENT_INTERNAL_TOKEN
• ENRICHMENT_CREDENTIAL_SECRET
• MCP_SECRET_REFERENCES_JSON
• GRAFANA_ADMIN_PASSWORD when bundled Grafana is enabled

Redis

The chart can deploy an internal Redis instance:

redis:
  enabled: true
  persistence:
    enabled: true
    size: 1Gi

For managed Redis, disable the bundled Redis workload and provide the external URL:

redis:
  enabled: false
secrets:
  redisUrl: redis://redis.example.internal:6379/0

OpenSearch

The bundled single-node OpenSearch StatefulSet is enabled by default and uses persistent storage. A post-install/post-upgrade Job creates realm-log and anonymous-data index templates, indexes, and retention policies:

opensearch:
  enabled: true
  persistence:
    enabled: true
    size: 50Gi
  init:
    logRetentionDays: 30
    dataRetentionDays: 90

The bundled profile disables the OpenSearch security plugin and is intended for a namespace-internal development or controlled single-node installation. Production HA deployments should use a secured managed or dedicated cluster:

opensearch:
  enabled: false
  externalUrl: https://opensearch.example.internal

Use NetworkPolicy, TLS, authentication, backup, restore, and multi-node settings appropriate to the target environment. An external OpenSearch URL is required when the bundled component is disabled.

Monitoring

Prometheus, Alertmanager, and Grafana are enabled by default. Prometheus discovers enabled ACP services, loads the ACP alert rules, and sends alerts to Alertmanager. Grafana is provisioned with Prometheus and OpenSearch datasources plus the ACP service overview dashboard.

monitoring:
  prometheus:
    enabled: true
    persistence:
      size: 20Gi
  alertmanager:
    enabled: true
    config:
      route:
        receiver: platform-alerts
      receivers:
        - name: platform-alerts
          webhook_configs:
            - url: https://alerts.example.internal/acp
  grafana:
    enabled: true
    publicUrl: https://grafana.example.com
  publicUrls:
    prometheus: https://prometheus.example.com
    alertmanager: https://alertmanager.example.com

All monitoring services are ClusterIP. Expose them only through an approved Ingress or port-forward policy. Public URL values configure Manager links; they do not create public exposure. When using an external platform, disable the corresponding bundled component and configure its externalUrl for Manager's server-side access.

Database and Migrations

PostgreSQL is intentionally external to this chart. Set secrets.dbUrl to a reachable database and apply repository migrations through the approved deployment pipeline before rolling out application pods. The chart does not silently initialize or mutate a production database.

Engine Ingress

Ingress is disabled by default. Enable it for the engine only:

ingress:
  enabled: true
  className: nginx
  hosts:
    - host: engine.example.com
      paths:
        - path: /
          pathType: Prefix

Manager Ingress

Manager has a separate ingress so the UI and API hostnames can be managed independently:

managerIngress:
  enabled: true
  className: nginx
  hosts:
    - host: manager.example.com
      paths:
        - path: /
          pathType: Prefix

By default, Manager receives NEXT_PUBLIC_ENGINE_URL pointing to the in-cluster engine service. Override it when the browser must call a public API hostname:

services:
  manager:
    engineUrl: https://engine.example.com

MCP Ingress

The unified MCP service has its own ingress so MCP clients can use a dedicated endpoint:

mcpIngress:
  enabled: true
  className: nginx
  hosts:
    - host: mcp.example.com
      paths:
        - path: /
          pathType: Prefix

By default, mcp receives ENGINE_BASE_URL pointing to the in-cluster engine service. Override it only when the public MCP facade must call another engine hostname:

services:
  mcp:
    engineUrl: https://engine.example.com

Built-in Catalog MCP tools authenticate with a merchant API key created in Merchant Dashboard > Developers. Send it as Authorization: Bearer or x-api-key; its merchant, store, or custom scope controls the available stores.

Realm-bound Engine MCP tools authenticate with a realm service identity created through the engine:

POST /api/v1/realms/:id/identities/services

Then pass the returned service credentials to the MCP endpoint:

• X-ACP-Realm-ID
• X-ACP-Access-Key
• X-ACP-Secret-Key

The MCP service rejects realm service credentials whose token realm does not match a realm-bound Engine request and rejects merchant keys for stores outside their allowed scope.

Scaling

Each service has independent replica, resource, HPA, and PDB settings:

services:
  ai:
    replicaCount: 3
    autoscaling:
      enabled: true
      minReplicas: 3
      maxReplicas: 10
      targetCPUUtilizationPercentage: 70

Internal Routing

The engine receives internal service URLs automatically through Kubernetes service DNS:

• AUTH_SERVICE_URL
• RUNTIME_SERVICE_URL
• AI_SERVICE_URL
• MCP_SERVICE_URL
• USAGE_SERVICE_URL
• CATALOG_SERVICE_URL
• DATA_SERVICE_URL
• SAFE_ZONE_SERVICE_URL

Frontend, mobile, SDK, ADK, and Manager clients should call only the engine. MCP clients should call the public endpoint of mcp-service, which then calls the engine.

Catalog, Enrichment, Data, and Safe Zone

The chart defines private Catalog, Enrichment, Data, and Safe Zone workloads and wires their service URLs into Engine or Manager as appropriate. Keep these services private by default. If an approved merchant integration requires a dedicated Catalog ingress, add TLS, network controls, rate limits, and Auth-backed merchant/store scope validation explicitly. Data and Safe Zone routes must remain behind Engine or their signed internal-service boundaries.