Context
ECS Exec opens an interactive session inside a running ECS container through Systems Manager technology. It is useful when image contents or runtime behavior cannot be established from application logs alone. An existing ECS service being healthy does not prove that its tasks have the session agent, permissions or connectivity needed for Exec.
Prerequisites and access scope
Identify the cluster, service, task ARN, container name, launch environment and platform support. The operator needs the supported AWS CLI and Session Manager plugin, plus narrowly scoped authorization for the intended tasks. The task needs an appropriate IAM role for session-channel communication. Keep the operator role, task role and task execution role distinct in your notes.
Agree on permitted diagnostic actions and session logging before opening a shell. AWS documents that commands run as root inside the container. Plan the session as a privileged operation even when the image normally uses another user.
1. Check how the task was launched
Inspect the task's enableExecuteCommand setting and managed-agent status with the ECS task details or describe-tasks. Use the task ARN from the incident, not whichever task currently appears first in the console. A replacement task can have different launch settings from its predecessor.
Exec cannot simply be enabled on an already-running task. If the service needs the feature, review the configuration and roll out new tasks through the normal deployment process. Account for application availability and deployment capacity while making that change.
2. Verify agent prerequisites and the network path
Check the task role for the documented ssmmessages channel permissions. Inspect the container's filesystem settings: a read-only root filesystem is incompatible with the agent's required writes. Correct a mismatch in the task definition rather than trying to patch the running container.
For a private task, trace its path to Session Manager messaging. Where interface endpoints are used, inspect the relevant ssmmessages endpoint, security groups and DNS. If customer-managed KMS encryption is configured for sessions, include its network and authorization path. A working application connection to its database does not establish these separate dependencies.
3. Separate failures using task-level evidence
| Evidence | What it establishes | Next check |
|---|---|---|
| Exec disabled on the task | Task launch omitted the feature | Reviewed deployment settings |
| Execute-command agent not running | Session agent did not become available | Filesystem and supported task environment |
| Operator receives access denied | Caller cannot perform the requested operation | Scoped ECS and related session policy |
| Agent exists but connection fails | Session path still needs investigation | Task role, endpoints and egress |
An explicitly illustrative scenario: a Fargate service is redeployed with Exec enabled, but only the web container can be reached. The worker container has a read-only root filesystem. The team reproduces the difference using two nonproduction task definitions, then chooses an approved diagnostic design for the worker. Adding administrator access to the human operator would not make the worker filesystem writable.
Correct and verify without changing business data
After a reviewed task rollout, select the exact new task and container. Start with an allowed read-only diagnostic such as checking the process list or release identifier. Do not display environment variables, mounted secrets or credential files. Verify the expected audit trail and session-log destination as separate acceptance checks.
The SOP should record allowed roles, task-selection steps, session purpose, logging ownership and how temporary access expires. Review Exec availability after task-definition hardening and platform upgrades. Use session findings to improve normal application telemetry so privileged interactive access remains a deliberate diagnostic tool.
Explore Clouvenix containers kubernetes for implementation and operational handover.
Technical reference
ECS Exec documentation describes prerequisites and limitations. Task IAM roles documents the session-channel permissions.