sonic-screwdriver 1.1.0 → 1.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 4e57a38964860cd1bb9eda130089260cb75aeca6
-  data.tar.gz: 40339059f215ef4b643cb7d16d2f3da251808554
+  metadata.gz: 9fcf3cedf767fb24e46f926676e90e6665a16b7e
+  data.tar.gz: 61a4e4f685b0ebff993ade25c55d0c790f440d2a
 SHA512:
-  metadata.gz: e3aa5c463b9e60841adc238db79d1cdd45ee41ff1a0bbb9b74c241534e5c63e9a8151fd39375b889a568805480327dc28cc964c18a1e4f66c51398ec60a3b925
-  data.tar.gz: 7fd9256e2820fed70aa533cc558cc2d7131eeb49de76d7d71120297207c3ce1ed61ef1e2fc4d5a3e39cbc0d3ba81db2bcfbaa02bb35684b93b373f6935ca3138
+  metadata.gz: 70c990f11c3d1bd7f6ddf3d2ed1d2f4156c7dde78601e3964d28e73fe9eff41f0f70d5280910793d9250e78eefef16a46d39e1f544d64d3b1a8d0bd913e480df
+  data.tar.gz: 896df9f8754358469a65376534b564950314e751a3a1c21634c30d0e640f789a295854d46233fd661e2b54735b8a939cfd341772deccfea0e66022f2c4c9a6b9

data/CHANGELOG.md

