Helm Chart

The octo chart deploys the full platform (the editor UI, the orchestrator, the observability service, Postgres, NATS and Redis) onto any Kubernetes cluster. It is published as an OCI artifact on every release, so installing it needs no checkout:

helm install octo oci://ghcr.io/juancavallotti/charts/octo \--version 0.11.7 \--namespace octo --create-namespace \--set ingress.host=octo.example.com \--set postgres.auth.password=<strong-password>

The defaults point at the public Docker Hub images, and image.tag falls back to the chart's appVersion, so a chart installs the images of its own release rather than drifting onto latest. Both --sets are required: the chart has no default host and no default password, and rendering fails by name without them. If your cluster has no default IngressClass, add --set ingress.className=<yours> as well (see Ingress and TLS).

What the chart deploys

Five images are not chart workloads. octo-runtime is passed to the orchestrator as RUNTIME_IMAGE, and the orchestrator deploys one pod set per integration from it at runtime. octo-agenticrunner is the alternative for an integration that asked for the agentic runner (see Agentic runner). octo-devruntime and octo-devsidecar are the two containers of a dev run (see Dev runs), created the same way, and octo-statssidecar is injected beside every deployed integration when Pod Stats is on. The schema Job is annotated helm.sh/hook: post-install,post-upgrade with the before-hook-creation delete policy, so it re-runs (idempotently) on every upgrade.

How the chart is put together

octo is an application chart built on octo-common, a library chart holding every reusable template: naming, labels, image references, and the generic Deployment / StatefulSet / Service / RBAC / Secret renderers. The application templates are thin stubs naming a component:

# helm/templates/observability/deployment.yaml (the whole file)
{{- include "octo-common.deployment" (dict "root" $ "component" "observability" ...) }}

