AWS Terraform module which runs Atlantis on AWS Fargate

Atlantis is tool which provides unified workflow for collaborating on Terraform through GitHub, GitLab and Bitbucket Cloud.

This repository contains Terraform infrastructure code which creates AWS resources required to run Atlantis on AWS, including:

• Virtual Private Cloud (VPC)
• SSL certificate using Amazon Certificate Manager (ACM)
• Application Load Balancer (ALB)
• Domain name using AWS Route53 which points to ALB
• AWS Elastic Container Service (ECS) and AWS Fargate running Atlantis Docker image
• AWS Parameter Store to keep secrets and access them in ECS task natively

AWS Fargate with optional support for Fargate Spot is used to reduce the bill, and it is also a cool AWS service.

Depending on which SCM system you use, Github repositories or Gitlab projects has to be configured to post events to Atlantis webhook URL.

See README.md in examples for Github or Gitlab for complete details.

Before using Atlantis and the code in this repository please make sure that you have read and understood the security implications described in the official Atlantis documentation.

How to use this?

As often with the code published in terraform-aws-modules GitHub organization you should have everything to run this code and get Atlantis up and running.

There are three ways to do this:

1. As a standalone project
2. As a Terraform module
3. As a part of an existing AWS infrastructure

Run Atlantis as a standalone project

1. Clone this github repository:

$ git clone [email protected]:terraform-aws-modules/terraform-aws-atlantis.git
$ cd terraform-aws-atlantis

2. Copy sample terraform.tfvars.sample into terraform.tfvars and specify required variables there.

3. Run terraform init to download required providers and modules.

4. Run terraform apply to apply the Terraform configuration and create required infrastructure.

5. Run terraform output atlantis_url to get URL where Atlantis is publicly reachable. (Note: It may take a minute or two to get it reachable for the first time)

6. Github webhook is automatically created if github_token, github_owner and github_repo_names were specified. Read Add GitHub Webhook in the official Atlantis documentation or check example "GitHub repository webhook for Atlantis" to add more webhooks.

Run Atlantis as a Terraform module

This way allows integration with your existing Terraform configurations.

module "atlantis" {
  source  = "terraform-aws-modules/atlantis/aws"
  version = "~> 3.0"

  name = "atlantis"

  # VPC
  cidr            = "10.20.0.0/16"
  azs             = ["eu-west-1a", "eu-west-1b", "eu-west-1c"]
  private_subnets = ["10.20.1.0/24", "10.20.2.0/24", "10.20.3.0/24"]
  public_subnets  = ["10.20.101.0/24", "10.20.102.0/24", "10.20.103.0/24"]

  # DNS (without trailing dot)
  route53_zone_name = "example.com"

  # ACM (SSL certificate) - Specify ARN of an existing certificate or new one will be created and validated using Route53 DNS
  certificate_arn = "arn:aws:acm:eu-west-1:135367859851:certificate/70e008e1-c0e1-4c7e-9670-7bb5bd4f5a84"

  # Atlantis
  atlantis_github_app_id     = "1234567"
  atlantis_github_app_key    = "-----BEGIN RSA PRIVATE KEY-----(...)"
  atlantis_repo_allowlist    = ["github.com/terraform-aws-modules/*"]
}

Provide Atlantis with server yaml configuration

server-atlantis.yaml

repos:
  - id: /.*/
    allow_custom_workflows: true
    allowed_overrides:
      - apply_requirements
      - workflow
    apply_requirements:
      - approved
    workflow: default

main.tf

module "atlantis" {
  source  = "terraform-aws-modules/atlantis/aws"

  # ...

  custom_environment_variables = [
    {
      name : "ATLANTIS_REPO_CONFIG_JSON",
      value : jsonencode(yamldecode(file("${path.module}/server-atlantis.yaml"))),
    },
  ]

  # ...
}

Run Atlantis as a part of an existing AWS infrastructure (use existing VPC)

This way allows integration with your existing AWS resources - VPC, public and private subnets. Specify the following arguments (see methods described above):

vpc_id             = "vpc-1651acf1"
private_subnet_ids = ["subnet-1fe3d837", "subnet-129d66ab"]
public_subnet_ids  = ["subnet-1211eef5", "subnet-163466ab"]

If vpc_id is specified it will take precedence over cidr and existing VPC will be used. private_subnet_ids and public_subnet_ids must be specified also.

Make sure that both private and public subnets were created in the same set of availability zones (ALB will be created in public subnets, ECS Fargate service in private subnets).

If all provided subnets are public (no NAT gateway) then ecs_service_assign_public_ip should be set to true.

Using GitHub App

An Atlantis GitHub App can be generated using multiple methods:

• You can follow Atlantis instructions depicted here. The Atlantis method mostly automates the GitHub App generation using GitHub App Manifest, but you need an exposed endpoint to complete the process.
• The other method is to manually create the GitHub App as instructed here.

1. You create a GitHub App and give it a name - that name must be unique across the world (you can change it later).
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. The Atlantis webhook server path is located by default at https://atlantis.mydomain.com/events
4. Generate a Webhook Secret - this is used for Atlantis to trust the deliveries. This is your github_webhook_secret.
5. Generate a Private Key - this is your github_app_key
6. On the App's settings page (at the top) you find the App ID. This is your github_app_id
7. On the Permissions & Events you need to setup all the permissions and events according to Atlantis documentation

