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-ecs-atlantis

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

# License of this project
license: "APACHE2"

# Canonical GitHub repo
github_repo: cloudposse/terraform-aws-ecs-atlantis

# Screenshots
screenshots:
  - name: "demo"
    description: "Example of a Pull Request comment from running `terraform plan` using `atlantis`"
    url: "docs/example.png"

# Badges to display
badges:
  - name: "Latest Release"
    image: "https://img.shields.io/github/release/cloudposse/terraform-aws-ecs-atlantis.svg"
    url: "https://github.com/cloudposse/terraform-aws-ecs-atlantis/releases/latest"
  - name: "Slack Community"
    image: "https://slack.cloudposse.com/badge.svg"
    url: "https://slack.cloudposse.com"

related:
  - name: "terraform-aws-ecs-web-app"
    description: "Terraform module that implements a web app on ECS and supports autoscaling, CI/CD, monitoring, ALB integration, and much more"
    url: "https://github.com/cloudposse/terraform-aws-ecs-web-app"
  - name: "terraform-aws-alb"
    description: "Terraform module to provision a standard ALB for HTTP/HTTP traffic"
    url: "https://github.com/cloudposse/terraform-aws-alb"
  - name: "terraform-aws-alb-ingress"
    description: "Terraform module to provision an HTTP style ingress rule based on hostname and path for an ALB"
    url: "https://github.com/cloudposse/terraform-aws-alb-ingress"
  - name: "terraform-aws-codebuild"
    description: "Terraform Module to easily leverage AWS CodeBuild for Continuous Integration"
    url: "https://github.com/cloudposse/terraform-aws-codebuild"
  - name: "terraform-aws-ecr"
    description: "Terraform Module to manage Docker Container Registries on AWS ECR"
    url: "https://github.com/cloudposse/terraform-aws-ecr"
  - name: "terraform-aws-ecs-alb-service-task"
    description: "Terraform module which implements an ECS service which exposes a web service via ALB."
    url: "https://github.com/cloudposse/terraform-aws-ecs-alb-service-task"
  - name: "terraform-aws-ecs-codepipeline"
    description: "Terraform Module for CI/CD with AWS Code Pipeline and Code Build for ECS"
    url: "https://github.com/cloudposse/terraform-aws-ecs-codepipeline"
  - name: "terraform-aws-ecs-container-definition"
    description: "Terraform module to generate well-formed JSON documents that are passed to the aws_ecs_task_definition Terraform resource"
    url: "https://github.com/cloudposse/terraform-aws-ecs-container-definition"
  - name: "terraform-aws-lb-s3-bucket"
    description: "Terraform module to provision an S3 bucket with built in IAM policy to allow AWS Load Balancers to ship access logs."
    url: "https://github.com/cloudposse/terraform-aws-lb-s3-bucket"


