Skip to content

Commit

Permalink
Fix doc
Browse files Browse the repository at this point in the history
  • Loading branch information
@daaru00
daaru00 committed Oct 24, 2020
1 parent 8eb7eb0 commit 3276733
Show file tree
Hide file tree
Showing 3 changed files with 225 additions and 99 deletions.
79 changes: 79 additions & 0 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,85 @@ and then install it into your system:
sudo cp bb-aws-connect /usr/local/bin/bb-aws-connect
```

## Debug and troubleshooting

Is possible to enable some verbose logging in order to identify errors and issues.

### Shell commands

If you want to see executed command (both in background and foreground) set `BB_AWS_CONNECT_COMMAND_DEBUG` environment variable with any value:
```
export BB_AWS_CONNECT_COMMAND_DEBUG=yes
```
then when you execute a command the CLI will print the full command parameters:
```
bb-aws-connect ssm tunnel --host db.prod.internal --port 3306 --key /my/key/path --username ec2-user --local-port 3306
----------------------------------------
Executing command: aws ssm start-session --profile myprofile --region eu-west-1 --target i-0cd15458284749f64 --document-name AWS-StartPortForwardingSession --parameters portNumber=22,localPortNumber=59392
----------------------------------------
SSH tunnel to remote instance opened on local port: 59392
Tunnel to remote db.prod.internal:3306 is available on local port: 3306
----------------------------------------
Executing command: ssh -i /my/key/path -o StrictHostKeyChecking=no -p 59392 ec2-user@localhost -L 3306:db.prod.internal:3306 -T -q
----------------------------------------
```

### AWS API requests

If you want to see AWS API executed set `BB_AWS_CONNECT_AWS_DEBUG` environment variable with any value:
```
export BB_AWS_CONNECT_AWS_DEBUG=yes
```
then when you execute a command the CLI will print the full command parameters:
```
bb-aws-connect ssm connect -s cron -e test
---[ REQUEST POST-SIGN ]-----------------------------
POST / HTTP/1.1
Host: ec2.eu-west-1.amazonaws.com
User-Agent: aws-sdk-go/1.30.9 (go1.15.2; linux; amd64)
Content-Length: 210
Authorization: AWS4-HMAC-SHA256 Credential=XXXXXXXXXXXXXXXXXX/20201023/eu-west-1/ec2/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date;x-amz-security-token, Signature=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
Content-Type: application/x-www-form-urlencoded; charset=utf-8
X-Amz-Date: 20201023T092849Z
X-Amz-Security-Token: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
Accept-Encoding: gzip
Action=DescribeInstances&Filter.1.Name=instance-state-name&Filter.1.Value.1=running&Filter.2.Name=tag%3AEnvironment&Filter.2.Value.1=test&Filter.3.Name=tag%3AServiceType&Filter.3.Value.1=cron&Version=2016-11-15
-----------------------------------------------------
2020/10/23 11:28:50 DEBUG: Response ec2/DescribeInstances Details:
---[ RESPONSE ]--------------------------------------
HTTP/1.1 200 OK
Transfer-Encoding: chunked
Content-Type: text/xml;charset=UTF-8
Date: Fri, 23 Oct 2020 09:28:49 GMT
Server: AmazonEC2
Vary: accept-encoding
X-Amzn-Requestid: 32631f6f-7c31-442e-8489-b6659fba9601
-----------------------------------------------------
2020/10/23 11:28:50 <?xml version="1.0" encoding="UTF-8"?>
<DescribeInstancesResponse xmlns="http://ec2.amazonaws.com/doc/2016-11-15/">
<requestId>32631f6f-7c31-442e-8489-b6659fba9601</requestId>
<reservationSet>
<item>
<reservationId>r-04bc33g3b153hb3e8</reservationId>
<ownerId>280215039121</ownerId>
<groupSet/>
<instancesSet>
<item>
<instanceId>i-07fe49beh29s7d406</instanceId>
<imageId>ami-0d3a49g55e266bee0</imageId>
<instanceState>
<code>16</code>
<name>running</name>
</instanceState>
```

## Resources

* [A tour of Go](https://tour.golang.org/list)
Expand Down
230 changes: 146 additions & 84 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Bitbull AWS Connect CLI

This project is CLI used to collect together repeatable commands and procedures into a single high-level command.
This project is CLI to simplify remote connection on AWS resources using System Manager service to remotely open session, tunnel and execute commands.

## Install CLI

Expand Down Expand Up @@ -30,24 +30,17 @@ Unlock CLI executable file going to "System Preference > Security and Privacy >

## Commands

Check more infos at [commands documentations](cmd/README.md)
- [ECS commands](cmd/ecs/README.md)
- [SSM commands](cmd/ssm/README.md)

## Running commands into different directories

You can execute command into a different directory changing CWD (current working directory) using `--root` flag:
```bash
bb-aws-connect --root ~/Projects/MyProjectA app build
bb-aws-connect --root ~/Projects/MyProjectB app build
```

## Configuration file
## Project configuration file

This CLI use some options to provide defaults to commands parameters.
By default CLI will search for `.bb-aws-connect.yml` file into current working directory (if not changed by `--root` flag).

You can override this behaviour using `--config` flag:
```
bb-aws-connect --config /etc/bb-aws-connect.yml app build
bb-aws-connect --config /etc/bb-aws-connect.yml ssm connect
```

An example of configuration file can be found into this project root `.bb-aws-connect.yml` file:
Expand All @@ -61,85 +54,154 @@ ssm:
user: root
```
## Wants to contribute?
Here a [contributing guide](CONTRIBUTING.md)
## Debug and troubleshooting
Is possible to enable some verbose logging in order to identify errors and issues.
## Infrastructure configurations
### Shell commands
### Tags on resources
If you want to see executed command (both in background and foreground) set `BB_AWS_CONNECT_COMMAND_DEBUG` environment variable with any value:
EC2 instances should have these tags to be able to filter them using `--env` and `--service` parameters:
```
export BB_AWS_CONNECT_COMMAND_DEBUG=yes
Environment: prod
ServiceType: frontend
```
then when you execute a command the CLI will print the full command parameters:
no particular value is required, can be customized depending on the use cases, for example:
```
bb-aws-connect ssm tunnel --host db.prod.internal --port 3306 --key /my/key/path --username ec2-user --local-port 3306

----------------------------------------
Executing command: aws ssm start-session --profile myprofile --region eu-west-1 --target i-0cd15458284749f64 --document-name AWS-StartPortForwardingSession --parameters portNumber=22,localPortNumber=59392
----------------------------------------

SSH tunnel to remote instance opened on local port: 59392
Tunnel to remote db.prod.internal:3306 is available on local port: 3306

----------------------------------------
Executing command: ssh -i /my/key/path -o StrictHostKeyChecking=no -p 59392 ec2-user@localhost -L 3306:db.prod.internal:3306 -T -q
----------------------------------------
Environment: stage
ServiceType: varnish
```
### AWS API requests
If you want to see AWS API executed set `BB_AWS_CONNECT_AWS_DEBUG` environment variable with any value:
```
export BB_AWS_CONNECT_AWS_DEBUG=yes
Environment: stage
ServiceType: cron
```
then when you execute a command the CLI will print the full command parameters:
these tags can be applied for a single instance or an AutoScalingGroup. Read more about tagging on [AWS documentation](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/Using_Tags.html)
### SystemManager agent
EC2 instances must have the SystemManager agent installed and connected, follow the [AWS documentation](https://docs.aws.amazon.com/systems-manager/latest/userguide/sysman-install-ssm-agent.html) and complete the steps.
### IAM permissions
IAM user that execute commands require the following permissions:
```json
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ec2:DescribeInstances"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"ecs:ListClusters",
"ecs:DescribeClusters",
"ecs:ListServices",
"ecs:DescribeServices",
"ecs:ListTasks",
"ecs:DescribeTasks",
"ecs:DescribeContainerInstances",
"ecs:DescribeTaskDefinition",
"ecs:DescribeTasks"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"ssm:ListCommandInvocations",
"ssm:ListDocuments",
"ssm:DescribeDocument"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"ssm:SendCommand"
],
"Resource": [
"arn:aws:ssm:*:*:document/*"
]
},
{
"Effect": "Allow",
"Action": [
"ssm:SendCommand",
"ssm:StartSession"
],
"Resource": [
"arn:aws:ec2:*:*:instance/*"
]
},
{
"Effect": "Allow",
"Action": [
"ssm:TerminateSession"
],
"Resource": [
"arn:aws:ssm:*:*:session/${aws:username}-*"
]
}
]
}
```

Is possible to restrict session access to instances based on tags:
```json
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ssm:SendCommand",
"ssm:StartSession"
],
"Resource": [
"arn:aws:ec2:*:*:instance/*"
],
"Condition": {
"StringLike": {
"ssm:resourceTag/ServiceType": [
"frontend",
"varnish",
"cron"
]
}
}
}
]
}
```
bb-aws-connect ssm connect -s cron -e test

---[ REQUEST POST-SIGN ]-----------------------------
POST / HTTP/1.1
Host: ec2.eu-west-1.amazonaws.com
User-Agent: aws-sdk-go/1.30.9 (go1.15.2; linux; amd64)
Content-Length: 210
Authorization: AWS4-HMAC-SHA256 Credential=XXXXXXXXXXXXXXXXXX/20201023/eu-west-1/ec2/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date;x-amz-security-token, Signature=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
Content-Type: application/x-www-form-urlencoded; charset=utf-8
X-Amz-Date: 20201023T092849Z
X-Amz-Security-Token: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
Accept-Encoding: gzip

Action=DescribeInstances&Filter.1.Name=instance-state-name&Filter.1.Value.1=running&Filter.2.Name=tag%3AEnvironment&Filter.2.Value.1=test&Filter.3.Name=tag%3AServiceType&Filter.3.Value.1=cron&Version=2016-11-15
-----------------------------------------------------
2020/10/23 11:28:50 DEBUG: Response ec2/DescribeInstances Details:
---[ RESPONSE ]--------------------------------------
HTTP/1.1 200 OK
Transfer-Encoding: chunked
Content-Type: text/xml;charset=UTF-8
Date: Fri, 23 Oct 2020 09:28:49 GMT
Server: AmazonEC2
Vary: accept-encoding
X-Amzn-Requestid: 32631f6f-7c31-442e-8489-b6659fba9601


-----------------------------------------------------
2020/10/23 11:28:50 <?xml version="1.0" encoding="UTF-8"?>
<DescribeInstancesResponse xmlns="http://ec2.amazonaws.com/doc/2016-11-15/">
<requestId>32631f6f-7c31-442e-8489-b6659fba9601</requestId>
<reservationSet>
<item>
<reservationId>r-04bc33g3b153hb3e8</reservationId>
<ownerId>280215039121</ownerId>
<groupSet/>
<instancesSet>
<item>
<instanceId>i-07fe49beh29s7d406</instanceId>
<imageId>ami-0d3a49g55e266bee0</imageId>
<instanceState>
<code>16</code>
<name>running</name>
</instanceState>
or only deny access to production instances:
```json
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Deny",
"Action": [
"ssm:StartSession"
],
"Resource": [
"arn:aws:ec2:*:*:instance/*"
],
"Condition": {
"StringLike": {
"ssm:resourceTag/Environment": [
"prod"
]
}
}
}
]
}
```

read more about this on [AWS documentation](https://docs.aws.amazon.com/systems-manager/latest/userguide/getting-started-restrict-access-examples.html)

## Wants to contribute?

Here the [contributing guide](CONTRIBUTING.md) with some additional tips for debug and local testing.
15 changes: 0 additions & 15 deletions cmd/README.md
View file

This file was deleted.

0 comments on commit 3276733

Please sign in to comment.