Amazon ECS Exec Checker

check-ecs-exec.sh checks and validates both your CLI environment and ECS cluster/task are ready for ECS Exec, by calling various AWS APIs on behalf of you.

Prerequisites

• jq
• AWS CLI v1.19.28/v2.1.30 or later
• IAM role permissions:

  {
    "Version": "2012-10-17",
    "Statement": [
      {
        "Effect": "Allow",
        "Action": [
          "iam:ListRoles",
          "iam:GetInstanceProfile",
          "iam:SimulatePrincipalPolicy",
          "kms:DescribeKey",
          "ec2:DescribeSubnets",
          "ec2:DescribeVpcEndpoints",
          "ecs:DescribeClusters",
          "ecs:DescribeContainerInstances",
          "ecs:DescribeTaskDefinition",
          "ecs:DescribeTasks"
        ],
        "Resource": "*"
      }
    ]
  }

Usage

Basic

./check-ecs-exec.sh <YOUR_ECS_CLUSTER_NAME> <YOUR_ECS_TASK_ID>

Run without cloning Git repo

It will use your default AWS CLI profile and the AWS region.

bash <( curl -Ls https://raw.githubusercontent.com/aws-containers/amazon-ecs-exec-checker/main/check-ecs-exec.sh ) \ 
  <YOUR_ECS_CLUSTER_NAME> <YOUR_ECS_TASK_ID>

Run with AWS_* variables

export AWS_PROFILE=myprofile
export AWS_REGION=eu-west-1

bash ./check-ecs-exec.sh <YOUR_ECS_CLUSTER_NAME> <YOUR_ECS_TASK_ID>

Run with MFA

• It autodetects your MFA configuration for the AWS CLI.

  [profile profile-one]
  role_arn = arn:aws:iam::123456789012:role/cool-role
  mfa_serial = arn:aws:iam::123456789012:mfa/user_name
  source_profile = iam
  region = eu-west-1
  output = json

• You can also use the AWS_MFA_SERIAL environment variable.

Switch AWS CLI binaries

AWS_CLI_BIN=aws-v1 ./check-ecs-exec.sh <YOUR_ECS_CLUSTER_NAME> <YOUR_ECS_TASK_ID>

Checks

• 🟢 (Green) - The configuration or the status is okay.
• 🟡 (Yellow) - The configuration or the status should or would be recommended to fix, but you can use ECS Exec without fixing them.
• 🔴 (Red) - You need to fix those results before using ECS Exec.

FAQ

Pre-flight

• 🔴 Pre-flight check failed: jq command is missing: install the jq command.
• 🔴 Pre-flight check failed: aws command is missing: install the latest AWS CLI.
• 🔴 Pre-flight check failed: ECS Exec requires the AWS CLI v1.19.28/v2.1.30 or later: upgrade AWS CLI.

Configuration

• 🔴 Session Manager Plugin | Missing: install the Session Manager plugin.
• 🟡 Cluster Configuration | Audit Logging Not Configured / Disabled: Recomendation, not blocker.

Command execution

• 🔴 Can I ExecuteCommand? | ecs:ExecuteCommand: implicitDeny: you need ecs:ExecuteCommand. Note: the Condition element of the IAM policy is not currently supported to evaluate by check-ecs-exec.sh.
• 🔴 Can I ExecuteCommand? | kms:GenerateDataKey: implicitDeny: You need kms:GenerateDataKey, with the given KMS Key ID which you’re using for the logging and auditing configuration for ECS exec.
• 🟡 Can I ExecuteCommand? | ssm:StartSession denied?: allowed: You need ssm:StartSession. Recomendation, not blocker.

Task status

• 🔴 Task Status | DEACTIVATING or STOPPING or DEPROVISIONING or STOPPED: the ECS task has already stopped, or is shutting down. Restart it, check Task lifecycle.
• 🟡 Task Status | PROVISIONING or ACTIVATING or PENDING:the ECS task is in the middle of its starting process. Wait few more seconds for the task to be ready.

Version issues

• 🔴 Platform Version | 1.3.0 (Required: >= 1.4.0): On AWS Fargate, ECS Exec requires the Platform version 1.4.0 or higher (Linux) or 1.0.0 (Windows).
  • ECS service case: update the platform version by specifying the PlatformVersion parameter for the UpdateService API.
  • Standalone task case: re-run the ECS task with the PlatformVersion parameter specified for the RunTask API.
• 🔴 ECS Agent Version | x.y.z (Required: >= 1.50.2): update the version of the ECS Container Agent for your EC2 instance where your ECS task runs.

Resource issues

• 🔴 Exec Enabled for Task | NO: enable the ECS Exec feature.
  • ECS service case: update the ECS by specifying the EnableExecuteCommand parameter for the UpdateService API.
  • Standalone task case: re-run the ECS task with the EnableExecuteCommand parameter specified for the RunTask API.
• 🔴 Managed Agent Status | STOPPED (Reason: stopped-reason-here): The managed agent for a container in your Task has stopped for reasons related to other existing problems. Clearing other errors detected and rerun.
• 🟡 Init Process Enabled | Disabled: Recommended, not blocker. Add the initProcessEnabled flag to your ECS task definition for each container to avoid having orphaned and zombie processes.
• 🔴 Read-Only Root Filesystem | ReadOnly: the SSM agent requires that the container file system is able to be written in order to create the required directories and files.You need to set the readonlyRootFilesystem flag as false in your task definition.
• 🔴 EC2 or Task Role | Not Configured” or {serviceName}:{ActionName}: implicitDeny: it needs a task role or an instance role of the underlying EC2 instance with some permissions for using SSM Session Manager at least. Note: that the Condition element of the IAM policy is not currently supported.
• 🟡 SSM PrivateLink “com.amazonaws.(region).ssmmessages” not found: there are VPC endpoints configured in the VPC for your task, so you may want to add an additional SSM PrivateLink for your VPC.
• 🔴 VPC Endpoints | CHECK FAILED: check-ecs-exec.sh doesn’t support checking this item for shared VPC subnets using AWS Resouce Access Manager (AWS RAM). In short, this may not an issue to use ECS Exec if your ECS task VPC doesn’t have any VPC endpoint and the task has proper outbound internet connectivity. Make sure to consult your administrator with the official ECS Exec documentation to find if your VPC need to have an additional VPC endpoint.
• 🟡 Environment Variables : defined: SSM uses the AWS SDK, which uses the default chain when determining authentication.If AWS_ACCESS_KEY, AWS_ACCESS_KEY_ID, and AWS_SECRET_ACCESS_KEY are defined in the environment variables and the permissions there do not provide the required permissions for SSM to work, then the execute-command will fail. It is recomended not to define these environment variables.