ADR-0016: Resolve Firecall previews to exact loopback Pod processes
Date: 2026-08-29 Status: accepted Decider: OpenMined platform owner
Context
Firecall v2 needs bounded application previews for selected Kubernetes workloads. The browser must not receive a Kubernetes credential, Pod address, or local forwarding port.
Kubernetes Service forwarding can select a different Pod after creation. It can also hide stale or external endpoints. Firecall needs one reviewable target that does not change during a preview.
The existing root-owned loopback Kubernetes proxy owns Azure authentication and AKS trust. The unprivileged Firecall agent can use that proxy without an Azure credential.
Decision
The Firecall agent resolves every preview to one exact Pod UID and declared TCP container port.
For a Service, the agent verifies the Service, every applicable EndpointSlice, the selected endpoint, the selected Pod, and the complete Service selector. It rejects selectorless, external, stale, mixed, unresolved, or unowned endpoints.
For a direct Pod, the agent permits HTTP only.
Every selected Pod must be ready, managed, and not terminating. The agent rejects
hostNetwork, hostPort, hostPath, and privileged containers.
The agent starts the pinned kubectl executable without a shell. It uses this
fixed command shape:
/usr/local/bin/kubectl \
--kubeconfig=<fixed-agent-kubeconfig> \
--namespace=<validated-namespace> \
port-forward \
--address=127.0.0.1 \
pod/<exact-pod-name> \
:<exact-pod-port>
The operating system selects the local port. The process binds only to loopback. The agent never forwards a Service.
The persisted target binds the Service and selected Pod UIDs and resource versions. It also binds every EndpointSlice UID and resource version.
The agent resolves the complete target before process start. After kubectl
reports readiness, it resolves the target again. It exposes the loopback
endpoint only when both results match.
The agent owns preview process lifecycle. Root sessiond receives no new network
authority. The agent stops every preview on target drift, explicit deletion,
15-minute inactivity, session revocation, session expiry, or agent shutdown.
One session permits at most three preview processes. Preview identifiers contain 128 random bits encoded as canonical lowercase unpadded Base32.
One create request has a 25-second end-to-end deadline. Incomplete response delivery stops and deletes the newly created preview.
The agent persists only safe target metadata. It does not persist or return the process identifier, local port, kubeconfig, bearer token, cookies, authorization headers, or application bodies.
A clean agent shutdown first stops every preview process. It then writes one restart permission for each stopped preview. Restore persists that permission as consumed before it starts any process. A second crash cannot reuse it.
This decision covers the private loopback process boundary only. A later change must add preview-origin authentication, application proxy controls, a separate registrable domain, and the browser view.
Options considered
Forward a Service
- Kubernetes selects a current backend.
- The selected Pod can change after the user confirms the target.
- Firecall cannot bind the preview record to one reviewed Pod.
Forward one exact Pod
- The preview stays bound to the selected Pod UID and port.
- Target drift closes the preview instead of silently changing the target.
- Firecall must resolve and revalidate Service endpoints itself.
Add forwarding to root sessiond
- Root could supervise the process.
- This adds network authority to the smallest privileged service.
- The agent already owns preview policy and session shutdown signals.
Consequences
- Resolver tests must cover every Pod and EndpointSlice rejection.
- Process tests must prove fixed arguments, loopback binding, limits, and termination.
- The Kubernetes proxy must reject namespaces outside the signed session scope.
- The image must provide agent-readable fixed kubeconfigs without changing user access.
- A live canary must prove one real AKS port forward before activation.
- Public previews remain unavailable until the separate origin proxy passes its tests.
Supersession and rollback
A later ADR can replace kubectl port-forward with another exact-Pod transport.
Removing the manager restores the fail-closed unavailable preview backend.
Program links
- Program decision: The delivery-program workflow is suspended by ADR-0013.
- Dependent work packages: None.