README.yaml

#
# This is the canonical configuration for the `README.md`
# Run `make readme` to rebuild the `README.md`
#

# Name of this project
name: terraform-aws-cicd

# Tags of this project
tags:
  - aws
  - terraform
  - terraform-modules
  - cicd
  - codepipeline
  - codebuild
  - continuous-integration
  - continuous-delivery

# Categories of this project
categories:
  - terraform-modules/cicd

# Logo for this project
#logo: docs/logo.png

# License of this project
license: "APACHE2"

# Canonical GitHub repo
github_repo: cloudposse/terraform-aws-cicd

# Badges to display
badges:
  - name: Latest Release
    image: https://img.shields.io/github/release/cloudposse/terraform-aws-cicd.svg?style=for-the-badge
    url: https://github.com/cloudposse/terraform-aws-cicd/releases/latest
  - name: Last Updated
    image: https://img.shields.io/github/last-commit/cloudposse/terraform-aws-cicd.svg?style=for-the-badge
    url: https://github.com/cloudposse/terraform-aws-cicd/commits
  - name: Slack Community
    image: https://slack.cloudposse.com/for-the-badge.svg
    url: https://slack.cloudposse.com

# List any related terraform modules that this module may be used with or that this module depends on.
related:

# Short description of this project
description: |-
  Terraform module to create AWS [`CodePipeline`](https://aws.amazon.com/codepipeline/) with [`CodeBuild`](https://aws.amazon.com/codebuild/) for [`CI/CD`](https://en.wikipedia.org/wiki/CI/CD)

  This module supports three use-cases:

  1. **GitHub -> S3 (build artifact) -> Elastic Beanstalk (running application stack)**.
  The module gets the code from a ``GitHub`` repository (public or private), builds it by executing the ``buildspec.yml`` file from the repository, pushes the built artifact to an S3 bucket,
  and deploys the artifact to ``Elastic Beanstalk`` running one of the supported stacks (_e.g._ ``Java``, ``Go``, ``Node``, ``IIS``, ``Python``, ``Ruby``, etc.).
      - http://docs.aws.amazon.com/codebuild/latest/userguide/sample-maven-5m.html
      - http://docs.aws.amazon.com/codebuild/latest/userguide/sample-nodejs-hw.html
      - http://docs.aws.amazon.com/codebuild/latest/userguide/sample-go-hw.html


  2. **GitHub -> ECR (Docker image) -> Elastic Beanstalk (running Docker stack)**.
  The module gets the code from a ``GitHub`` repository, builds a ``Docker`` image from it by executing the ``buildspec.yml`` and ``Dockerfile`` files from the repository,
  pushes the ``Docker`` image to an ``ECR`` repository, and deploys the ``Docker`` image to ``Elastic Beanstalk`` running ``Docker`` stack.
      - http://docs.aws.amazon.com/codebuild/latest/userguide/sample-docker.html


  3. **GitHub -> ECR (Docker image)**.
  The module gets the code from a ``GitHub`` repository, builds a ``Docker`` image from it by executing the ``buildspec.yml`` and ``Dockerfile`` files from the repository,
  and pushes the ``Docker`` image to an ``ECR`` repository. This is used when we want to build a ``Docker`` image from the code and push it to ``ECR`` without deploying to ``Elastic Beanstalk``.
  To activate this mode, don't specify the ``app`` and ``env`` attributes for the module.
      - http://docs.aws.amazon.com/codebuild/latest/userguide/sample-docker.html

# How to use this project
usage: |-
  Include this repository as a module in your existing terraform code:

  ```hcl
  module "build" {
    source = "cloudposse/cicd/aws"
    # Cloud Posse recommends pinning every module to a specific version
    # version = "x.x.x"
    namespace           = "eg"
    stage               = "staging"
    name                = "app"

    # Enable the pipeline creation
    enabled             = true

    # Elastic Beanstalk
    elastic_beanstalk_application_name = "<(Optional) Elastic Beanstalk application name>"
    elastic_beanstalk_environment_name = "<(Optional) Elastic Beanstalk environment name>"

    # Application repository on GitHub
    github_oauth_token  = "(Required) <GitHub Oauth Token with permissions to access private repositories>"
    repo_owner          = "<GitHub Organization or Person name>"
    repo_name           = "<GitHub repository name of the application to be built and deployed to Elastic Beanstalk>"
    branch              = "<Branch of the GitHub repository>"

    # http://docs.aws.amazon.com/codebuild/latest/userguide/build-env-ref.html
    # http://docs.aws.amazon.com/codebuild/latest/userguide/build-spec-ref.html
    build_image         = "aws/codebuild/standard:2.0"
    build_compute_type  = "BUILD_GENERAL1_SMALL"

    # These attributes are optional, used as ENV variables when building Docker images and pushing them to ECR
    # For more info:
    # http://docs.aws.amazon.com/codebuild/latest/userguide/sample-docker.html
    # https://www.terraform.io/docs/providers/aws/r/codebuild_project.html
    privileged_mode     = true
    region              = "us-east-1"
    aws_account_id      = "xxxxxxxxxx"
    image_repo_name     = "ecr-repo-name"
    image_tag           = "latest"

    # Optional extra environment variables
    environment_variables = [{
      name  = "JENKINS_URL"
      value = "https://jenkins.example.com"
    },
    {
      name  = "COMPANY_NAME"
      value = "Amazon"
    },
    {
      name = "TIME_ZONE"
      value = "Pacific/Auckland"
    }]
  }
  ```

# Example usage
examples: |-
  ### Example: GitHub, NodeJS, S3 and EB

  This is an example to build a Node app, store the build artifact to an S3 bucket, and then deploy it to Elastic Beanstalk running ``Node`` stack


  `buildspec.yml` file

  ```yaml
  version: 0.2

  phases:
    install:
      commands:
        - echo Starting installation ...
    pre_build:
      commands:
        - echo Installing NPM dependencies...
        - npm install
    build:
      commands:
        - echo Build started on `date`
    post_build:
      commands:
        - echo Build completed on `date`
  artifacts:
    files:
      - node_modules/**/*
      - public/**/*
      - routes/**/*
      - views/**/*
      - app.js
  ```

  ### Example: GitHub, NodeJS, Docker, ECR and EB

  This is an example to build a ``Docker`` image for a Node app, push the ``Docker`` image to an ECR repository, and then deploy it to Elastic Beanstalk running ``Docker`` stack

  `buildspec.yml` file

  ```yaml
  version: 0.2

  phases:
    pre_build:
      commands:
        - echo Logging in to Amazon ECR...
        - $(aws ecr get-login --region $AWS_REGION)
    build:
      commands:
        - echo Build started on `date`
        - echo Building the Docker image...
        - docker build -t $IMAGE_REPO_NAME .
        - docker tag $IMAGE_REPO_NAME:$IMAGE_TAG $AWS_ACCOUNT_ID.dkr.ecr.$AWS_REGION.amazonaws.com/$IMAGE_REPO_NAME:$IMAGE_TAG
    post_build:
      commands:
        - echo Build completed on `date`
        - echo Pushing the Docker image to ECR...
        - docker push $AWS_ACCOUNT_ID.dkr.ecr.$AWS_REGION.amazonaws.com/$IMAGE_REPO_NAME:$IMAGE_TAG
  artifacts:
    files:
      - '**/*'
  ```

  `Dockerfile`

  ```dockerfile
  FROM node:latest

  WORKDIR /usr/src/app

  COPY package.json package-lock.json ./
  RUN npm install
  COPY . .

  EXPOSE 8081
  CMD [ "npm", "start" ]
  ```

# How to get started quickly
#quickstart: |-
#  Here's how to get started...

# Other files to include in this README from the project folder
include:
  - "docs/targets.md"
  - "docs/terraform.md"

# Contributors to this project
contributors: []