-
Notifications
You must be signed in to change notification settings - Fork 1.1k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #417 from runatlantis/tfe-state-docs
Add docs about using tfe remote state.
- Loading branch information
Showing
7 changed files
with
130 additions
and
72 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,61 @@ | ||
| # Provider Credentials | ||
|
|
||
| ## AWS | ||
| Atlantis simply shells out to `terraform` so you don't need to do anything special with AWS credentials. | ||
| As long as `terraform` commands works where you're hosting Atlantis, then Atlantis will work. | ||
| See [https://www.terraform.io/docs/providers/aws/#authentication](https://www.terraform.io/docs/providers/aws/#authentication) for more detail. | ||
|
|
||
| ### Multiple AWS Accounts | ||
| Atlantis supports multiple AWS accounts through the use of Terraform's | ||
| [AWS Authentication](https://www.terraform.io/docs/providers/aws/#authentication). | ||
|
|
||
| If you're using the [Shared Credentials file](https://www.terraform.io/docs/providers/aws/#shared-credentials-file) | ||
| you'll need to ensure the server that Atlantis is executing on has the corresponding credentials file. | ||
|
|
||
| If you're using [Assume role](https://www.terraform.io/docs/providers/aws/#assume-role) | ||
| you'll need to ensure that the credentials file has a `default` profile that is able | ||
| to assume all required roles. | ||
|
|
||
| [Environment variables](https://www.terraform.io/docs/providers/aws/#environment-variables) authentication | ||
| won't work for multiple accounts since Atlantis wouldn't know which environment variables to execute | ||
| Terraform with. | ||
|
|
||
| ### Assume Role Session Names | ||
| Atlantis injects 5 Terraform variables that can be used to dynamically name the assume role session name. | ||
| Setting the `session_name` allows you to trace API calls made through Atlantis back to a specific | ||
| user and repo via CloudWatch: | ||
|
|
||
| ```bash | ||
| provider "aws" { | ||
| assume_role { | ||
| role_arn = "arn:aws:iam::ACCOUNT_ID:role/ROLE_NAME" | ||
| session_name = "${var.atlantis_user}-${var.atlantis_repo_owner}-${var.atlantis_repo_name}-${var.atlantis_pull_num}" | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| Atlantis runs `terraform` with the following variables: | ||
| | `-var` Argument | Description | | ||
| |-------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------| | ||
| | `atlantis_user=lkysow` | The VCS username of who is running the plan command. | | ||
| | `atlantis_repo=runatlantis/atlantis` | The full name of the repo the pull request is in. NOTE: This variable can't be used in the AWS session name because it contains a `/`. | | ||
| | `atlantis_repo_owner=runatlantis` | The name of the **owner** of the repo the pull request is in. | | ||
| | `atlantis_repo_name=atlantis` | The name of the repo the pull request is in. | | ||
| | `atlantis_pull_num=200` | The pull request number. | | ||
|
|
||
| If you want to use `assume_role` with Atlantis and you're also using the [S3 Backend](https://www.terraform.io/docs/backends/types/s3.html), | ||
| make sure to add the `role_arn` option: | ||
|
|
||
| ```bash | ||
| terraform { | ||
| backend "s3" { | ||
| bucket = "mybucket" | ||
| key = "path/to/my/key" | ||
| region = "us-east-1" | ||
| role_arn = "arn:aws:iam::ACCOUNT_ID:role/ROLE_NAME" | ||
| # can't use var.atlantis_user as the session name because | ||
| # interpolations are not allowed in backend configuration | ||
| # session_name = "${var.atlantis_user}" WON'T WORK | ||
| } | ||
| } | ||
| ``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,45 @@ | ||
| # Terraform Enterprise | ||
|
|
||
| Atlantis integrates seamlessly with Terraform Enterprise's new [Free Remote State Management](https://app.terraform.io/signup). | ||
|
|
||
| [[toc]] | ||
|
|
||
| ## Migrating to TFE's Remote State | ||
| If you're using a different state backend, you first need to migrate your state | ||
| to use Terraform Enterprise (TFE). Read [TODO: use right link](https://www.terraform.io/docs/enterprise/migrate/index.html) | ||
| for more information on how to migrate. | ||
|
|
||
| ## Configuring Atlantis | ||
| Once you've migrated your state to TFE, and your code is using the TFE backend: | ||
|
|
||
| ```bash | ||
| # Example configuration | ||
| terraform { | ||
| backend "remote" { | ||
| organization = "company" | ||
| workspaces { | ||
| name = "my-app-prod" | ||
| } | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| You need to provide Atlantis with a TFE [User Token](https://www.terraform.io/docs/enterprise/users-teams-organizations/users.html#api-tokens) | ||
| that it will use to access the TFE API. | ||
|
|
||
| You can provide this token by either: | ||
| 1. Setting the `--tfe-token` flag, or the `ATLANTIS_TFE_TOKEN` environment variable | ||
| 1. Creating a `.terraformrc` file in the home directory of whichever user is executing Atlantis | ||
| with the following contents: | ||
| ```json | ||
| credentials "app.terraform.io" { | ||
| token = "xxxxxx.hunter2.zzzzzzzzzzzzz" | ||
| } | ||
| ``` | ||
|
|
||
| Notes: | ||
| * If you specify the `--tfe-token` or `ATLANTIS_TFE_TOKEN` environment variable, | ||
| on startup, Atlantis will generate a config file to `~/.terraformrc`. If | ||
| this file already exists, Atlantis will error. | ||
| * If you're using the Atlantis Docker image, the `.terraformrc` file should be | ||
| placed in `/home/atlantis/.terraformrc` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters