From 257cad9cc366690e9de75b918743a25a8126f82c Mon Sep 17 00:00:00 2001 From: nickveenhof Date: Thu, 10 Mar 2016 14:01:57 -0500 Subject: [PATCH] Adding CLI documentation --- .gitignore | 3 +- docs/example.md | 90 +++++--- docs/index.md | 3 +- docs/mechanisms/artifact-repository.md | 16 ++ docs/mechanisms/build.md | 12 + docs/mechanisms/deployment.md | 24 ++ docs/user-guide/cli.md | 206 ++++++++++++++++++ docs/user-guide/include_in_your_project.md | 64 +++++- docs/user-guide/parent_stacks.md | 2 +- mkdocs.yml | 18 +- sample/README.md | 78 ------- sample/bin/{environment.dist => environment} | 10 +- sample/bin/setup.sh | 23 -- ...e-app.yml.dist => moonshot-sample-app.yml} | 2 +- sample/docroot/{index.php.dist => index.php} | 0 15 files changed, 397 insertions(+), 154 deletions(-) create mode 100644 docs/mechanisms/artifact-repository.md create mode 100644 docs/mechanisms/build.md create mode 100644 docs/mechanisms/deployment.md create mode 100644 docs/user-guide/cli.md delete mode 100644 sample/README.md rename sample/bin/{environment.dist => environment} (60%) delete mode 100755 sample/bin/setup.sh rename sample/cloud_formation/parameters/{moonshot-sample-app.yml.dist => moonshot-sample-app.yml} (74%) rename sample/docroot/{index.php.dist => index.php} (100%) diff --git a/.gitignore b/.gitignore index dd048e74..926950e2 100644 --- a/.gitignore +++ b/.gitignore @@ -1,4 +1,5 @@ /Gemfile.lock /vendor /coverage -site/ \ No newline at end of file +site/ +sample/gems \ No newline at end of file diff --git a/docs/example.md b/docs/example.md index b33549ed..d8f840d2 100644 --- a/docs/example.md +++ b/docs/example.md @@ -1,10 +1,31 @@ # Example usage of the Moonshot Library +In this example we are going to use the resources of the sample directo This example assumes you have access to an Amazon AWS account and have sufficient permissions to create roles and resources. -## Configuring your AWS account +## So, what's in it for me? -### CodeDeploy Role +After setup, you will be able to repeatedly deploy a PHP app to one or more +isolated environments on AWS by running the following command: + +```shell +bundle exec bin/environment deploy-code +``` + +You will also be able to update the OS and supporting software by pulling the +latest changes in this repository and updating the stack with following command: + +```shell +bundle exec bin/environment update +``` + +Lastly, you get a disposable, light-weight application that can be used to learn +and hack on Moonshot without having to muck with applications that actually +matter. + +## Setup + +### Create a service role for Code Deploy in your AWS account. Create a role called CodeDeployRole with the AWSCodeDeployRole policy @@ -27,64 +48,71 @@ aws iam create-role --role-name CodeDeployRole --assume-role-policy-document '{ aws iam attach-role-policy --role-name CodeDeployRole --policy-arn arn:aws:iam::aws:policy/service-role/AWSCodeDeployRole ``` -## Create a Ruby wrapper +If you wish to do this manually, follow the +[Create a Service Role for AWS CodeDeploy](http://docs.aws.amazon.com/codedeploy/latest/userguide/how-to-create-service-role.html) +documentation, and make sure to name the role `CodeDeployRole` as that is +what Moonshot expects. + +### Install Moonshot and it's dependencies. -Now, let's create a ruby wrapper that implements the Moonshot tool and makes your CLI. -The base class is a subclass of Thor, so you can extend it using the [full Thor extensibility](http://whatisthor.com/). Here's a basic example using all the defaults: +This step assumes that you have [Bundler](http://bundler.io/) and a modern version of Ruby installed on your system. See Moonshot's [requirements](index.md#requirements) -```ruby -#!/usr/bin/env ruby +```shell +bundle install +``` -require 'moonshot' +## Usage of the CLI -# Set up Moonshot tooling for our environment. -class MyService < Moonshot::CLI - self.application_name = 'my-service' - self.artifact_repository = S3Bucket.new('my-service-builds') - self.build_mechanism = Script.new('build/script.sh') - self.deployment_mechanism = CodeDeploy.new(asg: 'AutoScalingGroup') -end +Run the following commands to create your environment and deploy code to it. +Note that you will have to set the `AWS_REGION` environment variable prior to running these commands. If it's not set, it will use the default AWS region which at the time of this writing is us-east-1. -MyService.start -``` +A detailed explanation of [all the CLI commands can be found in the User Guide](user-guide/cli.md) -This example assumes: -- You have a CloudFormation JSON template in folder called "cloud_formation/my-service.json". -- You have an S3 bucket called "my-service-builds". -- You have a script in "script/build.sh" that will build a tarball output.tar.gz. -- You have a working CodeDeploy setup, including the CodeDeployRole. +You can now deploy your software to a new stack with: -If all that is true, you can now deploy your software to a new stack with: -``` +```shell $ ./bin/environment create ``` -By default, you'll get a development environment named `my-service-dev-giraffe`, -where `giraffe` is your username. If you want to provision test or production +By default, you'll get a development environment named `moonshot-sample-app`. If you want to provision test or production named environment, use: -``` + +```shell $ ./bin/environment create -n my-service-staging $ ./bin/environment create -n my-service-production ``` By default, create launches the stack and deploys code. If you want to only create the stack and not deploy code, use: -``` + +```shell $ ./bin/environment create --no-deploy ``` If you make changes to your application and want to release a development build to your stack, run: -``` + +```shell $ ./bin/environment deploy-code ``` To build a "named build" for releasing through test and production environments, use: + +```shell +$ ./bin/environment build-version v0.1.0 +$ ./bin/environment deploy-version v0.1.0 -n ``` + +To see the outputs of the stack you just spun up: + +```shell $ ./bin/environment build-version v0.1.0 $ ./bin/environment deploy-version v0.1.0 -n ``` -We recommend using a CI system like Jenkins to perform those activities, for -consistency. \ No newline at end of file +Tear down your stack by running the following command: + +```shell +bundle exec bin/environment delete +``` \ No newline at end of file diff --git a/docs/index.md b/docs/index.md index 660e4849..efba2c47 100644 --- a/docs/index.md +++ b/docs/index.md @@ -37,10 +37,11 @@ Or install it yourself as: $ gem install moonshot +After installation, there is still some work required. Follow the [example documentation](example.md) as described below to dig in! ## Getting started -The Moonshot tool has been designed to be an extensible library for your specific use-case. Interested in how it can be used? See our [example](example.md) documentation or look at our [sample application](https://github.com/acquia/moonshot-sample-app) +The Moonshot tool has been designed to be an extensible library for your specific use-case. Interested in how it can be used? See our [example documentation](example.md). The example doc uses the files shown in the [sample directory](https://github.com/acquia/moonshot/tree/master/sample) so you can figure out how to modify this for your own deployment strategy. ## Requirements diff --git a/docs/mechanisms/artifact-repository.md b/docs/mechanisms/artifact-repository.md new file mode 100644 index 00000000..ce00e227 --- /dev/null +++ b/docs/mechanisms/artifact-repository.md @@ -0,0 +1,16 @@ +## ArtifactRepository + +Supported ArtifactRepositories: +- S3 + +### S3Bucket + +To create a new S3Bucket ArtifactRepository: +```ruby +class MyApplication < Moonshot::CLI + self.artifact_repository = S3Bucket.new('my-bucket-name') +end +``` + +The store action will simply upload the file using the S3 PutObject API call. +The local environment must be configured with appropriate credentials. diff --git a/docs/mechanisms/build.md b/docs/mechanisms/build.md new file mode 100644 index 00000000..83fab01e --- /dev/null +++ b/docs/mechanisms/build.md @@ -0,0 +1,12 @@ +## BuildMechanism + +### Script + +The Script BuildMechanism will execute a local shell script, with certain +expectations. The script will run with some environment variables: + +- `VERSION`: The named version string passed to `build-version`. +- `OUTPUT_FILE`: The file that the script is expected to produce. + +If the file is not created by the build script, deployment will fail. Otherwise, +the output file will be uploaded using the ArtifactRepository. diff --git a/docs/mechanisms/deployment.md b/docs/mechanisms/deployment.md new file mode 100644 index 00000000..b1196ebc --- /dev/null +++ b/docs/mechanisms/deployment.md @@ -0,0 +1,24 @@ + +## DeploymentMechanism + +Supported DeploymentMechanisms: +- CodeDeploy + +### CodeDeploy + +The CodeDeploy DeploymentMechanism will create a CodeDeploy Application and +Deployment Group matching the application name. The created Deployment Group +will point at the logical resource id provided to the constructor (e.g. +`CodeDeploy.new(asg: 'MyAutoScalingGroup')`). During the `deploy-code` action, +the ArtifactRepository is checked for compatibility with CodeDeploy. Currently +only the S3Bucket is supported, though CodeDeploy itself supports deploying from +a git source. + +Assumptions made by the CodeDeploy mechanism: +- You are using an S3Bucket ArtifactRepository. +- You want to deploy using the OneAtATime method. +- Your build artifact contains an appspec.yml file. + +For more information about CodeDeploy, see the [AWS Documentation][1]. + +[1]: http://docs.aws.amazon.com/codedeploy/latest/userguide/welcome.html diff --git a/docs/user-guide/cli.md b/docs/user-guide/cli.md new file mode 100644 index 00000000..5a47e683 --- /dev/null +++ b/docs/user-guide/cli.md @@ -0,0 +1,206 @@ +# CLI Commands + +## List + +List stacks for this application. + +|Description|Long Form|Short Form|Type|Example|Default| +|---|---|---|---|---|---| +|Parent stack to import parameters from|--parent|-p|string|moonshot-database-sample-app|None| +|Choose if code should be deployed after stack is created|deploy|d|boolean||true| +|Show all stack events during update. When present, it will show all events|show_all_events||boolean||Errors only| +|Environment Name|name|n|string|moonshot-sample-app|None| +|Interactive Logger|interactive_logger||boolean||true| +|Verbose|verbose|v|boolean||false| + + +Example: +```shell +./bin/environment list +``` + +Output: + +```shell +``` + +## Create +Create a new environment. + +|Description|Long Form|Short Form|Type|Example|Default| +|---|---|---|---|---|---| +|Parent stack to import parameters from|parent|p|string|moonshot-database-sample-app|None| +|Choose if code should be deployed after stack is created|deploy|d|boolean||true| +|Show all stack events during update. When present, it will show all events|show_all_events||boolean||Errors only| +|Environment Name|name|n|string|moonshot-sample-app|None| +|Interactive Logger|interactive_logger||boolean||true| +|Verbose|verbose|v|boolean||false| + +Example: + +```shell +./bin/environment create --name my-service-staging --verbose +``` + +Output: + +```shell +``` + + +## Update + +Update the CloudFormation stack within an environment. + +@todo: Add more description here as to what it exactly does. + +Options: + +|Description|Long Form|Short Form|Type|Example|Default| +|---|---|---|---|---|---| +|Parent stack to import parameters from|--parent|-p|string|moonshot-database-sample-app|None| +|Show all stack events during update. When present, it will show all events|show_all_events||boolean||Errors only| +|Environment Name|name|n|string|moonshot-sample-app|None| +|Interactive Logger|interactive_logger||boolean||true| +|Verbose|verbose|v|boolean||false| + +Example: + +```shell +./bin/environment create --name my-service-staging --verbose +``` + +Output: + +```shell +``` + +## Status + +Get the status of an existing environment. + +|Description|Long Form|Short Form|Type|Example|Default| +|---|---|---|---|---|---| +|Environment Name|name|n|string|moonshot-sample-app|None| +|Interactive Logger|interactive_logger||boolean||true| +|Verbose|verbose|v|boolean||false| + +Example: + +```shell +./bin/environment create --name my-service-staging --verbose +``` + +Output: + +```shell +``` + + +## Deploy Code + +Create a build from the working directory, and deploy it. + +|Description|Long Form|Short Form|Type|Example|Default| +|---|---|---|---|---|---| +|Environment Name|name|n|string|moonshot-sample-app|None| +|Interactive Logger|interactive_logger||boolean||true| +|Verbose|verbose|v|boolean||false| + +Example: + +```shell +./bin/environment create --name my-service-staging --verbose +``` + +Output: + +```shell +``` + +## Build Version + +Build a tarball of the software, ready for deployment. +Requires a version name parameter. + +|Description|Long Form|Short Form|Type|Example|Default| +|---|---|---|---|---|---| +|Environment Name|name|n|string|moonshot-sample-app|None| +|Interactive Logger|interactive_logger||boolean||true| +|Verbose|verbose|v|boolean||false| + +Example: + +```shell +./bin/environment create --name my-service-staging --verbose +``` + +Output: + +```shell +``` + +## Deploy Version + +Deploy a versioned release to both Elastic Beanstalk environments in an environment. +Requires a version name parameter. + +|Description|Long Form|Short Form|Type|Example|Default| +|---|---|---|---|---|---| +|Environment Name|name|n|string|moonshot-sample-app|None| +|Interactive Logger|interactive_logger||boolean||true| +|Verbose|verbose|v|boolean||false| + +Example: + +```shell +./bin/environment create --name my-service-staging --verbose +``` + +Output: + +```shell +``` + +## Delete + +Delete an existing environment. + +|Description|Long Form|Short Form|Type|Example|Default| +|---|---|---|---|---|---| +|Show all stack events during update. When present, it will show all events|show_all_events||boolean||Errors only| +|Environment Name|name|n|string|moonshot-sample-app|None| +|Interactive Logger|interactive_logger||boolean||true| +|Verbose|verbose|v|boolean||false| + +Example: + +```shell +./bin/environment create --name my-service-staging --verbose +``` + +Output: + +```shell +``` + +## Doctor +Run configuration checks against current environment. Throws an error if one or more checks failed. +For example, if you are using a deployment_mechanism that is using S3, it will check if the bucket actually exists and that you have access to. Each mechanism is able to add checks themselves that will be recognized and run. + +|Description|Long Form|Short Form|Type|Example|Default| +|---|---|---|---|---|---| +|Environment Name|name|n|string|moonshot-sample-app|None| +|Interactive Logger|interactive_logger||boolean||true| +|Verbose|verbose|v|boolean||false| + +Example: + +```shell +./bin/environment create --name my-service-staging --verbose +``` + +Output: + +```shell +``` diff --git a/docs/user-guide/include_in_your_project.md b/docs/user-guide/include_in_your_project.md index 199f8941..694a0401 100644 --- a/docs/user-guide/include_in_your_project.md +++ b/docs/user-guide/include_in_your_project.md @@ -1,5 +1,63 @@ # Including Moonshot-based tooling in your project -You'll want to build a tool using the template in Basic Usage as a starting point, -then grab a **release build**, either by using git directly from Bundler, or -including the gem directly in your `vendor/cache` directory. \ No newline at end of file +## Create a Ruby wrapper + +Now, let's create a ruby wrapper that implements the Moonshot tool and makes your CLI. +The base class is a subclass of Thor, so you can extend it using the [full Thor extensibility](http://whatisthor.com/). Here's a basic example using all the defaults: + +```ruby +#!/usr/bin/env ruby + +require 'moonshot' + +# Set up Moonshot tooling for our environment. +class MyService < Moonshot::CLI + self.application_name = 'my-service' + self.artifact_repository = S3Bucket.new('my-service-builds') + self.build_mechanism = Script.new('build/script.sh') + self.deployment_mechanism = CodeDeploy.new(asg: 'AutoScalingGroup') +end + +MyService.start +``` + +This example assumes: +- You have a CloudFormation JSON template in folder called "cloud_formation/my-service.json". +- You have an S3 bucket called "my-service-builds". +- You have a script in "script/build.sh" that will build a tarball output.tar.gz. +- You have a working CodeDeploy setup, including the CodeDeployRole. + +If all that is true, you can now deploy your software to a new stack with: +``` +$ ./bin/environment create +``` + +By default, you'll get a development environment named `my-service-dev-giraffe`, +where `giraffe` is your username. If you want to provision test or production +named environment, use: +``` +$ ./bin/environment create -n my-service-staging +$ ./bin/environment create -n my-service-production +``` + +By default, create launches the stack and deploys code. If you want to only +create the stack and not deploy code, use: +``` +$ ./bin/environment create --no-deploy +``` + +If you make changes to your application and want to release a development build +to your stack, run: +``` +$ ./bin/environment deploy-code +``` + +To build a "named build" for releasing through test and production environments, +use: +``` +$ ./bin/environment build-version v0.1.0 +$ ./bin/environment deploy-version v0.1.0 -n +``` + +We recommend using a CI system like Jenkins to perform those activities, for +consistency. diff --git a/docs/user-guide/parent_stacks.md b/docs/user-guide/parent_stacks.md index eacfbe6d..b7517f42 100644 --- a/docs/user-guide/parent_stacks.md +++ b/docs/user-guide/parent_stacks.md @@ -1,6 +1,6 @@ ## Parent Stacks -Since 0.5.3, Moonshot supports referencing another CloudFormation stack as a +Moonshot supports referencing another CloudFormation stack as a "Parent" during creation time. This relationship is used only for creation, where any outputs of that stack that match names of the parameters for the local stack will be used as parameters, and saved into a local .yml file for future diff --git a/mkdocs.yml b/mkdocs.yml index 5a29bf44..a899eee7 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -2,12 +2,16 @@ site_name: Moonshot pages: - Home: 'index.md' - Example: example.md -- Plugins: plugins.md -- Mechanisms: mechanisms.md - User Guide: - - 'Including Moonshot in your project': 'user-guide/include_in_your_project.md' - - 'Working with parent stacks': 'user-guide/parent_stacks.md' - - 'Overriding Stack Parameters': 'user-guide/stack_parameters_override.md' + - 'CLI Commands': 'user-guide/cli.md' + - 'Including Moonshot in your project': 'user-guide/include_in_your_project.md' + - 'Working with parent stacks': 'user-guide/parent_stacks.md' + - 'Overriding Stack Parameters': 'user-guide/stack_parameters_override.md' +- Mechanisms: + - 'Artifact Repository': 'mechanisms/artifact-repository.md' + - 'Build': 'mechanisms/build.md' + - 'Deployment': 'mechanisms/deployment.md' +- Plugins: plugins.md - About: - - 'How to Contribute': 'about/contribute.md' - - 'License': 'about/license.md' + - 'How to Contribute': 'about/contribute.md' + - 'License': 'about/license.md' diff --git a/sample/README.md b/sample/README.md deleted file mode 100644 index 6da53eb2..00000000 --- a/sample/README.md +++ /dev/null @@ -1,78 +0,0 @@ -# Moonshot Sample Application - -A small PHP application that is used to demo the -[Moonshot](https://github.com/acquia/moonshot) deployment tool. - -## So, what's in it for me? - -After setup, you will be able to repeatedly deploy a PHP app to one or more -isolated environments on AWS by running the following command: - -``` -bundle exec bin/environment deploy-code -``` - -You will also be able to update the OS and supporting software by pulling the -latest changes in this repository and updating the stack with following command: - -``` -bundle exec bin/environment update -``` - -Lastly, you get a disposable, light-weight application that can be used to learn -and hack on Moonshot without having to muck with applications that actually -matter. - -## Setup - -1. Create a service role for Code Deploy in your AWS account. - - Run the commands in the [Configuring an AWS account](https://github.com/acquia/moonshot#codedeploy-role) - section of Moonshot's README. If you wish to do this manually, follow the - [Create a Service Role for AWS CodeDeploy](http://docs.aws.amazon.com/codedeploy/latest/userguide/how-to-create-service-role.html) - documentation, and make sure to name the role `CodeDeployRole` as that is - what Moonshot expects. - -2. Install Moonshot and it's dependencies. - - This step assumes that you have [Bundler](http://bundler.io/) and a modern - version of Ruby installed on your system. - - ```shell - bundle install - ``` - -3. Run the setup script to create a provisioning script, a parameters file for - your default environment, and a default `index.php` file. Change - `[S3_BUCKET]` to an S3 bucket you can write to, e.g. `my-s3-bucket`. - - ```shell - ./bin/setup.sh [S3-BUCKET] - ``` - -4. [OPTIONAL] Modify `./docroot/index.php` accordingly. - - By default, a simple phpinfo() page is displayed. - -## Usage - -Run the following commands to create your environment and deploy code to it. -Note that you will likely have to set the `AWS_REGION` environment variable -prior to running these commands. - -``` -bundle exec bin/environment create -bundle exec bin/environment deploy-code -``` - -Visit the AWS console, view your Cloud Formation stack, and click on the link in -the "URL" key's value in the "Outputs" tab to view your app. - -Tear down your stack by running the following command: - -``` -bundle exec bin/environment delete -``` - -See https://github.com/acquia/moonshot#basic-usage for more advanced -usage of Moonshot. diff --git a/sample/bin/environment.dist b/sample/bin/environment similarity index 60% rename from sample/bin/environment.dist rename to sample/bin/environment index e5c34f17..88dc36cc 100755 --- a/sample/bin/environment.dist +++ b/sample/bin/environment @@ -5,15 +5,9 @@ require 'moonshot' # Set up Moonshot tooling for our environment. class MoonshotSampleApp < Moonshot::CLI self.application_name = 'moonshot-sample-app' - self.artifact_repository = S3Bucket.new('{{bucket}}') + self.artifact_repository = S3Bucket.new('my-s3-bucket') self.build_mechanism = Script.new('bin/build.sh') self.deployment_mechanism = CodeDeploy.new(asg: 'AutoScalingGroup') end -begin - MoonshotSampleApp.start -rescue => e - warn "Uncaught exception: #{e.class}: #{e.message}" - warn "at: #{e.backtrace.first}" - exit(1) -end +MoonshotSampleApp.start diff --git a/sample/bin/setup.sh b/sample/bin/setup.sh deleted file mode 100755 index d9444967..00000000 --- a/sample/bin/setup.sh +++ /dev/null @@ -1,23 +0,0 @@ -#!/usr/bin/env bash -e - -if [ -z "$1" ]; then - >&2 echo "Usage: $0 [S3-BUCKET]" - exit 1 -fi - -# The project's root directory. -PROJECT_DIR=$(dirname $0)/.. - -# Name of the user's default environment. -STACK_NAME=moonshot-sample-app-dev-$(echo $USER | sed 's/[^a-zA-Z0-9_]*//g') - -# Creates the provisioning script and parameters file. -cp $PROJECT_DIR/bin/environment.dist $PROJECT_DIR/bin/environment -cp $PROJECT_DIR/cloud_formation/parameters/moonshot-sample-app.yml.dist $PROJECT_DIR/cloud_formation/parameters/$STACK_NAME.yml - -# Changes the S3 bucket in the provisioning script and parameters file. -sed -i '' "s#{{bucket}}#$1#" "$PROJECT_DIR/bin/environment" -sed -i '' "s#{{bucket}}#$1#" "$PROJECT_DIR/cloud_formation/parameters/$STACK_NAME.yml" - -# Create an index.php file, which is the "application". -cp $PROJECT_DIR/docroot/index.php.dist $PROJECT_DIR/docroot/index.php diff --git a/sample/cloud_formation/parameters/moonshot-sample-app.yml.dist b/sample/cloud_formation/parameters/moonshot-sample-app.yml similarity index 74% rename from sample/cloud_formation/parameters/moonshot-sample-app.yml.dist rename to sample/cloud_formation/parameters/moonshot-sample-app.yml index 4febbf1d..f9ac5088 100644 --- a/sample/cloud_formation/parameters/moonshot-sample-app.yml.dist +++ b/sample/cloud_formation/parameters/moonshot-sample-app.yml @@ -1,5 +1,5 @@ --- -ArtifactBucket: "{{bucket}}" +ArtifactBucket: "my-s3-bucket" AvailabilityZone1: "us-east-1a" AvailabilityZone2: "us-east-1b" DesiredCapacity: "2" diff --git a/sample/docroot/index.php.dist b/sample/docroot/index.php similarity index 100% rename from sample/docroot/index.php.dist rename to sample/docroot/index.php