terraform-aws-atlantis: running the Atlantis Terraform runner on Fargate

What Atlantis is, and what the module builds

The module description is a Terraform module to deploy Atlantis on AWS Fargate, and the readme explains the tool first.

Atlantis is a tool which provides unified workflow for collaborating on Terraform through GitHub, GitLab and Bitbucket Cloud. The mechanism is that you comment a command on a pull request and Atlantis runs the corresponding Terraform command against the pull request's branch, then posts the plan back as a comment.

So the deployment target is a server with a persistent identity, a git provider connection and a webhook endpoint, and Fargate is a reasonable host for it because the workload is bursty and mostly waits on git and Terraform rather than on CPU.

The module creates all resources required to run Atlantis on AWS Fargate, and the readme states that plainly. The composed pieces are visible in the module dependencies: the ACM module for the certificate, the ALB module for the load balancer, the ECS cluster module and the ECS service module for the compute, and the EFS module for the optional storage.

The version pins are current. The ACM module is at 6.1.1, the ALB module at 10.2.0, the ECS cluster and service modules at 6.7.0 and the EFS module at 2.0.0. The module itself requires Terraform 1.10 or later and the AWS provider 6.28 or later, and it declares no providers of its own, which is the correct arrangement for a reusable module: the caller supplies the provider configuration.

The readme also carries a caution before anything else, and it is the first thing an evaluator should read. 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.

That is a reasonable thing for a module that hands out cloud credentials to say, since Atlantis by design runs Terraform against your infrastructure and therefore needs permission to do so.

The complete deployment, and how the secrets are wired

The first usage example, GitHub Complete, is the module call with everything specified, and its structure tells you how the pieces fit together.

The atlantis block holds the container definition as a map, with environment and secrets as separate lists. The environment list carries plain values, and the example shows the Atlantis GitHub user and the repository allowlist. The secrets list carries Secrets Manager ARNs through valueFrom, and the example shows the GitHub token and the webhook secret.

That split is the whole secret-handling story of the module. Atlantis needs a token with write access to the git provider and a shared secret for webhook verification, and both are values that must not end up in the Terraform state in plain text. Passing them as valueFrom ARNs keeps them as references, so the state records where the secret is rather than what it is.

The service block carries the subnet identifiers, the list of secret ARNs that the task execution role may read, and tasks_iam_role_policies, which the example populates with the AWS managed AdministratorAccess policy. The comment on that line says to provide Atlantis permission necessary to create or destroy resources, which is the honest description of what Atlantis needs for a plan-and-apply workflow. The example uses AdministratorAccess because it is short, but the readme is not endorsing it, and the module taking a policy map rather than hard-coding one is what lets you narrow it.

The ALB block carries subnet identifiers for the load balancer, and the certificate_domain_name and route53_zone_id sit at the top level of the module call because they are inputs to the ACM certificate rather than to the load balancer.

The tags map at the end is a conventional example, with Environment and Terraform set to true.