# Short description of this project
description: |-

  A Terraform module for deploying [Atlantis](https://runatlantis.io) to an AWS ECS cluster.

introduction: |-

  Atlantis enables GitOps workflows so that teams can collaborate on operations using Pull Requests.

  Under the hood, it's a small self-hosted daemon (`#golang`) that listens for Pull Request webhook events from GitHub.

  With Atlantis, engineers can run `terraform plan` and `terraform apply` using "chat ops" type comments on the Pull Request.

  ### Features

  This module provisions the following resources:

  - ECS Atlantis web application, which includes:
      - ECR Docker registry
      - ALB target group, listener rule and alarms
      - ECS container definition (using a default backend)
      - ECS task definition and IAM role
      - ECS service and IAM role
      - ECS task autoscaling
      - ECS SNS based alarms
      - ECS Codepipeline to build our Atlantis image on GitHub release
      - ECS Codedeploy to deploy our ECS Atlantis web app
  - SSH key pair for Atlantis to pull private Github repositories, which are written to SSM for reading with [chamber](https://github.com/segmentio/chamber)
  - Route53 alias for Atlantis
  - GitHub webhook to trigger Atlantis for a given repository

  What this module does not provision:

    - ECS Cluster (BYOC)
    - ALB
    - ACM certificate
    - VPC
    - Subnets

  ## Caveats

  - This project assumes that the repo being deployed defines a `Dockerfile` which runs `atlantis`. It might not work with the official version of atlantis. We use [`geodesic`](https://github.com/cloudposse/geodesic) as our docker base image.
  - This project defines parameters which are not available in the *official version* of `atlantis`. Our [fork](https://github.com/cloudposse/atlantis) implements the ability to restrict `plan` and `apply` to GitHub teams.


  ### GitHub Repo Scopes

  This module accepts two GitHub OAuth tokens:

  1. `github_oauth_token` with permissions to pull private repos. Used by CodePipeline to clone repos before the build, and by the atlantis server to clone repos and comment on Pull Requests.

      The token needs the following OAuth scopes:

      - `repo`
        * `repo:status`
        * `repo_deployment`
        * `public_repo`
        * `repo:invite`

  2. `github_webhooks_token` with permissions to create GitHub webhooks.
      Only used by [Terraform GitHub Provider](https://www.terraform.io/docs/providers/github/index.html) when provisioning the module.

      The token needs the following OAuth scopes:

        - `admin:repo_hook`
          * `write:repo_hook`
          * `read:repo_hook`

  We suggest the following steps when creating the tokens and provisioning the module:

  1. Create a GitHub bot user
  2. Create the two Personal Access Tokens and add them to the bot
  3. In `github.com/<org>/<repo>/settings/collaboration`, create a Team for the bot and add the bot user to it
  4. Give `Admin` permissions to the Team (select it from the dropdown). We need it temporalily to provision GitHub webhooks on the repo
  5. Provision the module with Terraform.
    [Terraform GitHub Provider](https://www.terraform.io/docs/providers/github/index.html) will use the `github_webhooks_token` to create webhooks on the repo
  6. Go to `github.com/<org>/<repo>/settings/hooks` and make sure that two webhooks have been created: one for the CodePipeline with `Releases` events,
    the other is for the `atlantis` server with `Issue comments`, `Pull request reviews`, `Pull requests`, `Pull request review comments` and `Pushes` events
  7. **IMPORTANT:** Remove the `Admin` permissions and add `Read` permissions for the bot Team.
    The CodePipeline and `atlantis` server will use the `github_oauth_token` to clone repos, which does not require escalated privileges

  **IMPORTANT:** Do not commit the tokens to source control (_e.g._ via `terraform.tvfars`).

  **NOTE:** If the two tokens are not provided (left empty), they will be looked up from SSM Parameter Store.
  You can write `atlantis atlantis_gh` and `github_webhooks_token` to SSM Parameter Store before provisioning the module.
  For example, by using [chamber](https://github.com/segmentio/chamber):

  ```sh
    chamber write atlantis atlantis_gh_token "....."
    chamber write atlantis github_webhooks_token "....."
  ```

# How to use this project
usage: |-

  For a complete example, see [examples/complete](examples/complete).

  For automated tests of the complete example using [bats](https://github.com/bats-core/bats-core) and [Terratest](https://github.com/gruntwork-io/terratest) (which tests and deploys the example on AWS), see [test](test).

  Other examples:

  - [without authentication](examples/without_authentication) - example without authentication
  - [with Google OIDC authentication](examples/with_google_oidc_authentication) - example with Google OIDC authentication
  - [with Cognito authentication](examples/with_cognito_authentication) - example with Cognito authentication


  **NOTE:**

    If no `github_oauth_token` is set, the module attempts to look one up from SSM.

    If no `github_webhooks_token` is set, [Terraform GitHub Provider](https://www.terraform.io/docs/providers/github/index.html) attempts to look one up in the `GITHUB_TOKEN` environment variable.

  ```hcl
    provider "aws" {
      region = var.region
    }

    module "label" {
      source     = "git::https://github.com/cloudposse/terraform-null-label.git?ref=tags/0.16.0"
      namespace  = var.namespace
      name       = var.name
      stage      = var.stage
      delimiter  = var.delimiter
      attributes = var.attributes
      tags       = var.tags
    }

    module "vpc" {
      source     = "git::https://github.com/cloudposse/terraform-aws-vpc.git?ref=tags/0.8.1"
      namespace  = var.namespace
      stage      = var.stage
      name       = var.name
      delimiter  = var.delimiter
      attributes = var.attributes
      cidr_block = var.vpc_cidr_block
      tags       = var.tags
    }

    module "subnets" {
      source               = "git::https://github.com/cloudposse/terraform-aws-dynamic-subnets.git?ref=tags/0.16.1"
      availability_zones   = var.availability_zones
      namespace            = var.namespace
      stage                = var.stage
      name                 = var.name
      attributes           = var.attributes
      delimiter            = var.delimiter
      vpc_id               = module.vpc.vpc_id
      igw_id               = module.vpc.igw_id
      cidr_block           = module.vpc.vpc_cidr_block
      nat_gateway_enabled  = true
      nat_instance_enabled = false
      tags                 = var.tags
    }

    module "alb" {
      source                                  = "git::https://github.com/cloudposse/terraform-aws-alb.git?ref=tags/0.7.0"
      namespace                               = var.namespace
      stage                                   = var.stage
      name                                    = var.name
      attributes                              = var.attributes
      delimiter                               = var.delimiter
      vpc_id                                  = module.vpc.vpc_id
      security_group_ids                      = [module.vpc.vpc_default_security_group_id]
      subnet_ids                              = module.subnets.public_subnet_ids
      internal                                = false
      http_enabled                            = true
      access_logs_enabled                     = false
      alb_access_logs_s3_bucket_force_destroy = true
      access_logs_region                      = var.region
      cross_zone_load_balancing_enabled       = true
      http2_enabled                           = true
      deletion_protection_enabled             = false
      tags                                    = var.tags
    }

    resource "aws_ecs_cluster" "default" {
      name = module.label.id
      tags = module.label.tags
    }

    resource "aws_sns_topic" "sns_topic" {
      name         = module.label.id
      display_name = "Test terraform-aws-ecs-atlantis"
      tags         = module.label.tags
    }

    module "kms_key" {
      source                  = "git::https://github.com/cloudposse/terraform-aws-kms-key.git?ref=tags/0.3.0"
      enabled                 = var.enabled
      namespace               = var.namespace
      stage                   = var.stage
      name                    = var.name
      attributes              = var.attributes
      delimiter               = var.delimiter
      tags                    = var.tags
      description             = "Test terraform-aws-ecs-atlantis KMS key"
      deletion_window_in_days = 7
      enable_key_rotation     = false
    }

    module "atlantis" {
      source = "cloudposse/ecs-atlantis/aws"
      # Cloud Posse recommends pinning every module to a specific version
      # version = "x.x.x"
      enabled    = var.enabled
      namespace  = var.namespace
      stage      = var.stage
      name       = var.name
      attributes = var.attributes
      delimiter  = var.delimiter
      tags       = var.tags

      region               = var.region
      vpc_id               = module.vpc.vpc_id
      policy_arn           = var.policy_arn
      ssh_private_key_name = var.ssh_private_key_name
      ssh_public_key_name  = var.ssh_public_key_name
      kms_key_id           = module.kms_key.key_id

      atlantis_gh_user           = var.atlantis_gh_user
      atlantis_gh_team_whitelist = var.atlantis_gh_team_whitelist
      atlantis_gh_webhook_secret = var.atlantis_gh_webhook_secret
      atlantis_log_level         = var.atlantis_log_level
      atlantis_repo_config       = var.atlantis_repo_config
      atlantis_repo_whitelist    = var.atlantis_repo_whitelist
      atlantis_port              = var.atlantis_port
      atlantis_webhook_format    = var.atlantis_webhook_format
      atlantis_url_format        = var.atlantis_url_format

      default_backend_image = var.default_backend_image
      healthcheck_path      = var.healthcheck_path
      short_name            = var.short_name
      hostname              = var.hostname
      parent_zone_id        = var.parent_zone_id

      // Container
      container_cpu    = var.container_cpu
      container_memory = var.container_memory

      // Authentication
      authentication_type                           = var.authentication_type
      alb_ingress_listener_unauthenticated_priority = var.alb_ingress_listener_unauthenticated_priority
      alb_ingress_listener_authenticated_priority   = var.alb_ingress_listener_authenticated_priority
      alb_ingress_unauthenticated_hosts             = var.alb_ingress_unauthenticated_hosts
      alb_ingress_authenticated_hosts               = var.alb_ingress_authenticated_hosts
      alb_ingress_unauthenticated_paths             = var.alb_ingress_unauthenticated_paths
      alb_ingress_authenticated_paths               = var.alb_ingress_authenticated_paths
      authentication_cognito_user_pool_arn          = var.authentication_cognito_user_pool_arn
      authentication_cognito_user_pool_client_id    = var.authentication_cognito_user_pool_client_id
      authentication_cognito_user_pool_domain       = var.authentication_cognito_user_pool_domain
      authentication_oidc_client_id                 = var.authentication_oidc_client_id
      authentication_oidc_client_secret             = var.authentication_oidc_client_secret
      authentication_oidc_issuer                    = var.authentication_oidc_issuer
      authentication_oidc_authorization_endpoint    = var.authentication_oidc_authorization_endpoint
      authentication_oidc_token_endpoint            = var.authentication_oidc_token_endpoint
      authentication_oidc_user_info_endpoint        = var.authentication_oidc_user_info_endpoint

      // ECS
      private_subnet_ids = module.subnets.private_subnet_ids
      ecs_cluster_arn    = aws_ecs_cluster.default.arn
      ecs_cluster_name   = aws_ecs_cluster.default.name
      security_group_ids = var.security_group_ids
      desired_count      = var.desired_count
      launch_type        = var.launch_type

      // ALB
      alb_zone_id                                     = module.alb.alb_zone_id
      alb_arn_suffix                                  = module.alb.alb_arn_suffix
      alb_dns_name                                    = module.alb.alb_dns_name
      alb_security_group                              = module.alb.security_group_id
      alb_ingress_unauthenticated_listener_arns       = [module.alb.http_listener_arn]
      alb_ingress_unauthenticated_listener_arns_count = 1

      // CodePipeline
      codepipeline_enabled                 = var.codepipeline_enabled
      github_oauth_token                   = var.github_oauth_token
      github_webhooks_token                = var.github_webhooks_token
      repo_owner                           = var.repo_owner
      repo_name                            = var.repo_name
      branch                               = var.branch
      build_timeout                        = var.build_timeout
      webhook_enabled                      = var.webhook_enabled
      webhook_secret_length                = var.webhook_secret_length
      webhook_events                       = var.webhook_events
      codepipeline_s3_bucket_force_destroy = var.codepipeline_s3_bucket_force_destroy

      // Autoscaling
      autoscaling_enabled      = var.autoscaling_enabled
      autoscaling_min_capacity = var.autoscaling_min_capacity
      autoscaling_max_capacity = var.autoscaling_max_capacity

      // Alarms
      alb_target_group_alarms_enabled                   = var.alb_target_group_alarms_enabled
      ecs_alarms_enabled                                = var.ecs_alarms_enabled
      alb_target_group_alarms_alarm_actions             = [aws_sns_topic.sns_topic.arn]
      alb_target_group_alarms_ok_actions                = [aws_sns_topic.sns_topic.arn]
      alb_target_group_alarms_insufficient_data_actions = [aws_sns_topic.sns_topic.arn]
      ecs_alarms_cpu_utilization_high_alarm_actions     = [aws_sns_topic.sns_topic.arn]
      ecs_alarms_cpu_utilization_high_ok_actions        = [aws_sns_topic.sns_topic.arn]
      ecs_alarms_cpu_utilization_low_alarm_actions      = [aws_sns_topic.sns_topic.arn]
      ecs_alarms_cpu_utilization_low_ok_actions         = [aws_sns_topic.sns_topic.arn]
      ecs_alarms_memory_utilization_high_alarm_actions  = [aws_sns_topic.sns_topic.arn]
      ecs_alarms_memory_utilization_high_ok_actions     = [aws_sns_topic.sns_topic.arn]
      ecs_alarms_memory_utilization_low_alarm_actions   = [aws_sns_topic.sns_topic.arn]
      ecs_alarms_memory_utilization_low_ok_actions      = [aws_sns_topic.sns_topic.arn]
    }
  ```

# Example usage
#examples: |-
#  Example goes here...

# 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"

references:
  - name: "atlantis"
    description: "Official home of the Atlantis project"
    url: "https://runatlantis.io"

# Contributors to this project
contributors:
  - name: "Josh Myers"
    github: "joshmyers"
  - name: "Erik Osterman"
    github: "osterman"
  - name: "Andriy Knysh"
    github: "aknysh"
  - name: "Igor Rodionov"
    github: "goruha"