Packaging & Deployment

A provider ships as a container image plus a Helm chart. The quickstart provider’s chart (providers/quickstart/deploy/chart/) is the canonical copy-me template.

Chart shape

deploy/chart/
├── Chart.yaml
├── values.yaml
└── templates/
    ├── deployment.yaml       # initContainer (init) + serve container
    ├── service.yaml          # ClusterIP the hub proxies to
    ├── serviceaccount.yaml
    └── catalogentry.yaml     # renders manifest.yaml into a ConfigMap

The key wiring in deployment.yaml:

• initContainer runs your binary with args: ["init"]. In charts that use the init/bootstrap path, it mounts the hub-minted kubeconfig Secret (providerKubeconfig.secretName, default faros-provider-kubeconfig, key kubeconfig) at /var/run/secrets/faros/ and the CatalogEntry ConfigMap at /etc/faros/catalogentry/. That Secret mount is intentionally non-optional in this mode, so the pod waits until the hub’s provider reconciler delivers it. Charts using an external or hub-provisioned serve-only mode may make the same mount optional and serve limited catalog/readiness traffic while waiting; follow that provider chart’s values and README.
• serve container runs the long-lived process: portal assets, backend API, controllers, MCP, heartbeat.
• The CatalogEntry goes into a ConfigMap, not the host cluster — it’s a kcp resource; init applies it into your provider workspace using the minted kubeconfig. In-cluster the chart points ui.url/backend.url at the Service DNS (http://<release>.<namespace>.svc.cluster.local:<port>).

values.yaml highlights: image.*, replicaCount (2 by default — drop to 1 only if you terminate revdial tunnels ), service.port, hub.url, hub.tokenSecretRef, providerKubeconfig.secretName, catalogEntry.enabled.

Environment variables

The conventional contract your binary reads:

Providers with extra needs add their own namespaced vars (AGENTS_DATABASE_URL, GITHUB_OAUTH_*, …).

The Docker image

Three stages, mirroring the quickstart Dockerfile:

1. Frontend — npm ci && npm run build produces portal/dist.
2. Go build — the binary embeds portal/dist via go:embed (frontend must build first).
3. Runtime — distroless static, non-root, schemas baked at /etc/faros/schemas, entrypoint the binary.

Health, readiness, heartbeat

Serve /healthz → 200; the chart wires it into liveness and readiness probes, and the hub health-checks your backend.healthPath. Separately, heartbeat the hub every 30s — losing heartbeats (90s TTL) flips you Not-Ready: UI proxy 503s and your MCP tools drop out of federation.

Onboarding a provider to a hub

The admin-side steps, in order:

1. kubectl apply -f provider.yaml (the Provider object) against the hub — provisions workspace, SA, kubeconfig Secret.
2. Read the kubeconfig data from the minted Secret (<name>-kubeconfig in root:faros:system:providers) and create a Secret with that data key in the runtime cluster’s provider namespace. A Kubernetes Secret does not cross clusters by itself; use the generated onboarding command or an equivalent sealed-secret/GitOps process.
3. helm install the chart. Init bootstraps the API; serve starts heartbeating; the provider appears in the catalog.
4. If your export claims *.faros.sh groups, supply the required identityHash values from the hub admin view.

There’s also a fully self-supplied variant — you provide a workspace-admin kubeconfig yourself instead of the hub-minted one — useful for development or running a provider entirely outside the hub’s cluster. Everything downstream of the kubeconfig mount is identical.

Publishing

In the faros monorepo each providers/<name> directory is split-mirrored (history preserved) to a standalone read-only repo faroshq/provider-<name>, and the provider’s go.mod module path is the mirror URL — so third parties can go get the code, while images and charts build from the monorepo CI. If you build out-of-tree, none of this applies to you: any repo that produces an image + chart with the contract above is a valid provider.