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

Merge pull request #411 from runatlantis/docs-reorg

Browse Source 
Reorganize docs.
This commit is contained in:
Luke Kysow
2019-01-07 16:39:15 -05:00
committed by GitHub
parent 5d072683e5 37e2ab85a8
commit cc03368e60
17 changed files with 525 additions and 304 deletions
Download Patch File Download Diff File Expand all files Collapse all files

16
.circleci/config.yml
View File

@@ -24,6 +24,18 @@ jobs:
# We don't run e2e tests on fork PRs because they don't have access to the secret env vars.
- run: if [ -z "${CIRCLE_PR_REPONAME}" ]; then ./scripts/e2e.sh; fi
# Check the website that this PR creates for broken links.
website_link_check:
docker:
- image: lkysow/netlify-broken-link-checker:latest
environment:
GITHUB_ORG: runatlantis
GITHUB_REPO: atlantis
MUFFET_ARGS: '-e https://github\.com/runatlantis/atlantis/edit/master/.* -e https://github.com/helm/charts/tree/master/stable/atlantis#customization'
DELAY_SECONDS: 30
steps:
- run: check-links
# Build and push 'latest' Docker tag.
docker_master:
working_directory: /go/src/github.com/runatlantis/atlantis
@@ -77,6 +89,10 @@ workflows:
filters:
branches:
ignore: /.*-docs/
- website_link_check:
filters:
branches:
ignore: master
- docker_master:
requires: [e2e]
filters:

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

@@ -34,29 +34,58 @@ module.exports = {
{text: 'Blog', link: 'https://medium.com/runatlantis'}
],
sidebar: {
'/docs/': [
'',
'pull-request-commands',
'deployment',
'server-configuration',
'apply-requirements',
'locking',
'autoplanning',
['atlantis-yaml-reference', 'atlantis.yaml Reference'],
'upgrading-atlantis-yaml-to-version-2',
'security',
'faq',
],
'/guide/': [
'',
'test-drive',
'getting-started',
'requirements',
'atlantis-yaml-use-cases'
],
'/docs/': [
['', 'Overview'],
{
title: 'Installing Atlantis',
collapsable: true,
children: [
'installation-guide',
'requirements',
'access-credentials',
'webhook-secrets',
'deployment',
'configuring-webhooks',
'server-configuration',
'security'
]
},
{
title: 'Using Atlantis',
collapsable: true,
children: [
['using-atlantis', 'Overview']
]
},
{
title: 'Customizing Atlantis',
collapsable: true,
children: [
['customizing-atlantis', 'Overview'],
'atlantis-yaml-reference',
'upgrading-atlantis-yaml-to-version-2',
'apply-requirements'
]
},
{
title: 'How Atlantis Works',
collapsable: true,
children: [
['how-atlantis-works', 'Overview'],
'locking',
'autoplanning'
]
}
]
},
repo: 'runatlantis/atlantis',
docsDir: 'runatlantis.io',
editLinks: true,
}
}
}

4
runatlantis.io/.vuepress/style.styl
View File

@@ -32,3 +32,7 @@
}
}
}
.sidebar-heading {
font-size: inherit
}

26
runatlantis.io/docs/README.md
View File

@@ -1,18 +1,14 @@
# Overview
This documentation is divided into sections:
* [Pull Request Commands](pull-request-commands.html) - the commands that Atlantis supports via pull request comments.
* [Production-Ready Deployment](deployment.html) - how to deploy Atlantis.
* [Server Configuration](server-configuration.html) - how to configure the Atlantis server.
* [Apply Requirements](apply-requirements.html) - what requirements can be set before `atlantis apply` is allowed.
* [Locking](locking.html) - how and why Atlantis does locking.
* [Autoplanning](autoplanning.html) - how Atlantis runs plan automatically.
* [`atlantis.yaml` Reference](atlantis-yaml-reference.html) - reference docs for the `atlantis.yaml` configuration file.
* [Security](security.html) - what you need to think about in terms of security for Atlantis.
* [FAQ](faq.html) - Frequently asked questions.
# Atlantis Documentation
These docs are for users that are ready to get Atlantis installed and start using it.
:::tip Looking to get started?
If you're new here, check out the [Guide](/guide/)
where you can try our [Test Drive](/guide/test-drive.html) or [Run Atlantis Locally](/guide/getting-started.html).
:::
### Next Steps
* [Installing Atlantis](/docs/installation-guide.html)  –  Get Atlantis up and running
* [Using Atlantis](using-atlantis.html)  –  How do I use Atlantis to run Terraform
* [Customizing Atlantis](customizing-atlantis.html)  –  Modify how Atlantis works for my use case
* [How Atlantis Works](how-atlantis-works.html)  –  Internals of what Atlantis is doing

46
runatlantis.io/docs/access-credentials.md Normal file
View File

