The check-ecs-exec.sh
script allows you to check and validate both your CLI environment and ECS cluster/task are ready for ECS Exec
, by calling various AWS APIs on behalf of you. You can learn more about ECS Exec on the containers blog post and the official developer guide.
The check-ecs-exec.sh
requires the following commands.
- jq
- AWS CLI v1.19.28/v2.1.30 or later
$ ./check-ecs-exec.sh <YOUR_ECS_CLUSTER_NAME> <YOUR_ECS_TASK_ID>
Example 1 - Run without cloning Git repo
The check-ecs-exec.sh
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>
Example 2 - With AWS_* variables
The check-ecs-exec.sh
will use the myprofile
AWS CLI profile and us-west-2
AWS region.
$ export AWS_PROFILE=myprofile
$ export AWS_REGION=us-west-2
$ 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>
Example 3 - Switch AWS CLI binaries
If you have multiple AWS CLI installations in your environment, both AWS CLI v1 and v2 for example, you can choose which AWS CLI binary to use by passing the AWS_CLI_BIN
env variable.
$ AWS_CLI_BIN=aws-v1 ./check-ecs-exec.sh <YOUR_ECS_CLUSTER_NAME> <YOUR_ECS_TASK_ID>
The check-ecs-exec.sh
shows the results with three text colors, 🟢(Green), 🟡(Yellow), and 🔴(Red). Each color tells how you'll handle the results.
- 🟢(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.
In the following screenshot for instance, we need to install the Session Manager plugin and give required permissions to the task role at least, but we can ignore the audit-logging configuration.
Note that it shows "SSM PrivateLink" at the bottom as a 🟡(yellow) result, but it can be a 🔴(red) result if your ECS task doesn't have proper outbound internet connectivity. In this case, you will need to configure an SSM PrivateLink in your VPC.
-
🔴 Pre-flight check failed:
jq
command is missing
Install thejq
command. See the official documentation for the details and how to install. -
🔴 Pre-flight check failed:
aws
command is missing
Install the latest AWS CLI. See the official documentation for the AWS CLI v2 or the official documentation for the AWS CLI v1 for the details and how to install. -
🔴 Pre-flight check failed: ECS Exec requires the AWS CLI v1.19.28/v2.1.30 or later
Upgrade to the latest AWS CLI. See the official documentation for the AWS CLI v2 or the official documentation for the AWS CLI v1 for the details and how to upgrade. -
🔴 Session Manager Plugin | Missing
Install the Session Manager plugin. See the official documentation for the details and how to install. -
🟡 Cluster Configuration | Audit Logging Not Configured / Disabled This check item won't block you to use ECS Exec, but we recommend you to enable logging and auditing for your ECS cluster from the security perspective. See the official documentation for the details and how to enable them.
-
🔴 Can I ExecuteCommand? | ecs:ExecuteCommand: implicitDeny
The IAM user/role you used for thecheck-ecs-exec.sh
are not allowed to use theecs:ExecuteCommand
API. See the "Using IAM policies to limit access to ECS Exec section in the official documenation to add the required permission to the IAM user/role.
Note that theCondition
element of the IAM policy is not currently supported to evaluate bycheck-ecs-exec.sh
. -
🔴 Can I ExecuteCommand? | kms:GenerateDataKey: implicitDeny
The IAM user/role you used for thecheck-ecs-exec.sh
are not allowed to use thekms:GenerateDataKey
API with the given KMS Key ID which you're using for the logging and auditing configuration for ECS exec. See the "IAM permissions required for encryption using your own KMS customer master key (CMK) section under the "Logging and Auditing using ECS Exec" section in the official documenation to add the required permission to the IAM user/role.
Note that theCondition
element of the IAM policy is not currently supported to evaluate bycheck-ecs-exec.sh
. -
🔴 Platform Version | 1.3.0 (Required: >= 1.4.0)
On AWS Fargate,ECS Exec
requires the Platform version 1.4.0 or newer. If your ECS task is part of an ECS service, then you can update the platform version by specifying thePlatformVersion
parameter for theUpdateService
API. If your ECS task is a standalone task, then you need to re-run the ECS task with thePlatformVersion
parameter specified for theRunTask
API. See also the migration guide from the previous PVs. -
🔴 ECS Agent Version | x.y.z (Required: >= 1.50.2)
You need to update the version of the ECS Container Agent for your EC2 instance where your ECS task runs. See the official documentation for the details and how to update. -
🔴 Exec Enabled for Task | NO
You need to enable the ECS Exec feature for your ECS service or your ECS standalone task. If your ECS task is part of an ECS service, then you can update the ECS by specifying theEnableExecuteCommand
parameter for theUpdateService
API. If your ECS task is a standalone task, then you need to re-run the ECS task with theEnableExecuteCommand
parameter specified for theRunTask
API. -
🔴 Managed Agent Status | STOPPED (Reason: stopped-reason-here)
The managed agent for a container in your Task has stopped for some reasons. If you see this error again and again even after re-running your ECS task, then make sure you have other results fromcheck-ecs-exec.sh
are all green. -
🔴 EC2 or Task Role | Not Configured" or {serviceName}:{ActionName}: implicitDeny
Your ECS task needs a task role or an instance role of the underlying EC2 instance with some permissions for using SSM Session Manager at least. See the IAM permissions required for ECS Exec section and the Enabling logging and auditing in your tasks and services section in the official documentation for the details.
Note that theCondition
element of the IAM policy is not currently supported to evaluate bycheck-ecs-exec.sh
. -
🟡 SSM PrivateLink "com.amazonaws.(region).ssmmessages" not found
Thecheck-ecs-exec.sh
found one or more VPC endpoints configured in the VPC for your task, so you may want to add an additional SSM PrivateLink for your VPC. Make sure your ECS task has proper outbound internet connectivity, and if it doesn't, then you need to configure an additional SSM PrivateLink for your VPC.
See CONTRIBUTING for more information.
Licensed under the MIT-0 License. See the LICENSE file.