Using Abbey with Atlantis

Estimated time: ~15 minutes

In this tutorial, you'll learn how to use Abbey with Atlantis.

Abbey helps you manage the workflows for access requests and approvals, making it easier for people to get access to Resources.

Atlantis is an application for automating Terraform via pull requests. It is deployed as a standalone application into your infrastructure. No third-party has access to your credentials.

By using Abbey and Atlantis together, you can:

1. Scalably manage your infrastructure access.

2. Standardize your workflows.

3. Increase visibility for how and when Terraform changes occur.

Before you start

1. Create an Abbey account.

2. Have a GitHub account.

Atlantis Setup

Setting up Atlantis contains 5 steps:

1. Step 1: Choose An Atlantis Deployment Type

2. Step 2: Set Up Your GitHub App

3. Step 3: Configure Atlantis Secrets

4. Step 4: Configure Terraform Provider Credentials

5. Step 5: Set Up a State Backend

Step 1: Choose An Atlantis Deployment Type

First, follow the official Atlantis docs to choose a deployment type for deploying an Atlantis server.

Step 2: Set Up Your GitHub App

Follow the official instructions to create a GitHub App Using Atlantis.

Make sure to follow instructions on the Atlantis installation screen titled "Visit https://github.com/apps/installation//installations/new to install the app for your user or organization…".

Your connection won't be complete without doing this step.

Atlantis installation screen.

You will be redirected to GitHub's website to perform the typical OAuth flow. Select repo scopes for your app, then install.

If you miss some of the above steps, you'll see an error when launching Atlantis:

Error: initializing server: error initializing github authentication transport: wrong number of installations, expected 1, found 0

Because you have set up GitHub using Atlantis's native GitHub App setup flow, you won't have to configure webhook secrets and a webhook URL.

Note about webhooks from the Atlantis docs.

Step 3: Configure Atlantis Secrets

You may configure Atlantis Secrets in one of two ways:

1. Using atlantis.yaml

2. Using environment variables

Using atlantis.yaml

Modify your Atlantis server's server config to configure required configurations, such as:

1. GitHub App ID

2. App Key

3. Webhook Secret

4. Web Basic Auth

5. Web Username

6. Web Password

This is where you can also configure optional configurations such as your Repo Allowlist.

Using environment variables

You may also configure these same configuration variables via environment variables.

To do this, you will prefix your variables with ATLANTIS.

Example Atlantis config using environment variables.

Step 4: Configure Terraform Provider Credentials

Now you will configure your Terraform provider credentials.

For each Terraform Provider or Module you have in your repo, you will need to add credentials so Atlantis can make API calls (via the providers) to each of their services.

For example, if you have infrastructure configuration for GitHub, AWS, and Okta, you will need 3 sets of credentials, one for each of those services.

You will add your provider credentials similar to step 3 above, either using the atlantis.yaml or environment variables.

Step 5: Set Up a State Backend

Atlantis by default does not come with a state backend.

Some of the usual options for a state backend are:

1. AWS S3 to hold state with AWS Dynamo DB for state locking

2. Terraform Cloud (only for state)

You may use Abbey's HTTP-based state backend for sandbox or prototyping, but it is not recommended for production use at scale.

You must not use file state with Atlantis because Atlantis does not have permanent storage and does not commit it back to version control.

🎉 Wrap up

That's it! Congrats, you have now set up Abbey with Atlantis!

When your users request access to resources in Abbey, a Pull Request will be created on GitHub. Once all policy and workflow checks pass, reviewers will be notified to approve or deny the request.

You can then perform atlantis apply as usual.

After that, you can approve the request on the Abbey App. Abbey will merge the Pull Request.

If your resource has an auto revocation policy, then Abbey will automatically revoke access in which another Pull Request will be created and the same git-based flow will occur, this time undoing the previous access grant.

Recommendations

Project Structure

.
├── LICENSE
├── README.md
├── atlantis.yaml
├── environments
│   ├── prod
│   |   ├── main.tf
│   |   ├── terragrunt.hcl
│   |   └── variables.tf
│   └── staging
|
├── modules
│   ├── <app>
│   │   ├── README.md
│   │   ├── access.tf
│   │   ├── main.tf
│   │   ├── outputs.tf
│   │   ├── provider.tf
│   │   ├── variables.tf
│   │   └── versions.tf
│   └── <app>-access
│       ├── README.md
│       ├── main.tf
│       ├── outputs.tf
│       ├── provider.tf
│       ├── variables.tf
│       └── versions.tf
└── policies
    └── soc2
        └── cc1.rego

Atlantis Repo Config

version: 3

projects:
- name: sandbox-atlantis
  branch: /main/
  dir: environments/sandbox-atlantis
  workflow: terragrunt
  autoplan:
    when_modified: ["*.tf"]
    enabled: true

workflows:
  terragrunt:
    plan:
      steps:
        - env:
            name: TERRAGRUNT_TFPATH
            command: 'echo "terraform${ATLANTIS_TERRAFORM_VERSION}"'
        - env:
            # Reduce Terraform suggestion output
            name: TF_IN_AUTOMATION
            value: 'true'
        - run:
            command: terragrunt plan -input=false -out=$PLANFILE
            output: strip_refreshing
    apply:
      steps:
        - env:
            name: TERRAGRUNT_TFPATH
            command: 'echo "terraform${ATLANTIS_TERRAFORM_VERSION}"'
        - env:
            # Reduce Terraform suggestion output
            name: TF_IN_AUTOMATION
            value: 'true'
        - run: terragrunt apply $PLANFILE

Security Best Practices

1. Hold your sensitive variables in a secrets manager such as Hashicorp Vault, Doppler, or AWS Secrets Manager (or their Azure and GCP equivalent).

2. Atlantis needs to be exposed to GitHub.

   • If via the public internet, configure Basic Auth with a strong password for your Atlantis server.

   • If via VPC, then make sure to have a proxy to relay/route traffic from GitHub to your private/isolated Atlantis server.

3. Make sure that you properly scope your access to repos specific to Atlantis and have appropriate number of members and member privileges to those repos.

4. Make sure to configure a webhook secret if using GitHub. This is the way to authenticate Atlantis against GitHub.

5. Make sure to configure a Repo Allowlist to only repos you want Atlantis to watch. This helps with security scope and scalability as Atlantis will only need to watch a select number of repos.

Next Steps

To learn more about what Resources you can configure, try one of our Step-by-Step Tutorials.