# Helm chart: engram

> The control-plane chart, what it deploys and does not, and the values that matter.

Source: https://engramsfactory.com/docs/reference/helm-engram/

`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

**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

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

- **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-fleet` chart](https://engramsfactory.com/docs/reference/helm-engram-host-fleet/).
- **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

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

`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](https://engramsfactory.com/docs/guides/upgrade/#when-a-release-changes-how-hosts-run-vms). |
| `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](#sign-in)), the public URL, and integration settings. |

## 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](https://engramsfactory.com/docs/guides/upgrade/) is the procedure from one release to
the next.
