Initial implementation of Atlantis ECS module (#1)

* Initial implementation of Atlantis ECS module * add images * Add disclaimers * Add example
cloudposse-archives · Jan 18, 2019 · 04cd4bb · 04cd4bb
1 parent 0f0b161
commit 04cd4bb
Show file tree

Hide file tree

Showing 9 changed files with 1,032 additions and 7 deletions.
diff --git a/README.md b/README.md
@@ -6,7 +6,9 @@
 # terraform-aws-ecs-atlantis [![Build Status](https://travis-ci.org/cloudposse/terraform-aws-ecs-atlantis.svg?branch=master)](https://travis-ci.org/cloudposse/terraform-aws-ecs-atlantis) [![Latest Release](https://img.shields.io/github/release/cloudposse/terraform-aws-ecs-atlantis.svg)](https://github.com/cloudposse/terraform-aws-ecs-atlantis/releases/latest) [![Slack Community](https://slack.cloudposse.com/badge.svg)](https://slack.cloudposse.com)
 
 
-A Terraform module for deploying Atlantis to an AWS ECS cluster.
+![terraform-aws-ecs-atlantis](docs/logo.png)
+
+A Terraform module for deploying [Atlantis](https://runatlantis.io) to an AWS ECS cluster.
 
 
 ---
@@ -20,6 +22,8 @@ This project is part of our comprehensive ["SweetOps"](https://cpco.io/sweetops)
 [<img align="right" title="Share on Twitter" src="https://docs.cloudposse.com/images/ionicons/social-twitter-outline-2.0.1-16x16-999999.svg" />][share_twitter]
 
 
+[![Terraform Open Source Modules](https://docs.cloudposse.com/images/terraform-open-source-modules.svg)][terraform_modules]
+
 
 
 It's 100% Open Source and licensed under the [APACHE2](LICENSE).
@@ -30,16 +34,109 @@ It's 100% Open Source and licensed under the [APACHE2](LICENSE).
 
 
 
+We literally have [*hundreds of terraform modules*][terraform_modules] that are Open Source and well-maintained. Check them out! 
+
+
+
+
+
+## Screenshots
+
+
+![demo](docs/example.png)
+*Example of a Pull Request comment from running `terraform plan` using `atlantis`*
+
+
+## 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
+
+We suggest creating a personal access token for a GitHub bot user with the following scopes:
+
+  - `repo`
+    * `repo:status`
+    * `repo_deployment`
+    * `public_repo`
+    * `repo:invite`
+  - `admin:repo_hook`
+    * `write:repo_hook`
+    * `read:repo_hook`
+
+![GitHub Repo Scopes](docs/github-repo-scopes.png)
+
+**IMPORTANT:** Do not commit this `github_oauth_token` to source control (e.g. via `terraform.tvfars`). 
 
 ## Usage
 
+
+**NOTE:** if no `github_oauth_token` is set, this module attempts to look one up from SSM. 
+
 ```
-TODO
+module "atlantis" {
+  source = "git::https://github.com/cloudposse/terraform-aws-ecs-atlantis.git?ref=master"
+  enabled   = "true"
+  name      = "${var.name}"
+  namespace = "${var.namespace}"
+  region    = "${var.region}"
+  stage     = "${var.stage}"
+
+  atlantis_gh_team_whitelist = "admins:*,engineering:plan"
+  atlantis_gh_user           = "atlantis_bot"
+  atlantis_repo_whitelist    = ["github.com/testing.example.co/*"]
+
+  alb_arn_suffix    = "${module.alb.alb_arn_suffix}"
+  alb_dns_name      = "${module.alb.alb_dns_name}"
+  alb_listener_arns = ["${module.alb.listener_arns}"]
+  alb_name          = "${module.alb.alb_name}"
+  alb_zone_id       = "${module.alb.alb_zone_id}"
+
+  domain_name        = "${var.domain_name}"
+  ecs_cluster_arn    = "${aws_ecs_cluster.default.arn}"
+  ecs_cluster_name   = "${aws_ecs_cluster.default.name}"
+  repo_name          = "testing.example.co"
+  repo_owner         = "example_org"
+  private_subnet_ids = ["${module.subnets.private_subnet_ids}"]
+  security_group_ids = ["${module.vpc.vpc_default_security_group_id}"]
+  vpc_id             = "${module.vpc.vpc_id}"
 }
 ```
 
@@ -58,6 +155,74 @@ Available targets:
   lint                                Lint terraform code
 
 ```
+## Inputs
+
+| Name | Description | Type | Default | Required |
+|------|-------------|:----:|:-----:|:-----:|
+| alb_arn_suffix | The ARN suffix of the ALB | string | - | yes |
+| alb_dns_name | DNS name of ALB | string | - | yes |
+| alb_ingress_paths | Path pattern to match (a maximum of 1 can be defined), at least one of hosts or paths must be set | list | `<list>` | no |
+| alb_listener_arns | A list of ALB listener ARNs | list | - | yes |
+| alb_name | The Name of the ALB | string | - | yes |
+| alb_target_group_alarms_alarm_actions | A list of ARNs (i.e. SNS Topic ARN) to execute when ALB Target Group alarms transition into an ALARM state from any other state. | list | `<list>` | no |
+| alb_target_group_alarms_insufficient_data_actions | A list of ARNs (i.e. SNS Topic ARN) to execute when ALB Target Group alarms transition into an INSUFFICIENT_DATA state from any other state. | list | `<list>` | no |
+| alb_target_group_alarms_ok_actions | A list of ARNs (i.e. SNS Topic ARN) to execute when ALB Target Group alarms transition into an OK state from any other state. | list | `<list>` | no |
+| alb_zone_id | The ID of the zone in which ALB is provisioned | string | - | yes |
+| atlantis_allow_repo_config | Allow Atlantis to use atlantis.yaml | string | `true` | no |
+| atlantis_gh_team_whitelist | Atlantis GitHub team whitelist | string | `` | no |
+| atlantis_gh_user | Atlantis GitHub user | string | - | yes |
+| atlantis_gh_webhook_secret | Atlantis GitHub webhook secret | string | `` | no |
+| atlantis_log_level | Atlantis log level | string | `info` | no |
+| atlantis_port | Atlantis container port | string | `4141` | no |
+| atlantis_repo_config | Path to atlantis config file | string | `atlantis.yaml` | no |
+| atlantis_repo_whitelist | Whitelist of repositories Atlantis will accept webhooks from | list | `<list>` | no |
+| atlantis_wake_word | Wake world for Atlantis | string | `atlantis` | no |
+| atlantis_webhook_format | Template for the Atlantis webhook URL which is populated with the hostname | string | `https://%s/events` | no |
+| attributes | Additional attributes (e.g. `1`) | list | `<list>` | no |
+| autoscaling_max_capacity | Atlantis maximum tasks to run | string | `1` | no |
+| autoscaling_min_capacity | Atlantis minimum tasks to run | string | `1` | no |
+| branch | Atlantis branch of the GitHub repository, _e.g._ `master` | string | `master` | no |
+| build_timeout | How long in minutes, from 5 to 480 (8 hours), for AWS CodeBuild to wait until timing out any related build that does not get marked as completed. | string | `5` | no |
+| chamber_format | Format to store parameters in SSM, for consumption with chamber | string | `/%s/%s` | no |
+| chamber_service | SSM parameter service name for use with chamber. This is used in chamber_format where /$chamber_service/$parameter would be the default. | string | `atlantis` | no |
+| container_cpu | Atlantis CPUs per task | string | `256` | no |
+| container_memory | Atlantis memory per task | string | `512` | no |
+| default_backend_image | ECS default (bootstrap) image | string | `cloudposse/default-backend:0.1.2` | no |
+| delimiter | Delimiter to be used between `namespace`, `stage`, `name` and `attributes` | string | `-` | no |
+| desired_count | Atlantis desired number of tasks | string | `1` | no |
+| domain_name | A domain name for which the certificate should be issued | string | - | yes |
+| ecs_cluster_arn | ARN of the ECS cluster to deploy Atlantis | string | - | yes |
+| ecs_cluster_name | Name of the ECS cluster to deploy Atlantis | string | - | yes |
+| enabled | Whether to create the resources. Set to `false` to prevent the module from creating any resources | string | `false` | no |
+| github_oauth_token | GitHub Oauth token. If not provided the token is looked up from SSM. | string | `` | no |
+| github_oauth_token_ssm_name | SSM param name to lookup GitHub OAuth token if not provided | string | `` | no |
+| healthcheck_path | Healthcheck path | string | `/healthz` | no |
+| hostname | Atlantis URL | string | `` | no |
+| kms_key_id | KMS key ID used to encrypt SSM SecureString parameters | string | `` | no |
+| name | Application or solution name (e.g. `app`) | string | `ecs` | no |
+| namespace | Namespace (e.g. `eg` or `cp`) | string | - | yes |
+| overwrite_ssm_parameter | Whether to overwrite an existing SSM parameter | string | `true` | no |
+| policy_arn | Permission to grant to atlantis server | string | `arn:aws:iam::aws:policy/AdministratorAccess` | no |
+| private_subnet_ids | The private subnet IDs | list | `<list>` | no |
+| region | AWS Region for Atlantis deployment | string | `us-west-2` | no |
+| repo_name | GitHub repository name of the atlantis to be built and deployed to ECS. | string | - | yes |
+| repo_owner | GitHub organization containing the Atlantis repository | string | - | yes |
+| security_group_ids | Additional Security Group IDs to allow into ECS Service. | list | `<list>` | no |
+| short_name | Alantis Short DNS name (E.g. `atlantis`) | string | `atlantis` | no |
+| ssh_private_key_name | Atlantis SSH private key name | string | `atlantis_ssh_private_key` | no |
+| ssh_public_key_name | Atlantis SSH public key name | string | `atlantis_ssh_public_key` | no |
+| stage | Stage (e.g. `prod`, `dev`, `staging`) | string | - | yes |
+| tags | Additional tags (e.g. map(`BusinessUnit`,`XYZ`) | map | `<map>` | no |
+| vpc_id | VPC ID for the ECS Cluster | string | - | yes |
+| webhook_events | A list of events which should trigger the webhook. | list | `<list>` | no |
+| webhook_secret_length | GitHub webhook secret length | string | `32` | no |
+
+## Outputs
+
+| Name | Description |
+|------|-------------|
+| atlantis_ssh_public_key | Atlantis SSH Public Key |
+| badge_url | the url of the build badge when badge_enabled is enabled |
 
 
 
@@ -73,8 +238,8 @@ Are you using this project or any of our other projects? Consider [leaving a tes
 
 Check out these related projects.
 
-- [terraform-aws-ecs-webapp](https://github.com/cloudposse/terraform-aws-ecs-web-app) - Terraform module that implements a web app on ECS and supports autoscaling, CI/CD, monitoring, ALB integration, and much more
-- [terraform-aws-ecs-web-app](https://github.com/cloudposse/terraform-aws-alb) - Terraform module to provision a standard ALB for HTTP/HTTP traffic
+- [terraform-aws-ecs-web-app](https://github.com/cloudposse/terraform-aws-ecs-web-app) - Terraform module that implements a web app on ECS and supporting AWS resources
+- [terraform-aws-alb](https://github.com/cloudposse/terraform-aws-alb) - Terraform module to provision a standard ALB for HTTP/HTTP traffic
 - [terraform-aws-alb-ingress](https://github.com/cloudposse/terraform-aws-alb-ingress) - Terraform module to provision an HTTP style ingress rule based on hostname and path for an ALB
 - [terraform-aws-codebuild](https://github.com/cloudposse/terraform-aws-codebuild) - Terraform Module to easily leverage AWS CodeBuild for Continuous Integration
 - [terraform-aws-ecr](https://github.com/cloudposse/terraform-aws-ecr) - Terraform Module to manage Docker Container Registries on AWS ECR
@@ -85,6 +250,14 @@ Check out these related projects.
 
 
 
+
+## References
+
+For additional context, refer to some of these links. 
+
+- [atlantis](https://runatlantis.io) - Official home of the Atlantis project
+
+
 ## Help
 
 **Got a question?**
@@ -111,6 +284,10 @@ We provide [*commercial support*][commercial_support] for all of our [Open Sourc
 
 
 
+## Terraform Module Development
+
+Are you interested in custom Terraform module development? Submit your inquiry using [our form][module_development] today and we'll get back to you ASAP.
+
 
 ## Slack Community