codepipeline 0.1.0 → 0.2.0

data/docs/_docs/dsl/pipeline/codebuild.md

@@ -0,0 +1,62 @@
+---
+title: Codebuild Project
+nav_text: Codebuild
+categories: dsl-pipeline
+nav_order: 12
+---
+
+The `codebuild` method is one of the most useful methods in the `pipeline.rb` DSL arsenal.  With it, you can add codebuild projects to your pipeline and sequence them quickly.  Let's start with the simplest form.
+
+## String Form
+
+With the String form, the String sets both the name of the CodePipeline Action and CodeBuild Project.
+
+```ruby
+stage "Deploy" do
+  codebuild "demo1"
+  codebuild "demo2", "demo3" # runs in parallel
+  codebuild "demo4"
+end
+```
+
+With just a few lines of code, we have define the pipeline to run the `demo1` codebuild project first.  Then run `demo2` and `demo3` in parallel. Last, run `demo4`.
+
+## Simplified Hash Form
+
+With the Simplified Hash form, we have more control over the CodePipeline Action and CodeBuild Project names.
+
+```ruby
+stage "Deploy" do
+  codebuild(name: "action1", project_name: "demo1")
+  codebuild({name: "action2", project_name: "demo2"}, {name: "action3", project_name: "demo3"}) # runs in parallel
+  codebuild(name: "action4", project_name: "demo4")
+end
+```
+
+In this form, we can explicitly set what the Action Name shows up as in the CodePipeline. We can also set the CodeBuild project name explicitly.
+
+## Full Hash Form
+
+With the Full Hash Form, we have full control of the Action properties.  To keep this example concise, we'll declare only one codebuild Action.
+
+```ruby
+stage "Build" do
+  codebuild(
+    name: "action1",
+    action_type_id: {
+      category: "Build",
+      owner: "AWS",
+      provider: "CodeBuild",
+      version: "1",
+    },
+    run_order: 1,
+    configuration: { project_name: 'demo1' },
+    # output_artifacts: [name: "BuildArtifact#{name}"], # optional
+    input_artifacts: [name: "SourceArtifact"], # default
+  )
+end
+```
+
+The various forms all use ultimately all merge the properties down to the Full Hash Form.  Generally, it is recommended you start with the simplest form and use the more complex forms when required.
+
+{% include prev_next.md %}

data/docs/_docs/dsl/pipeline/prefix-and-suffix.md

@@ -0,0 +1,57 @@
+---
+title: Prefix and Suffix Option
+nav_text: Prefix and Suffix
+categories: dsl-pipeline
+nav_order: 13
+---
+
+Somewhat interesting options are the `codebuild_prefix` and `codebuild_suffix` option. These options affect the `codebuild` method and allow you to remove some duplication in the pipeline declaration.
+
+## Example
+
+An example helps explain:
+
+Let's say you have 3 codebuild projects that deploy different tiers of the same codebase:
+
+* demo-web-deploy
+* demo-clock-deploy
+* demo-worker-deploy
+
+The setup makes use of 3 codebuild projects, so we have control over deploying each tier separately if desired. Typically, to define this with `pipeline.rb`, it could look something like this.
+
+```ruby
+# Example 1
+stage "Deploy" do
+  codebuild "demo-web-deploy", "demo-clock-deploy", "demo-worker-deploy"
+end
+```
+
+The Action names in the Stage would be a little lengthy and look like this: DemoWebDeploy, DemoClockDeploy, DemoWorkerDeploy. If you wanted to use shorter names, you'd need to use the [Simpified Hash Form]({% link _docs/dsl/pipeline/codebuild.md %}).
+
+```ruby
+# Example 2
+stage "Deploy" do
+  codebuild(
+    {name: "Web", project_name: "demo-web-deploy"},
+    {name: "Clock", project_name: "demo-clock-deploy"},
+    {name: "Worker", project_name: "demo-worker-deploy"}
+end
+```
+
+## Prefix and Suffix Option
+
+If you use the `codebuild_prefix` and `codebuild_suffix`, it'll remove the need to use the Simplified Hash Form.
+
+```ruby
+# Example 3
+codebuild_prefix "demo-"
+codebuild_suffix "-deploy"
+
+stage "Deploy" do
+  codebuild "web", "clock", "worker"
+end
+```
+
+So Example 2 and Examle 3 are equivalent.
+
+{% include prev_next.md %}

