# Using Abbey with Atlantis {% hint style="info" %} **Estimated time:** \~15 minutes {% endhint %} In this tutorial, you'll learn how to use Abbey with [Atlantis](https://www.runatlantis.io/). Abbey helps you manage the workflows for access requests and approvals, making it easier for people to get access to [Resources](/how-abbey-works/concepts.md#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 ](https://accounts.abbey.io/sign-up)account. 2. Have a [GitHub](https://docs.github.com/en/get-started/quickstart/creating-an-account-on-github) account. ## Atlantis Setup Setting up Atlantis contains 5 steps: 1. [#step-1-choose-an-atlantis-deployment-type](#step-1-choose-an-atlantis-deployment-type "mention") 2. [#step-2-set-up-your-github-app](#step-2-set-up-your-github-app "mention") 3. [#step-3-configure-atlantis-secrets](#step-3-configure-atlantis-secrets "mention") 4. [#step-4-configure-terraform-provider-credentials](#step-4-configure-terraform-provider-credentials "mention") 5. [#step-5-set-up-a-state-backend](#step-5-set-up-a-state-backend "mention") ## Step 1: Choose An Atlantis Deployment Type First, follow the official Atlantis docs to [choose a deployment type](https://www.runatlantis.io/docs/deployment.html#deployment-1) for deploying an Atlantis server. ## Step 2: Set Up Your GitHub App Follow the official instructions to [create a GitHub App Using Atlantis](https://www.runatlantis.io/docs/access-credentials.html#github-app). {% hint style="warning" %} Make sure to follow instructions on the Atlantis installation screen titled "**Visit to install the app for your user or organization…**". Your connection won't be complete without doing this step. {% endhint %}

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. {% hint style="warning" %} If you miss some of the above steps, you'll see an error when launching Atlantis: {% code overflow="wrap" %} ```log Error: initializing server: error initializing github authentication transport: wrong number of installations, expected 1, found 0 ``` {% endcode %} {% endhint %} {% hint style="success" %} 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. {% endhint %}

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](https://www.runatlantis.io/docs/server-configuration.html) 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](https://www.runatlantis.io/docs/server-configuration.html#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) {% hint style="info" %} You may use Abbey's HTTP-based state backend for sandbox or prototyping, but it is not recommended for production use at scale. {% endhint %} {% hint style="warning" %} You must not use file state with Atlantis because [Atlantis does not have permanent storage and does not commit it back to version control](https://www.runatlantis.io/docs/requirements.html#terraform-state). {% endhint %} ## :tada: 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 ```shell-session . ├── LICENSE ├── README.md ├── atlantis.yaml ├── environments │ ├── prod │ | ├── main.tf │ | ├── terragrunt.hcl │ | └── variables.tf │ └── staging | ├── modules │ ├── │ │ ├── README.md │ │ ├── access.tf │ │ ├── main.tf │ │ ├── outputs.tf │ │ ├── provider.tf │ │ ├── variables.tf │ │ └── versions.tf │ └── -access │ ├── README.md │ ├── main.tf │ ├── outputs.tf │ ├── provider.tf │ ├── variables.tf │ └── versions.tf └── policies └── soc2 └── cc1.rego ``` ### Atlantis Repo Config {% code lineNumbers="true" %} ```yaml 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 ``` {% endcode %} ### Security Best Practices 1. Hold your sensitive variables in a secrets manager such as [Hashicorp Vault](https://www.hashicorp.com/products/vault), [Doppler](https://www.doppler.com/), or AWS [Secrets Manager](https://aws.amazon.com/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](/resources/privacy-policy.md) you can configure, try one of our [Step-by-Step Tutorials](/getting-started/tutorials.md). --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.abbey.io/getting-started/tutorials/using-abbey-with-atlantis.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.