terraform-aws-modules · bryantbiggs · Nov 4, 2023 · Aug 15, 2023 · Nov 3, 2023 · antonbabenko
diff --git a/.github/.gitkeep b/.github/.gitkeep
diff --git a/.gitignore b/.gitignore
@@ -1,3 +1,5 @@
+.DS_Store
+
 # Local .terraform directories
 **/.terraform/*
 
@@ -7,6 +9,7 @@
 # .tfstate files
 *.tfstate
 *.tfstate.*
+*.tfplan
 
 # Crash log files
 crash.log

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -1,6 +1,6 @@
 repos:
   - repo: https://github.com/antonbabenko/pre-commit-terraform
-    rev: v1.76.0
+    rev: v1.83.5
     hooks:
       - id: terraform_fmt
       - id: terraform_validate
@@ -23,6 +23,6 @@ repos:
           - '--args=--only=terraform_standard_module_structure'
           - '--args=--only=terraform_workspace_remote'
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.3.0
+    rev: v4.5.0
     hooks:
       - id: check-merge-conflict
diff --git a/README.md b/README.md
diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,57 @@
+# Supplemental Documentation
+
+## GitHub
+
+### Authenticated Access via GitHub App
+
+A [GitHub App](https://docs.github.com/en/apps/creating-github-apps/about-creating-github-apps/about-creating-github-apps) can be generated to provide Atlantis access instead of using a GitHub personal access token (PAT):
+
+1. Create a GitHub App and give it a name - that name must be globally unique, and you can change it later if needed.
+2. Provide a valid Homepage URL - this can be the atlantis server url, for instance `https://atlantis.mydomain.com`
+3. Provide a valid [Webhook URL](https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/using-webhooks-with-github-apps). The Atlantis webhook server path is located by default at `https://atlantis.mydomain.com/events`.
+4. Generate a [Webhook Secret](https://docs.github.com/en/webhooks/using-webhooks/validating-webhook-deliveries). This is the value supplied to the `ATLANTIS_GH_WEBHOOK_SECRET` in the Atlantis server configuration.
+5. Generate a Private Key. This is the value supplied to the `ATLANTIS_GH_APP_KEY` in the Atlantis server configuration.
+6. On the App's settings page (at the top) you find the App ID. This is the value supplied to `ATLANTIS_GH_APP_ID` in the Atlantis server configuration.
+7. On the Permissions & Events you need to setup all the permissions and events according to [Atlantis documentation](https://www.runatlantis.io/docs/access-credentials.html#github-app)
+
+Now you need to [install the App](https://docs.github.com/en/apps/using-github-apps/installing-your-own-github-app) on your organization.
+
+A self-provisioned GitHub App usually has two parts: the App and the Installation.
+
+The App part is the first step and its where you setup all the requirements, such as authentication, webhook, permissions, etc... The Installation part is where you add the created App to an organization/personal-account. It is on the installation page where you setup which repositories the application can access and receive events from.
+
+Once you have your GitHub App registered you will be able to access/manage the required parameters either through `environment` or `secret` (we strongly suggest supplying these through `secret`):
+
+```hcl
+module "atlantis" {
+  source  = "terraform-aws-modules/atlantis/aws"
+
+  # Truncated for brevity ...
+
+  # ECS Container Definition
+  atlantis = {
+    secrets = [
+      {
+        name      = "ATLANTIS_GH_APP_ID"
+        valueFrom = "<SECRETSMANAGER_ARN>"
+      },
+      {
+        name      = "ATLANTIS_GH_APP_KEY"
+        valueFrom =  "<SECRETSMANAGER_ARN>"
+      },
+      {
+        name      = "ATLANTIS_GH_WEBHOOK_SECRET"
+        valueFrom =  "<SECRETSMANAGER_ARN>"
+      },
+    ]
+  }
+}
+```
+
+## GitLab
+
+> TODO
+
+## BitBucket
+
+> TODO
diff --git a/examples/README.md b/examples/README.md
@@ -0,0 +1,8 @@
+# Examples
+
+Please note - the examples provided serve two primary means:
+
+1. Show users working examples of the various ways in which the module can be configured and features supported
+2. A means of testing/validating module changes
+
+Please do not mistake the examples provided as "best practices". It is up to users to consult the AWS service documentation for best practices, usage recommendations, etc.
diff --git a/examples/github-complete/README.md b/examples/github-complete/README.md
@@ -1,86 +1,70 @@
-# Complete Atlantis example with GitHub App and Webhooks
+# Complete GitHub example
 
-Configuration in this directory creates the necessary infrastructure and resources for running Atlantis on Fargate plus GitHub repository webhooks configured to Atlantis URL.
-
-An existing Route53 hosted zone and domain is required to deploy this example.
+Configuration in this directory provisions Atlantis on ECS with EFS storage, ALB, Route53 record and GitHub repository webhooks.
 
 ## Usage
 
 To run this code you need to copy `terraform.tfvars.sample` into `terraform.tfvars` and update the values locally or specify them using environment variables (`TF_VAR_github_app_id=xxx`, `TF_VAR_github_owner=xxx`, etc.). Ensure that `bootstrap_github_app` is `true`.  Once ready, execute:
 
 ```bash
-$ terraform init
-$ terraform plan
-$ terraform apply
+terraform init
+terraform plan
+terraform apply
 ```
 
-Terraform will output a URL to setup a new Github App via Atlantis, which should look something like https://$ATLANTIS_HOST/github-app/setup. Open that URL and go through the setup process. Before closing the window, click the link to install the new GitHub App on you repositories and copy the values `github_app_id`, `github_app_key`, and `github_webhook_secret` into `terraform.tfvars`. You should also set `bootstrap_github_app` to `false` . Now execute:
-
-```bash
-$ terraform plan
-$ terraform apply
-
-```
-
-Note - if you receive the following error when running apply:
-
-`Error: InvalidParameterException: The new ARN and resource ID format must be enabled to add tags to the service. Opt in to the new format and try again. "atlantiscomplete"`
-
-Go to https://eu-west-1.console.aws.amazon.com/ecs/home?region=eu-west-1#/settings (update for your region of use) and change `Container instance`, `Service`, and `Task` to `Enabled`.
-
-⚠️ This example will create resources which cost money. Run `terraform destroy` when you don't need these resources. ⚠️
+Note that this example may create resources which cost money. Run `terraform destroy` when you don't need these resources.
 
 <!-- BEGINNING OF PRE-COMMIT-TERRAFORM DOCS HOOK -->
 ## Requirements
 
 | Name | Version |
 |------|---------|
-| <a name="requirement_terraform"></a> [terraform](#requirement\_terraform) | >= 0.13.1 |
-| <a name="requirement_aws"></a> [aws](#requirement\_aws) | >= 3.69 |
-| <a name="requirement_github"></a> [github](#requirement\_github) | >= 4.8 |
+| <a name="requirement_terraform"></a> [terraform](#requirement\_terraform) | >= 1.0 |
+| <a name="requirement_aws"></a> [aws](#requirement\_aws) | >= 5.0 |
+| <a name="requirement_github"></a> [github](#requirement\_github) | >= 5.0 |
+| <a name="requirement_random"></a> [random](#requirement\_random) | >= 3.0 |
 
 ## Providers
 
 | Name | Version |
 |------|---------|
-| <a name="provider_aws"></a> [aws](#provider\_aws) | >= 3.69 |
+| <a name="provider_aws"></a> [aws](#provider\_aws) | >= 5.0 |
+| <a name="provider_random"></a> [random](#provider\_random) | >= 3.0 |
 
 ## Modules
 
 | Name | Source | Version |
 |------|--------|---------|
 | <a name="module_atlantis"></a> [atlantis](#module\_atlantis) | ../../ | n/a |
-| <a name="module_atlantis_access_log_bucket"></a> [atlantis\_access\_log\_bucket](#module\_atlantis\_access\_log\_bucket) | terraform-aws-modules/s3-bucket/aws | ~> 3.0 |
+| <a name="module_github_repository_webhooks"></a> [github\_repository\_webhooks](#module\_github\_repository\_webhooks) | ../../modules/github-repository-webhook | n/a |
+| <a name="module_secrets_manager"></a> [secrets\_manager](#module\_secrets\_manager) | terraform-aws-modules/secrets-manager/aws | ~> 1.0 |
+| <a name="module_vpc"></a> [vpc](#module\_vpc) | terraform-aws-modules/vpc/aws | ~> 5.0 |
 
 ## Resources
 
 | Name | Type |
 |------|------|
-| [aws_caller_identity.current](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/caller_identity) | data source |
-| [aws_elb_service_account.current](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/elb_service_account) | data source |
-| [aws_iam_policy_document.atlantis_access_log_bucket_policy](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/iam_policy_document) | data source |
-| [aws_region.current](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/region) | data source |
+| [random_password.webhook_secret](https://registry.terraform.io/providers/hashicorp/random/latest/docs/resources/password) | resource |
+| [aws_availability_zones.available](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/availability_zones) | data source |
+| [aws_route53_zone.this](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/route53_zone) | data source |
 
 ## Inputs
 
 | Name | Description | Type | Default | Required |
 |------|-------------|------|---------|:--------:|
-| <a name="input_alb_ingress_cidr_blocks"></a> [alb\_ingress\_cidr\_blocks](#input\_alb\_ingress\_cidr\_blocks) | List of IPv4 CIDR ranges to use on all ingress rules of the ALB - use your personal IP in the form of `x.x.x.x/32` for restricted testing | `list(string)` | n/a | yes |
-| <a name="input_bootstrap_github_app"></a> [bootstrap\_github\_app](#input\_bootstrap\_github\_app) | Flag to configure Atlantis to bootstrap a new Github App | `bool` | n/a | yes |
+| <a name="input_atlantis_github_user"></a> [atlantis\_github\_user](#input\_atlantis\_github\_user) | GitHub user or organization name | `string` | n/a | yes |
+| <a name="input_atlantis_repo_allowlist"></a> [atlantis\_repo\_allowlist](#input\_atlantis\_repo\_allowlist) | List of GitHub repositories that Atlantis will be allowed to access | `list(string)` | n/a | yes |
 | <a name="input_domain"></a> [domain](#input\_domain) | Route53 domain name to use for ACM certificate. Route53 zone for this domain should be created in advance | `string` | n/a | yes |
-| <a name="input_github_app_id"></a> [github\_app\_id](#input\_github\_app\_id) | GitHub App ID that is running the Atlantis command | `string` | n/a | yes |
-| <a name="input_github_app_key"></a> [github\_app\_key](#input\_github\_app\_key) | The PEM encoded private key for the GitHub App | `string` | n/a | yes |
-| <a name="input_github_owner"></a> [github\_owner](#input\_github\_owner) | Github owner | `string` | n/a | yes |
-| <a name="input_github_repo_names"></a> [github\_repo\_names](#input\_github\_repo\_names) | List of Github repositories that should be monitored by Atlantis | `list(string)` | n/a | yes |
-| <a name="input_github_webhook_secret"></a> [github\_webhook\_secret](#input\_github\_webhook\_secret) | Webhook secret | `string` | n/a | yes |
+| <a name="input_github_owner"></a> [github\_owner](#input\_github\_owner) | Github owner to use when creating webhook | `string` | n/a | yes |
+| <a name="input_github_token"></a> [github\_token](#input\_github\_token) | Github token to use when creating webhook | `string` | n/a | yes |
 
 ## Outputs
 
 | Name | Description |
 |------|-------------|
-| <a name="output_atlantis_github_app_setup_url"></a> [atlantis\_github\_app\_setup\_url](#output\_atlantis\_github\_app\_setup\_url) | URL to create a new Github App with Atlantis |
-| <a name="output_atlantis_repo_allowlist"></a> [atlantis\_repo\_allowlist](#output\_atlantis\_repo\_allowlist) | Git repositories where webhook should be created |
+| <a name="output_alb"></a> [alb](#output\_alb) | ALB created and all of its associated outputs |
 | <a name="output_atlantis_url"></a> [atlantis\_url](#output\_atlantis\_url) | URL of Atlantis |
-| <a name="output_ecs_task_definition"></a> [ecs\_task\_definition](#output\_ecs\_task\_definition) | Task definition for ECS service (used for external triggers) |
-| <a name="output_task_role_arn"></a> [task\_role\_arn](#output\_task\_role\_arn) | The Atlantis ECS task role arn |
+| <a name="output_cluster"></a> [cluster](#output\_cluster) | ECS cluster created and all of its associated outputs |
+| <a name="output_efs"></a> [efs](#output\_efs) | EFS created and all of its associated outputs |
+| <a name="output_service"></a> [service](#output\_service) | ECS service created and all of its associated |
 <!-- END OF PRE-COMMIT-TERRAFORM DOCS HOOK -->