sonic-screwdriver 1.4.0 → 2.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/.circleci/bin/commit_docs.sh +26 -0
- data/.circleci/config.yml +70 -0
- data/.gitignore +1 -1
- data/.ruby-version +1 -0
- data/CHANGELOG.md +13 -2
- data/Gemfile +3 -3
- data/Gemfile.lock +43 -14
- data/Guardfile +17 -10
- data/LICENSE.txt +2 -2
- data/README.md +10 -10
- data/Rakefile +9 -2
- data/docs/_config.yml +3 -0
- data/docs/_docs/help.md +1 -1
- data/docs/_docs/install-bastion.md +5 -15
- data/docs/_docs/install.md +3 -3
- data/docs/_docs/settings.md +40 -56
- data/docs/_docs/tutorial-ecs-exec.md +16 -20
- data/docs/_docs/tutorial-ecs-sh.md +73 -0
- data/docs/_docs/tutorial-execute.md +93 -17
- data/docs/_docs/tutorial-ssh.md +13 -18
- data/docs/_docs/why-ec2-run-command.md +1 -1
- data/docs/_includes/commands.html +5 -5
- data/docs/_includes/content.html +5 -0
- data/docs/_includes/css/main.css +15 -9
- data/docs/_includes/css/sonic.css +7 -5
- data/docs/_includes/example.html +4 -4
- data/docs/_includes/reference.md +1 -0
- data/docs/_includes/subnav.html +2 -1
- data/docs/_reference/sonic-completion.md +44 -0
- data/docs/_reference/sonic-completion_script.md +25 -0
- data/docs/_reference/sonic-ecs-exec.md +30 -0
- data/docs/_reference/sonic-ecs-help.md +21 -0
- data/docs/_reference/sonic-ecs-sh.md +35 -0
- data/docs/_reference/sonic-ecs.md +25 -0
- data/docs/_reference/sonic-execute.md +84 -0
- data/docs/_reference/sonic-list.md +40 -0
- data/docs/_reference/sonic-ssh.md +86 -0
- data/docs/_reference/sonic-version.md +21 -0
- data/docs/img/tutorials/ec2-console-run-command.png +0 -0
- data/docs/quick-start.md +9 -10
- data/docs/reference.md +12 -0
- data/{bin → exe}/sonic +3 -3
- data/lib/bash_scripts/docker-exec.sh +1 -0
- data/lib/bash_scripts/docker-run.sh +8 -1
- data/lib/sonic.rb +10 -2
- data/lib/sonic/{aws_services.rb → aws_service.rb} +6 -1
- data/lib/sonic/base_command.rb +82 -0
- data/lib/sonic/cli.rb +37 -27
- data/lib/sonic/command.rb +8 -22
- data/lib/sonic/completer.rb +161 -0
- data/lib/sonic/completer/script.rb +6 -0
- data/lib/sonic/completer/script.sh +10 -0
- data/lib/sonic/core.rb +15 -0
- data/lib/sonic/default/settings.yml +6 -16
- data/lib/sonic/docker.rb +29 -1
- data/lib/sonic/ecs.rb +22 -0
- data/lib/sonic/execute.rb +153 -18
- data/lib/sonic/help.rb +9 -0
- data/lib/sonic/help/command/send.md +10 -0
- data/lib/sonic/help/completion.md +22 -0
- data/lib/sonic/help/completion_script.md +3 -0
- data/lib/sonic/help/ecs/exec.md +8 -0
- data/lib/sonic/help/ecs/sh.md +13 -0
- data/lib/sonic/help/execute.md +60 -0
- data/lib/sonic/help/list.md +17 -0
- data/lib/sonic/help/ssh.md +60 -0
- data/lib/sonic/list.rb +4 -1
- data/lib/sonic/setting.rb +47 -0
- data/lib/sonic/ssh.rb +41 -20
- data/lib/sonic/ssh/identifier_detector.rb +6 -2
- data/lib/sonic/version.rb +1 -1
- data/sonic.gemspec +14 -9
- data/spec/lib/cli_spec.rb +5 -10
- data/spec/lib/sonic/execute_spec.rb +0 -1
- data/spec/spec_helper.rb +18 -10
- metadata +115 -16
- data/docs/_docs/tutorial-ecs-run.md +0 -100
- data/lib/sonic/cli/help.rb +0 -152
- data/lib/sonic/settings.rb +0 -115
@@ -0,0 +1,84 @@
|
|
1
|
+
---
|
2
|
+
title: sonic execute
|
3
|
+
reference: true
|
4
|
+
---
|
5
|
+
|
6
|
+
## Usage
|
7
|
+
|
8
|
+
sonic execute [FILTER] [COMMAND]
|
9
|
+
|
10
|
+
## Description
|
11
|
+
|
12
|
+
Runs command across fleet of servers via AWS Run Command.
|
13
|
+
|
14
|
+
Run as a command across a list of servers. A filter must be provided. The filter can be a mix of instance ids and ec2 tags. This command can also take a path to a file. To specify a path to a file use file:// at the beginning of your file.
|
15
|
+
|
16
|
+
## Examples Summary
|
17
|
+
|
18
|
+
$ sonic execute hi-web-prod uptime
|
19
|
+
$ sonic execute hi-web-prod,hi-worker-prod,hi-clock-prod uptime
|
20
|
+
$ sonic execute i-030033c20c54bf149,i-030033c20c54bf150 uname -a
|
21
|
+
$ sonic execute i-030033c20c54bf149 file://hello.sh
|
22
|
+
|
23
|
+
You cannot mix instance ids and tag names in the filter.
|
24
|
+
|
25
|
+
## Example Detailed
|
26
|
+
|
27
|
+
Here's a command example output in detailed:
|
28
|
+
|
29
|
+
```sh
|
30
|
+
$ sonic execute i-0bf51a000ab4e73a8 uptime
|
31
|
+
Sending command to SSM with options:
|
32
|
+
---
|
33
|
+
instance_ids:
|
34
|
+
- i-0bf51a000ab4e73a8
|
35
|
+
document_name: AWS-RunShellScript
|
36
|
+
comment: sonic execute i-0bf51a000ab4e73a8 uptime
|
37
|
+
parameters:
|
38
|
+
commands:
|
39
|
+
- uptime
|
40
|
+
output_s3_region: us-east-1
|
41
|
+
output_s3_bucket_name: [reacted]
|
42
|
+
output_s3_key_prefix: ssm/commands/sonic
|
43
|
+
|
44
|
+
Command sent to AWS SSM. To check the details of the command:
|
45
|
+
aws ssm list-commands --command-id 0bb18d58-6436-49fd-9bfd-0c4b6c51c7a2
|
46
|
+
aws ssm get-command-invocation --command-id 0bb18d58-6436-49fd-9bfd-0c4b6c51c7a2 --instance-id i-0bf51a000ab4e73a8
|
47
|
+
|
48
|
+
Waiting for ssm command to finish.....
|
49
|
+
Command finished.
|
50
|
+
|
51
|
+
Displaying output for i-0bf51a000ab4e73a8.
|
52
|
+
Command status: Success
|
53
|
+
Command standard output:
|
54
|
+
01:08:10 up 8 days, 6:41, 0 users, load average: 0.00, 0.00, 0.00
|
55
|
+
|
56
|
+
To see the more output details visit:
|
57
|
+
https://us-west-2.console.aws.amazon.com/systems-manager/run-command/0bb18d58-6436-49fd-9bfd-0c4b6c51c7a2
|
58
|
+
|
59
|
+
Pro tip: the console url is already in your copy/paste clipboard.
|
60
|
+
$
|
61
|
+
```
|
62
|
+
|
63
|
+
Notice the conveniences of `sonic execute`, it:
|
64
|
+
|
65
|
+
1. Showed the parameters that will be sent as part of the send_command call to SSM.
|
66
|
+
2. Sent the command to SSM.
|
67
|
+
3. Waited for the command to finish.
|
68
|
+
4. Displayed the output of the command.
|
69
|
+
5. Provided the console url that visit to view more details about the SSM command.
|
70
|
+
|
71
|
+
The AWS SSM console looks like this:
|
72
|
+
|
73
|
+
<img src="/img/tutorials/ec2-console-run-command.png" class="doc-photo" />
|
74
|
+
|
75
|
+
|
76
|
+
## Options
|
77
|
+
|
78
|
+
```
|
79
|
+
[--zero-warn], [--no-zero-warn] # Warns user when no instances found
|
80
|
+
# Default: true
|
81
|
+
[--verbose], [--no-verbose]
|
82
|
+
[--noop], [--no-noop]
|
83
|
+
```
|
84
|
+
|
@@ -0,0 +1,40 @@
|
|
1
|
+
---
|
2
|
+
title: sonic list
|
3
|
+
reference: true
|
4
|
+
---
|
5
|
+
|
6
|
+
## Usage
|
7
|
+
|
8
|
+
sonic list [FILTER]
|
9
|
+
|
10
|
+
## Description
|
11
|
+
|
12
|
+
Lists ec2 instances.
|
13
|
+
|
14
|
+
List ec2 servers. A filter must be provided. The filter can be a mix of instance ids and ec2 tags. sonic list will auto-detect the what type of filter it is filter appropriately. The filter for listing is optional.
|
15
|
+
|
16
|
+
Examples:
|
17
|
+
|
18
|
+
$ sonic list
|
19
|
+
$ sonic list hi-web-prod
|
20
|
+
$ sonic list hi-web-prod,hi-clock-prod
|
21
|
+
$ sonic list i-09482b1a6e330fbf7
|
22
|
+
|
23
|
+
Example Output:
|
24
|
+
|
25
|
+
$ sonic list --header i-09482b1a6e330fbf7
|
26
|
+
Instance Id Public IP Private IP Type
|
27
|
+
i-09482b1a6e330fbf7 54.202.152.168 172.31.21.108 t2.small
|
28
|
+
$
|
29
|
+
|
30
|
+
You cannot mix instance ids and tag names in the filter.
|
31
|
+
|
32
|
+
|
33
|
+
## Options
|
34
|
+
|
35
|
+
```
|
36
|
+
[--header], [--no-header] # Displays header
|
37
|
+
[--verbose], [--no-verbose]
|
38
|
+
[--noop], [--no-noop]
|
39
|
+
```
|
40
|
+
|
@@ -0,0 +1,86 @@
|
|
1
|
+
---
|
2
|
+
title: sonic ssh
|
3
|
+
reference: true
|
4
|
+
---
|
5
|
+
|
6
|
+
## Usage
|
7
|
+
|
8
|
+
sonic ssh [IDENTIFER]
|
9
|
+
|
10
|
+
## Description
|
11
|
+
|
12
|
+
Ssh into a instance using identifier. identifer can be several things: instance id, ec2 tag, ECS service name, etc.
|
13
|
+
|
14
|
+
* EC2 instance id. Example: i-067c5e3f026c1e801
|
15
|
+
* EC2 tag value. Any tag value is search, the tag key does not matter only the tag value matters. Example: hi-web
|
16
|
+
* ECS service. Example: my-ecs-service
|
17
|
+
* ECS container instance id. Example: 7fbc8c75-4675-4d39-a5a4-0395ff8cd474
|
18
|
+
* ECS task id. Example: 1ed12abd-645c-4a05-9acf-739b9d790170
|
19
|
+
|
20
|
+
When using ecs identifiers the `--cluster` option is required or can be set in ~/.sonic/settings.yml.
|
21
|
+
|
22
|
+
Examples:
|
23
|
+
|
24
|
+
$ sonic ssh i-067c5e3f026c1e801
|
25
|
+
$ sonic ssh hi-web
|
26
|
+
$ sonic ssh --cluster my-cluster my-ecs-service
|
27
|
+
$ sonic ssh 7fbc8c75-4675-4d39-a5a4-0395ff8cd474
|
28
|
+
$ sonic ssh 1ed12abd-645c-4a05-9acf-739b9d790170
|
29
|
+
|
30
|
+
Sonic ssh builds up the ssh command and shells out to it. For example, the following commands:
|
31
|
+
|
32
|
+
sonic ssh i-027363802c6ff314f
|
33
|
+
|
34
|
+
Translates to:
|
35
|
+
|
36
|
+
ssh ec2-user@ec2-52-24-216-170.us-west-2.compute.amazonaws.com
|
37
|
+
|
38
|
+
You can also tack on any command to be run at the end of the command. Example:
|
39
|
+
|
40
|
+
$ sonic ssh i-027363802c6ff314f uptime
|
41
|
+
=> ssh ec2-user@ec2-52-24-216-170.us-west-2.compute.amazonaws.com uptime
|
42
|
+
15:57:02 up 18:21, 0 users, load average: 0.00, 0.01, 0.00
|
43
|
+
|
44
|
+
## Specifying pem keys
|
45
|
+
|
46
|
+
The recommended way to specify custom private keys is to use ssh-agent as covered here: https://blog.boltops.com/2017/09/21/3-ssh-tips-ssh-agent-tunnel-and-escaping-from-the-dead
|
47
|
+
|
48
|
+
But you can also specify the pem key to use with the -i option. Example:
|
49
|
+
|
50
|
+
$ sonic ssh -i ~/.ssh/id_rsa-custom ec2-user@ec2-52-24-216-170.us-west-2.compute.amazonaws.com
|
51
|
+
|
52
|
+
## Retry option
|
53
|
+
|
54
|
+
For newly launched instances, the instance's ssh access might not be quite ready. Typically, you must press up enter repeatedly until the instance is ready. Sonic ssh has a retry option that automates this. Example:
|
55
|
+
|
56
|
+
$ sonic ssh -r i-027363802c6ff314f
|
57
|
+
|
58
|
+
Bastion Host Support
|
59
|
+
|
60
|
+
Sonic ssh also supports a bastion host.
|
61
|
+
|
62
|
+
$ sonic ssh --bastion bastion.domain.com i-027363802c6ff314f
|
63
|
+
$ sonic ssh --bastion user@bastion.domain.com i-027363802c6ff314f
|
64
|
+
|
65
|
+
Here's what the output looks like:
|
66
|
+
|
67
|
+
$ sonic ssh --bastion 34.211.223.3 i-0f7f833131a51ce35 uptime
|
68
|
+
=> ssh -At ec2-user@34.211.223.3 ssh ec2-user@10.10.110.135 uptime
|
69
|
+
17:57:59 up 37 min, 0 users, load average: 0.00, 0.02, 0.00
|
70
|
+
Connection to 34.211.223.3 closed.
|
71
|
+
$
|
72
|
+
|
73
|
+
You can also set the bastion host and other options with a [settings file](http://sonic-screwdriver.cloud/docs/settings/).
|
74
|
+
|
75
|
+
|
76
|
+
## Options
|
77
|
+
|
78
|
+
```
|
79
|
+
-i, [--keys=KEYS] # comma separated list of ssh private key paths
|
80
|
+
-r, [--retry], [--no-retry] # keep retrying the server login until successful. Useful when on newly launched instances.
|
81
|
+
[--bastion=BASTION] # Bastion jump host to use. Defaults to no bastion server.
|
82
|
+
[--cluster=CLUSTER] # ECS Cluster to use. Default cluster is default
|
83
|
+
[--verbose], [--no-verbose]
|
84
|
+
[--noop], [--no-noop]
|
85
|
+
```
|
86
|
+
|
Binary file
|
data/docs/quick-start.md
CHANGED
@@ -15,26 +15,25 @@ gem install sonic-screwdriver
|
|
15
15
|
```sh
|
16
16
|
# ssh into an instance
|
17
17
|
sonic ssh i-0f7f833131a51ce35
|
18
|
-
sonic ssh hi-web
|
19
|
-
sonic ssh hi-web
|
20
|
-
sonic ssh
|
21
|
-
sonic ssh
|
22
|
-
sonic ssh 1ed12abd-645c-4a05-9acf-739b9d790170 --cluster stag # ECS task id
|
18
|
+
sonic ssh hi-web # ec2 tag
|
19
|
+
sonic ssh hi-web --cluster staging # ecs service name
|
20
|
+
sonic ssh 7fbc8c75-4675-4d39-a5a4-0395ff8cd474 --cluster staging # ECS container id
|
21
|
+
sonic ssh 1ed12abd-645c-4a05-9acf-739b9d790170 --cluster staging # ECS task id
|
23
22
|
|
24
23
|
# docker exec to a running ECS docker container
|
25
|
-
sonic ecs
|
24
|
+
sonic ecs exec hi-web
|
26
25
|
|
27
26
|
# docker run with same environment as the ECS docker running containers
|
28
|
-
sonic ecs
|
27
|
+
sonic ecs sh hi-web
|
29
28
|
|
30
29
|
# run command on 1 instance
|
31
30
|
sonic execute i-0f7f833131a51ce35 uptime
|
32
31
|
|
33
|
-
# run command on all instances tagged with hi-web
|
34
|
-
sonic execute hi-web
|
32
|
+
# run command on all instances tagged with hi-web and worker
|
33
|
+
sonic execute hi-web,hi-worker uptime
|
35
34
|
|
36
35
|
# list ec2 instances
|
37
|
-
sonic list hi-web
|
36
|
+
sonic list hi-web
|
38
37
|
```
|
39
38
|
|
40
39
|
Congratulations! You now know the basic sonic screwdriver commands now.
|
data/docs/reference.md
ADDED
@@ -0,0 +1,12 @@
|
|
1
|
+
---
|
2
|
+
title: CLI Reference
|
3
|
+
---
|
4
|
+
{% include reference.md %}
|
5
|
+
|
6
|
+
* [sonic completion]({% link _reference/sonic-completion.md %})
|
7
|
+
* [sonic completion_script]({% link _reference/sonic-completion_script.md %})
|
8
|
+
* [sonic ecs]({% link _reference/sonic-ecs.md %})
|
9
|
+
* [sonic execute]({% link _reference/sonic-execute.md %})
|
10
|
+
* [sonic list]({% link _reference/sonic-list.md %})
|
11
|
+
* [sonic ssh]({% link _reference/sonic-ssh.md %})
|
12
|
+
* [sonic version]({% link _reference/sonic-version.md %})
|
data/{bin → exe}/sonic
RENAMED
@@ -12,4 +12,11 @@ CONTAINER_IMAGE=$(cat /tmp/sonic/docker-image.txt)
|
|
12
12
|
cp /tmp/sonic/env-file.txt ~/
|
13
13
|
rm -rf /tmp/sonic
|
14
14
|
|
15
|
-
|
15
|
+
if [ $# -eq 0 ]; then
|
16
|
+
COMMAND=bash
|
17
|
+
else
|
18
|
+
COMMAND=$@
|
19
|
+
fi
|
20
|
+
|
21
|
+
set -x
|
22
|
+
exec docker run -ti --env-file ~/env-file.txt "$CONTAINER_IMAGE" $COMMAND
|
data/lib/sonic.rb
CHANGED
@@ -3,14 +3,22 @@ require "sonic/version"
|
|
3
3
|
require "colorize"
|
4
4
|
|
5
5
|
module Sonic
|
6
|
-
autoload :
|
6
|
+
autoload :Core, 'sonic/core'
|
7
|
+
autoload :Help, 'sonic/help'
|
8
|
+
autoload :AwsService, 'sonic/aws_service'
|
7
9
|
autoload :CLI, 'sonic/cli'
|
10
|
+
autoload :BaseCommand, 'sonic/base_command'
|
8
11
|
autoload :Command, 'sonic/command'
|
9
12
|
autoload :Docker, 'sonic/docker'
|
10
13
|
autoload :Execute, 'sonic/execute'
|
11
14
|
autoload :List, 'sonic/list'
|
12
|
-
autoload :
|
15
|
+
autoload :Setting, 'sonic/setting'
|
13
16
|
autoload :Ssh, 'sonic/ssh'
|
14
17
|
autoload :UI, 'sonic/ui'
|
15
18
|
autoload :Checks, 'sonic/checks'
|
19
|
+
autoload :Completion, "sonic/completion"
|
20
|
+
autoload :Completer, "sonic/completer"
|
21
|
+
autoload :Ecs, "sonic/ecs"
|
22
|
+
|
23
|
+
extend Core
|
16
24
|
end
|
@@ -1,9 +1,10 @@
|
|
1
1
|
require "aws-sdk-ec2"
|
2
2
|
require "aws-sdk-ecs"
|
3
3
|
require "aws-sdk-ssm"
|
4
|
+
require "aws-sdk-s3"
|
4
5
|
|
5
6
|
module Sonic
|
6
|
-
module
|
7
|
+
module AwsService
|
7
8
|
def ecs
|
8
9
|
@ecs ||= Aws::ECS::Client.new
|
9
10
|
end
|
@@ -19,5 +20,9 @@ module Sonic
|
|
19
20
|
def ssm
|
20
21
|
@ssm ||= Aws::SSM::Client.new
|
21
22
|
end
|
23
|
+
|
24
|
+
def s3
|
25
|
+
@s3 ||= Aws::S3::Client.new
|
26
|
+
end
|
22
27
|
end
|
23
28
|
end
|
@@ -0,0 +1,82 @@
|
|
1
|
+
require "thor"
|
2
|
+
|
3
|
+
# Override thor's long_desc identation behavior
|
4
|
+
# https://github.com/erikhuda/thor/issues/398
|
5
|
+
class Thor
|
6
|
+
module Shell
|
7
|
+
class Basic
|
8
|
+
def print_wrapped(message, options = {})
|
9
|
+
message = "\n#{message}" unless message[0] == "\n"
|
10
|
+
stdout.puts message
|
11
|
+
end
|
12
|
+
end
|
13
|
+
end
|
14
|
+
end
|
15
|
+
|
16
|
+
module Sonic
|
17
|
+
class BaseCommand < Thor
|
18
|
+
class << self
|
19
|
+
def dispatch(m, args, options, config)
|
20
|
+
# Allow calling for help via:
|
21
|
+
# sonic command help
|
22
|
+
# sonic command -h
|
23
|
+
# sonic command --help
|
24
|
+
# sonic command -D
|
25
|
+
#
|
26
|
+
# as well thor's normal way:
|
27
|
+
#
|
28
|
+
# sonic help command
|
29
|
+
help_flags = Thor::HELP_MAPPINGS + ["help"]
|
30
|
+
if args.length > 1 && !(args & help_flags).empty?
|
31
|
+
args -= help_flags
|
32
|
+
args.insert(-2, "help")
|
33
|
+
end
|
34
|
+
|
35
|
+
# sonic version
|
36
|
+
# sonic --version
|
37
|
+
# sonic -v
|
38
|
+
version_flags = ["--version", "-v"]
|
39
|
+
if args.length == 1 && !(args & version_flags).empty?
|
40
|
+
args = ["version"]
|
41
|
+
end
|
42
|
+
|
43
|
+
super
|
44
|
+
end
|
45
|
+
|
46
|
+
# Override command_help to include the description at the top of the
|
47
|
+
# long_description.
|
48
|
+
def command_help(shell, command_name)
|
49
|
+
meth = normalize_command_name(command_name)
|
50
|
+
command = all_commands[meth]
|
51
|
+
alter_command_description(command)
|
52
|
+
super
|
53
|
+
end
|
54
|
+
|
55
|
+
def alter_command_description(command)
|
56
|
+
return unless command
|
57
|
+
|
58
|
+
# Add description to beginning of long_description
|
59
|
+
long_desc = if command.long_description
|
60
|
+
"#{command.description}\n\n#{command.long_description}"
|
61
|
+
else
|
62
|
+
command.description
|
63
|
+
end
|
64
|
+
|
65
|
+
# add reference url to end of the long_description
|
66
|
+
unless website.empty?
|
67
|
+
full_command = [command.ancestor_name, command.name].compact.join('-')
|
68
|
+
url = "#{website}/reference/sonic-#{full_command}"
|
69
|
+
long_desc += "\n\nHelp also available at: #{url}"
|
70
|
+
end
|
71
|
+
|
72
|
+
command.long_description = long_desc
|
73
|
+
end
|
74
|
+
private :alter_command_description
|
75
|
+
|
76
|
+
# meant to be overriden
|
77
|
+
def website
|
78
|
+
"http://sonic-screwdriver.cloud"
|
79
|
+
end
|
80
|
+
end
|
81
|
+
end
|
82
|
+
end
|