diff --git a/runatlantis.io/.vuepress/config.js b/runatlantis.io/.vuepress/config.js index ed54775422..32a297b38b 100644 --- a/runatlantis.io/.vuepress/config.js +++ b/runatlantis.io/.vuepress/config.js @@ -53,7 +53,8 @@ module.exports = { 'deployment', 'configuring-webhooks', 'server-configuration', - 'security' + 'provider-credentials', + 'terraform-enterprise' ] }, { @@ -79,7 +80,8 @@ module.exports = { children: [ ['how-atlantis-works', 'Overview'], 'locking', - 'autoplanning' + 'autoplanning', + 'security' ] } ] diff --git a/runatlantis.io/docs/deployment.md b/runatlantis.io/docs/deployment.md index 982ceb86a7..97eb052720 100644 --- a/runatlantis.io/docs/deployment.md +++ b/runatlantis.io/docs/deployment.md @@ -37,7 +37,7 @@ Pick your deployment type: * [AWS Fargate](#aws-fargate) * [Google Kubernetes Engine (GKE)](#google-kubernetes-engine-gke) * [Docker](#docker) -* [Roll your own](#roll-your-own) +* [Roll Your Own](#roll-your-own) ### Kubernetes Helm Chart @@ -57,13 +57,12 @@ To install: token: bar secret: baz ``` -1. Edit `values.yaml` and set your `orgWhitelist` +1. Edit `values.yaml` and set your `orgWhitelist` (see [Repo Whitelist](server-configuration.html#repo-whitelist) for more information) ```yaml orgWhitelist: github.com/runatlantis/* ``` - See [Repo Whitelist](server-configuration.html#repo-whitelist) for more information. -1. Configure any other variables. See [https://github.com/helm/charts/tree/master/stable/atlantis#customization](https://github.com/helm/charts/tree/master/stable/atlantis#customization) - for documentation. +1. Configure any other variables (see [https://github.com/helm/charts/tree/master/stable/atlantis#customization](https://github.com/helm/charts/tree/master/stable/atlantis#customization) + for documentation) 1. Run ```sh helm install -f values.yaml stable/atlantis diff --git a/runatlantis.io/docs/provider-credentials.md b/runatlantis.io/docs/provider-credentials.md new file mode 100644 index 0000000000..0be0d9cfe4 --- /dev/null +++ b/runatlantis.io/docs/provider-credentials.md @@ -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 + } +} +``` diff --git a/runatlantis.io/docs/requirements.md b/runatlantis.io/docs/requirements.md index f15dadd810..e0de6a4c8f 100644 --- a/runatlantis.io/docs/requirements.md +++ b/runatlantis.io/docs/requirements.md @@ -4,7 +4,7 @@ it works with yours. [[toc]] -## Git host +## Git Host Atlantis integrates with the following Git hosts: * GitHub (public, private or enterprise) @@ -13,8 +13,14 @@ Atlantis integrates with the following Git hosts: * Bitbucket Server aka Stash ## Terraform State -Atlantis supports all **remote state** backends. It **does not** support local state -because it does not commit the modified state files back to version control. +Atlantis supports all backend types **except for local state**. We don't support local state +because Atlantis does not have permanent storage and it doesn't commit the new +statefile back to version control. + +:::tip +If you're looking for an easy remote state solution, check out [free remote state](https://app.terraform.io/signup) +storage from Terraform Enterprise. This is fully supported by Atlantis. +::: ## Repository Structure Atlantis supports any Terraform repository structure, for example: diff --git a/runatlantis.io/docs/server-configuration.md b/runatlantis.io/docs/server-configuration.md index d4fe5e8ad6..773dcf32a0 100644 --- a/runatlantis.io/docs/server-configuration.md +++ b/runatlantis.io/docs/server-configuration.md @@ -26,66 +26,6 @@ To see a list of all flags and their descriptions run `atlantis server --help` The flag `--atlantis-url` is set by the environment variable `ATLANTIS_ATLANTIS_URL` **NOT** `ATLANTIS_URL`. ::: -## AWS Credentials -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 - } -} -``` - ## Repo Whitelist Atlantis requires you to specify a whitelist of repositories it will accept webhooks from via the `--repo-whitelist` flag. diff --git a/runatlantis.io/docs/terraform-enterprise.md b/runatlantis.io/docs/terraform-enterprise.md new file mode 100644 index 0000000000..0997519227 --- /dev/null +++ b/runatlantis.io/docs/terraform-enterprise.md @@ -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` diff --git a/runatlantis.io/docs/webhook-secrets.md b/runatlantis.io/docs/webhook-secrets.md index 0fa34689c1..83696b8a3a 100644 --- a/runatlantis.io/docs/webhook-secrets.md +++ b/runatlantis.io/docs/webhook-secrets.md @@ -7,11 +7,16 @@ One way to confirm this would be to whitelist requests to only come from the IPs of your Git host but an easier way is to use a Webhook Secret. -::: tip Note +::: tip NOTE Webhook secrets are actually optional. However they're highly recommended for security. ::: +::: warning +Bitbucket.org **does not** support webhook secrets. +To mitigate, use repo whitelists and IP whitelists. See [Security](security.html#bitbucket-cloud-bitbucket-org) for more information. +::: + ## Generating A Webhook Secret You can use any random string generator to create your Webhook secret. It should be > 24 characters. @@ -19,7 +24,7 @@ For example: * Generate via Ruby with `ruby -rsecurerandom -e 'puts SecureRandom.hex(20)'` * Generate online with [https://www.random.org/passwords/?num=2&len=20&format=html&rnd=new](https://www.random.org/passwords/?num=2&len=20&format=html&rnd=new) -::: tip +::: tip NOTE You must use **the same** webhook secret for each repo. :::