@@ -0,0 +1,46 @@
# Git Host Access Credentials
This doc describes how to create credentials on your Git host (GitHub, GitLab or Bitbucket)
that Atlantis will use to make API calls.
[[toc]]
## Create an Atlantis user (optional)
We recommend creating a new user named **@atlantis** (or something close) or using a dedicated CI user.
This isn't required (you can use an existing user), however all the comments that Atlantis writes
will come from that user so it might be confusing if its coming from a personal account.
![Example Comment](./images/example-comment.png)
<p align="center"><i>An example comment coming from the @atlantisbot user</i></p>
## Generating an Access Token
Once you've created a new user (or decided to use an existing one), you need to
generate an access token. Read on for the instructions for your Git host.
### Create a GitHub Token
**NOTE: The Atlantis user must have "Write permissions" (for repos in an organization) or be a "Collaborator" (for repos in a user account) to be able to set commit statuses:**
![Atlantis status](./images/status.png)
- create a Personal Access Token by following [https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/#creating-a-token](https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/#creating-a-token)
- create the token with **repo** scope
- record the access token
### Create a GitLab Token
- follow [https://docs.gitlab.com/ce/user/profile/personal_access_tokens.html#creating-a-personal-access-token](https://docs.gitlab.com/ce/user/profile/personal_access_tokens.html#creating-a-personal-access-token)
- create a token with **api** scope
- record the access token
### Create a Bitbucket Cloud (bitbucket.org) App Password
- create an App Password by following [https://confluence.atlassian.com/bitbucket/app-passwords-828781300.html#Apppasswords-Createanapppassword](https://confluence.atlassian.com/bitbucket/app-passwords-828781300.html#Apppasswords-Createanapppassword)
- Label the password "atlantis"
- Select **Pull requests**: **Read** and **Write** so that Atlantis can read your pull requests and write comments to them
- record the access token
### Create a Bitbucket Server (aka Stash) Personal Access Token
- Click on your avatar in the top right and select **Manage account**
- Click **Personal access tokens** in the sidebar
- Click **Create a token**
- Name the token **atlantis**
- Give the token **Read** Project permissions and **Write** Pull request permissions
- Click **Create** and record the access token
## Next Steps
Once you've got your user and access token, you're ready to create a webhook secret. See [Creating a Webhook Secret](webhook-secrets.html).

88
runatlantis.io/docs/configuring-webhooks.md Normal file
View File

@@ -0,0 +1,88 @@
# Configuring Webhooks
Atlantis needs to receive Webhooks from your Git host so that it can respond to pull request events.
:::tip Pre-Requisites
* You have created an [access credential](access-credentials.html)
* You have created a [webhook secret](webhook-secrets.html)
* You have [deployed](deployment.html) Atlantis and have a url for it
:::
See the instructions for your specific provider below.
[[toc]]
## GitHub/GitHub Enterprise Webhook
You can install your webhook at the organization level, or for each repository.
If only some of the repos in your organization are to be managed by Atlantis, then you
may want to only install on specific repos for now.
::: tip
If you're not sure if you have a GitHub organization see [https://help.github.com/articles/differences-between-user-and-organization-accounts/](https://help.github.com/articles/differences-between-user-and-organization-accounts/)
:::
If you're installing on the organization, navigate to your organization's page and click **Settings**.
If installing on a single repository, navigate to the repository home page and click **Settings**.
- Select **Webhooks** or **Hooks** in the sidebar
- Click **Add webhook**
- set **Payload URL** to `http://$URL/events` (or `https://$URL/events` if you're using SSL) where `$URL` is where Atlantis is hosted. **Be sure to add `/events`**
- double-check you added `/events` to the end of your URL.
- set **Content type** to `application/json`
- set **Secret** to the Webhook Secret you generated previously
- **NOTE** If you're adding a webhook to multiple repositories, each repository will need to use the **same** secret.
- select **Let me select individual events**
- check the boxes
- **Pull request reviews**
- **Pushes**
- **Issue comments**
- **Pull requests**
- leave **Active** checked
- click **Add webhook**
## GitLab Webhook
If you're using GitLab, navigate to your project's home page in GitLab
- Click **Settings > Integrations** in the sidebar
- set **URL** to `http://$URL/events` (or `https://$URL/events` if you're using SSL) where `$URL` is where Atlantis is hosted. **Be sure to add `/events`**
- double-check you added `/events` to the end of your URL.
- set **Secret Token** to the Webhook Secret you generated previously
- **NOTE** If you're adding a webhook to multiple repositories, each repository will need to use the **same** secret.
- check the boxes
- **Push events**
- **Comments**
- **Merge Request events**
- leave **Enable SSL verification** checked
- click **Add webhook**
## Bitbucket Cloud (bitbucket.org) Webhook
- Go to your repo's home page
- Click **Settings** in the sidebar
- Click **Webhooks** under the **WORKFLOW** section
- Click **Add webhook**
- Enter "Atlantis" for **Title**
- set **URL** to `http://$URL/events` (or `https://$URL/events` if you're using SSL) where `$URL` is where Atlantis is hosted. **Be sure to add `/events`**
- double-check you added `/events` to the end of your URL.
- Keep **Status** as Active
- Don't check **Skip certificate validation** because NGROK has a valid cert.
- Select **Choose from a full list of triggers**
- Under **Repository** **un**check everything
- Under **Issues** leave everything **un**checked
- Under **Pull Request**, select: Created, Updated, Merged, Declined and Comment created
- Click **Save**
<img src="../guide/images/bitbucket-webhook.png" alt="Bitbucket Webhook" style="max-height: 500px">
## Bitbucket Server (aka Stash) Webhook
- Go to your repo's home page
- Click **Settings** in the sidebar
- Click **Webhooks** under the **WORKFLOW** section
- Click **Create webhook**
- Enter "Atlantis" for **Name**
- set **URL** to `http://$URL/events` (or `https://$URL/events` if you're using SSL) where `$URL` is where Atlantis is hosted. **Be sure to add `/events`**
- Double-check you added `/events` to the end of your URL.
- Set **Secret** to the Webhook Secret you generated previously
- **NOTE** If you're adding a webhook to multiple repositories, each repository will need to use the **same** secret.
- Under **Repository** select **Push**
- Under **Pull Request**, select: Opened, Modified, Merged, Declined, Deleted and Comment added
- Click **Save**<img src="../guide/images/bitbucket-server-webhook.png" alt="Bitbucket Webhook" style="max-height: 500px;">
## Next Steps
* Now you're finally ready to use Atlantis! Open up a Terraform pull request
and you should see Atlantis respond.

7
runatlantis.io/docs/customizing-atlantis.md Normal file
View File

@@ -0,0 +1,7 @@
# Customizing Atlantis
How Atlantis exactly operates for each repo can be customized via an
`atlantis.yaml` file placed at the root of each repo.
* Read about the possible [use cases](/guide/atlantis-yaml-use-cases.html)
* Check out the [atlantis.yaml reference](atlantis-yaml-reference.html)

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

@@ -1,255 +1,86 @@
# Production-Ready Deployment
[[toc]]
# Deployment
This doc covers getting Atlantis up and running in your infrastructure.
## Install Terraform
`terraform` needs to be in the `$PATH` for Atlantis.
Download from https://www.terraform.io/downloads.html
```bash
unzip path/to/terraform_*.zip -d /usr/local/bin
```
Check that it's in your `$PATH`
```
$ terraform version
Terraform v0.10.0
```
If you want to use a different version of Terraform see [Terraform Versions](#terraform-versions)
## Hosting Atlantis
Atlantis needs to be hosted somewhere that github.com/gitlab.com/bitbucket.org or your GitHub/GitLab Enterprise installation can reach.
Developers in your organization also need to be able to access Atlantis to view the UI and to delete locks.
By default Atlantis runs on port `4141`. This can be changed with the `--port` flag.
## Install Atlantis
Get the latest release from [https://github.com/runatlantis/atlantis/releases](https://github.com/runatlantis/atlantis/releases) and unpackage it.
## Add Webhook
Once you've decided where to host Atlantis you need to add that URL as a webhook
to your Git host so that Atlantis gets notified about pull request events.
See the instructions for your specific provider below:
### GitHub/GitHub Enterprise Webhook
If you already have a GitHub organization we recommend installing the webhook at the **organization level** rather than on each repository, however both methods will work.
::: tip
If you're not sure if you have a GitHub organization see [https://help.github.com/articles/differences-between-user-and-organization-accounts/](https://help.github.com/articles/differences-between-user-and-organization-accounts/)
::: tip Pre-Requisites
* You have created an [access credential](access-credentials.html)
* You have created a [webhook secret](webhook-secrets.html)
:::
If you're installing on the organization, navigate to your organization's page and click **Settings**.
If installing on a single repository, navigate to the repository home page and click **Settings**.
- Select **Webhooks** or **Hooks** in the sidebar
- Click **Add webhook**
- set **Payload URL** to `http://$URL/events` (or `https://$URL/events` if you're using SSL) where `$URL` is where Atlantis is hosted. **Be sure to add `/events`**
- double-check you added `/events` to the end of your URL.
- set **Content type** to `application/json`
- set **Secret** to a random key (https://www.random.org/strings/). You'll need to pass this value to the `--gh-webhook-secret` flag when you start Atlantis
- **NOTE** If you're adding a webhook to multiple repositories, each repository will need to use the **same** secret.
- select **Let me select individual events**
- check the boxes
- **Pull request reviews**
- **Pushes**
- **Issue comments**
- **Pull requests**
- leave **Active** checked
- click **Add webhook**
[[toc]]
### GitLab Webhook
If you're using GitLab, navigate to your project's home page in GitLab
- Click **Settings > Integrations** in the sidebar
- set **URL** to `http://$URL/events` (or `https://$URL/events` if you're using SSL) where `$URL` is where Atlantis is hosted. **Be sure to add `/events`**
- double-check you added `/events` to the end of your URL.
- set **Secret Token** to a random key (https://www.random.org/strings/). You'll need to pass this value to the `--gitlab-webhook-secret` flag when you start Atlantis
- **NOTE** If you're adding a webhook to multiple repositories, each repository will need to use the **same** secret.
- check the boxes
- **Push events**
- **Comments**
- **Merge Request events**
- leave **Enable SSL verification** checked
- click **Add webhook**
## Architecture Overview
### Runtime
Atlantis is a simple [Go](https://golang.org/) app. It receives webhooks from
your Git host and executes Terraform commands locally. There is an official
Atlantis [Docker image](https://hub.docker.com/r/runatlantis/atlantis/).
### Bitbucket Cloud (bitbucket.org) Webhook
- Go to your repo's home page
- Click **Settings** in the sidebar
- Click **Webhooks** under the **WORKFLOW** section
- Click **Add webhook**
- Enter "Atlantis" for **Title**
- set **URL** to `http://$URL/events` (or `https://$URL/events` if you're using SSL) where `$URL` is where Atlantis is hosted. **Be sure to add `/events`**
- double-check you added `/events` to the end of your URL.
- Keep **Status** as Active
- Don't check **Skip certificate validation** because NGROK has a valid cert.
- Select **Choose from a full list of triggers**
- Under **Repository** **un**check everything
- Under **Issues** leave everything **un**checked
- Under **Pull Request**, select: Created, Updated, Merged, Declined and Comment created
- Click **Save**
<img src="../guide/images/bitbucket-webhook.png" alt="Bitbucket Webhook" style="max-height: 500px">
### Routing
Because Atlantis needs to receive webhooks from your Git host, it must be routable
from that Git host. If you're using a public Git host like GitHub.com, GitLab.com
or Bitbucket.org then you'll need to expose Atlantis to the internet.
### Bitbucket Server (aka Stash) Webhook
- Go to your repo's home page
- Click **Settings** in the sidebar
- Click **Webhooks** under the **WORKFLOW** section
- Click **Create webhook**
- Enter "Atlantis" for **Name**
- set **URL** to `http://$URL/events` (or `https://$URL/events` if you're using SSL) where `$URL` is where Atlantis is hosted. **Be sure to add `/events`**
- Double-check you added `/events` to the end of your URL.
- Set **Secret** to a random key (https://www.random.org/strings/). You'll need to pass this value to the `--bitbucket-webhook-secret` flag when you start Atlantis
- **NOTE** If you're adding a webhook to multiple repositories, each repository will need to use the **same** secret.
- Under **Repository** select **Push**
- Under **Pull Request**, select: Opened, Modified, Merged, Declined, Deleted and Comment added
- Click **Save**<img src="../guide/images/bitbucket-server-webhook.png" alt="Bitbucket Webhook" style="max-height: 500px;">
If you're using a private Git host like GitHub Enterprise, GitLab Enterprise or
Bitbucket Server, then you just need Atlantis to be routable from there.
## Create an access token for Atlantis
We recommend using a dedicated CI user or creating a new user named **@atlantis** that performs all API actions, however for testing,
you can use your own user. Here we'll create the access token that Atlantis uses to comment on the pull request and
set commit statuses.
### Data
Atlantis has no external database. Atlantis stores Terraform plan files on disk.
If Atlantis loses that data in between a `plan` and `apply` cycle, then users will have
to re-run `plan`. Because of this, you may want to provision a persistent disk
for Atlantis.
### Create a GitHub Token
**NOTE: The Atlantis user must have "Write permissions" (for repos in an organization) or be a "Collaborator" (for repos in a user account) to be able to set commit statuses:**
![Atlantis status](./images/status.png)
- create a Personal Access Token by following [https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/#creating-a-token](https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/#creating-a-token)
- create the token with **repo** scope
- copy the access token
## Deployment
### Create a GitLab Token
- follow [https://docs.gitlab.com/ce/user/profile/personal_access_tokens.html#creating-a-personal-access-token](https://docs.gitlab.com/ce/user/profile/personal_access_tokens.html#creating-a-personal-access-token)
- create a token with **api** scope
- copy the access token
Pick your deployment type:
* [Kubernetes Helm Chart](#kubernetes-helm-chart)
* [Kubernetes Manifests](#kubernetes-manifests)
* [OpenShift](#openshift)
* [AWS Fargate](#aws-fargate)
* [Google Kubernetes Engine (GKE)](#google-kubernetes-engine-gke)
* [Docker](#docker)
* [Roll your own](#roll-your-own)
### Create a Bitbucket Cloud (bitbucket.org) App Password
- create an App Password by following [https://confluence.atlassian.com/bitbucket/app-passwords-828781300.html#Apppasswords-Createanapppassword](https://confluence.atlassian.com/bitbucket/app-passwords-828781300.html#Apppasswords-Createanapppassword)
- Label the password "atlantis"
- Select **Pull requests**: **Read** and **Write** so that Atlantis can read your pull requests and write comments to them
- copy the access token
### Create a Bitbucket Server (aka Stash) Personal Access Token
- Click on your avatar in the top right and select **Manage account**
- Click **Personal access tokens** in the sidebar
- Click **Create a token**
- Name the token **atlantis**
- Give the token **Read** Project permissions and **Write** Pull request permissions
- Click **Create** and copy the access token
### Kubernetes Helm Chart
Atlantis has an [official Helm chart](https://hub.kubeapps.com/charts/stable/atlantis).
## Start Atlantis
Now you're ready to start Atlantis! The exact command depends on your Git host:
To install:
1. `cd` into a directory where you're going to configure your Atlantis Helm chart
1. Create a `values.yaml` file by running
```bash
helm inspect values stable/atlantis > values.yaml
```
1. Edit `values.yaml` and add your access credentials and webhook secret
```yaml
# for example
github:
user: foo
token: bar
secret: baz
```
1. Edit `values.yaml` and set your `orgWhitelist`
```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. Run
```sh
helm install -f values.yaml stable/atlantis
```
### GitHub Command
```bash
atlantis server \
--atlantis-url="$URL" \
--gh-user="$USERNAME" \
--gh-token="$TOKEN" \
--gh-webhook-secret="$SECRET" \
--repo-whitelist="$REPO_WHITELIST"
```
### GitHub Enterprise Command
```bash
HOSTNAME=YOUR_GITHUB_ENTERPRISE_HOSTNAME # ex. github.runatlantis.io
atlantis server \
--atlantis-url="$URL" \
--gh-user="$USERNAME" \
--gh-token="$TOKEN" \
--gh-webhook-secret="$SECRET" \
--gh-hostname="$HOSTNAME" \
--repo-whitelist="$REPO_WHITELIST"
```
Atlantis should be up and running in minutes! See [Next Steps](#next-steps) for
what to do next.
### GitLab Command
```bash
atlantis server \
--atlantis-url="$URL" \
--gitlab-user="$USERNAME" \
--gitlab-token="$TOKEN" \
--gitlab-webhook-secret="$SECRET" \
--repo-whitelist="$REPO_WHITELIST"
```
### GitLab Enterprise Command
```bash
HOSTNAME=YOUR_GITLAB_ENTERPRISE_HOSTNAME # ex. gitlab.runatlantis.io
atlantis server \
--atlantis-url="$URL" \
--gitlab-user="$USERNAME" \
--gitlab-token="$TOKEN" \
--gitlab-webhook-secret="$SECRET" \
--gitlab-hostname="$HOSTNAME" \
--repo-whitelist="$REPO_WHITELIST"
```
### Bitbucket Cloud (bitbucket.org) Command
```bash
atlantis server \
--atlantis-url="$URL" \
--bitbucket-user="$USERNAME" \
--bitbucket-token="$TOKEN" \
--repo-whitelist="$REPO_WHITELIST"
```
### Bitbucket Server (aka Stash) Command
```bash
BASE_URL=YOUR_BITBUCKET_SERVER_URL # ex. http://bitbucket.mycorp:7990
atlantis server \
--atlantis-url="$URL" \
--bitbucket-user="$USERNAME" \
--bitbucket-token="$TOKEN" \
--bitbucket-webhook-secret="$SECRET" \
--bitbucket-base-url="$BASE_URL" \
--repo-whitelist="$REPO_WHITELIST"
```
Where
- `$URL` is the URL that Atlantis can be reached at
- `$USERNAME` is the GitHub/GitLab/Bitbucket username you generated the token for
- `$TOKEN` is the access token you created. If you don't want this to be passed in as an argument for security reasons you can specify it in a config file (see [Configuration](/docs/server-configuration.html#environment-variables)) or as an environment variable: `ATLANTIS_GH_TOKEN` or `ATLANTIS_GITLAB_TOKEN` or `ATLANTIS_BITBUCKET_TOKEN`
- `$SECRET` is the random key you used for the webhook secret. If you don't want this to be passed in as an argument for security reasons you can specify it in a config file (see [Configuration](/docs/server-configuration.html#environment-variables)) or as an environment variable: `ATLANTIS_GH_WEBHOOK_SECRET` or `ATLANTIS_GITLAB_WEBHOOK_SECRET`
- `$REPO_WHITELIST` is which repos Atlantis can run on, ex. `github.com/runatlantis/*` or `github.enterprise.corp.com/*`. See [www.runatlantis.io/docs/security.html#repo-whitelist](/docs/security.html#repo-whitelist) for more details.
Atlantis is now running!
**We recommend running it under something like Systemd or Supervisord.**
## Docker
Atlantis also ships inside a docker image. Run the docker image:
```bash
docker run runatlantis/atlantis:latest server <required options>
```
### Usage
If you need to modify the Docker image that we provide, for instance to add a specific version of Terraform, you can do something like this:
* Create a custom docker file
```bash
vim Dockerfile-custom
```
```dockerfile
FROM runatlantis/atlantis
# copy a terraform binary of the version you need
COPY terraform /usr/local/bin/terraform
```
* Build docker image
```bash
docker build -t {YOUR_DOCKER_ORG}/atlantis-custom -f Dockerfile-custom .
```
* Run docker image
```bash
docker run {YOUR_DOCKER_ORG}/atlantis-custom server --gh-user=GITHUB_USERNAME --gh-token=GITHUB_TOKEN
```
## Kubernetes
Atlantis can be deployed into Kubernetes as a
### Kubernetes Manifests
If you'd like to use a raw Kubernetes manifest, we offer either a
[Deployment](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/)
or as a [Statefulset](https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/) with persistent storage.
or a [Statefulset](https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/) with persistent storage.
StatefulSet is recommended because Atlantis stores its data on disk and so if your Pod dies
or you upgrade Atlantis, you won't lose the data. On the other hand, the only data that
Atlantis has right now is any plans that haven't been applied and Atlantis locks. If
Atlantis loses that data, you just need to run `atlantis plan` again so it's not the end of the world.
or you upgrade Atlantis, you won't lose plans that haven't been applied. If
you do lose that data, you just need to run `atlantis plan` again so it's not the end of the world.
Regardless of whether you choose a Deployment or StatefulSet, first create a Secret with the webhook secret and access token:
```bash
@@ -257,16 +88,16 @@ echo -n "yourtoken" > token
echo -n "yoursecret" > webhook-secret
kubectl create secret generic atlantis-vcs --from-file=token --from-file=webhook-secret
```
::: tip
::: tip Note
If you're using Bitbucket Cloud then there is no webhook secret since it's not supported.
:::
Next, edit the manifests below as follows:
1. Replace `<VERSION>` in `image: runatlantis/atlantis:<VERSION>` with the most recent version from https://github.com/runatlantis/atlantis/releases/latest.
1. Replace `<VERSION>` in `image: runatlantis/atlantis:<VERSION>` with the most recent version from [https://github.com/runatlantis/atlantis/releases/latest](https://github.com/runatlantis/atlantis/releases/latest).
* NOTE: You never want to run with `:latest` because if your Pod moves to a new node, Kubernetes will pull the latest image and you might end
up upgrading Atlantis by accident!
2. Replace `value: github.com/yourorg/*` under `name: ATLANTIS_REPO_WHITELIST` with the whitelist pattern
for your Terraform repos. See [--repo-whitelist](/docs/security.html#repo-whitelist) for more details.
for your Terraform repos. See [Repo Whitelist](server-configuration.html#repo-whitelist) for more details.
3. If you're using GitHub:
1. Replace `<YOUR_GITHUB_USER>` with the username of your Atlantis GitHub user without the `@`.
2. Delete all the `ATLANTIS_GITLAB_*` and `ATLANTIS_BITBUCKET_*` environment variables.
@@ -277,7 +108,7 @@ for your Terraform repos. See [--repo-whitelist](/docs/security.html#repo-whitel
1. Replace `<YOUR_BITBUCKET_USER>` with the username of your Atlantis Bitbucket user without the `@`.
2. Delete all the `ATLANTIS_GH_*` and `ATLANTIS_GITLAB_*` environment variables.
### StatefulSet Manifest
#### StatefulSet Manifest
<details>
<summary>Show...</summary>
@@ -339,7 +170,7 @@ spec:
name: atlantis-vcs
key: webhook-secret
### End GitLab Config ###
### Bitbucket Config ###
- name: ATLANTIS_BITBUCKET_USER
value: <YOUR_BITBUCKET_USER> # 5i. If you're using Bitbucket replace <YOUR_BITBUCKET_USER> with the username of your Atlantis Bitbucket user without the `@`.
@@ -409,7 +240,7 @@ spec:
</details>
### Deployment Manifest
#### Deployment Manifest
<details>
<summary>Show...</summary>
@@ -520,7 +351,7 @@ spec:
```
</details>
### Routing and SSL
#### Routing and SSL
The manifests above create a Kubernetes `Service` of type `ClusterIP` which isn't accessible outside your cluster.
Depending on how you're doing routing into Kubernetes, you may want to use a `LoadBalancer` so that Atlantis is accessible
to GitHub/GitLab and your internal users.
@@ -529,31 +360,161 @@ If you want to add SSL you can use something like [https://github.com/jetstack/c
certs and mount them into the Pod. Then set the `ATLANTIS_SSL_CERT_FILE` and `ATLANTIS_SSL_KEY_FILE` environment variables to enable SSL.
You could also set up SSL at your LoadBalancer.
**You're done! See [Next Steps](#next-steps) for what to do next.**
### OpenShift
The Atlantis Docker image is compatible with OpenShift, however you need to run
with an additional flag: `--data-dir=/home/atlantis`. This is required because
The Helm chart and Kubernetes manifests above are compatible with OpenShift, however you need to run
with an additional environment variable: `ATLANTIS_DATA_DIR=/home/atlantis`. This is required because
OpenShift runs Docker images with random user id's that use `/` as their home directory.
Since Atlantis defaults to using the home directory as its data dir and `/` doesn't have the correct permissions,
you need to set `--data-dir` or the environment variable `ATLANTIS_DATA_DIR` to `/home/atlantis`.
## AWS Fargate
### AWS Fargate
If you'd like to run Atlantis on [AWS Fargate](https://aws.amazon.com/fargate/)
check out the Atlantis module on the Terraform Module Registry: [https://registry.terraform.io/modules/terraform-aws-modules/atlantis/aws](https://registry.terraform.io/modules/terraform-aws-modules/atlantis/aws)
and then check out the [Next Steps](#next-steps).
If you'd like to run Atlantis on [AWS Fargate](https://aws.amazon.com/fargate/) check out the Atlantis module on the Terraform Module Registry: https://registry.terraform.io/modules/terraform-aws-modules/atlantis/aws
### Google Kubernetes Engine (GKE)
You can run Atlantis on GKE using the [Helm chart](#kubernetes-helm-chart) or the [manifests](#kubernetes-manifests).
## Testing Out Atlantis on GitHub
There is also a set of full Terraform configurations that create a GKE Cluster,
Cloud Storage Backend and TLS certs: [https://github.com/sethvargo/atlantis-on-gke](https://github.com/sethvargo/atlantis-on-gke).
If you'd like to test out Atlantis before running it on your own repositories you can fork our example repo.
Once you're done, see [Next Steps](#next-steps).
- Fork [https://github.com/runatlantis/atlantis-example](https://github.com/runatlantis/atlantis-example)
- If you didn't add the Webhook as to your organization add Atlantis as a Webhook to the forked repo (see [Add GitHub Webhook](#add-github-webhook))
- Now that Atlantis can receive events you should be able to comment on a pull request to trigger Atlantis. Create a pull request
- Click **Branches** on your forked repo's homepage
- click the **New pull request** button next to the `example` branch
- Change the `base` to `{your-repo}/master`
- click **Create pull request**
- Now you can test out Atlantis
- Create a comment `atlantis help` to see what commands you can run from the pull request
- `atlantis plan` will run `terraform plan` behind the scenes. You should see the output commented back on the pull request. You should also see some logs show up where you're running `atlantis server`
- `atlantis apply` will run `terraform apply`. Since our pull request creates a `null_resource` (which does nothing) this is safe to do.
### Docker
Atlantis has an [official](https://hub.docker.com/r/runatlantis/atlantis/) Docker image: `runatlantis/atlantis`.
#### Customization
If you need to modify the Docker image that we provide, for instance to add a specific version of Terraform, you can do something like this:
1. Create a custom docker file
```dockerfile
FROM runatlantis/atlantis:{latest version}
# copy a terraform binary of the version you need
COPY terraform /usr/local/bin/terraform
```
1. Build your Docker image
```bash
docker build -t {YOUR_DOCKER_ORG}/atlantis-custom .
```
1. Run your image
```bash
docker run {YOUR_DOCKER_ORG}/atlantis-custom server --gh-user=GITHUB_USERNAME --gh-token=GITHUB_TOKEN
```
### Roll Your Own
If you're deploying Atlantis into infrastructure not listed above, here's what
Atlantis needs in its environment.
#### Terraform
The `terraform` binary needs to be in the `$PATH` for Atlantis.
Download from https://www.terraform.io/downloads.html
```bash
unzip path/to/terraform_*.zip -d /usr/local/bin
```
Check that it's in your `$PATH`
```
$ terraform version
Terraform v0.10.0
```
If you want to use a different version of Terraform see [Terraform Versions](requirements.html#terraform-versions)
#### Atlantis Binary
Get the latest release from [https://github.com/runatlantis/atlantis/releases](https://github.com/runatlantis/atlantis/releases) and unpackage it.
#### Startup Command
The exact flags to `atlantis server` depends on your Git host:
##### GitHub
```bash
atlantis server \
--atlantis-url="$URL" \
--gh-user="$USERNAME" \
--gh-token="$TOKEN" \
--gh-webhook-secret="$SECRET" \
--repo-whitelist="$REPO_WHITELIST"
```
##### GitHub Enterprise
```bash
HOSTNAME=YOUR_GITHUB_ENTERPRISE_HOSTNAME # ex. github.runatlantis.io
atlantis server \
--atlantis-url="$URL" \
--gh-user="$USERNAME" \
--gh-token="$TOKEN" \
--gh-webhook-secret="$SECRET" \
--gh-hostname="$HOSTNAME" \
--repo-whitelist="$REPO_WHITELIST"
```
##### GitLab
```bash
atlantis server \
--atlantis-url="$URL" \
--gitlab-user="$USERNAME" \
--gitlab-token="$TOKEN" \
--gitlab-webhook-secret="$SECRET" \
--repo-whitelist="$REPO_WHITELIST"
```
##### GitLab Enterprise
```bash
HOSTNAME=YOUR_GITLAB_ENTERPRISE_HOSTNAME # ex. gitlab.runatlantis.io
atlantis server \
--atlantis-url="$URL" \
--gitlab-user="$USERNAME" \
--gitlab-token="$TOKEN" \
--gitlab-webhook-secret="$SECRET" \
--gitlab-hostname="$HOSTNAME" \
--repo-whitelist="$REPO_WHITELIST"
```
##### Bitbucket Cloud (bitbucket.org)
```bash
atlantis server \
--atlantis-url="$URL" \
--bitbucket-user="$USERNAME" \
--bitbucket-token="$TOKEN" \
--repo-whitelist="$REPO_WHITELIST"
```
##### Bitbucket Server (aka Stash)
```bash
BASE_URL=YOUR_BITBUCKET_SERVER_URL # ex. http://bitbucket.mycorp:7990
atlantis server \
--atlantis-url="$URL" \
--bitbucket-user="$USERNAME" \
--bitbucket-token="$TOKEN" \
--bitbucket-webhook-secret="$SECRET" \
--bitbucket-base-url="$BASE_URL" \
--repo-whitelist="$REPO_WHITELIST"
```
Where
- `$URL` is the URL that Atlantis can be reached at
- `$USERNAME` is the GitHub/GitLab/Bitbucket username you generated the token for
- `$TOKEN` is the access token you created. If you don't want this to be passed
in as an argument for security reasons you can specify it in a config file
(see [Configuration](/docs/server-configuration.html#environment-variables))
or as an environment variable: `ATLANTIS_GH_TOKEN` or `ATLANTIS_GITLAB_TOKEN`
or `ATLANTIS_BITBUCKET_TOKEN`
- `$SECRET` is the random key you used for the webhook secret.
If you don't want this to be passed in as an argument for security reasons
you can specify it in a config file
(see [Configuration](/docs/server-configuration.html#environment-variables))
or as an environment variable: `ATLANTIS_GH_WEBHOOK_SECRET` or `ATLANTIS_GITLAB_WEBHOOK_SECRET`
- `$REPO_WHITELIST` is which repos Atlantis can run on, ex.
`github.com/runatlantis/*` or `github.enterprise.corp.com/*`.
See [Repo Whitelist](server-configuration.html#repo-whitelist) for more details.
Atlantis is now running!
::: tip
We recommend running it under something like Systemd or Supervisord. That will
restart it in case of failure.
:::
## Next Steps
* To ensure Atlantis is running, load its UI. By default Atlantis runs on port `4141`.
* Now you're ready to add Webhooks to your repos. See [Configuring Webhooks](configuring-webhooks.html).

5
runatlantis.io/docs/how-atlantis-works.md Normal file
View File

@@ -0,0 +1,5 @@
# How Atlantis Works
This section of docs talks about how Atlantis at deeper level.
* [Locking](locking.html)
* [Autoplanning](autoplanning.html)

BIN
runatlantis.io/docs/images/example-comment.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 79 KiB

13
runatlantis.io/docs/installation-guide.md Normal file
View File

@@ -0,0 +1,13 @@
# Installation Guide
To get Atlantis running you need to:
1. Create **access credentials** on your Git host (GitHub, GitLab, Bitbucket)
* See [Generating Git host Access Credentials](access-credentials.html)
1. Create a **webhook secret** so Atlantis can validate webhooks securely
* See [Creating a Webhook Secret](webhook-secrets.html)
1. **Deploy** Atlantis into your infrastructure
* See [Deployment](deployment.html)
1. Configure **Webhooks** on your Git host so Atlantis can respond to your pull requests
* See [Configuring Webhooks](configuring-webhooks.html)
And before you do all this, first check that you meet all the [Requirements](requirements.html).

25
runatlantis.io/guide/requirements.md → runatlantis.io/docs/requirements.md
View File

@@ -1,19 +1,23 @@
# Requirements
Atlantis works with most Git hosts and Terraform setups. Read on to confirm
it works with yours.
[[toc]]
## Git Host
## Git host
Atlantis integrates with the following Git hosts:
* GitHub (public, private or enterprise)
* GitLab (public, private or enterprise)
* Bitbucket Cloud aka bitbucket.org (public or private)
* Bitbucket Server aka Stash
## Remote State
Atlantis supports all remote state backends. It **does not** support local state
## 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.
## Repository Structure
Atlantis supports any Terraform project structures, for example:
Atlantis supports any Terraform repository structure, for example:
### Single Terraform project at repo root
```
@@ -45,15 +49,15 @@ Atlantis supports any Terraform project structures, for example:
└── ...
```
With modules, if you want `project1` automatically planned when `module1` is modified
you need to create an `atlantis.yaml` file. See [atlantis.yaml Use Cases](atlantis-yaml-use-cases.html#configuring-autoplanning) for more details.
you need to create an `atlantis.yaml` file. See [atlantis.yaml Use Cases](/guide/atlantis-yaml-use-cases.html#configuring-autoplanning) for more details.
### Terraform Workspaces
::: tip
See [Terraform's docs](https://www.terraform.io/docs/state/workspaces.html) if you are unfamiliar with workspaces.
:::
If you're using a Terraform version >= 0.9.0, Atlantis supports workspaces through an
If you're using Terraform `>= 0.9.0`, Atlantis supports workspaces through an
`atlantis.yaml` file that tells Atlantis the names of your workspaces
(see [atlantis.yaml Use Cases](atlantis-yaml-use-cases.html#supporting-terraform-workspaces) for more details)
(see [atlantis.yaml Use Cases](/guide/atlantis-yaml-use-cases.html#supporting-terraform-workspaces) for more details)
or through the `-w` flag. For example:
```
atlantis plan -w staging
@@ -70,7 +74,7 @@ atlantis apply -w staging
```
For Atlantis to be able to plan automatically with `.tfvars files`, you need to create
an `atlantis.yaml` file to tell it to use `-var-file={YOUR_FILE}`.
See [atlantis.yaml Use Cases](atlantis-yaml-use-cases.html#using-tfvars-files) for more details.
See [atlantis.yaml Use Cases](/guide/atlantis-yaml-use-cases.html#using-tfvars-files) for more details.
## Terraform Versions
By default, Atlantis will use the `terraform` executable that is in its path.
@@ -78,7 +82,8 @@ To use a specific version of Terraform:
1. Install the desired version of Terraform into the `$PATH` of where Atlantis is
running and name it `terraform{version}`, ex. `terraform0.8.8`.
2. Create an `atlantis.yaml` file for your repo and set the `terraform_version` key.
See [atlantis.yaml Use Cases](atlantis-yaml-use-cases.html#terraform-versions) for more details.
See [atlantis.yaml Use Cases](/guide/atlantis-yaml-use-cases.html#terraform-versions) for more details.
## Next Steps
Check out our [full documentation](../docs/).
* If your Terraform setup meets the Atlantis requirements, head back to our [Installation Guide](installation-guide.html) to get started
installing Atlantis

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

@@ -85,3 +85,22 @@ terraform {
}
}
```
## Repo Whitelist
Atlantis requires you to specify a whitelist of repositories it will accept webhooks from via the `--repo-whitelist` flag.
Notes:
* Accepts a comma separated list, ex. `definition1,definition2`
* Format is `{hostname}/{owner}/{repo}`, ex. `github.com/runatlantis/atlantis`
* `*` matches any characters, ex. `github.com/runatlantis/*` will match all repos in the runatlantis organization
* For Bitbucket Server: `{hostname}` is the domain without scheme and port, `{owner}` is the name of the project (not the key), and `{repo}` is the repo name
Examples:
* Whitelist `myorg/repo1` and `myorg/repo2` on `github.com`
* `--repo-whitelist=github.com/myorg/repo1,github.com/myorg/repo2`
* Whitelist all repos under `myorg` on `github.com`
* `--repo-whitelist='github.com/myorg/*'`
* Whitelist all repos in my GitHub Enterprise installation
* `--repo-whitelist='github.yourcompany.com/*'`
* Whitelist all repositories
* `--repo-whitelist='*'`

6
runatlantis.io/docs/pull-request-commands.md → runatlantis.io/docs/using-atlantis.md
View File

@@ -1,4 +1,5 @@
# Pull Request Commands
# Using Atlantis
Atlantis currently supports three commands that can be run via pull request comments:
[[toc]]
@@ -51,7 +52,7 @@ you can append them to the end of the comment after `--`, ex.
```
atlantis plan -d dir -- -var 'foo=bar'
```
If you always need to append a certain flag, see [Project-Specific Customization](#project-specific-customization).
If you always need to append a certain flag, see [atlantis.yaml Use Cases](/guide/atlantis-yaml-use-cases.html#adding-extra-arguments-to-terraform-commands).
---
## atlantis apply
@@ -96,3 +97,4 @@ Because Atlantis under the hood is running `terraform apply plan.tfplan`, any Te
They're ignored because they can't be specified for an already generated planfile.
If you would like to specify these flags, do it while running `atlantis plan`.

30
runatlantis.io/docs/webhook-secrets.md Normal file
View File

@@ -0,0 +1,30 @@
# Webhook Secrets
Atlantis uses Webhook secrets to validate that the webhooks it receives from your
Git host are legitimate.
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
Webhook secrets are actually optional. However they're highly recommended for
security.
:::
## Generating A Webhook Secret
You can use any random string generator to create your Webhook secret. It should be > 24 characters.
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
You must use **the same** webhook secret for each repo.
:::
## Next Steps
* Record your secret
* You'll be using it later to [configure your webhooks](configuring-webhooks.html), however if you're
following the [Installation Guide](installation-guide.html) then your next step is to
[Deploy Atlantis](deployment.html)

2
runatlantis.io/guide/README.md
View File

@@ -56,4 +56,4 @@ to construct your ideal workflow.
## Next Steps
* If you'd like to try out Atlantis on a test repo, check out the [Test Drive](test-drive.html).
* If you're ready to deploy it on your own repos, check out [Getting Started](getting-started.html).
* If you're wondering if Atlantis supports how you run Terraform, read [Requirements](requirements.html).
* If you're wondering if Atlantis supports how you run Terraform, read [Requirements](/docs/requirements.html).

2
runatlantis.io/guide/getting-started.md
View File

@@ -195,7 +195,7 @@ REPO_WHITELIST="$YOUR_GIT_HOST/$YOUR_USERNAME/$YOUR_REPO"
# server without scheme or port and $YOUR_USERNAME will be the name of the **project** the repo
# is under, **not the key** of the project.
```
Now you can start Atlantis. The exact command differs depending on your Git Host:
Now you can start Atlantis. The exact command differs depending on your Git host:
### GitHub Command
```bash