public/atlantis
1
0
Fork 0
mirror of https://git.vectorsigma.ru/public/atlantis.git synced 2026-08-03 16:08:49 +00:00
Code Issues Packages Projects Releases Wiki Activity

Add docs about using tfe remote state.

Browse Source
This commit is contained in:
Luke Kysow
2019-01-08 16:00:49 -05:00
parent 89516f0378
commit 255a5b7fc1
7 changed files with 130 additions and 72 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
runatlantis.io/.vuepress/config.js
View File

@@ -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'
]
}
]

9
runatlantis.io/docs/deployment.md
View File

@@ -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

61
runatlantis.io/docs/provider-credentials.md Normal file
View File

@@ -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
}
}
```

12
runatlantis.io/docs/requirements.md
View File

@@ -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:

60
runatlantis.io/docs/server-configuration.md
View File

@@ -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.

45
runatlantis.io/docs/terraform-enterprise.md Normal file
View File

@@ -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`

9
runatlantis.io/docs/webhook-secrets.md
View File

@@ -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.
:::