@@ -3,6 +3,9 @@
 All notable changes to this project will be documented in this file.
 This project *tries* to adhere to [Semantic Versioning](http://semver.org/), even before v1.0.
 
+## [1.1.1]
+- update docs and help
+
 ## [1.1.0]
 - standardize filter to be first argument
 

data/README.md

@@ -1,7 +1,11 @@
 # Sonic
 
+[![CircleCI](https://circleci.com/gh/boltopslabs/sonic.svg?style=svg)](https://circleci.com/gh/boltopslabs/sonic)
+
 Sonic is a multi-functional tool that helps you manage AWS resources. Sonic contains is a group of commands that help debug EC2 instances and ECS containers quickly.
 
+See [sonic-screwdriver.cloud](http://sonic-screwdriver.cloud) for full documentation.
+
 ## Why Sonic Was Created
 
 After I exhaust debugging an ECS service with CloudWatch Logs I usually take it to the next step: ssh into the instance. I jump into an instance with a running task or docker container and poke around to figure out the root issue.
@@ -24,149 +28,44 @@ By the time I get into the container, I need to remind my brain on what the orig
 
 ## Install
 
-### Install Via RubyGems
-
-```
-gem install sonic-screwdriver
-```
-
-Set up your AWS credentials at `~/.aws/credentials` and `~/.aws/config`.  This is the [AWS standard way of setting up credentials](https://aws.amazon.com/blogs/security/a-new-and-standardized-way-to-manage-credentials-in-the-aws-sdks/).
-
-Note that the gem is named `sonic-screwdriver` but the command is `sonic`.
-
-## Requirements
-
-* [jq](https://stedolan.github.io/jq/manual/) - a lightweight and flexible command-line JSON processor
-
-If you are also using the `ecs-exec` and `ecs-run` commands, then you will need to ensure that [jq](https://stedolan.github.io/jq/) is installed on all of your ECS container instances.  If you are only using the `sonic ssh` command then you do not need the jq dependency.
-
-## Usage
-
-### sonic ssh
-
-To ssh into the host or container instance where an ECS service called `my-service` is running, simply run:
-
-```
-$ sonic ssh my-service --cluster my-cluster
-# now you are on the container instance
-$ docker ps
-$ curl -s http://localhost:51678/v1/meta | jq .
-```
-
-The `my-service` can possible run on multiple container instances.  The `sonic` command chooses the first container instance that it finds.  If you need to ssh into a specific container instance, use `sonic ssh` instead.
-
-You can also use the instance id, container instance arn or task arn to ssh into the machine.  Examples:
-
-```
-$ sonic ssh my-ecs-service --cluster my-cluster # cluster is required or ~/.sonic/settings.yml
-$ sonic ssh i-067c5e3f026c1e801
-$ sonic ssh 7fbc8c75-4675-4d39-a5a4-0395ff8cd474
-$ sonic ssh 1ed12abd-645c-4a05-9acf-739b9d790170
-```
-
-### sonic ecs-exec
-
-`sonic ecs-exec` will hop one more level and get you all the way into a live container for a service.  To quickly get yourself into a docker exec bash shell for a service:
-
-```
-$ sonic ecs-exec SERVICE bash
-$ sonic ecs-exec SERVICE # same as above, defaults to bash shell
-```
-
-This ultimately runs the following command after it ssh into the container instance:
-
-```
-$ docker run -ti SERVICE_CONTAINER bash
-```
-
-Here are examples to show what is possible:
-
-```
-$ sonic ecs-exec my-service bash
-# You're in the docker container now
-$ ls # check out some files to make sure you're the right place
-$ ps auxxx | grep puma # is the web process up?
-$ env # are the environment variables properly set?
-$ bundle exec rails c # start up a rails console to debug
-```
-
-You can also pass in bundle exec rails console if you want to get to that as quickly as possible.
-
-```
-$ sonic ecs-exec my-service 'bundle exec rails console'
-# You're a rails console in the docker container now
-> User.count
-```
-
-You must put commands with spaces in quotes.
-
-You can also use the container instance id or instance id in place of the service name:
-
-```
-$ sonic ecs-exec 9f1dadc7-4f67-41da-abec-ec08810bfbc9 bash
-$ i-006a097bb10643e20
-```
-
-### sonic ecs-run
-
-The `sonic ecs-run` command is similar to the `sonic ecs-exec` command except it'll run a brand new container with the same environment variables as the task associated with the service. This allows you to debug in a container with the exact environment variables as the running tasks/containers without affecting the live service. So this is safer since you will not be able to mess up a live container that is in service.
-
-This also allows you to run one off commands like a rake task. Here's an example:
+If you want to quickly install sonic without having to worry about sonic's dependencies you can simply install the Bolts Toolbelt which has sonic included.
 
-```
-sonic ecs-run my-service bundle exec 'rake do:something'
+```sh
+brew cask install boltopslabs/software/bolts
 ```
 
-The default command opens up a bash shell.
+Or if you prefer you can install ufo with RubyGems
 
-```
-sonic ecs-run my-service # start a bash shell
-sonic ecs-run my-service bash # same thing
+```sh
+gem install ufo
 ```
 
-## Settings
+Full installation instructions are at [Install Sonic Screwdriver](http://localhost:4000/docs/install/).  There are some server side dependencies for some of the sonic commands so it is important to read through the full installation guide.
 
-A `~/.sonic/settings.yml` file is useful to adjust the behavior of sonic. One of the useful options is the `service_clsuter`.  This optoin maps services to clusters.  This saves you from  typing the `--cluster` option every time.  Here is an example `~/.sonic/settings.yml`:
+## Quick Start
 
-```yaml
-service_cluster:
-  default: my-default-cluster
-  hi-web-prod: prod
-  hi-clock-prod: prod
-  hi-worker-prod: prod
-  hi-web-stag: stag
-  hi-clock-stag: stag
-  hi-worker-stag: stag
-```
+Here is a quick overview of sonic abilities:
 
-This results in shorter commands:
+```sh
+# ssh into an instance
+sonic ssh i-0f7f833131a51ce35
+sonic ssh hi-web-stag
 
-```
-sonic ssh hi-web-prod
-sonic ssh hi-clock-prod
-sonic ssh hi-worker-stag
-```
+# docker exec to a running ECS docker container
+sonic ecs-exec hi-web-stag
 
-Instead of what you normally would have to type:
+# docker run with same environment as the ECS docker running containers
+sonic ecs-run hi-web-stag
 
-```
-sonic ssh hi-web-prod --cluster prod
-sonic ssh hi-clock-prod --cluster prod
-sonic ssh hi-worker-stag --cluster stag
-```
+# run command on 1 instance
+sonic execute i-0f7f833131a51ce35 uptime
 
-## Help and CLI Options
+# run command on all instances tagged with hi-web-stag and worker
+sonic execute hi-web-stag,hi-worker-stag uptime
 
+# list ec2 instances
+sonic list hi-web-stag
 ```
-sonic help
-sonic help ssh
-sonic help ecs-exec
-sonic help ecs-run
-```
-
-## Internals
-
-If are interested in the internal logic to achieve what the sonic commands it is detailed on the [wiki](https://github.com/boltopslabs/sonic/wiki).
 
 ## Contributing
 

data/docs/_docs/install.md

@@ -26,7 +26,7 @@ Or you can add sonic to your Gemfile in your project if you are working with a r
 gem "sonic-screwdriver"
 ```
 
-### Additional Server Side Dependencies
+### Server Side Dependencies
 
 #### sonic ecs-* dependencies
 

data/docs/_docs/tutorial-ecs-exec.md

@@ -4,7 +4,7 @@ title: ECS Exec
 
 In the previous section we showed you how to use `sonic ssh` to quickly ssh into an instance.  Some of the identifiers used were ECS identifiers.  As you can see sonic is ECS smart.
 
-One of the additional things `sonic` can do is go from your local machine, ssh into an EC2 Container Instance, find the running docker instance and jump into the docker container via `docker exec`.
+One of the additional things `sonic` can do is hop one more level and get you all the way to the running docker container via `docker exec`.
 
 It does this with a variety of scripts and trickery and is covered in [How It Works]({% link _docs/how-it-works.md %}).  Let's go through examples of how sonic can help you get into an running ECS docker container quickly.
 
@@ -31,7 +31,35 @@ Warning: Permanently added '34.211.195.71' (ECDSA) to the list of known hosts.
 root@fc4035f90bdc:/app#
 ```
 
-What you see in the last line above is a bash prompt because you are in a bash shell within the docker container!  With one command you have placed yourself into the running container 🎉
+What you see in the last line above is a bash prompt because you are in a bash shell within the docker container!  Ultimately sonic runs runs a `docker exec -ti ECS_SERVICE_CONTAINER bash` after ssh-ing into the instance.  With one command you have placed yourself into the running container 🎉
+
+Here are examples to show what is possible:
+
+```
+$ sonic ecs-exec hi-web-stag bash
+# You're in the docker container now
+$ ls # check out some files to make sure you're the right place
+$ ps auxxx | grep puma # is the web process up?
+$ env # are the environment variables properly set?
+$ bundle exec rails c # start up a rails console to debug
+```
+
+You can also pass in bundle exec rails console if you want to get to that as quickly as possible.
+
+```
+$ sonic ecs-exec hi-web-stag bundle exec rails console
+# You're a rails console in the docker container now
+> User.count
+```
+
+You can also use the container instance id or instance id in place of the service name:
+
+```
+sonic ecs-exec 9f1dadc7-4f67-41da-abec-ec08810bfbc9 bash
+sonic ecs-exec i-006a097bb10643e20 bash
+```
+
+### Settings - service_cluster
 
 As mentioned in the [previous section]({% link _docs/tutorial-ssh.md %}) and also in the [Settings documentation]({% link _docs/settings.md %}) you can configure a `~/.sonic/settings.yml` file which shortens the command further.  Let's add this to your settings:
 

data/docs/_docs/tutorial-ecs-run.md

@@ -6,7 +6,7 @@ The nice thing about the previous `ecs-exec` command we covered is that it allow
 
 ### sonic ecs-run
 
-Sonic provides a `sonic ecs-run` command that allows you to start up a new container with the same environment as one of the running containers. Here's an example:
+The `sonic ecs-run` command is similar to the `sonic ecs-exec` command except it'll run a brand new container with the same environment variables as the task associated with the service. This allows you to debug in a container with the exact environment variables as the running tasks/containers without affecting the live service. So this is safer since you will not be able to mess up a live container that is in service.  Here's an example:
 
 ```sh
 sonic ecs-run hi-web-stag

data/docs/_docs/tutorial-execute.md

@@ -18,7 +18,7 @@ sonic execute hi-web-stag yum install -y curl
 
 The output of the command will show a useful `aws ssm list-commands` command to get status of the requested command.
 
-```
+```sh
 $ sonic execute hi-web-stag uptime
 Command sent to AWS SSM. To check the details of the command:
 aws ssm list-commands --command-id 4133e5eb-aa18-40dd-be25-a176eb15e515
@@ -30,6 +30,12 @@ The output of the commands ran are also showed in the EC2 Run Command Console.
 
 <img src="/img/tutorials/ec2-console-run-command.png" class="doc-photo" />
 
+You can execute a command with a list of filters seprated by commas. For example, this will run the uptime command on any server with a tag value of hi-web-stag,hi-clock-stag, or hi-worker-stag.
+
+```sh
+sonic execute hi-web-stag,hi-clock-stag,hi-worker-stag uptime
+```
+
 ### Run Scripts
 
 Sometimes you might want to run more than just a one-liner command. If you need to run a full script, you can provide the file path to the script by designating it with `file://`.  For example, here's a file called `hi.sh`:

data/docs/_docs/tutorial-ssh.md

@@ -46,6 +46,8 @@ user: ec2-user
 
 More information about sonic settings in available in the docs: [Settings]({% link _docs/settings.md %}).
 
+### Different Identifiers
+
 The `sonic ssh` command can auto-detect the proper ip address with a variety of different identifiers.  It is not just limited to the instance id. This is convenient in case you happen to be on a dashboard with another identifer close by and handy.  Here are examples of other identifiers that `sonic ssh` understands.
 
 ```
@@ -68,10 +70,9 @@ service_cluster:
   hi-worker-stag: stag
 ```
 
-With these settings in place, the commands get shorten to become:
+With these settings in place, the ECS identifier commands get shorten to become:
 
 ```sh
-sonic ssh EC2_TAG_VALUE
 sonic ssh ECS_CONTAINER_ID
 sonic ssh ECS_SERVICE
 sonic ssh ECS_TASK_ID
@@ -80,7 +81,19 @@ sonic ssh ECS_TASK_ID
 It then becomes very easy to ssh into an EC2 Container Instance with the ECS service name.  For example if the ECS service name is `hi-web-stag` then the command becomes.
 
 ```sh
-sonic ssh hi-web-stag
+$ sonic ssh hi-web-stag
+# now you are on the container instance
+$ docker ps
+$ curl -s http://localhost:51678/v1/meta | jq .
+```
+
+The `hi-web-stag` can possibly be running on multiple container instances.  The `sonic` command chooses the first container instance that it finds.  If you need to ssh into a specific container instance, use `sonic ssh` instead.
+
+You can also use the ECS container instance arn or task id to ssh into the machine.  Examples:
+
+```
+$ sonic ssh 7fbc8c75-4675-4d39-a5a4-0395ff8cd474 # ECS container id
+$ sonic ssh 1ed12abd-645c-4a05-9acf-739b9d790170 # ECS task id
 ```
 
 ### Bastion Host

data/lib/sonic/cli/help.rb

@@ -28,7 +28,7 @@ Examples:
 
 $ sonic ssh i-067c5e3f026c1e801
 $ sonic ssh hi-web-prod
-$ sonic ssh my-ecs-service --cluster my-cluster # cluster is required or ~/.sonic/settings.yml
+$ sonic ssh --cluster my-cluster my-ecs-service # cluster is required or ~/.sonic/settings.yml
 $ sonic ssh 7fbc8c75-4675-4d39-a5a4-0395ff8cd474
 $ sonic ssh 1ed12abd-645c-4a05-9acf-739b9d790170
 
@@ -50,8 +50,8 @@ Bastion Host Support
 
 Sonic ssh also supports a bastion host.
 
-$ sonic ssh i-027363802c6ff314f --bastion bastion.domain.com
-$ sonic ssh i-027363802c6ff314f --bastion user@bastion.domain.com
+$ sonic ssh --bastion bastion.domain.com i-027363802c6ff314f
+$ sonic ssh --bastion user@bastion.domain.com i-027363802c6ff314f
 
 Here's what the output looks like:
 
@@ -81,8 +81,8 @@ environment and image as the specified running service.
 
 Examples:
 
-$ sonic ecs-run my-service --cluster my-cluster
-$ sonic ecs-run my-service --cluster my-cluster
+$ sonic ecs-run --cluster my-cluster my-service
+$ sonic ecs-run --cluster my-cluster my-service
 
 # If there are flags in the command that you want to pass down to the docker
 run command you will need to put the command in single quotes.  This is due to
@@ -120,7 +120,7 @@ $ sonic list i-09482b1a6e330fbf7
 
 Example Output:
 
-$ sonic list i-09482b1a6e330fbf7 --header
+$ sonic list --header i-09482b1a6e330fbf7
 Instance Id Public IP Private IP  Type
 i-09482b1a6e330fbf7 54.202.152.168  172.31.21.108 t2.small
 $

data/lib/sonic/ssh.rb

@@ -42,6 +42,8 @@ module Sonic
     end
 
     def build_ssh_host
+      return @identifier if ENV['TEST']
+
       detector = Ssh::IdentifierDetector.new(@cluster, @service, @identifier, @options)
       instance_id = detector.detect!
       instance_hostname(instance_id)

data/lib/sonic/version.rb

@@ -1,3 +1,3 @@
 module Sonic
-  VERSION = "1.1.0"
+  VERSION = "1.1.1"
 end

data/spec/lib/cli_spec.rb

@@ -12,7 +12,7 @@ describe Sonic::CLI do
 
   describe "sonic" do
     it "ssh should print out ssh command to be ran" do
-      out = execute("bin/sonic ssh my-service #{@args} --cluster default")
+      out = execute("bin/sonic ssh #{@args} --cluster default my-service")
       expect(out).to include("=> ssh")
     end
 
@@ -22,8 +22,8 @@ describe Sonic::CLI do
     end
 
     it "list should list running instances" do
-      out = execute("bin/sonic list #{@args} 1,2,3 --header")
-      expect(out).to include("Instance Id")
+      out = execute("bin/sonic list #{@args} --header 1,2,3")
+      expect(out).to include("No instances found")
     end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: sonic-screwdriver
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.1.1
 platform: ruby
 authors:
 - Tung Nguyen
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-06-21 00:00:00.000000000 Z
+date: 2017-06-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: thor