Skip to content

Commit

Permalink
V1 Documentation Updates (#40)
Browse files Browse the repository at this point in the history 
* Update ssm run documentation with v1 changes.

* Update ssm session readme with v1 changes.

* Update gifs for v1
  • Loading branch information
@ncatelli
ncatelli committed Sep 1, 2020
1 parent e65ae5e commit ed7c423
Show file tree
Hide file tree
Showing 9 changed files with 131 additions and 158 deletions.
2 changes: 1 addition & 1 deletion .github/CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -41,5 +41,5 @@ Dependencies are managed with `go mod` for local development and package release

Some special dependencies you may want to be aware of are:
* [gomux](https://github.com/disneystreaming/gomux) library for managing tmux sessions with `ssm-session`
* [go-ssm-helpers](https://github.com/disneystreaming/go-ssm-helpers) library for interacting with the AWS SSM API.
* [go-ssm-helpers](https://github.com/disneystreaming/go-ssm-helpers) library for interacting with the AWS SSM API. **for v0.\*.\* releases**
* [aws-session-manager-plugin](https://docs.aws.amazon.com/systems-manager/latest/userguide/session-manager-working-with-install-plugin.html) The `brew install` method will install the AWS Session Manager plugin but that code is not open sourced and your computer will pull the releases directly from AWS. Updates to the plugin should PR the [homebrew-tap](https://github.com/disneystreaming/homebrew-tap/blob/master/Formula/aws-session-manager-plugin.rb#L4) repository.
2 changes: 1 addition & 1 deletion README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

Helpers to manage you systems with [AWS Systems Manager](https://aws.amazon.com/systems-manager/) suite of management tools.

![](/img/ssm-helpers.gif)
![](img/ssm-helpers.gif)

## Tools in this repo

Expand Down
170 changes: 78 additions & 92 deletions cmd/ssm-run/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
# ssm-run
# ssm run

Run a command on a list of instances or based on instance tags.
Increase `-log-level` to see individual instances or command output.
Run multiple commands in the same shell context (e.g. `-c 'uptime;hostname'`) or a local script with `-f`.
Increase `--verbose` to see individual instances or command output.
Run multiple commands in the same shell context (e.g. `-c 'uptime;hostname'`).

![](../../img/ssm-run.gif)

Expand All @@ -12,7 +12,7 @@ Run multiple commands in the same shell context (e.g. `-c 'uptime;hostname'`) or

### basic usage

By default, `ssm-run` will attempt to search/connect for instances in your default AWS profile (specified in your ~/.aws/config, or via the `AWS_PROFILE` environment variable if set), and the default region linked to that profile (or the `AWS_REGION` environment variable, if set).
By default, `ssm run` will attempt to search/connect for instances in your default AWS profile (specified in your ~/.aws/config, or via the `AWS_PROFILE` environment variable if set), and the default region linked to that profile (or the `AWS_REGION` environment variable, if set).

The order of preference for profile/region settings is set as follows:

Expand All @@ -24,7 +24,7 @@ To use a specific profile and/or region, use the `-p (--profiles)` or `-r (--reg

e.g. `-p account1,account2 -r us-east-1,us-west-2`

Take careful note that if multiple regions *and* profiles are specified, `ssm-run` will attempt to run your commands across all the possible permutations.
Take careful note that if multiple regions *and* profiles are specified, `ssm run` will attempt to run your commands across all the possible permutations.

For example, using the flags `--profiles foo,bar,baz --regions us-east-1,us-west-2,eu-east-1` will target instances in each of the profile/region combinations:

Expand All @@ -40,42 +40,48 @@ If a region is not specified, you will receive the following warning, but execut
WARNING No AWS region setting found. Will default to the region linked to any profile in use.
```

The use of the `--limit` flag, if set, will result in your command being executed on the specified number of random instances returned for each profile/region combination. For example, if you set `--limit=10` on the account `foo` for regions `us-east-1` and `us-west-2`, your command would be executed on up to 20 total instances.

#### running command(s) on a single instance

```
> ./ssm-run -i i-12345 -c "uname -a"
INFO Command(s) to be executed: uname -a
INFO Fetched 1 instances for account [profile1] in [us-east-1].
INFO Instance ID Region Profile Status
INFO i-12345 us-east-1 profile1 Success
> ssm run -p 'profile1' -i i-12345 -c 'uname'
INFO Command(s) to be executed:
uname
INFO Started invocation f73f2225-8fb2-4e63-ba63-6e2af54b8659 for profile1 in us-east-1
INFO Instance ID Region Profile Status
INFO i-12345 us-east-1 profile1 Success
INFO Linux
INFO Execution results: 1 SUCCESS, 0 FAILED
```

Running multiple commands is easy; just separate your commands with semicolons (;). These commands will be executed in series, in the same console context (e.g., variables you set can be used between commands).

```
> ./ssm-run -i i-12345 -c "uname -a; hostname; ifconfig"
INFO Command(s) to be executed: uname -a, hostname, ifconfig
INFO Fetched 1 instances for account [profile1] in [us-east-1].
INFO Instance ID Region Profile Status
INFO i-12345 us-east-1 profile1 Success
INFO Execution results: 1 SUCCESS, 0 FAILED
> ssm run -p 'profile1' -i i-12345 -c 'uname;uname;uname'
INFO Command(s) to be executed:
uname
uname
uname
INFO Started invocation 73ee2f4c-fd54-4505-8ef7-1bb2baecd64f for profile1 in us-east-1
INFO Instance ID Region Profile Status
INFO i-12345 us-east-1 profile1 Success
INFO Linux
Linux
Linux
INFO Execution results: 1 SUCCESS, 0 FAILED
```

#### running command(s) on multiple instances

```
> ./ssm-run -i i-12345,i-67890 -c "uname -a"
INFO Command(s) to be executed: uname -a
INFO Fetched 2 instances for account [profile1] in [us-east-1].
INFO Instance ID Region Profile Status
INFO i-12345 us-east-1 profile1 Success
INFO i-67890 us-east-1 profile1 Success
> ssm run -p 'profile1' -i 'i-0879fe217fe11ad86,i-062aede5be23eef7a' -c 'uname -sm'
INFO Command(s) to be executed:
uname > /dev/null 2>&1
INFO Started invocation cda5592a-a099-4117-8863-32a88909eae6 for profile1 in us-east-1
INFO Instance ID Region Profile Status
INFO i-12345 us-east-1 profile1 Success
Linux
INFO i-23456 us-east-1 profile1 Success
Linux
INFO Execution results: 2 SUCCESS, 0 FAILED
```

Expand All @@ -84,100 +90,80 @@ INFO Execution results: 2 SUCCESS, 0 FAILED
By default, if no instance or filters are specified, `ssm-run` will target all instances in the current account + region.

```
> ./ssm-run -c "uname -a"
INFO Command(s) to be executed: uname -a
INFO Fetched 5 instances for account [profile1] in [us-east-1].
INFO Instance ID Region Profile Status
INFO i-054151b14a3cf1234 us-east-1 profile1 Success
INFO i-022572ac837c21234 us-east-1 profile1 Success
INFO i-08f4076ee1fa41234 us-east-1 profile1 Success
INFO i-0dfbe7c5db0b21234 us-east-1 profile1 Success
INFO i-064937fab1f211234 us-east-1 profile1 Success
INFO Execution results: 5 SUCCESS, 0 FAILED
> ssm run -p 'profile1' -c 'uname > /dev/null 2>&1'
INFO Command(s) to be executed:
uname > /dev/null 2>&1
INFO Started invocation a0fc81ce-a256-4b19-803f-8b24e453172d for profile1 in us-east-1
INFO Instance ID Region Profile Status
INFO i-12345 us-east-1 profile1 Success
INFO i-23456 us-east-1 profile1 Success
INFO i-34567 us-east-1 profile1 Success
INFO Execution results: 3 SUCCESS, 0 FAILED
```

#### searching for instances in multiple accounts and/or regions

```
> ./ssm-run -c "uname -a" -r us-east-1,us-west-2
INFO Command(s) to be executed: uname -a
INFO Fetched 5 instances for account [profile1] in [us-east-1].
INFO Fetched 1 instances for account [profile1] in [us-west-2].
> ssm run -p 'profile1' -c 'uname > /dev/null 2>&1' --region 'us-east-1,us-west-2'
INFO Command(s) to be executed:
uname > /dev/null 2>&1
INFO Started invocation b94eafc1-c9ab-4f9b-848e-c4e16beecee2 for profile1 in us-east-1
INFO Started invocation 83a0a57b-1127-4ff8-9fb9-136f040a05fd for profile1 in us-west-2
INFO Instance ID Region Profile Status
INFO i-054151b14a3cf1234 us-east-1 profile1 Success
INFO i-022572ac837c21234 us-east-1 profile1 Success
INFO i-08f4076ee1fa41234 us-east-1 profile1 Success
INFO i-0dfbe7c5db0b21234 us-east-1 profile1 Success
INFO i-064937fab1f211234 us-east-1 profile1 Success
INFO i-04a827989613b1234 us-west-2 profile1 Success
INFO Execution results: 6 SUCCESS, 0 FAILED
INFO i-12345 us-east-1 profile1 Success
INFO i-23456 us-west-2 profile1 Success
INFO Execution results: 2 SUCCESS, 0 FAILED
```

#### filtering instance results

Tag-based filtering can also be applied to your search results (including if you manually specify instance names). These filters are additive, which means that each filter you provide will prune down your results to include only instances that match *all* of the provided filters.

```
> ./ssm-run -c "uname -a" -p profile1 -f app=myapp -f env=prod
INFO Command(s) to be executed: uname -a
INFO Fetched 6 instances for account [profile1] in [us-east-1].
INFO Instance ID Region Profile Status
INFO i-ccdc371a us-east-1 profile1 Success
INFO i-9cdd364a us-east-1 profile1 Success
INFO i-7268418e us-east-1 profile1 Success
INFO i-1289eeef us-east-1 profile1 Success
INFO i-2f96f1d2 us-east-1 profile1 Success
INFO i-7b6f4687 us-east-1 profile1 Success
INFO Execution results: 6 SUCCESS, 0 FAILED
> ssm run -p 'profile1' -f 'app=myapp,env=prod' -c 'uname > /dev/null 2>&1' --region us-east-1
INFO Command(s) to be executed:
uname > /dev/null 2>&1
INFO Started invocation 1a781eaf-a6fc-4cf0-8875-5ecaace29e4f for profile1 in us-east-1
INFO Instance ID Region Profile Status
INFO i-12345 us-east-1 profile1 Success
INFO Execution results: 1 SUCCESS, 0 FAILED
```

### usage flags

```
-all-profiles
--all-profiles
[USE WITH CAUTION] Parse through ~/.aws/config to target all profiles.
-c value
--commands (shorthand)
-commands value
-c, --command string
Specify any number of commands to be run.
Multiple allowed, enclosed in double quotes and delimited by semicolons (e.g. --comands "hostname; uname -a")
-dry-run
Retrieve the list of profiles, regions, and instances your command(s) would target.
-f value
--filter (shorthand)
-file string
--dry-run
Retrieve the list of profiles, regions, and instances your command(s) would target
--file string
Specify the path to a shell script to use as input for the AWS-RunShellScript document.
This can be used in combination with the --commands/-c flag, and will be run after the specified commands.
-filter value
his can be used in combination with the --commands/-c flag, and will be run after the specified commands.
-f, --filter strings
Filter instances based on tag value. Tags are evaluated with logical AND (instances must match all tags).
Multiple allowed, delimited by commas (e.g. env=dev,foo=bar)
-i value
--instances (shorthand)
-instances value
-h, --help
help for run
-i, --instance strings
Specify what instance IDs you want to target.
Multiple allowed, delimited by commas (e.g. --instances i-12345,i-23456)
-limit int
Set a limit for the number of instance results returned per profile/region combination (0 = no limit)
-log-level int
Sets verbosity of output:
0 = quiet, 1 = terse, 2 = standard, 3 = debug (default 2)
-p value
--profiles (shorthand)
-profiles value
Multiple allowed, delimited by commas (e.g. --instance i-12345,i-23456)
--max-concurrency string
Max targets to run the command in parallel. Both numbers, such as 50, and percentages, such as 50%, are allowed (default "50")
--max-errors string
Max errors allowed before running on additional targets. Both numbers, such as 10, and percentages, such as 10%, are allowed (default "0")
-p, --profile strings
Specify a specific profile to use with your API calls.
Multiple allowed, delimited by commas (e.g. --profiles profile1,profile2)
-r value
--regions (shorthand)
-regions value
Multiple allowed, delimited by commas (e.g. --profile profile1,profile2)
-r, --region strings
Specify a specific region to use with your API calls.
This option will override any profile settings in your config file.
Multiple allowed, delimited by commas (e.g. --regions us-east-1,us-west-2)
Multiple allowed, delimited by commas (e.g. --region us-east-1,us-west-2)
[NOTE] Mixing --profiles and --regions will result in your command targeting every matching instance in the selected profiles and regions.
e.g., "--profiles foo,bar,baz --regions us-east-1,us-west-2,eu-east-1" will target instances in each of the profile/region combinations:
[NOTE] Mixing --profile and --region will result in your command targeting every matching instance in the selected profiles and regions.
e.g., "--profile foo,bar,baz --region us-east-1,us-west-2,eu-east-1" will target instances in each of the profile/region combinations:
"foo@us-east-1, foo@us-west-2, foo@eu-east-1"
"bar@us-east-1, bar@us-west-2, bar@eu-east-1"
"baz@us-east-1, baz@us-west-2, baz@eu-east-1"
Expand Down

0 comments on commit ed7c423

Please sign in to comment.