data/docs/_docs/dsl/role.md

@@ -0,0 +1,79 @@
+---
+title: Role DSL
+nav_text: Role
+categories: dsl
+nav_order: 14
+---
+
+The codepipeline tool can create the IAM service role associated with the pipeline. Here's an example:
+
+.codepipeline/role.rb:
+
+```ruby
+iam_policy("logs", "ssm")
+```
+
+For more control, here's a longer form:
+
+```ruby
+iam_policy(
+  action: [
+    "logs:CreateLogGroup",
+    "logs:CreateLogStream",
+    "logs:PutLogEvents",
+    "ssm:*",
+  ],
+  effect: "Allow",
+  resource: "*"
+)
+```
+
+You can also create managed IAM policy.
+
+```ruby
+managed_iam_policy("AmazonS3ReadOnlyAccess")
+```
+
+You can also add multiple managed IAM policies:
+
+```ruby
+managed_iam_policy("AmazonS3ReadOnlyAccess", "AmazonEC2ReadOnlyAccess")
+```
+
+## Full DSL
+
+The convenience methods merely wrap properties of the [AWS::IAM::Role
+ CloudFormation Resource](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-iam-role.html).  If you wanted to set the CloudFormation properties more directly, here's an example of using the "Full" DSL.
+
+.codepipeline/role.rb:
+
+```ruby
+assume_role_policy_document(
+  statement: [{
+    action: ["sts:AssumeRole"],
+    effect: "Allow",
+    principal: {
+      service: ["codepipeline.amazonaws.com"]
+    }
+  }],
+  version: "2012-10-17"
+)
+path("/")
+policies([{
+  policy_name: "CodeBuildAccess",
+  policy_document: {
+    version: "2012-10-17",
+    statement: [{
+      action: [
+        "logs:CreateLogGroup",
+        "logs:CreateLogStream",
+        "logs:PutLogEvents",
+      ],
+      effect: "Allow",
+      resource: "*"
+    }]
+  }
+}])
+```
+
+{% include prev_next.md %}

data/docs/_docs/dsl/schedule.md