Now you need to install the 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:

• atlantis_github_app_id to identify the GitHub app.
• atlantis_github_app_key to interact with GitHub.
• atlantis_github_webhook_secret to receive and validate incoming webhook invocations from GitHub.

GitHub Personal Access Token (PAT) is no longer recommended

While still supported, the use of GitHub Personal Access Token (PAT) is no longer the recommended method in favor of GitHub App.

GitHub Apps provide more control over repository access/permissions and does not require the use of bot accounts.

Secure Atlantis with ALB Built-in Authentication

OpenID Connect (OIDC)

You can use service like Auth0 to secure access to Atlantis and require authentication on ALB. To enable this, you need to create Auth0 application and provide correct arguments to Atlantis module. Make sure to update application hostname, client id and client secret:

Read more in this post.

Auth0

alb_authenticate_oidc = {
  issuer                              = "https://youruser.eu.auth0.com/"
  token_endpoint                      = "https://youruser.eu.auth0.com/oauth/token"
  user_info_endpoint                  = "https://youruser.eu.auth0.com/userinfo"
  authorization_endpoint              = "https://youruser.eu.auth0.com/authorize"
  authentication_request_extra_params = {}
  client_id                           = "clientid"
  client_secret                       = "secret123" # a data source would be good here
}

Read more in this post.

Okta

alb_authenticate_oidc = {
  issuer                              = "https://dev-42069.okta.com/"
  token_endpoint                      = "https://dev-42069.okta.com/oauth2/v1/token"
  user_info_endpoint                  = "https://dev-42069.okta.com/oauth2/v1/userinfo"
  authorization_endpoint              = "https://dev-42069.okta.com/oauth2/v1/authorize"
  authentication_request_extra_params = {}
  client_id                           = "clientid"
  client_secret                       = "secret123" # a data source would be good here
}

Read more in this post.

Google

  alb_authenticate_oidc = {
    issuer                              = "https://accounts.google.com"
    token_endpoint                      = "https://oauth2.googleapis.com/token"
    user_info_endpoint                  = "https://openidconnect.googleapis.com/v1/userinfo"
    authorization_endpoint              = "https://accounts.google.com/o/oauth2/v2/auth"
    authentication_request_extra_params = {}
    client_id                           = "google_client_id"
    client_secret                       = "google_client_secret"
  }

• See the iap_client resource in the Google provider if you want to create this configuration in Terraform.
• Remember to set your google consent screen to internal to only allow users from your own domain.

AWS Cognito with SAML

The AWS Cognito service allows you to define SAML applications tied to an identity provider (e.g., GSuite). The Atlantis ALB can then be configured to require an authenticated user managed by your identity provider.

To configure AWS Cognito connecting to a GSuite SAML application, you can use the gsuite-saml-cognito Terraform module.

To enable Cognito authentication on the Atlantis ALB, specify the following arguments containing attributes from your Cognito configuration.

alb_authenticate_cognito = {
  user_pool_arn       = "arn:aws:cognito-idp:us-west-2:1234567890:userpool/us-west-2_aBcDeFG"
  user_pool_client_id = "clientid123"
  user_pool_domain    = "sso.your-corp.com"
}

Allow GitHub Webhooks Unauthenticated Access

If you are using one of the authentication methods above along with managed GitHub (not self-hosted enterprise version), you'll need to allow unauthenticated access to GitHub's Webhook static IPs:

allow_unauthenticated_access = true
allow_github_webhooks        = true

Notes

1. AWS Route53 zone is not created by this module, so zone specified as a value in route53_zone_name should be created before using this module. Check documentation for aws_route53_zone.
2. Currently this module configures Atlantis in a way that it can not be used to work with GitHub and Gitlab simultaneously (can't make list of ECS secrets conditionally).
3. For Bitbucket Cloud webhook configuration follow instructions in the official Atlantis documentation.

Examples

• Complete Atlantis with GitHub webhook
• GitHub repository webhook for Atlantis
• GitLab repository webhook for Atlantis

Requirements

Providers

Modules

Resources

Inputs

[
  "0.0.0.0/0"
]

[
  "::/0"
]

list(object({
    containerName = string
    condition     = string
  }))

list(object(
    {
      name      = string
      valueFrom = string
    }
  ))

list(object(
    {
      name  = string
      value = string
    }
  ))

object({
    type    = string
    options = map(string)
  })

[
  "140.82.112.0/20",
  "185.199.108.0/22",
  "192.30.252.0/22",
  "143.55.64.0/20"
]

[
  "2a0a:a440::/29",
  "2606:50c0::/32"
]

list(object({
    name      = string
    hardLimit = number
    softLimit = number
  }))

list(object({
    sourceContainer = string
    readOnly        = bool
  }))

Outputs

Authors

Module is maintained by Anton Babenko with help from these awesome contributors.

License

Apache 2 Licensed. See LICENSE for full details.

Additional information for users from Russia and Belarus

• Russia has illegally annexed Crimea in 2014 and brought the war in Donbas followed by full-scale invasion of Ukraine in 2022.
• Russia has brought sorrow and devastations to millions of Ukrainians, killed hundreds of innocent people, damaged thousands of buildings, and forced several million people to flee.
• Putin khuylo!