Deployment model
A deployment runs one FACE instance, managed by TIDE, in the namespace
face-system. This page lists the workloads in that namespace, says which ones the
operator builds and which are plain manifests, and shows what to edit to change each one.
All of them are declared in TIDE’s manifests. FACE’s own CD only rolls them once they
exist (see Upgrades and CD).
The workloads
| Workload | Role | Built by | Ports |
|---|---|---|---|
face-control-plane | SERVICE_ROLE=server. It serves the FACE app’s gRPC-web and gRPC API, holds sessions and metadata, runs briefs and self-healing, and forwards every fetch to a runner. It never runs a fetch itself. | face-operator, from the ControlPlane resource face-control-plane | app 7100 (loopback only), health 7101, raft 7443, mTLS front door 8443 |
face-runner | SERVICE_ROLE=runner. It runs the fetch pipeline (connectors, derivations, agents). | Static manifest in TIDE’s on-host bundle | 7102 |
face-frontend | Serves the Flutter web bundle and forwards backend calls to the control plane. | Static manifest in TIDE’s on-host bundle | 8080 (Service port 80) |
objectd | The object store FACE’s data lives in. Service face-objectd:9000. | TIDE manifest | 9000 |
face-operator | Reconciles the ControlPlane resource into the control-plane Deployment and Service. | TIDE manifest | none |
The control plane and the runner use the same face-backend image. Only the role differs.
TLS for browsers ends at the platform edge in front of these workloads. FACE itself has
no browser certificate to configure.
face-control-plane Deployment, the operator reconciles your change away. Edit the
ControlPlane resource instead, usually its env list. The static workloads
(face-runner, face-frontend) are not reconciled by any operator: change them in
TIDE’s on-host bundle.The ControlPlane resource
face-operator owns the kind ControlPlane (API group runink.org/v1alpha1, short name
cp). TIDE’s FACE manifests declare one, named face-control-plane.
| Field | Effect |
|---|---|
image | The FACE backend image. |
replicas | The pod count. The Deployment uses the Recreate strategy (see Upgrades). |
raftNodeId | This control plane’s consensus node id, 1. |
tenant | Becomes FACE_TENANT. Leave it empty: the operator then reads the tenant from the ConfigMap face-install-config, key FACE_TENANT. The reference is required, so a missing ConfigMap stops the pod instead of starting FACE on an empty tenant. The static face-runner reads the same key, so the two always agree. |
objectStoreEndpoint | The object-store Service, as host:port. The default is face-objectd:9000. |
embeddingUrl | Becomes EMBEDDING_URL, which FACE does not read. |
managedRunnerEndpoint | Becomes MANAGED_RUNNER_ENDPOINT, the runner the control plane forwards fetches to. The deployment sets face-runner.face-system.svc:7102. |
scheduleExecuteFetch | Sets SCHEDULE_EXECUTE_FETCH=true, so briefs run real fetches. |
ambassador | The mTLS front door (mode: terminate, listenPort: 8443). With it on, FACE binds its app port to 127.0.0.1, the kubelet probes the health port 7101, and the Service carries only the mTLS and raft ports. |
probes | Tunes the kubelet probes (see Health and troubleshooting). |
resources | The backend container’s requests and limits. Unset, the operator uses CPU request 2 and limit 4, memory request 256Mi and limit 4Gi. |
tmp | An emptyDir at /tmp with the given sizeLimit, for headless Chrome. |
env | Extra environment variables. They are appended after the operator’s own list, so a literal here overrides the operator’s value of the same name. FACE_TENANT and the operator’s TIDE_PLATFORM_ADMIN are appended after env, so env cannot override them. A FACE_APPFS_DIR set here is honoured. |
nodeSelector | A hard pin to labelled nodes, on top of the operator’s default placement. |
The operator also accepts a FaceInstance kind (a per-tenant runner). The deployment
declares none: fetches run on the static face-runner.
A further kind, ClientInstance (core.runink.org/v1alpha1), belongs to TIDE’s
operator. It records an instance’s app, tenant, image, users and subscription. FACE’s
instance picker lists the ClientInstances whose spec.app matches RUNINK_APP
(default face). The pod’s ServiceAccount needs list on
clientinstances.core.runink.org for this.
What the operator puts in the control-plane pod
Containers
face-backendruns/app/server serve --port 7100.ambassador, the mTLS front door, whenspec.ambassadorenables it. It admits only a client certificate that chains to the mesh CA.
Init containers, in this order:
connections-permsandraft-permsprepare the connections and raft volumes. The connections directory is made owner-only (mode0700).ensure-bucketruns/app/server ensure-bucket.
Volumes
| Mount | Kind | Holds |
|---|---|---|
/data | emptyDir | Scratch only, such as uploads (/data/uploads) and the ingest spool. No database lives here. |
/raft | node-local hostPath under /var/lib/tide/raft (RAFT_HOSTPATH on the operator overrides the base) | Consensus state (RAFT_DATA_DIR). |
/connections | node-local hostPath under /var/lib/tide/face-connections (CONNECTIONS_HOSTPATH overrides the base) | The legacy connection layout (FACE_CONNECTIONS_DIR), imported once into the appfs root, and the local appfs root (appfs/) when there is no object store. |
/etc/face-runner-ca | Secret face-control-plane-runner-ca | The data-runner CA (FACE_RUNNER_CA_DIR), minted once by the operator and never rotated. |
Environment. The operator sets the role, port, raft settings, inference URLs,
object-store settings and admission defaults (FACE_ADMIT_MAX=1, FACE_ADMIT_QUEUE=32).
It also references these Secrets:
| Secret | Keys | Required on the pod | Created by the operator |
|---|---|---|---|
face-session | AUTH_JWT_SECRET | yes | yes, if it is absent. It is never rotated on reconcile. |
tide-envelope-kek | TIDE_ENVELOPE_KEK | yes | yes, if it is absent. It is never overwritten. |
tide-mesh-ca | MESH_CA_CERT, MESH_CA_KEY | yes | no. You distribute it with tide mesh ca --namespace face-system. |
face-control-plane-admin | email, password | yes | yes. It holds the break-glass admin as ADMIN_EMAIL and ADMIN_PASSWORD. |
objectd-key-face-app, objectd-key-face-vacuum | access-key, secret-key | yes, once they exist | by TIDE’s provisioner. Until they exist, the pod uses the shared objectstore-creds pair. |
face-oauth | google-client-id, oidc-issuer, allowed-emails, seed-users | optional | no |
face-recaptcha | site-key, hostnames, secret-key | optional | no. The login captcha stays off while this Secret is absent. reCAPTCHA is not enforced on FACE (owner, 2026-11-02). |
license | LICENSE, LICENSE_PUBLIC_KEY | optional | no. You mint it with TIDE’s license tool. |
A required reference to a missing Secret or ConfigMap stops the pod before FACE runs.
Kubernetes reports it as CreateContainerConfigError and names the object, so the cause
shows up in kubectl describe pod and not in an application log.
The static runner
face-runner runs the same image as SERVICE_ROLE=runner on port 7102, with
RUNNER_ID=face-runner so its state survives restarts. It reads FACE_TENANT from
face-install-config, uses the same object-store keys, KEK, session key and mesh CA as
the control plane, and calls the model plane through TIDE’s model router. It does not set
RAFT_NODE_ID, because runners are not consensus voters. The control plane reaches it
over mesh mTLS.
The frontend
face-frontend is a small static Go server in a distroless image. It serves /web and
forwards a request to BACKEND_ADDR when the request is one of these:
- a gRPC-web request;
- a request under
/auth/,/api/,/webrtc/or/oauth/(the mailbox connect’s OAuth callback); - a dotted gRPC service path.
In the deployment, BACKEND_ADDR is http://127.0.0.1:8081: an ambassador sidecar in
the same pod (mode: originate) carries the call to face-control-plane on port 8443
over mTLS. The web app’s config.json (the sign-in client id) comes from the ConfigMap
face-frontend-config, which tide wizard writes.
The release web build bakes in no backend host. The FACE app takes its origin from the page it was loaded from, so one bundle works behind any hostname.
| Variable | Default | Purpose |
|---|---|---|
PORT | 8080 | The listen port. |
WEB_DIR | /web | The Flutter bundle directory. |
BACKEND_ADDR | http://face-control-plane:7100 | Where backend calls are forwarded. |