codebuild 0.5.0 → 0.6.0

data/docs/{dsl → _docs/dsl}/role.md

@@ -1,4 +1,40 @@
-# IAM Role DSL
+---
+title: Role DSL
+nav_text: Role
+categories: dsl
+nav_order: 13
+---
+
+The codebuild tool can create the IAM service role associated with the codebuild project. Here's an example:
+
+.codebuild/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")
+```
+
+## 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.
@@ -33,3 +69,5 @@ policies([{
   }
 }])
 ```
+
+{% include prev_next.md %}

data/docs/_docs/dsl/schedule.md

@@ -0,0 +1,29 @@
+---
+title: Schedule DSL
+nav_text: Schedule
+categories: dsl
+nav_order: 14
+---
+
+The codebuild tool supports creating a CloudWatch scheduled event rule that will trigger the codebuild project periodically.  You define the schedule in `.codebuild/schedule.rb`. Here's an example of what that looks like:
+
+.codebuild/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.
+
+.codebuild/schedule.rb:
+
+```ruby
+description "my description"
+schedule_expression "rate(1 day)"
+```
+
+{% include prev_next.md %}

data/docs/_docs/examples.md

@@ -0,0 +1,12 @@
+---
+title: Examples
+nav_order: 15
+---
+
+<ul>
+  {% assign docs = site.docs | where: "categories","example" %} {% for doc in docs -%}
+  <li><a href='{{doc.url}}'>{{doc.nav_text}}</a></li>
+  {% endfor %}
+</ul>
+
+{% include prev_next.md %}

data/docs/_docs/examples/ecs.md

@@ -0,0 +1,94 @@
+---
+title: ECS
+nav_text: ECS
+categories: example
+nav_order: 16
+---
+
+This example will show some powerful patterns with the codebuild tool.  We'll use codebuild with the [ufo](https://ufoships.com) tool to deploy an application to ECS.
+
+Here's the project DSL.
+
+.codebuild/project.rb:
+
+
+```ruby
+github_url("https://github.com/tongueroo/demo-ufo)
+linux_image("aws/codebuild/ruby:2.5.3-1.7.0")
+environment_variables(
+  UFO_ENV: Codebuild.env,
+  UFO_APP: project_name,
+)
+```
+
+Notice the use of `Codebuild.env` and `project_name` to set environment variables. The environment variables are later used in the `.buildspec.yml`.
+
+* The `Codebuild.env` method contains the value of `CB_ENV` when you run the `cb deploy` command.
+* The `project_name` is the CodeBuild project name itself.
+
+If CodeBuild project name matches the ufo ECS service name, then it makes the commands very simple. For example.
+
+    CB_ENV=production cb deploy demo-web
+
+Creates a CodeBuild project that will deploy your app to production and create an ECS service named `demo-web` via ufo.
+
+Here's the buildspec that references the environment variables set in `project.rb` earlier:
+
+.codebuild/buildspec.yml
+
+```yaml
+version: 0.2
+
+phases:
+  pre_build:
+    commands:
+      - gem install --no-document ufo
+  build:
+    commands:
+      - echo Deploying project to ECS started on `date`
+      - UFO_ENV=$UFO_ENV ufo ship $UFO_APP
+```
+
+Last, here's the IAM Policy that will give CodeBuild the IAM permissions necessary to create the ECS service and other resources that ufo can create:
+
+.codebuild/role.rb:
+
+
+```ruby
+iam_policy(
+  "cloudformation",
+  "ec2",
+  "ecr",
+  "ecs",
+  "elasticloadbalancing",
+  "elasticloadbalancingv2",
+  "logs",
+  "route53",
+  "ssm",
+  {
+      "Action": [
+          "iam:PassRole"
+      ],
+      "Effect": "Allow",
+      "Resource": "*",
+      "Condition": {
+          "StringLike": {
+              "iam:PassedToService": [
+                  "ecs-tasks.amazonaws.com"
+              ]
+          }
+      }
+  }
+)
+managed_iam_policy("AmazonS3ReadOnlyAccess") # optional but common to need read only access to s3
+```
+
+From a security perspective, using CodeBuild gives us a stronger security posture. The **only** permission the user calling [cb start]({% link _docs/start.md %}) really needs is CodeBuild access.  The permissions to create the ECS service and other deployment resources are delegated to the CodeBuild project itself. We know that the CodeBuild project will not run any arbitrary commands unless we update `buildspec.yml` and explicitly give permission to it's IAM role.
+
+## CodePipeline ECS Deploy Action
+
+If you are using CodePipeline also, you may be wondering why not just use the provided Amazon ECS deployment action instead.  It comes down to control. With a CodeBuild project, we have full control of how we want to build and deploy the Docker image to ECS.
+
+Also, with the CodePipeline ECS deploy action, we are unable to configure a timeout.  If the ECS deployment fails due to some reasons, we're stuck waiting 60 minutes for the pipeline timeout. There's a way to hack around this by literally overriding updating the CodeBuild project. You also must do it manually and are charged for the time. With CodeBuild project, you can set the timeout value yourself. Essentially, you have more control with CodeBuild.
+
+{% include prev_next.md %}

