Building Providers

A provider is how you teach kedge a new capability without forking the hub. Everything beyond raw connectivity ships as a provider: edge management, application templates, git repositories, AI agents, fleet-wide query — all built on the same contract a third-party provider uses.

A provider is a standalone service: its own binary, its own pod, its own Helm chart, its own release cycle. It plugs into the hub through five optional surfaces:

1. An API — custom resources published as a kcp APIExport that tenants bind into their workspaces. For most providers this is the heart of the integration.
2. Controllers — reconcilers that watch the provider’s resources across every tenant workspace at once through the export’s virtual workspace.
3. A backend — any HTTP surface (REST, GraphQL, WebSocket, MCP) the hub reverse-proxies at /services/providers/<name>/* with verified identity headers.
4. A portal UI — a Web Component micro-frontend the portal mounts at /providers/<name> — no iframes, shared theme.
5. MCP tools — a /mcp endpoint on the backend; the hub federates every provider’s tools into one aggregate MCP server for AI agents.

A minimal provider (the in-repo quickstart) is a single Go binary with init and serve subcommands, an embedded frontend, and two small YAML files.

The moving parts

                        kcp workspace tree
   root:kedge:providers:<name>      ← your workspace: APIExport, schemas, SA
   root:kedge:system:providers      ← Provider + CatalogEntry objects, kubeconfig Secret
   root:kedge:tenants:<org>:<ws>    ← tenants; APIBinding pulls your API in

   ┌──────────┐   /ui/providers/<name>/*        ┌────────────────┐
   │  portal  │ ──────────────────────────────► │                │
   └──────────┘                                 │   kedge hub    │
   ┌──────────┐   /services/providers/<name>/*  │  (UI + backend │      ┌───────────────┐
   │ CLI / AI │ ──────────────────────────────► │    proxies)    │ ───► │ your provider │
   └──────────┘                                 └────────────────┘      │      pod      │
                                                                        └──────┬────────┘
                                     APIExport virtual workspace               │
                                     (see tenant resources cross-workspace) ◄──┘

Two small YAML objects wire a provider in:

• Provider (admin.kedge.faros.sh) — applied by the platform admin. The hub provisions your workspace at root:kedge:providers:<name>, a service account with admin rights inside that workspace only, and a kubeconfig Secret your pod mounts.
• CatalogEntry (providers.kedge.faros.sh) — self-registered by your init step. Declares display metadata, UI/backend URLs, and which APIExport tenants bind. It drives the portal catalog, the Enable dialog, and the hub’s proxies.

Your binary’s init subcommand (running as an initContainer with the minted kubeconfig) creates the API surface itself: APIResourceSchemas, the APIExport, an APIExportEndpointSlice, and the bind grant. The hub provisions infrastructure; you own your API.

When to write a provider

You want a provider when you have a vertical slice that should be:

• Discoverable — a card in the catalog, separately enable-able per workspace.
• Tenant-scoped — resources each tenant manages in their own workspace, reconciled by your controllers.
• Independently shipped — your repo, your image, your release cadence; the hub doesn’t rebuild when you do.

If you just need a button on an existing page, patch the portal. Providers exist to draw boundaries that would otherwise grow into a monolith.

The guides

Read them roughly in order — each builds on the previous:

• Anatomy & lifecycle — the Provider / CatalogEntry objects, the init bootstrap, heartbeats, and the tenant Enable flow.
• Defining the API — APIResourceSchemas, the APIExport, permission claims, versioning.
• Virtual workspaces — how your controllers see all tenant workspaces at once, and the two access patterns (service identity vs. caller identity).
• Connectivity & proxies — the UI and backend proxies, identity headers, the revdial reverse tunnel, and data-plane subresources.
• RBAC & security — what your SA can touch, bind grants, claim acceptance, and the isolation rules every provider must follow.
• Building the UI — the custom-element contract, kedgeContext, navigation, and asset serving.
• MCP integration — exposing tools to AI agents through the hub’s aggregate endpoint.
• Packaging & deployment — the Helm chart shape, environment variables, Docker image, and publishing.
• Provider catalog — reference for the eight providers that ship with kedge today.