@@ -0,0 +1,29 @@
+---
+title: Schedule DSL
+nav_text: Schedule
+categories: dsl
+nav_order: 15
+---
+
+The codepipeline tool supports creating a CloudWatch scheduled event rule that will trigger the codepipeline project periodically.  You define the schedule in `.codepipeline/schedule.rb`. Here's an example of what that looks like:
+
+.codepipeline/schedule.rb:
+
+```ruby
+rate "1 day"
+# or
+cron("0 10 * * ? *") # Run at 10:00 am (UTC) every day
+```
+
+## Full DSL
+
+The convenience methods merely wrap properties of the [AWS::Events::Rule](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-events-rule.html#cfn-events-rule-description).  If you wanted to set the CloudFormation properties more directly, here's an example of using the Full DSL.
+
+.codepipeline/schedule.rb:
+
+```ruby
+description "my description"
+schedule_expression "rate(1 day)"
+```
+
+{% include prev_next.md %}

data/docs/_docs/dsl/sns.md

@@ -0,0 +1,27 @@
+---
+title: Sns Topic DSL
+nav_text: Sns Topic
+categories: dsl
+nav_order: 16
+---
+
+The codepipeline tool can optionally create an SNS Topic and associate it with your [Approval Action]({% link _docs/dsl/approve.md %}).
+If you have created an Approval Action in the pipeline with the `approve` method, then the codepipeline tool will create and manage the SNS topic for you.
+
+For most cases, the default SNS topic should suffice. However, if you wish to control the SNS topic properties you can do so with a `.codepipeline/sns.rb` file.  Here's an example:
+
+```ruby
+display_name "my display_name"
+kms_master_key_id "String"
+# subscription([{
+#   endpoint: '',
+#   protocol: ','
+# }])
+topic_name "string", # Recommend not setting because update requires: Replacement. Allow CloudFormation to set it so 2 pipelines dont have same SNS Topic name that collides
+```
+
+The methods in the `sns.rb` are simply properties of the [SNS::Topic](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-sns-topic.html) CloudFormation Resource
+
+Note: The codepipeline tool will only create the SNS Topic if you have declared an Approval Action in the `pipeline.rb` without specifying an existing SNS Topic ARN.
+
+{% include prev_next.md %}

data/docs/_docs/dsl/webhook.md

@@ -0,0 +1,31 @@
+---
+title: Webhook DSL
+nav_text: Webhook
+categories: dsl
+nav_order: 17
+---
+
+The simplest way to declare a webhook is to use the `github_token` method. This single line is enough to configure and set up the webhook.
+
+.codepipeline/webhook.rb:
+
+```ruby
+github_token(ssm("/codebuild/github/oauth_token"))
+```
+
+## Full DSL
+
+The convenience methods merely wrap properties of the [AWS::CodePipeline::Webhook](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-codepipeline-webhook.html).  If you wanted to set the CloudFormation properties more directly, here's an example of using the Full DSL.
+
+.codepipeline/webhook.rb:
+
+```ruby
+authentication "GITHUB_HMAC"
+authentication_configuration(secret_token: ssm("/codebuild/github/oauth_token"))
+filters([{
+  json_path: "$.ref",
+  match_equals: "refs/heads/{Branch}",
+}])
+```
+
+{% include prev_next.md %}

data/docs/_docs/ecs-deploy.md

@@ -0,0 +1,24 @@
+---
+title: 'ECS Deploy: Codebuild ufo ship vs CodePipeline ECS Deploy'
+nav_order: 19
+---
+
+CodePipeline comes with many [Action Type Integrations](https://docs.aws.amazon.com/codepipeline/latest/userguide/integrations-action-type.html).  One of the Integrations is [Amazon Elastic Container Service](https://docs.aws.amazon.com/codepipeline/latest/userguide/integrations-action-type.html#integrations-deploy) deployment.
+
+Currently, it is recommended to use [codebuild and ufo](https://codebuild.cloud/docs/examples/ecs/) to handle deployment to ECS though.  We discuss the main reasons below.
+
+## Timeout
+
+With the CodePipeline ECS Deploy if your ECS service fails to stabilize then the pipeline stage will not timeout until 60 minutes later. There is no built-in way to abort the pipeline stage. This is discussed here: [CodePipeline stage timeouts / abort?](https://forums.aws.amazon.com/thread.jspa?threadID=216350).
+
+A workaround is discussed here: [How to stop an execution or set set timeout for an action in AWS CodePipeline?](https://stackoverflow.com/questions/50925732/how-to-stop-an-execution-or-set-set-timeout-for-an-action-in-aws-codepipeline/50929558). So to workaround waiting for 60 minutes, we can update the pipeline. This is a little bit inconvenient.
+
+By using a codebuild project, we have control over the timeout.
+
+## It's Less Powerful
+
+The way the current CodePipeline ECS Deploy Action works is that it pulls down the current ECS task definition that ECS service is using. It then replaces the image property on it. Last, it then updates the ECS service with the newly built Docker image.
+
+The [ufo tool] is more powerful.  The `ufo ship` command also handles creating the [ELB Load Balancer]((https://ufoships.com/docs/extras/load-balancer/)) and a vanity [Route53 endpoint](https://ufoships.com/docs/extras/route53-support/) for us.  Also, it keeps task definition codified.
+
+{% include prev_next.md %}

data/docs/_docs/examples/different-branches.md

@@ -0,0 +1,50 @@
+---
+title: Using Different Branches
+nav_text: Different Branches
+categories: examples
+nav_order: 18
+---
+
+CodePipeline currently does not supports starting the pipeline execution with different branches natively. To get around this, we can:
+
+1. update the pipeline before starting it.
+2. create additional pipelines.
+
+The codepipeline tool supports both methods.
+
+## Update Pipeline Approach
+
+With the update pipeline approach, the pipeline gets updated if the current pipeline branch is different from the requested branch before a pipeline execution starts. Examples:
+
+    pipe start -b master
+    pipe start -b qa
+
+Note: With this approach, since the pipeline gets updated, the pipeline will maintain the last branch it was started with.
+
+## Multiple Pipelines Approach
+
+You might normally set the branch option in your pipeline.rb. Example:
+
+```ruby
+stage "Source" do
+  github(
+    source: "tongueroo/demo-cb",
+    branch: "master", # optional, defaults to master
+    auth_token: ssm("/github/user/token")
+  )
+end
+```
+
+When we deploy to create the pipelines, we can explicitly specify the branch to use. The cli option overrides the branch specified in `pipeline.rb`. Examples:
+
+    pipe deploy demo-master -b master
+    pipe deploy demo-qa -b qa
+
+This creates 2 pipelines. The demo-master pipeline will use the master branch, and the demo-qa pipeline will use the qa branch.
+
+To start the pipelines:
+
+    pipe start demo-master
+    pipe start demo-qa
+
+{% include prev_next.md %}

data/docs/_docs/install.md

@@ -0,0 +1,14 @@
+---
+title: Installation
+nav_order: 3
+---
+
+## RubyGems
+
+Install codepipeline via RubyGems.
+
+    gem install codepipeline
+
+The [Quick Start]({% link quick-start.md %}) provides a guide on how to use the codebuild tool.  The [DSL Docs]({% link _docs/dsl.md %}) provide more detail on the syntax.
+
+{% include prev_next.md %}

data/docs/_docs/next-steps.md

@@ -0,0 +1,16 @@
+---
+title: Next Steps
+nav_order: 21
+---
+
+Hopefully, you have a good feel for how codepipeline works now. From here, there are a few resources that can help you continue along:
+
+* Check out the [codepipeline](https://github.com/tongueroo/codepipeline) repo on GitHub
+* ⭐️ the codepipeline project on GitHub
+* Write a blog post about codepipeline
+* Post on your favorite discussion about codepipeline
+* Contribute a pull request
+
+Everyone can contribute to making codepipeline better, including the documentation. These docs are the codepipeline repo located the [docs folder](https://github.com/tongueroo/codepipeline/tree/master/docs). Please fork the project and open a pull request!  We love your pull requests. Contributions are encouraged and welcomed!
+
+{% include prev_next.md %}

data/docs/_docs/settings.md

@@ -0,0 +1,34 @@
+---
+title: Settings
+nav_order: 6
+---
+
+The `.codepipeline/settings.yml` file can be used to adjust some of the behavior of the codepipeline tool.  Here's an example of a settings.yml file:
+
+```yaml
+base:
+  # stack_naming:
+  #   append_env: true # default false
+
+development:
+  # aws_profile: dev_profile
+
+production:
+  # aws_profile: prod_profile
+```
+
+The base settings are common and used for all the environments. The other environments are used according to the value of `PIPE_ENV`.
+
+## Example
+
+    cb deploy # will use the development settings since development is the default
+    PIPE_ENV=production cb deploy # will use the production settings
+
+## Options
+
+Name | Description
+--- | ---
+stack_naming.append_env | Determines if `PIPE_ENV` value is append to the pipeline name.
+aws_profile | This provides a way to bind PIPE_ENV to AWS_PROFILE tightly. This prevents you from forgetting to switch your PIPE_ENV when switching your AWS_PROFILE, thereby accidentally launching a stack in the wrong environment.
+
+{% include prev_next.md %}

data/docs/_docs/start.md

@@ -0,0 +1,31 @@
+---
+title: Start
+nav_order: 5
+---
+
+You can start a pipeline with the `pipe start` command. Here's an example:
+
+    $ pipe start
+    Pipeline started: demo
+    Please check the CodePipeline console for the status.
+    CodePipeline Console: https://us-west-2.console.aws.amazon.com/codesuite/codepipeline/pipelines/demo/view
+    Pipeline cli: aws codepipeline get-pipeline-execution --pipeline-execution-id 02579d64-9271-4edc-aa45-bc9629d732bb --pipeline-name demo
+    $
+
+## Specifying Code Branch
+
+If you would like start a build using a specific code branch you can use the `--branch` or `-b` option.  Example:
+
+    pipe start -b feature-branch
+
+## AWS CLI Equivalent
+
+The `pipe start` command is a simple wrapper to the AWS API with the ruby sdk. You can also start pipelines with the `aws codepipeline` cli.  Here's the equivalent CLI command:
+
+    aws codepipeline start-pipeline-execution --name demo
+
+## CLI Reference
+
+Also, for help info you can check the [pipe start]({% link _reference/pipe-start.md %}) CLI reference.
+
+{% include prev_next.md %}