Skip to content

Commit 44ece83

Browse files
toriclstoricls
committed
Initial import
0 parents  commit 44ece83

File tree

6 files changed

+675
-0
lines changed

6 files changed

+675
-0
lines changed

‎CONTRIBUTING.md

+57
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
# Contributing Guidelines
2+
3+
Thank you for your interest in contributing to our project. Whether it's a bug report, new feature, correction, or additional
4+
documentation, we greatly value feedback and contributions from our community.
5+
6+
Please read through this document before submitting any issues or pull requests to ensure we have all the necessary
7+
information to effectively respond to your bug report or contribution.
8+
9+
## Reporting Bugs/Feature Requests
10+
11+
We welcome you to use the GitHub issue tracker to report bugs or suggest features.
12+
13+
When filing an issue, please check existing open, or recently closed, issues to make sure somebody else hasn't already
14+
reported the issue. Please try to include as much information as you can. Details like these are incredibly useful:
15+
16+
* A reproducible test case or series of steps
17+
* The version of our code being used
18+
* Any modifications you've made relevant to the bug
19+
* Anything unusual about your environment or deployment
20+
21+
## Contributing via Pull Requests
22+
23+
Contributions via pull requests are much appreciated. Before sending us a pull request, please ensure that:
24+
25+
1. You are working against the latest source on the *main* branch.
26+
2. You check existing open, and recently merged, pull requests to make sure someone else hasn't addressed the problem already.
27+
3. You open an issue to discuss any significant work - we would hate for your time to be wasted.
28+
29+
To send us a pull request, please:
30+
31+
1. Fork the repository.
32+
2. Modify the source; please focus on the specific change you are contributing. If you also reformat all the code, it will be hard for us to focus on your change.
33+
3. Ensure local tests pass.
34+
4. Commit to your fork using clear commit messages.
35+
5. Send us a pull request, answering any default questions in the pull request interface.
36+
6. Pay attention to any automated CI failures reported in the pull request, and stay involved in the conversation.
37+
38+
GitHub provides additional document on [forking a repository](https://help.github.com/articles/fork-a-repo/) and
39+
[creating a pull request](https://help.github.com/articles/creating-a-pull-request/).
40+
41+
## Finding contributions to work on
42+
43+
Looking at the existing issues is a great way to find something to contribute on. As our projects, by default, use the default GitHub issue labels (enhancement/bug/duplicate/help wanted/invalid/question/wontfix), looking at any 'help wanted' issues is a great place to start.
44+
45+
## Code of Conduct
46+
47+
This project has adopted the [Amazon Open Source Code of Conduct](https://aws.github.io/code-of-conduct).
48+
For more information see the [Code of Conduct FAQ](https://aws.github.io/code-of-conduct-faq) or contact
49+
[email protected] with any additional questions or comments.
50+
51+
## Security issue notifications
52+
53+
If you discover a potential security issue in this project we ask that you notify AWS/Amazon Security via our [vulnerability reporting page](http://aws.amazon.com/security/vulnerability-reporting/). Please do **not** create a public github issue.
54+
55+
## Licensing
56+
57+
See the [LICENSE](LICENSE) file for our project's licensing. We will ask you to confirm the licensing of your contribution.

‎LICENSE

+14
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
2+
3+
Permission is hereby granted, free of charge, to any person obtaining a copy of this
4+
software and associated documentation files (the "Software"), to deal in the Software
5+
without restriction, including without limitation the rights to use, copy, modify,
6+
merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
7+
permit persons to whom the Software is furnished to do so.
8+
9+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
10+
INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
11+
PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
12+
HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
13+
OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
14+
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

‎README.md

+105
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
# Amazon ECS Exec Checker
2+
3+
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](check-ecs-exec.sh#L21) on behalf of you. You can learn more about ECS Exec on [the containers blog post](https://aws.amazon.com/blogs/containers/new-using-amazon-ecs-exec-access-your-containers-fargate-ec2/) and [the official developer guide](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-exec.html).
4+
5+
![](demo.gif)
6+
7+
## Prerequisites
8+
9+
The `check-ecs-exec.sh` requires the following commands.
10+
11+
- jq
12+
- AWS CLI v1.19.28/v2.1.30 or later
13+
14+
## Usage
15+
16+
```shell
17+
$ ./check-ecs-exec.sh <YOUR_ECS_CLUSTER_NAME> <YOUR_ECS_TASK_ID>
18+
```
19+
20+
_Example 1 - Run without cloning Git repo_
21+
22+
The `check-ecs-exec.sh` will use your `default` AWS CLI profile and the AWS region.
23+
24+
```shell
25+
$ 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>
26+
```
27+
28+
_Example 2 - With AWS\_* variables_
29+
30+
The `check-ecs-exec.sh` will use the `myprofile` AWS CLI profile and `us-west-2` AWS region.
31+
32+
```shell
33+
$ export AWS_PROFILE=myprofile
34+
$ export AWS_REGION=us-west-2
35+
36+
$ 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>
37+
```
38+
39+
_Example 3 - Switch AWS CLI binaries_
40+
41+
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.
42+
43+
```shell
44+
$ AWS_CLI_BIN=aws-v1 ./check-ecs-exec.sh <YOUR_ECS_CLUSTER_NAME> <YOUR_ECS_TASK_ID>
45+
```
46+
47+
## Checks
48+
49+
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.
50+
51+
1. 🟢(Green) - The configuration or the status is okay.
52+
2. 🟡(Yellow) - The configuration or the status should or would be recommended to fix, but you can use ECS Exec without fixing them.
53+
3. 🔴(Red) - You need to fix those results to use ECS exec.
54+
55+
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.
56+
57+
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](https://docs.aws.amazon.com/vpc/latest/privatelink/vpce-interface.html#create-interface-endpoint) in your VPC.
58+
59+
[![example-result](example-result.png)](example-result.png)
60+
61+
## Reference - How to handle 🔴(Red) items
62+
63+
1. **_Pre-flight check failed: `jq` command is missing_**
64+
Install the `jq` command. See [the official documentation](https://stedolan.github.io/jq/download/) for the details and how to install.
65+
66+
2. **_Pre-flight check failed: `aws` command is missing_**
67+
Install the latest AWS CLI. See [the official documentation for the AWS CLI v2](https://docs.aws.amazon.com/cli/latest/userguide/install-cliv2.html) or [the official documentation for the AWS CLI v1](https://docs.aws.amazon.com/cli/latest/userguide/install-cliv1.html) for the details and how to install.
68+
69+
3. **_Pre-flight check failed: ECS exec requires the AWS CLI v1.19.28/v2.1.30 or later_**
70+
Upgrade to the latest AWS CLI. See [the official documentation for the AWS CLI v2](https://docs.aws.amazon.com/cli/latest/userguide/install-cliv2.html) or [the official documentation for the AWS CLI v1](https://docs.aws.amazon.com/cli/latest/userguide/install-cliv1.html) for the details and how to upgrade.
71+
72+
4. **_Session Manager Plugin | Missing_**
73+
Install the Session Manager plugin. See [the official documentation](https://docs.aws.amazon.com/systems-manager/latest/userguide/session-manager-working-with-install-plugin.html) for the details and how to install.
74+
75+
5. **_Can I ExecuteCommand? | ecs:ExecuteCommand: implicitDeny_**
76+
The IAM user/role you used for the `check-ecs-exec.sh` are not allowed to use the `ecs:ExecuteCommand` API. See the "[Using IAM policies to limit access to ECS Exec](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-exec.html#ecs-exec-best-practices-limit-access-execute-command) section in the official documenation to add the required permission to the IAM user/role.
77+
78+
6. **_Can I ExecuteCommand? | kms:GenerateDataKey: implicitDeny_**
79+
The IAM user/role you used for the `check-ecs-exec.sh` are not allowed to use the `kms: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)](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-exec.html#ecs-exec-logging) section under the "Logging and Auditing using ECS Exec" section in the official documenation to add the required permission to the IAM user/role.
80+
81+
7. **_Platform Version | 1.3.0 (Required: >= 1.4.0)_**
82+
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 the `PlatformVersion` parameter for the `UpdateService` API. If your ECS task is a standalone task, then you need to re-run the ECS task with the `PlatformVersion` parameter specified for the `RunTask` API. See also [the migration guide from the previous PVs](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/platform_versions.html#platform-version-migration).
83+
84+
8. **_ECS Agent Version | x.y.z (Required: >= 1.50.2)_**
85+
You need to update the version of the ECS Container Agent for your EC2 instance where your ECS task runs. See [the official documentation](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-agent-update.html) for the details and how to update.
86+
87+
9. **_Exec Enabled for Task | NO_**
88+
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 the `EnableExecuteCommand` parameter for the `UpdateService` API. If your ECS task is a standalone task, then you need to re-run the ECS task with the `EnableExecuteCommand` parameter specified for the `RunTask` API.
89+
90+
10. **_Managed Agent Status | STOPPED (Reason: stopped-reason-here)_**
91+
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 from `check-ecs-exec.sh` are all green.
92+
93+
11. **_EC2 or Task Role | Not Configured"_ or _{serviceName}:{ActionName}: implicitDeny_**
94+
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](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-exec.html#ecs-exec-enabling-and-using) section and the [Enabling logging and auditing in your tasks and services](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-exec.html#ecs-exec-logging) section in the official documentation for the details.
95+
96+
12. **_SSM PrivateLink "com.amazonaws.(region).ssmmessages" not found_**
97+
The `check-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.
98+
99+
## Security
100+
101+
See [CONTRIBUTING](CONTRIBUTING.md#security-issue-notifications) for more information.
102+
103+
## License
104+
105+
Licensed under the MIT-0 License. See the [LICENSE](LICENSE) file.

0 commit comments

Comments
 (0)