Skip to content

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

WorkloadRoleBuilt byPorts
face-control-planeSERVICE_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-planeapp 7100 (loopback only), health 7101, raft 7443, mTLS front door 8443
face-runnerSERVICE_ROLE=runner. It runs the fetch pipeline (connectors, derivations, agents).Static manifest in TIDE’s on-host bundle7102
face-frontendServes the Flutter web bundle and forwards backend calls to the control plane.Static manifest in TIDE’s on-host bundle8080 (Service port 80)
objectdThe object store FACE’s data lives in. Service face-objectd:9000.TIDE manifest9000
face-operatorReconciles the ControlPlane resource into the control-plane Deployment and Service.TIDE manifestnone

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.

The operator is the source of truth for the control-plane pod. If you edit the 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.

FieldEffect
imageThe FACE backend image.
replicasThe pod count. The Deployment uses the Recreate strategy (see Upgrades).
raftNodeIdThis control plane’s consensus node id, 1.
tenantBecomes 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.
objectStoreEndpointThe object-store Service, as host:port. The default is face-objectd:9000.
embeddingUrlBecomes EMBEDDING_URL, which FACE does not read.
managedRunnerEndpointBecomes MANAGED_RUNNER_ENDPOINT, the runner the control plane forwards fetches to. The deployment sets face-runner.face-system.svc:7102.
scheduleExecuteFetchSets SCHEDULE_EXECUTE_FETCH=true, so briefs run real fetches.
ambassadorThe 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.
probesTunes the kubelet probes (see Health and troubleshooting).
resourcesThe backend container’s requests and limits. Unset, the operator uses CPU request 2 and limit 4, memory request 256Mi and limit 4Gi.
tmpAn emptyDir at /tmp with the given sizeLimit, for headless Chrome.
envExtra 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.
nodeSelectorA 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-backend runs /app/server serve --port 7100.
  • ambassador, the mTLS front door, when spec.ambassador enables it. It admits only a client certificate that chains to the mesh CA.

Init containers, in this order:

  1. connections-perms and raft-perms prepare the connections and raft volumes. The connections directory is made owner-only (mode 0700).
  2. ensure-bucket runs /app/server ensure-bucket.

Volumes

MountKindHolds
/dataemptyDirScratch only, such as uploads (/data/uploads) and the ingest spool. No database lives here.
/raftnode-local hostPath under /var/lib/tide/raft (RAFT_HOSTPATH on the operator overrides the base)Consensus state (RAFT_DATA_DIR).
/connectionsnode-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-caSecret face-control-plane-runner-caThe 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:

SecretKeysRequired on the podCreated by the operator
face-sessionAUTH_JWT_SECRETyesyes, if it is absent. It is never rotated on reconcile.
tide-envelope-kekTIDE_ENVELOPE_KEKyesyes, if it is absent. It is never overwritten.
tide-mesh-caMESH_CA_CERT, MESH_CA_KEYyesno. You distribute it with tide mesh ca --namespace face-system.
face-control-plane-adminemail, passwordyesyes. It holds the break-glass admin as ADMIN_EMAIL and ADMIN_PASSWORD.
objectd-key-face-app, objectd-key-face-vacuumaccess-key, secret-keyyes, once they existby TIDE’s provisioner. Until they exist, the pod uses the shared objectstore-creds pair.
face-oauthgoogle-client-id, oidc-issuer, allowed-emails, seed-usersoptionalno
face-recaptchasite-key, hostnames, secret-keyoptionalno. The login captcha stays off while this Secret is absent. reCAPTCHA is not enforced on FACE (owner, 2026-11-02).
licenseLICENSE, LICENSE_PUBLIC_KEYoptionalno. 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.

VariableDefaultPurpose
PORT8080The listen port.
WEB_DIR/webThe Flutter bundle directory.
BACKEND_ADDRhttp://face-control-plane:7100Where backend calls are forwarded.