sonic-screwdriver 1.4.0 → 2.0.0

data/docs/_docs/tutorial-ssh.md

@@ -2,8 +2,6 @@
 title: SSH
 ---
 
-### SSH
-
 Sonic allows you to ssh into an instance quickly.
 
 Often when working with AWS EC2 it is helpful to ssh into an instance to debug.  To ssh into an instance, the first thing you do is go to the EC2 Console and grab the public IP address.
@@ -32,7 +30,7 @@ The above command effectively translates to:
 ssh ec2-user@52.24.216.170
 ```
 
-By default the user that sonic uses to log in to the server is `ec2-user`. You can override the user easily like so:
+By default the user that sonic uses to log in to the server is `ec2-user`. You can override the user as part of the sonic command like so:
 
 ```sh
 sonic ssh ubuntu@i-0f7f833131a51ce35
@@ -48,15 +46,15 @@ More information about sonic settings in available in the docs: [Settings]({% li
 
 ### Polymorphic Identifiers
 
-The `sonic ssh` command can auto-detect the proper IP address with a variety of different identifiers.  The identifier is not just limited to the instance id. The identifier can also be an EC2 tag-value filter, ECS service name, ECS container id or ECS task id.
+The `sonic ssh` command can auto-detect the proper IP address with a variety of different identifiers.  The identifier is not limited to the instance id. The identifier can be an EC2 tag-value filter, ECS service name, ECS container id or ECS task id.
 
 Polymorphic identifiers are convenient in case you happen to be on a dashboard with another identifier close by and handy.  Here are examples of identifiers that `sonic ssh` understands.
 
 ```
 sonic ssh EC2_TAG_FILTER
-sonic ssh ECS_SERVICE --cluster stag
-sonic ssh ECS_CONTAINER_ID --cluster stag
-sonic ssh ECS_TASK_ID --cluster stag
+sonic ssh ECS_SERVICE --cluster staging
+sonic ssh ECS_CONTAINER_ID --cluster staging
+sonic ssh ECS_TASK_ID --cluster staging
 ```
 
 The EC2 tag filter uses the 'tag-value' filter as described in the [AWS describe-instances](http://docs.aws.amazon.com/cli/latest/reference/ec2/describe-instances.html) filter docs. This filter is independent of the tag-key filter, which means any EC2 tag value will match, regardless of the tag key name.  Sonic does not support spaces in the EC2 tag filter.
@@ -64,14 +62,11 @@ The EC2 tag filter uses the 'tag-value' filter as described in the [AWS describe
 Notice, that when the `sonic ssh` is passed an ECS identifier then it also requires the ECS cluster name. The commands above with the ECS identifier are normally shorten further by configuring the a [settings]({% link _docs/settings.md %}) file.  Here's an example:
 
 ```yaml
-service_cluster:
+ecs_service_cluster_map:
   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
+  hi-web: production
+  hi-clock: production
+  hi-worker: production
 ```
 
 With these settings in place, the ECS identifier commands get shortened to become:
@@ -82,16 +77,16 @@ sonic ssh ECS_SERVICE
 sonic ssh ECS_TASK_ID
 ```
 
-It then becomes effortless 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.
+It then becomes effortless to ssh into an EC2 Container Instance with the ECS service name.  For example, if the ECS service name is `hi-web` then the command becomes.
 
 ```sh
-$ sonic ssh hi-web-stag
+$ sonic ssh hi-web
 # now you are on the container instance
 $ docker ps
 $ curl -s http://localhost:51678/v1/meta | jq .
 ```
 
-The `hi-web-stag` can be running on multiple container instances.  The `sonic ssh` command chooses the first container instance that it finds.  If you need to ssh into a specific container instance, then use the `sonic ssh` command with an instance id instead.
+The `hi-web` can be running on multiple container instances.  The `sonic ssh` command chooses the first container instance that it finds.  If you need to ssh into a specific container instance, then use the `sonic ssh` command with an instance id instead.
 
 You can also use the ECS container instance arn or task id to ssh into the machine.  Examples:
 
@@ -120,7 +115,7 @@ Can't ssh into the server yet.  Retrying until success.
 
 ### Specifying Custom Pem or Private Keys
 
-It is recommended that you use ssh-agent to specify a custom private key, covered here [3 SSH tips: Ssh-agent, Tunnel, and Escaping from the Dead](https://blog.boltops.com/2017/09/21/3-ssh-tips-ssh-agent-tunnel-and-escaping-from-the-dead).  You can specify the private key if you prefer with the `-i` option though.  Example:
+It is recommended that you use ssh-agent to specify a custom private key, covered here [3 SSH tips: Ssh-agent, Tunnel, and Escaping from the Dead](https://blog.boltops.com/2017/09/21/3-ssh-tips-ssh-agent-tunnel-and-escaping-from-the-dead).  But you can specify the private key if you prefer with the `-i` option though.  Example:
 
 ```sh
 $ sonic ssh -i ~/.ssh/id_rsa-custom i-0b21da68fff89937b

data/docs/_docs/why-ec2-run-command.md

@@ -9,7 +9,7 @@ Why use Amazon EC2 Run Command vs just using a multi-ssh session?
 * The EC2 Run Manager has the ability to run the command in "blue/green" fashion with concurrency controls. Say you have 100 servers, you can tell EC2 Run Manager to run the command on one server first and the expodentially roll it out to the rest of the servers until the command has successfully ran on all servers.  If it the command errors on one server then it halts execution and does not run on the rest of the servers.
 * This is all provided for free by using EC2 Run Manager.
 
-The iniitial ertia of setting up EC2 Run Manager is actually very little.  The [installation instructions]({% link _docs/install.md %}) demonstrate that installing EC2 Run Manager is literally one command.
+The initial ertia of setting up EC2 Run Manager is actually very little.  The [installation instructions]({% link _docs/install.md %}) demonstrate that installing EC2 Run Manager is literally one command.
 
 <a id="prev" class="btn btn-basic" href="{% link _docs/why.md %}">Back</a>
 <a id="next" class="btn btn-primary" href="{% link _docs/how-it-works.md %}">Next Step</a>

data/docs/_includes/commands.html

@@ -11,15 +11,15 @@
                 <div class="col-lg-8 col-lg-offset-2">
                     <div class="commands">
 {% highlight sh %}
-sonic ssh
+sonic ssh # ssh onto instance
 
-sonic ecs-run
+sonic ecs sh # docker run on ECS
 
-sonic ecs-exec
+sonic ecs exec # docker exec on ECS
 
-sonic list
+sonic list # list servers
 
-sonic execute
+sonic execute # run command with SSM
 {% endhighlight %}
                     </div>
                 </div>

data/docs/_includes/content.html

@@ -8,6 +8,11 @@
     <section id="main">
         <div class="container">
             <div class="row">
+                {% if page.reference %}
+                <div class="col-md-9 reference-nav">
+                    <a href="/reference">Back to Reference Index</a>
+                </div>
+                {% endif %}
                 <div class="col-md-9 content-body">
                     <h2>{{ page.title }}</h2>
                     {{ content }}

data/docs/_includes/css/main.css

@@ -9,11 +9,13 @@ body {
 }
 
 p {
-    font-size: 20px;
+    /*font-size: 20px;*/
+    font-size: 1.2em;
 }
 
 p.small {
-    font-size: 16px;
+    font-size: 1em;
+    /*font-size: 16px;*/
 }
 
 a,
@@ -31,16 +33,21 @@ h3,
 h4,
 h5,
 h6 {
-    text-transform: uppercase;
     font-family: Montserrat,"Helvetica Neue",Helvetica,Arial,sans-serif;
     font-weight: 700;
 }
 
-h3,
-h4,
-h5,
-h6 {
-    text-transform: none;
+h1 {
+    font-size: 1.6em;
+}
+h2 {
+    font-size: 1.5em;
+}
+h3 {
+    font-size: 1.4em;
+}
+h4 {
+    font-size: 1.3em;
 }
 
 hr.star-light,
@@ -201,7 +208,6 @@ section {
 section h2 {
     margin: 0;
     margin-bottom: 15px;
-    font-size: 2em;
 }
 
 section.success {

data/docs/_includes/css/sonic.css

@@ -28,7 +28,7 @@ section#main .intro-text .name {
     display: block;
     text-transform: uppercase;
     font-family: Montserrat,"Helvetica Neue",Helvetica,Arial,sans-serif;
-    font-size: 2em;
+    font-size: 1.5em;
     font-weight: 700;
 }
 
@@ -58,22 +58,23 @@ section#main .intro-text .skills {
 
 .content-body {
     text-align: left;
-    font-size: 1.2em;
+    font-size: 1em;
 }
 
 .content-body h2 {
-    text-align: center;
+    text-align: left;
 }
 
 .content-body ul,
 .content-body ol {
     margin-top: 0;
+    font-size: 17px;
 }
 
 .content-nav {
     /*background-color: green;*/
     margin-top: 40px;
-    font-size: 1.25em;
+    font-size: 1.15em;
 }
 
 .content-nav ul, .content-nav ol {
@@ -95,6 +96,7 @@ section#main .intro-text .skills {
 code {
     color: #443e40;
     background-color: #cdcbd4;
+    font-size: 0.72em;
 }
 
 footer h3 {
@@ -140,7 +142,7 @@ ul.tools li {
 .edit-on-github h2,
 .edit-on-github p,
 .edit-on-github li {
-    font-size: 1.5em;
+    /*font-size: 1.5em;*/
 }
 
 .use-cases {

data/docs/_includes/example.html

@@ -10,10 +10,10 @@
       <div class='col-md-offset-1 col-md-10'>
         <p>With one command you can go from your local machine into a live ECS running docker container. Boom!</p>
 {% highlight sh %}
-$ sonic ecs-exec hi-web-prod --cluster stag
-Running: scp -r /tmp/sonic ec2-user@ec2-52-24-216-170.us-west-2.compute.amazonaws.com:/tmp/sonic  > /dev/null
-=> ssh -t ec2-user@ec2-52-24-216-170.us-west-2.compute.amazonaws.com bash /tmp/sonic/bash_scripts/docker-exec.sh
-root@b371924fce50:/app#
+$ sonic ecs exec boltops-web
+...
++ exec docker exec -ti 385b643c7a895231d2b193574368b0c6c6bebce487267c3c175d0acea3082d4c bash
+root@385b643c7a89:/app#
 {% endhighlight %}
       </div>
     </div>

data/docs/_includes/reference.md

@@ -0,0 +1 @@
+Multi-functional tool to manage AWS infrastructure. A swiss army knife with a variety of uses.

data/docs/_includes/subnav.html

@@ -11,7 +11,7 @@
             <ul class="tutorial">
                 <li><a href="{% link _docs/tutorial-ssh.md %}">SSH</a></li>
                 <li><a href="{% link _docs/tutorial-ecs-exec.md %}">ECS Exec</a></li>
-                <li><a href="{% link _docs/tutorial-ecs-run.md %}">ECS Run</a></li>
+                <li><a href="{% link _docs/tutorial-ecs-sh.md %}">ECS Run</a></li>
                 <li><a href="{% link _docs/tutorial-execute.md %}">Execute</a></li>
                 <li><a href="{% link _docs/tutorial-list.md %}">List</a></li>
             </ul>
@@ -25,5 +25,6 @@
         </li>
         <li><a href="{% link _docs/how-it-works.md %}">How It Works</a></li>
         <li><a href="{% link _docs/next-steps.md %}">Next Steps</a></li>
+        <li><a href="{% link reference.md %}">CLI Reference</a></li>
     </ul>
 </div>

data/docs/_reference/sonic-completion.md

@@ -0,0 +1,44 @@
+---
+title: sonic completion
+reference: true
+---
+
+## Usage
+
+    sonic completion *PARAMS
+
+## Description
+
+Prints words for auto-completion.
+
+Example:
+
+    sonic completion
+
+Prints words for TAB auto-completion.
+
+Examples:
+
+    sonic completion
+    sonic completion execute
+    sonic completion list
+
+To enable, TAB auto-completion add the following to your profile:
+
+    eval $(sonic completion_script)
+
+Auto-completion example usage:
+
+    sonic [TAB]
+    sonic exe[TAB]
+    sonic execute [TAB]
+    sonic list [TAB]
+
+
+## Options
+
+```
+[--verbose], [--no-verbose]  
+[--noop], [--no-noop]        
+```
+

data/docs/_reference/sonic-completion_script.md

@@ -0,0 +1,25 @@
+---
+title: sonic completion_script
+reference: true
+---
+
+## Usage
+
+    sonic completion_script
+
+## Description
+
+Generates a script that can be eval to setup auto-completion.
+
+To use, add the following to your `~/.bashrc` or `~/.profile`
+
+    eval $(sonic completion_script)
+
+
+## Options
+
+```
+[--verbose], [--no-verbose]  
+[--noop], [--no-noop]        
+```
+

data/docs/_reference/sonic-ecs-exec.md

@@ -0,0 +1,30 @@
+---
+title: sonic ecs exec
+reference: true
+---
+
+## Usage
+
+    sonic ecs exec [ECS_SERVICE]
+
+## Description
+
+docker exec into running docker container associated with the service on a container instance
+
+Ssh into an ECS container instance, finds a running docker container associated
+with the service and docker exec's into it.
+
+Examples:
+
+    $ sonic ecs exec my-service --cluster my-cluster
+
+You can use a variety of identifiers.  These include the ECS service name and task id.
+
+
+## Options
+
+```
+[--bastion=BASTION]  # Bastion jump host to use.  Defaults to no bastion server.
+[--cluster=CLUSTER]  # ECS Cluster to use.  Default cluster is default
+```
+

data/docs/_reference/sonic-ecs-help.md

@@ -0,0 +1,21 @@
+---
+title: sonic ecs help
+reference: true
+---
+
+## Usage
+
+    sonic ecs help [COMMAND]
+
+## Description
+
+Describe subcommands or one specific subcommand
+
+
+## Options
+
+```
+[--bastion=BASTION]  # Bastion jump host to use.  Defaults to no bastion server.
+[--cluster=CLUSTER]  # ECS Cluster to use.  Default cluster is default
+```
+

data/docs/_reference/sonic-ecs-sh.md

@@ -0,0 +1,35 @@
+---
+title: sonic ecs sh
+reference: true
+---
+
+## Usage
+
+    sonic ecs sh [ECS_SERVICE]
+
+## Description
+
+docker run with the service on a container instance
+
+Ssh into an ECS container instance and runs a docker container using the same
+environment and image as the specified running service.
+
+Examples:
+
+    $ sonic ecs sh --cluster my-cluster my-service
+    $ sonic ecs sh --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
+the way Thor (what this tool uses) parses options.
+
+    $ sonic ecs sh --cluster production-hi hi-web 'rake -T'
+
+
+## Options
+
+```
+[--bastion=BASTION]  # Bastion jump host to use.  Defaults to no bastion server.
+[--cluster=CLUSTER]  # ECS Cluster to use.  Default cluster is default
+```
+

data/docs/_reference/sonic-ecs.md

@@ -0,0 +1,25 @@
+---
+title: sonic ecs
+reference: true
+---
+
+## Usage
+
+    sonic ecs SUBCOMMAND
+
+## Description
+
+ecs subcommands
+
+## Subcommands
+
+* [sonic ecs exec]({% link _reference/sonic-ecs-exec.md %}) - docker exec into running docker container associated with the service on a container instance
+* [sonic ecs sh]({% link _reference/sonic-ecs-sh.md %}) - docker run with the service on a container instance
+
+## Options
+
+```
+[--verbose], [--no-verbose]  
+[--noop], [--no-noop]        
+```
+