Exec sessions

Interactive exec into microservice containers uses a multi-session model aligned with Controller multi-exec sessions. Each session has its own id, WebSocket attach path, and runtime exec process.

Overview

Concern	Controller-initiated exec	Local edgelet ms exec
Who opens the session	Console user / EdgeOps via Controller	Operator CLI on the node
Session discovery	Field agent polls GET /api/v3/agent/exec/sessions	POST /v1/ms/{id}/exec/sessions
Attach transport	Agent WebSocket .../exec/microservice/{uuid}/{sessionId}	GET /v1/ms/{id}/exec/sessions/{sessionId}:attach
Concurrent limit	3 per microservice (Controller quota)	Unlimited (node resources only)
Reported in status	Yes: execSessionIds[] on agent status	No: local sessions are excluded from Controller status

Exec sessions are modeled like log sessions: poll a session list, attach per sessionId, reconcile when rows disappear.

See also: Edgelet API (local API routes), Field agent (controller bridge), Process manager (runtime registry).

Local exec (edgelet ms exec)

edgelet ms exec <uuid|namespace.name>
edgelet ms exec <uuid> -- /bin/sh -c 'ps aux'

Flow:

1. CLI calls POST /v1/ms/{id}/exec/sessions with the remote command (default interactive shell).
2. EdgeletAPI waits up to 15 seconds for the shell to start before returning.
3. CLI attaches over WebSocket and streams stdin/stdout/stderr until the remote command exits.

Multiple local sessions on the same microservice can run concurrently. Each session gets a unique runtime exec id ({containerID[:12]}-local-{uuid[:8]}) so local CLI exec does not collide with controller sessions.

Start timeout

If the shell does not become ready within 15 seconds, the API returns HTTP 504 with code EXEC_START_TIMEOUT. The CLI surfaces:

Error[EXEC_START_TIMEOUT]: Interactive shell did not start within 15 seconds. Retry `edgelet ms exec`; if the problem persists, check microservice and engine logs.

Common causes: container not running, image missing /bin/sh, engine overload, or stale containerd exec state after a prior crash.

Controller-initiated exec

When a user opens exec from Controller / EdgeOps:

1. Controller creates a session row and sets execSessions: true on the next config/changes.
2. The field agent polls the session list and opens one agent WebSocket per pending row.
3. MessagePack relay frames use execId = sessionId (not containerd runtime ids).
4. When the session row disappears from the poll, the agent tears down that attachment only.

The legacy single-session path (WS /agent/exec/{microserviceUuid} with init MessagePack pairing) is removed in v1.0.0-rc.6.

Status reporting

Agent status includes controller attachment session ids per microservice:

"execSessionIds": ["session-uuid-1", "session-uuid-2"]

Values are controller session ids for attachments this agent holds. Not containerd exec process names and not local CLI sessions.

Resize and close

Controller exec sessions accept a resize control frame after the shell has started:

{"type":"resize","cols":120,"rows":40}

Columns run from 2 through 4096. Rows run from 1 through 4096. A later size replaces one that is still in progress. The close control command is unchanged.

When the shell finishes or errors, remaining output is sent before the close frame. The close frame is not written into the shell.

The CLI sends the local terminal size when the session starts. On Unix it sends a new size when the window changes. Windows sends the size once. Interactive exec forwards stdin to the remote PTY, including Ctrl+C, Ctrl+D, exit, and logout. The local session ends when the remote side closes it, or when local stdin reaches EOF.

execEnabled (deprecated)

Edgelet no longer uses the microservice execEnabled flag to open or keep exec sessions. Controller multi-exec session poll (execSessions: true) drives attach and teardown.

The SQLite column may still exist on upgraded databases; removal from the microservice model is an application-level cleanup with no schema migration in this release. Operators do not need to toggle execEnabled for exec to work.

Related operations

• Control plane restart stops interactive exec on the controller microservice before bounce. See Local control plane.
• Health checks use a separate short-lived exec path (ExecWithExitCode) and are not part of the interactive session registry.

Troubleshooting

See Troubleshooting for timeout, orphan session, and concurrent-session scenarios.

See anything wrong with the document? Help us improve it!

Edit this page on GitHub!