Helm Chart Reference

Every field in values.yaml for the maestro Helm chart. Defaults shown are from the chart (charts/maestro/values.yaml).

Image

A single unified image runs both workloads. The chart picks the entrypoint.

image:
  repository: public.ecr.aws/cardinalhq.io/maestro
  tag: ""            # empty → Chart.appVersion (recommended: pin to a released tag)
  pullPolicy: IfNotPresent

Maestro workload

maestro:
  enabled: true
  replicas: 1
  port: 4200
  resources: {}
  labels: {}
  annotations: {}
  nodeSelector: {}
  tolerations: []
  affinity: {}
  env: []                 # extra env vars (auth, LLM, etc.)
  extraVolumes: []
  extraVolumeMounts: []

The Maestro pod runs with readOnlyRootFilesystem: true. A tmp emptyDir is mounted at /tmp. If you need additional writable paths (e.g., ontology workspaces), add them via extraVolumes + extraVolumeMounts.

An initContainer waits for the MCP gateway service to accept connections before Maestro starts.

MCP Gateway workload

Starting with chart 0.8.0, the MCP gateway runs as a Kubernetes native sidecar (initContainer with restartPolicy: Always) inside every Maestro pod and every github-cache pod. There is no standalone Deployment or Service by default — Maestro talks to it over localhost, so every MCP session stays pod-local. The mcpGateway.enabled and mcpGateway.replicas fields from older chart versions no longer exist.

mcpGateway:
  port: 8080
  debugPort: 9090
  apiKey: ""
  apiKeySecret:
    name: ""
    key: "MCP_API_KEY"
  service:
    enabled: false
  resources: {}
  env: []

Leave apiKey and apiKeySecret.name both empty for most installs — the sidecar runs unauthenticated on localhost, and external auth is enforced at the Maestro entry point via MAESTRO_MCP_API_KEY. The mcpGateway.apiKey* knobs only matter if you also flipped service.enabled: true to expose the sidecar directly (a single-pod-only path; in multi-replica installs, route external MCP traffic through Maestro per Connect AI Clients).

Database

Required. Maestro will not start without it.

database:
  secretName: "pg-credentials"
  create: true
  passwordKey: "MAESTRO_DB_PASSWORD"
  host: ""               # required
  port: 5432
  name: "maestro"
  username: "maestro"
  password: ""           # only used when create: true
  sslMode: "require"

The chart synthesizes MAESTRO_DATABASE_URL from these fields and injects it into both workloads — you do not need to set it yourself.

Ingress

ingress:
  enabled: false
  className: ""
  host: ""
  annotations: {}
  tls: []

The built-in Ingress is a minimal networking.k8s.io/v1 object that points at the Maestro service. It works for NGINX, Traefik, or anything that honors ingressClassName. If you need more control (IngressRoute, Gateway API, multiple hosts), disable this and create your own routing resource — the Maestro service is <release>-maestro on port 4200.

Service account

serviceAccount:
  create: true
  name: ""
  annotations: {}

Global

Applied to both workloads.

global:
  imagePullSecrets: []
  env: []                 # env vars merged into both containers
  labels: {}
  annotations: {}
  podSecurityContext:
    runAsNonRoot: true
    runAsUser: 65532
    runAsGroup: 65532
    fsGroup: 65532
  containerSecurityContext:
    allowPrivilegeEscalation: false
    readOnlyRootFilesystem: true
    capabilities:
      drop:
        - ALL
    seccompProfile:
      type: RuntimeDefault

Scheduling fields (nodeSelector, tolerations, affinity) can also be set at the global level and are merged with per-workload overrides.

Deploying on OpenShift

The chart renders cleanly under the restricted-v2 SCC once the UID fields are nulled out so the SCC can inject values from the namespace’s assigned UID range:

global:
  podSecurityContext:
    runAsNonRoot: true
    runAsUser: null
    runAsGroup: null
    fsGroup: null

With that in place the pod securityContext emits only runAsNonRoot: true; the SCC fills in runAsUser, runAsGroup, and fsGroup. All other hardening from global.containerSecurityContext (no-privilege-escalation, drop ALL, RuntimeDefault seccomp, read-only rootfs) stays in effect.

The built-in Ingress is a standard networking.k8s.io/v1 resource with a configurable ingressClassName — the OpenShift HAProxy router handles it out of the box; no nginx-specific annotations are emitted.