The Keel Control Plane

The control plane is an optional Lambda in your AWS account. Keel detects it automatically; there is no endpoint to add to keel.yml.

keel api deploy        # create or update it (admin)
keel api status        # deployment and connectivity
keel api whoami        # identity and authorization path seen by the server
keel api destroy       # remove it; direct operation keeps working

Everything still works without it. IAM sessions talk to AWS directly, and that direct path remains the bootstrap and break-glass route. The control plane is account-level rather than part of an application's stack, so one app's keel destroy cannot remove it.

What goes through it

The dashboard's shared reads go through a short-lived server cache. Ten people watching the same environment therefore produce one upstream metrics read per period rather than ten independent CloudWatch fan-outs. keel dashboard --direct bypasses the control plane for diagnosis.

An operator has no general-purpose AWS credential, so the control plane also becomes their authorization point. It handles two kinds of work:

• Served reads return display-shaped state, such as services, tasks, resources, deployment history, the roster, shared platforms, and authorization decisions.
• Brokered operations authorize a request, assume a purpose-built capability role for a few minutes, and let the client connect to AWS directly. Application logs, exec streams, config values, transcripts, scaling, restart, and rollback use this path; the Lambda does not relay application data.

The execution role remains read-only. Write authority lives on separate capability roles whose ceiling is broader than one request and whose session policy narrows each credential to the requested app, environment, service, or log group.

Failure and fallback

For an IAM session, an absent, unreachable, incompatible, or throttled control plane falls back silently to direct AWS reads. After three consecutive failures the dashboard stops retrying it for that session.

An authorization refusal is different from an outage. It does not trigger fallback or a retry counter: the server answered, and the remedy is a grant. An operator cannot fall back because their credential can invoke only the control plane.

Authentication boundary

The Function URL uses AWS_IAM authentication. IAM callers sign the request with their current Keel session. Operators first authenticate with Cognito; Keel verifies the token and maps its stable subject through the roster to an opaque prn_… principal. Email is a label for humans, never the authorization key.

See Operators for enrollment and grants, and Architecture for where this plane sits beside OpenTofu and direct runtime operations.