So a knob added once applies to every component and every target. Environment variables are the exception, being component-specific, so each component keeps its own _env.tpl. octo-common is vendored at helm/charts/octo-common and packaged inside the octo tarball, so installing octo pulls nothing extra. It is also published standalone at the same version (oci://ghcr.io/juancavallotti/charts/octo-common).

Environment profiles

The chart ships a values file per target. Each is a starting point: you still supply the hostname and a password.

Where to get a profile

The profiles ship inside the published chart, so getting one needs no checkout:

helm pull oci://ghcr.io/juancavallotti/charts/octo --version 0.11.7 --untarls octo/values-*.yaml# octo/values-eks.yaml  octo/values-gke-autopilot.yaml  octo/values-gke-standard.yaml# octo/values-k3d.yaml  octo/values-k3d-gateway.yaml  octo/values-k3d-traefik.yaml  octo/values-kind.yaml

Or download just the one you want:

curl -O https://raw.githubusercontent.com/juancavallotti/octo/main/helm/values-eks.yaml

They are also browsable on GitHub under helm/, where every value carries a comment explaining it. Then install with one:

helm install octo oci://ghcr.io/juancavallotti/charts/octo \--version 0.11.7 -n octo --create-namespace \-f values-eks.yaml --set ingress.host=octo.example.com

Values

Defaults live in helm/values.yaml, where every knob is documented inline. The ones that matter most:

Images

Components are platform, orchestrator, observability, embeddings, schema, runtime, agenticrunner, devsidecar, statssidecar and devruntime. postgres, nats and redis also take image.*, but do not inherit image.registry, which holds the octo-* images only. Point their own image.registry at a mirror for clusters that cannot reach Docker Hub.

The GCP release path pins by digest: Cloud Build renders a values file naming the exact digest of every image it pushed. Render one yourself with task helm:values:images IMAGE_BASE=… TAG=….

Per-workload knobs

Every workload accepts the same set, and defaults: applies them to all of them at once. A per-component value overrides the default; the two are merged, not replaced wholesale.

defaults:
  resources:
    requests: { cpu: 100m, memory: 256Mi }
  securityContext:
    runAsNonRoot: true
    allowPrivilegeEscalation: false
    capabilities: { drop: ["ALL"] }

platform:
  resources:
    requests: { cpu: 250m, memory: 512Mi }   # only this component

Available on defaults and on each component: resources, podSecurityContext, securityContext, imagePullSecrets, nodeSelector, tolerations, affinity, topologySpreadConstraints, priorityClassName, podAnnotations, podLabels, extraEnv, envFrom, extraVolumes, extraVolumeMounts, livenessProbe, startupProbe, revisionHistoryLimit and strategy.

The orchestrator, observability service and runtime additionally take serviceAccount.{create,name,annotations}, which is where GKE Workload Identity and EKS IRSA annotations go.

Private registries

If you mirror the images somewhere that needs credentials, create the pull Secret in the release namespace and name it once:

defaults:
  imagePullSecrets:
    - name: regcred

That reaches all the chart workloads and the integration pods, which the orchestrator creates at runtime from a value passed to it as an environment variable. Without it a mirrored install comes up healthy and every integration you deploy sits in ErrImagePull. Override it for the runtime image alone with runtime.imagePullSecrets; empty there inherits defaults.

Ingress and TLS

ingress.tls.mode is the biggest single difference between targets:

Empty auto-selects cert-manager when a clusterIssuer is set, else secret.

Worked examples

Complete values.yaml files, one per mode, each rendering and schema-validating as shown. Install with -f values.yaml.

ingress:
  enabled: true
  className: nginx
  host: octo.example.com
  tls:
    mode: cert-manager
    clusterIssuer: letsencrypt-prod
    secretName: octo-tls

# Per-integration endpoints at {slug}.apps.example.com, each getting its own
# certificate from the same issuer as it is deployed.
orchestrator:
  baseDomain: apps.example.com
  ingressClass: nginx
  clusterIssuer: letsencrypt-prod

postgres:
  auth:
    password: CHANGEME

Where certificates come from

1. Who issues, and who owns the issuer. This chart never creates an Issuer or ClusterIssuer; it names one that must already exist, so clusterIssuer: letsencrypt-prod presumes somebody created it. The k3s bootstrap in this repo does, which is why that name appears in the defaults.

2. How the challenge is solved. For ACME issuers (Let's Encrypt, ZeroSSL) this decides what you can issue:

So wildcardTLS.clusterIssuer defaults to a different issuer from ingress.tls.clusterIssuer: *.{baseDomain} needs a DNS solver, while the editor's own host works with HTTP-01.

3. "Cloud certificates" are two unrelated mechanisms. They differ in where the private key lives:

The first two never produce a Kubernetes Secret: the certificate is attached to the load balancer by annotation, which is why those Ingresses carry no tls block and why neither mode has a Gateway API equivalent. The last row is cert-manager issuing from a private CA (a corporate PKI, GoogleCASClusterIssuer, AWSPCAClusterIssuer), which lives outside the cert-manager.io API group, so the reference needs a kind and a group as well as a name, supplied as annotations:

ingress:
  enabled: true
  className: nginx
  host: octo.example.com
  annotations:
    # Out-of-tree issuer. AWS Private CA is:
    #   cert-manager.io/issuer-kind: AWSPCAClusterIssuer
    #   cert-manager.io/issuer-group: awspca.cert-manager.io
    cert-manager.io/issuer-kind: GoogleCASClusterIssuer
    cert-manager.io/issuer-group: cas-issuer.jetstack.io
  tls:
    mode: cert-manager
    clusterIssuer: cas-prod      # the external issuer's name
    secretName: octo-tls

ingress.className selects the controller (traefik, nginx, gce, alb); ingress.annotations carries controller-specific behaviour. Per-integration external endpoints are a separate axis: orchestrator.baseDomain plus orchestrator.ingressClass and orchestrator.ingressAnnotations, which the orchestrator stamps onto the Ingresses it generates at runtime.

Both class values default to empty, which omits ingressClassName and lets whichever IngressClass the cluster marks default claim the Ingress. Every environment profile sets it explicitly, and so should you if the cluster has no default, or has one that is not the controller you want:

--set ingress.className=nginx --set orchestrator.ingressClass=nginx

Gateway API

networking.mode selects which Kubernetes API publishes external endpoints, both the editor's and the ones the orchestrator creates per deployed integration. They are served by the same proxy, so it is one switch.

gateway covers kgateway, Envoy Gateway, Istio, Cilium, and the Gateway API modes of ingress-nginx and Traefik.

kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.6.1/standard-install.yamlhelm install octo oci://ghcr.io/juancavallotti/charts/octo \--version 0.11.7 \--namespace octo --create-namespace \--set networking.mode=gateway \--set networking.gateway.name=shared-gw \--set networking.gateway.namespace=ingress \--set ingress.host=octo.example.com

Any Gateway API release from v1.0 onwards works, in the Standard channel; v1.6.1 above is the current one. The orchestrator builds against the gateway.networking.k8s.io/v1 types, GA since v1.0, and uses only Core-support fields (parentRefs, hostnames, rules.matches, rules.backendRefs), so what it sends is accepted unchanged across that range. The Go module sigs.k8s.io/gateway-api is pinned lower than the CRDs you install, which changes nothing: only the serialised shape of an HTTPRoute matters.

Attaching to an existing Gateway is the default. The cluster owner owns the Gateway and octo owns only the routes in its own namespace; the orchestrator's Role grants httproutes and nothing on gateways. The listener owns the ingress class, the certificate arrangement and any controller-specific annotations, so orchestrator.clusterIssuer, orchestrator.ingressClass, orchestrator.ingressAnnotations and wildcardTLS's plumbing have no counterpart under gateway, and the chart stops passing them.

networking:
  mode: gateway
  gateway:
    name: shared-gw
    namespace: ingress

ingress:
  enabled: true
  host: octo.example.com
  # className, annotations and tls are Ingress-only and ignored here: the
  # listener on shared-gw decides the controller and holds the certificate.

orchestrator:
  baseDomain: apps.example.com
  # clusterIssuer / ingressClass / ingressAnnotations have no counterpart in
  # this mode; the listener answers all three.

postgres:
  auth:
    password: CHANGEME

create: true derives one listener per hostname the release already publishes (ingress.host and the *.{baseDomain} wildcard), so a route never has to name one. There is no listener override: anything more elaborate is a Gateway you should own, with create left false.

Certificates. For a Gateway it created, the chart writes the editor's Certificate itself rather than annotating the Gateway for cert-manager's gateway-shim, which needs config.gatewayAPI.enabled=true. On a Gateway you own, its listeners and their certificates are yours, and a Secret in the release namespace could not be referenced from another without a ReferenceGrant. With no ingress controller at all, an HTTP-01 issuer needs cert-manager's gatewayHTTPRoute solver, which is the ClusterIssuer's configuration.

kubectl -n octo get httproute -o jsonpath='{.items[*].status.parents[*].conditions[*]}'
kubectl -n ingress get gateway shared-gw -o jsonpath='{.status.listeners[*].attachedRoutes}'

The orchestrator fails at startup, rather than at the first deploy, when it is configured for Gateway API on a cluster without the CRDs. gke-managed-cert and acm are refused at render time under gateway, having no Gateway API equivalent.

Switching an existing release between modes

The chart's own objects swap over on helm upgrade: the editor's Ingress is replaced by an HTTPRoute, and vice versa. Deployments already running do not. A deployment created under ingress keeps its Ingress after the switch, and undeploying it under gateway removes an HTTPRoute it never had. Redeploy each exposed integration after switching, then sweep up what the old mode left:

# after switching to gateway
kubectl -n octo delete ingress -l app.kubernetes.io/managed-by=orchestrator
# after switching back to ingress
kubectl -n octo delete httproute -l app.kubernetes.io/managed-by=orchestrator

Database

The chart runs Postgres itself by default, or points at a managed one.

# Cloud SQL / RDS instead of the bundled StatefulSet
postgres:
  enabled: false
externalDatabase:
  host: octo.abcdef.us-east-1.rds.amazonaws.com
  database: octo
  user: octo
  sslmode: require
  existingSecret: rds-octo
  existingSecretPasswordKey: password

Prefer existingSecret over an inline password, because values persist in Helm release history. Either way the chart passes the password via secretKeyRef and lets Kubernetes expand it into DATABASE_URL, so it is never plaintext in a pod's environment.

Nothing in the chart deletes a database. The StatefulSet sets persistentVolumeClaimRetentionPolicy: Retain, so neither helm uninstall nor scaling to zero removes the claim, and the static volume carries helm.sh/resource-policy: keep.

Secrets and auth

Agentic runner

Configures the image the orchestrator deploys for an integration whose deployment asked for runner: agentic: the one carrying a shell, curl, jq, the standalone octo CLI, dolphin and a scratch workspace. Leave these at their defaults unless you are turning the runner off or sizing its pod. The platform agent requires it. See octo-agenticrunner.

To turn the runner off, clear agenticrunner.repository. The orchestrator then refuses an agentic deploy naming this value, and installing the agent is blocked up front with the reason shown.

Treat the pod as the boundary. A pod holding a shell and a runtime it can point at a definition it just wrote is a general execution environment, so no allow list inside the flow contains it. Everything that pod holds (secrets bound to its environment included) and everything it can reach on the network is reachable by anything it runs. Grant it per deployment on that basis.

Set resources where a pod's appetite matters. No integration pod carries requests or limits by default, and this is the one workload whose purpose is running other programs. GKE Autopilot requires them.

Dev runs

The editor's Run button, executed as a pod the orchestrator creates rather than as a child process of whichever platform replica answered the request. The platform runs several replicas with no session affinity, so a run living in one replica's memory would be invisible to the others. On by default; disabling it makes Run unavailable. See Dev runs for the feature.

The key must never change. A run's public hostname is derived from it, so rotating it re-labels every exposed dev run and a webhook registered against the old hostname silently stops being delivered. The chart requires the value instead of generating one, because a generated key would be regenerated by any render that cannot read the cluster (helm template, --dry-run, a GitOps pipeline). Hold it wherever you hold kv.encryptionKey.

A Secret rather than a values file is the better answer for every credential the chart takes. existingSecret is the same shape everywhere:

postgres:
  auth:
    existingSecret: octo-db-password     # key: postgres-password
kv:
  existingSecret: octo-kv-key            # key: kv-encryption-key
auth:
  existingSecret: octo-auth-creds        # keys: oidc-client-secret, auth-secret
embeddings:
  existingSecret: octo-embeddings-key    # key: apiKey
orchestrator:
  devRuns:
    existingSecret: octo-devrun-key      # key: dev-run-hash-secret

With references, no key material lands in the release history, and the chart creates no Secret of its own for the auth, KV, dev-run or embeddings credentials. {release}-postgres is still created because it carries the username and database name; with postgres.auth.existingSecret set it holds those two and no password.

Clear the inline value when you switch: setting both is refused, since leaving encryptionKey, hashSecret, apiKey or the two auth values beside an existingSecret would keep the copy the switch was made to avoid. Revisions written before the change still hold what they were given and helm history keeps them, so migrate before anything has been encrypted or deployed.

A dev-run hostname is stable but not private. It is an unguessable hash, not an access control. With orchestrator.clusterIssuer set, each one also gets a per-host certificate and therefore an entry in public CT logs, so prefer wildcardTLS (one *.{baseDomain} certificate) when dev runs are on. Without orchestrator.baseDomain a run still works, reachable only in-cluster.

Data retention

A CronJob that asks the observability service, once a night, to delete stored logs and traces older than the site's retention policy. These values decide whether the job exists and when it runs; how long to keep things is a policy in the database, edited in the admin section. See Data retention.

Scaling

Redis

Redis holds state shared between replicas of a component. Today that is one thing: the observability service folds the trace records a streaming block emits (one block.pre-invoke and one block.post-invoke per streamed token) into a single row. Its consumers are a NATS queue group, so one trace's records are spread across replicas.

It is not optional the way NATS is. nats.enabled=false only degrades live event streams to polling, but the aggregator refuses to start without a Redis, so an install with neither the bundled server nor externalRedis.url fails while rendering, with a message naming both values.

Nothing here is persisted: no volume, and the server runs with --save "" and --appendonly no. Losing it costs at most the trace records in the folds that were open. To use a managed Redis instead:

redis:
  enabled: false
externalRedis:
  url: redis://cache.internal:6379

The whole connection is that one string. If it contains a password, put it in a Secret instead. externalRedis.url is rendered into the workload as a literal environment value, readable by anyone who can read workloads:

kubectl create secret generic octo-redis \
  --from-literal=redis-url='rediss://default:pw@cache.example:6380'

redis:
  enabled: false
externalRedis:
  existingSecret: octo-redis   # wins over `url` when both are set
  existingSecretKey: redis-url # the default

The chart will not create that Secret for you. Whether the cluster's Redis is reachable is shown on the Platform services page, alongside Postgres, NATS and the Kubernetes API.

What the chart does not create

Four things a production chart often ships are deliberately absent, each with a workable answer in the meantime:

Image and chart compatibility

A chart at version X expects the images of release X, which is what it installs by default via the appVersion fallback. This matters because the images run as non-root, and the chart's cloud profiles pin the matching UIDs:

Pinning image.tag to an older release while using a newer chart is untested, and the security contexts in the profiles are the most likely thing to break; relax defaults.securityContext accordingly.

Cluster prerequisites

The chart deploys workloads, not cluster infrastructure. Depending on the values you choose, the cluster must already provide:

• an ingress controller matching ingress.className; none is installed here
• cert-manager and a ClusterIssuer, for tls.mode: cert-manager (and for wildcardTLS, which needs a DNS-01 issuer)
• a StorageClass for the Postgres PVC, unless postgres.storage.hostPath is set or postgres.enabled is false

Upgrade

helm upgrade octo oci://ghcr.io/juancavallotti/charts/octo \--version 0.11.7 --namespace octo --reuse-values

Because image.tag follows appVersion, a chart-version bump moves the images with it. What happens:

• changed image references rewrite the pod templates, so the platform, orchestrator and observability Deployments roll automatically
• the schema hook Job re-runs and applies sql/schema.sql; the schema is idempotent (IF NOT EXISTS / ON CONFLICT), so this is safe every time
• Postgres and its PVC are untouched, so your data survives the upgrade
• integrations already deployed keep running on the runtime image they were deployed with; redeploy them from the editor to pick up a new octo-runtime

Validating changes

task helm:test lints and renders every profile and pipes the output through kubeconform against the real Kubernetes schemas. CI runs it on every push, so a template change that breaks a target you cannot reach locally still fails on the pull request.

Per-target guides