Namespaces and plugins

A namespace is the wall a tenant's deployments, secrets, tokens and auth providers sit behind. These endpoints list and declare namespaces, install per-namespace plugins such as obs, switch plugins on for the fleet, and read each namespace's event feed.

Back to the API reference.

Namespaces

GET /namespaces lists the namespaces the caller can see, with the number of their deployments the caller may view. A credential confined to one namespace gets that namespace back even when it is empty.

[{"namespace": "team-a", "deployments": 4, "declared": true,
  "description": "Payments team", "created_at": 1760000000},
 {"namespace": "scratch", "deployments": 1, "declared": false}]

POST /namespaces declares one: {"name": "team-a", "description": "…"}. It answers 201 with {name, description, created_at} when new and 200 when it existed; re-declaring updates the description and keeps created_at. Declaring a namespace also installs every enabled plugin that installs automatically (see obs). A confined credential gets 403, and an invalid name 400.

DELETE /namespaces/:name undeclares one and answers 204. It is refused with 409 while deployments are still in it.

On Heyo's managed fleet, namespaces are created in Heyo cloud, not on app-lb.

Namespace plugins

Some plugins install per namespace. Two switches decide whether one does anything for a namespace: the operator enables it for the fleet (below), and a namespace administrator installs it into the namespace. Both must be on.

From namespace-plugins.json:

[
  {"id": "obs", "name": "Observability",
   "description": "Logs, metrics and alerts for every app in a namespace.",
   "enabled": true, "installed": true, "installed_at": 1760000000,
   "installed_by": "token:0123456789ab", "config": {}}
]

PUT installs the plugin or replaces its per-namespace config, and is idempotent. The body is {"config": {…}}, optional; the crate sends {} when config is None. DELETE uninstalls; it is allowed while the plugin is disabled. Both return the plugin as the namespace now sees it.

"Admin of the whole namespace" is the operator, a fleet admin token, a namespace token with admin scope and no deployments list (or ["*"]), or a federated namespace:<ns>:admin grant. A namespace token narrowed to particular deployments gets 403.

Fleet plugins

Plugins are compiled into app-lb and switched on per host. These routes are fleet-wide: a confined caller gets 403.

A plugin, from plugins.json:

{"id": "example", "name": "Example", "description": "A plugin that is switched on and failing.",
 "config_schema": {"type": "object", "properties": {"url": {"type": "string"}}},
 "per_namespace": true, "installed_in": ["team-a"],
 "enabled": true, "config": {"url": "http://127.0.0.1:34199"},
 "updated_at": 1760000000, "last_error": "connection refused", "status": {"state": "retrying"}}

PUT /api/plugins/:id takes {"enabled": true, "config": {…}}. With config omitted, the stored config is kept. It answers 200 once the record is saved, even if applying it failed: check last_error on the result. Invalid config is a 400.

GET /api/plugins/:id/installs lists every namespace the plugin is installed in. app-obs polls it to learn what to collect. From plugin-installs.json:

{"plugin": "obs", "enabled": true, "namespaces": ["team-a", "team-b"],
 "installs": {"team-a": {"installed_at": 1760000000, "installed_by": "user:u_123", "config": {}},
              "team-b": {"installed_at": 1760000000, "installed_by": null, "config": {}}}}

Feeds

Each namespace has a feed of lifecycle events and issues: deployments added, changed and removed, and problems such as cold-start timeouts.

GET /feeds lists namespaces with events: [{"namespace": "team-a", "events": 12}]. A namespace's feed is RSS by default, for feed readers; ?format=json returns the events, newest first:

{"id": 7, "ts": 1722400000, "last_ts": 1722400120, "count": 3, "namespace": "team-a",
 "deployment": "web", "kind": "issue", "title": "web: cold start timed out",
 "detail": "a request waited 120s and no VM became available"}