Helm chart: engram
The control-plane chart, what it deploys and does not, and the values that matter.
deploy/helm/engram deploys the control plane to any Kubernetes cluster: the coordinator,
the orchestrator, and nginx serving the dashboard. The chart is cloud-agnostic; the bindings
that differ per cloud, such as Workload Identity, KMS, and load-balancer annotations, live in
the values-gcp.yaml.example and values-aws.yaml.example overlays, and the Terraform
quickstarts render a second overlay with every value they know.
What it deploys
Section titled “What it deploys”The coordinator. A stateless Deployment with replicaCount replicas, a ClusterIP Service
for in-cluster traffic, a ServiceAccount annotated for the cloud’s identity binding, and a
ConfigMap of non-secret settings. Optionally a HorizontalPodAutoscaler, a
PodDisruptionBudget, and a NetworkPolicy. The coordinator’s Ingress is off by default and
should stay off: the coordinator has no authentication of its own for people.
The web frontend. With web.enabled, an nginx Deployment that serves the dashboard and
reverse-proxies API calls, event streams, and WebSockets to the orchestrator, plus the
Service the public Ingress targets. The web Ingress is the only public surface of a
deployment.
The orchestrator. With orchestrator.enabled, the Deployment that owns sign-in, tasks,
profiles, integrations, and the API. Its settings live under the orchestrator block.
Sign-in
Section titled “Sign-in”Every setting for how a person signs in is in orchestrator.auth. mode selects one door,
and only that door is open.
auth.mode |
The door | Settings |
|---|---|---|
oauth (default) |
A “Continue with” button for one OIDC identity provider: Google, Okta, Auth0, Keycloak, Cognito. | oauth.issuer, oauth.clientId, oauth.clientSecret, and the allowlist oauth.allowedDomains and oauth.allowedEmails. |
iap |
GCP Identity-Aware Proxy in front of the app host. | iap.audiences. IAP’s IAM binding decides who gets in. |
password |
Email and password. | password.signup opens or closes registration. |
auth.adminEmails names the accounts that become admins on first sign-in, in every mode.
An OAuth client admits every account its provider has, so oauth mode needs an allowlist
and the chart does not render without one. The orchestrator checks it on every sign-in. For
Google the domain is the Workspace organization of the account, not the text of the
address. allowedDomains: ["*"] admits every account the provider authenticates, which is
correct for a provider that holds only your own people.
password mode does not verify an address at sign-up. With password.signup: true, anyone
who can reach the login page can register any address, an admin address included. Use it
for evaluation, or on a network the internet cannot reach.
The chart fails the render when the active mode is missing a setting, and it renders only the active mode’s settings, so the other two blocks can stay filled in.
What it does not deploy
Section titled “What it does not deploy”- Postgres. Bring your own: Cloud SQL, RDS, or an in-cluster operator. The connection
string comes from a Secret named by
database.existingSecret. - The blob bucket. Provisioned outside the chart, by Terraform, and named in
blob. - The host fleet. That is the
engram-host-fleetchart. - The master key. A KMS key on AWS, or a base64 key placed in the coordinator’s Secret on GCP.
- The managed certificate and load balancer. Terraform creates them; the chart references them by name in annotations.
Prerequisites
Section titled “Prerequisites”A cluster (GKE 1.28 or later with Workload Identity, EKS 1.28 or later with IRSA, or any
conformant cluster with a Secret-based master key for development), a Postgres the pods can
reach, and a Secret named by database.existingSecret (default
engram-coordinator-secrets) that carries DATABASE_URL, ENGRAM_AUTH_TOKENS, and, with
the env-var master-key provider, ENGRAM_KEK_MASTER_KEY. The coordinator runs migrations
at boot.
The values that matter
Section titled “The values that matter”values.yaml is annotated line by line; this is the map of its sections.
| Section | What it sets |
|---|---|
replicaCount, image, imagePullSecrets |
Coordinator replicas and image. The defaults point at the published images on GHCR. |
mode |
coordinator for a real deployment. all runs a host agent inside the coordinator pod and is for single-binary development only. |
blob |
backend (gcs, s3, local), and the bucket, region, and endpoint for it. The key names match the fleet chart so the two agree. |
kek |
The master-key provider and its key: env-var with envVarName, or aws-kms with awsKeyId. |
secrets |
The secret backend, gcp with gcpProjectId or aws. |
database |
The Secret and key that hold DATABASE_URL. |
auth |
The Secret and key that hold the machine bearer tokens. |
appGrpc |
The coordinator’s private RPC port for the orchestrator, and the Secret with its bearer. Required in production; an empty bearer refuses every call. |
forge |
An optional GitHub App so agents can fetch short-lived git credentials and open pull requests without a durable token in the sandbox. |
service, serviceInternal, ingress |
The coordinator’s Services and the Ingress that should stay disabled. |
hpa, pdb, networkPolicy, resources, nodeSelector, tolerations, affinity |
Scheduling and availability. |
otel |
An OTLP endpoint for the coordinator’s own traces. |
upgradeDrain |
The job that runs before an upgrade whose host agents cannot adopt the VMs running now: whether it runs and its time budget. It runs the coordinator image. See Upgrade engrams. |
probes, drainSeconds, terminationGracePeriodSeconds |
Liveness on /healthz, readiness on /readyz, and how long a replica drains before it stops. |
web |
The dashboard: image, Ingress, and the annotations that attach a managed certificate. |
orchestrator |
The orchestrator: image, its Secret with the session-signing key, auth (see Sign-in), the public URL, and integration settings. |
Upgrades
Section titled “Upgrades”The coordinator is stateless, so helm upgrade is a rolling restart of whichever
Deployment’s template changed. Sessions live on the hosts and are untouched by a control-plane
roll; dashboard event streams reconnect with Last-Event-ID, and hosts re-register when the
coordinator comes back. Roll the two charts together when you upgrade engrams: the
coordinator and the host agents share a wire version and refuse to talk across a mismatch.
When a release’s host agents cannot adopt the VMs a host runs now, a job evicts every
running session to a checkpoint before the upgrade changes anything.
An image tag you leave empty falls back to the chart’s appVersion, which is the release the
checkout is. Upgrade engrams is the procedure from one release to
the next.