One detail worth noticing is the ATLANTIS_REPO_ALLOWLIST value in the example, github.com/terraform-aws-modules/*. Atlantis only responds to repositories matching that pattern, which is the first of several controls that matter and the one the caution in the readme is pointing at.

The separate variant, and when you want it

The second example, GitHub Separate, is the same module with two creation flags turned off, and the readme explains what it is for.

The Atlantis module creates most of the resources required to run Atlantis on AWS Fargate, except for the ECS Cluster and ALB. This allows you to integrate Atlantis with your existing AWS infrastructure.

The mechanism is two variables. create_cluster is false, and cluster_arn points at an existing cluster. create_alb is false, and alb_target_group_arn and alb_security_group_id point at an existing load balancer and security group.

So the module becomes a component in a larger setup rather than a standalone deployment. The likely reasons for that are practical ones. A company with an existing ECS cluster for other workloads may not want a second one, or may have a load balancer already fronting several services with the certificate and the DNS already configured. The security group in particular is worth thinking about, because Atlantis's inbound rules are part of your network perimeter and an organisation often has a policy about where those live.

What stays the same between the two examples is the container definition and the service configuration, which is the part that is specific to Atlantis. The git provider credentials, the repository allowlist and the ECS service settings are identical in both.

The readme also notes that GitHub is shown in the usage examples, however any git provider supported by Atlantis can be used by simply using the correct Atlantis environment variables and configuring the respective webhook for the given git provider. So the switch is the environment variables, not a code change.

There are two worked examples in the repository, github-complete and github-separate, each with its own folder and a readme, so the examples in the documentation are backed by runnable configurations rather than being illustrative fragments.

EFS for plan outputs, and supplying server configuration

Two features go beyond the basic deployment, and both address a real problem with running Atlantis on Fargate.

The first is persistent storage. You can enable EFS to ensure that any plan outputs are persisted to EFS in the event that the Atlantis Task is replaced. The configuration turns on enable_efs and supplies mount targets, one per availability zone, each with the subnet to mount into:

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

  # Truncated for brevity ...

  # EFS
  enable_efs = true
  efs = {
    mount_targets = {
      "eu-west-1a" = {
        subnet_id = "subnet-xyzde987"
      }
      "eu-west-1b" = {
        subnet_id = "subnet-slkjf456"
      }
      "eu-west-1c" = {
        subnet_id = "subnet-qeiru789"
      }
    }
  }
}

The problem it solves is that a Fargate task is disposable by design. When the task is replaced, the local filesystem goes with it, and any plan output that Atlantis had produced is lost. A plan that a reviewer approved and then cannot be re-fetched is a plan that might have to be regenerated, and a regenerated plan is not necessarily the same plan.

The second feature is supplying your own Atlantis server configuration. Atlantis is configured with a YAML file describing per-repository rules, and the module takes it as a JSON environment variable:

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

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

  # ...

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

The conversion from YAML to JSON with yamldecode and jsonencode is a neat trick, since it means you can keep the server configuration in the format Atlantis documents while still delivering it through an environment variable that only accepts JSON.

The example rules deserve a close read, because they are permissive and the caution in the readme is about exactly this. The repository pattern is /.*/, which matches every repository. allow_custom_workflows is true, which lets pull requests supply their own workflow file. allowed_overrides permits a pull request to override the apply requirements and the workflow. And apply_requirements demands an approved plan.

That combination is workable but it is permissive, and a real installation would normally narrow the repository pattern and decide which overrides are acceptable for a given organisation. The module does not decide that for you, which is the correct behaviour for infrastructure code, and it does mean the example is a starting point rather than a recommendation.

How Atlantis changes a Terraform workflow

Before looking at the module's inputs, it is worth being clear about what running Atlantis actually changes for a team, because the deployment is the easy part.

Without Atlantis, a Terraform change is applied by a person who has the credentials locally or in a CI job they configured. With Atlantis, the change is applied by a service that a pull request triggers. The person no longer needs standing cloud access, and that is the security improvement the readme's caution is about.

The mechanism is comments. A pull request gets a comment with a command such as plan or apply, Atlantis runs the Terraform command against the pull request's branch, and posts the output back as a comment. From there the review is a normal pull request review with the plan visible in the conversation, which is a considerable improvement on a plan pasted into a chat window.

Two properties of the workflow are visible in the server configuration example. The apply_requirements list says what has to be true before apply is allowed, and the example requires an approved plan, which means the sequence is plan first, a human approves that specific plan, and only then can apply run. And allowed_overrides says which of those requirements a pull request is allowed to change, with the example permitting the apply requirements and the workflow to be overridden.

That last part is where the caution bites. allow_custom_workflows together with overridable requirements means a pull request can, in principle, arrange for its own conditions to be relaxed. A team that wants a tight gate would not enable those overrides, and the module does not make that decision for you because the right answer depends on how much you trust the repositories that can reach the webhook.

The repository allowlist is the outer ring of that defence, since Atlantis ignores webhooks for repositories outside the list. The module passes it as an environment variable, which means the allowlist is part of your Terraform configuration and therefore part of your review and audit trail, rather than something set in a console.

All of this is why the readme's caution points at the upstream Atlantis security documentation rather than trying to summarise it. The module's job is to place the service correctly in your network and give it a manageable identity, and the policy decisions about who may apply what stay with the operator.

Editorial conclusion

Adopt this module if you want Atlantis running on Fargate rather than on a long-lived server, because Fargate removes the instance management and the module handles the container, service, load balancer and certificate wiring. Do not adopt it without reading the Atlantis security documentation first, because the readme carries an explicit caution about it and the module's own defaults involve broad IAM permissions. Before you commit, scope the IAM policy to what Atlantis actually needs rather than leaving the example AdministratorAccess in place, and restrict the repository allowlist.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. terraform-aws-modules/terraform-aws-atlantis on GitHub