data/docs/_docs/examples/jets.md

@@ -0,0 +1,68 @@
+---
+title: Jets
+nav_text: Jets
+categories: example
+nav_order: 17
+---
+
+This example shows to deploy a [Jets](https://rubyonjets.com/) application with codebuild to AWS Lambda.
+
+Here's the project DSL.
+
+.codebuild/project.rb:
+
+
+```ruby
+github_url("https://github.com/tongueroo/jets-hello-examples")
+linux_image("aws/codebuild/ruby:2.5.3-1.7.0") # currently must used ruby 2.5
+environment_variables(
+  JETS_ENV: Codebuild.env,
+)
+```
+
+Here's the buildspec:
+
+.codebuild/buildspec.yml
+
+```yaml
+version: 0.2
+
+phases:
+  install:
+    commands:
+      - apt-get update -y && apt-get install -y rsync # prequisite for jets
+  build:
+    commands:
+      - echo Build started on `date`
+      - sed -i '/BUNDLED WITH/Q' Gemfile.lock # hack to fix bundler issue: allow different versions of bundler to work
+      - gem install bundler:1.16.6
+      - export JETS_ENV=test
+      - bundle
+      - bundle exec rspec
+  post_build:
+    commands:
+      - bash -c 'if [ "$CODEBUILD_BUILD_SUCCEEDING" == "0" ]; then exit 1; fi'
+      - export JETS_AGREE=yes
+      - bundle exec jets deploy $JETS_ENV
+```
+
+And here are the IAM permissions required as described in [Jets Minimal IAM Deploy Policy](https://rubyonjets.com/docs/extras/minimal-deploy-iam/).
+
+.codebuild/role.rb:
+
+```ruby
+iam_policy(
+  "apigateway",
+  "cloudformation",
+  "dynamodb",
+  "events",
+  "iam",
+  "lambda",
+  "logs",
+  "route53",
+  "s3",
+  "ssm",
+)
+```
+
+{% include prev_next.md %}

data/docs/_docs/examples/ruby.md

@@ -0,0 +1,44 @@
+---
+title: Ruby
+nav_text: Ruby
+categories: example
+nav_order: 18
+---
+
+This examples show to run ruby unit tests.
+
+Here's the project DSL.
+
+.codebuild/project.rb:
+
+
+```ruby
+github_url("https://github.com/username/repo")
+linux_image("aws/codebuild/ruby:2.5.3-1.7.0")
+environment_variables(
+  JETS_ENV: Codebuild.env,
+)
+```
+
+Here's the buildspec:
+
+.codebuild/buildspec.yml
+
+```yaml
+version: 0.2
+
+phases:
+  install:
+    commands:
+      - apt-get update -y && apt-get install -y rsync # prequisite for jets
+  build:
+    commands:
+      - echo Build started on `date`
+      - sed -i '/BUNDLED WITH/Q' Gemfile.lock # hack to fix bundler issue: allow different versions of bundler to work
+      - gem install bundler:1.16.6
+      - export JETS_ENV=test
+      - bundle
+      - bundle exec rspec
+```
+
+{% include prev_next.md %}

data/docs/_docs/github_oauth.md

@@ -0,0 +1,51 @@
+---
+title: GitHub Oauth Token
+nav_order: 10
+---
+
+This page covers how to set up the GitHub oauth token that CodeBuild uses.
+
+CloudFormation docs has an oauth token property as part of the CloudFormation template source property under [AWS CodeBuild Project SourceAuth](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-codebuild-project-sourceauth.html). It does not seem to work though.
+
+
+Note: Am hoping that have either tested this incorrectly or that AWS fixes the bug.
+
+Instead, this guide [Using Access Tokens with Your Source Provider in CodeBuild](https://docs.aws.amazon.com/codebuild/latest/userguide/sample-access-tokens.html) with [aws codebuild import-source-credentials](https://docs.aws.amazon.com/cli/latest/reference/codebuild/import-source-credentials.html) works.
+
+## Create the GitHub Oauth Token
+
+Here are the steps to create a GitHub oauth token:
+
+1. Go to GitHub
+2. Settings
+3. Developer Settings
+4. Personal access tokens
+
+IMPORTANT: If using webhook, the oauth token needs `admin:repo_hook` also.  To check this, you can log into the github, go to the repo, and see if you have access to the "Settings" tab.
+
+![](https://raw.githubusercontent.com/tongueroo/codebuild/master/img/github-admin-settings-tab.png)
+
+## Commands
+
+Here's a guide to using the `import-source-credentials` commands.
+
+First, save the GitHub oauth token to parameter store, in case we need it in the future.
+
+    aws ssm put-parameter --name /codebuild/github/oauth_token --value secret-token-value --type SecureString
+
+Import the source credential into codebuild.
+
+    TOKEN=$(aws ssm get-parameter --name /codebuild/github/oauth_token --with-decryption | jq -r '.Parameter.Value')
+    cat > /tmp/codebuild-source-credentials.json <<EOL
+    {
+        "token": "$TOKEN",
+        "serverType": "GITHUB",
+        "authType": "PERSONAL_ACCESS_TOKEN"
+    }
+    EOL
+    aws codebuild import-source-credentials --cli-input-json file:///tmp/codebuild-source-credentials.json
+    aws codebuild list-source-credentials
+
+Setting this sets the oauth token used by the CodeBuild projects.
+
+{% include prev_next.md %}

data/docs/_docs/install.md

@@ -0,0 +1,14 @@
+---
+title: Installation
+nav_order: 3
+---
+
+## RubyGems
+
+Install codebuild via RubyGems.
+
+    gem install codebuild
+
+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: 20
+---
+
+Hopefully, you have a good feel for how codebuild works now. From here, there are a few resources that can help you continue along:
+
+* Check out the [codebuild](https://github.com/tongueroo/codebuild) repo on GitHub
+* ⭐️ the codebuild project on GitHub
+* Write a blog post about codebuild
+* Post on your favorite discussion about codebuild
+* Contribute a pull request
+
+Everyone can contribute to making codebuild better, including the documentation. These docs are the codebuild repo located the [docs folder](https://github.com/tongueroo/codebuild/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: 8
+---
+
+The `.codebuild/settings.yml` file can be used to adjust some of the behavior of the codebuild 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 `CB_ENV`.
+
+## Example
+
+    cb deploy # will use the development settings since development is the default
+    CB_ENV=production cb deploy # will use the production settings
+
+## Options
+
+Name | Description
+--- | ---
+stack_naming.append_env | Determines if `CB_ENV` value is append to the CodeBuild project name.
+aws_profile | This provides a way to bind CB_ENV to AWS_PROFILE tightly. This prevents you from forgetting to switch your CB_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,46 @@
+---
+title: Start
+nav_order: 7
+---
+
+You can start a CodeBuild project with the `cb start` command. Here's an example:
+
+    $ cb start
+    Build started for project: demo
+    Please check the CodeBuild console for the status.
+    Codebuild Log Url:
+    https://us-west-2.console.aws.amazon.com/codesuite/codebuild/projects/demo/build/demo%3A7bc4cb33-d918-467a-9e09-fe7fe1f57ed8/log
+    $
+
+## Specifying Code Branch
+
+If you would like start a build using a specific code branch you can use the `--branch` or `-b` option.  Example:
+
+    cb start -b feature-branch
+
+## AWS CLI Equivalent
+
+The `cb start` command is a simple wrapper to the AWS API with the ruby sdk. You can also start codebuild projects with the `aws codebuild` cli.  Here's the equivalent CLI command:
+
+    aws codebuild start-build --project-name demo --source-version master
+
+## Types
+
+If you are using multiple Codebuild projects with [Types]({% link _docs/type-option.md %}), you can start the specific CodeBuild project type with the `--type` option.  Example:
+
+    cb start --type unit
+
+## Override CodeBuild Environment Variables
+
+You can override CodeBuild env variables at runtime with `--env-vars`. Examples:
+
+    cb start --type vpc --env-vars K1=v1 K2=v2
+    cb start --type vpc --env-vars K1=v1 K2=ssm:v2 # support for PARAMETER_STORE
+
+Remember the environment variables are within the CodeBuild environment instance running the build script, not the application's environment.
+
+## CLI Reference
+
+Also, for help info you can check the [cb start]({% link _reference/codebuild-start.md %}) CLI reference.
+
+{% include prev_next.md %}