diff --git a/.circleci/config.yml b/.circleci/config.yml index edb590a88..8871419be 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -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: diff --git a/runatlantis.io/.vuepress/config.js b/runatlantis.io/.vuepress/config.js index ee81209ad..ed5477542 100644 --- a/runatlantis.io/.vuepress/config.js +++ b/runatlantis.io/.vuepress/config.js @@ -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, } -} \ No newline at end of file +} diff --git a/runatlantis.io/.vuepress/style.styl b/runatlantis.io/.vuepress/style.styl index f0fd8e7bc..ed600df81 100644 --- a/runatlantis.io/.vuepress/style.styl +++ b/runatlantis.io/.vuepress/style.styl @@ -32,3 +32,7 @@ } } } + +.sidebar-heading { + font-size: inherit +} diff --git a/runatlantis.io/docs/README.md b/runatlantis.io/docs/README.md index da4d83c95..215e12758 100644 --- a/runatlantis.io/docs/README.md +++ b/runatlantis.io/docs/README.md @@ -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 diff --git a/runatlantis.io/docs/access-credentials.md b/runatlantis.io/docs/access-credentials.md new file mode 100644 index 000000000..0e5d3203d --- /dev/null +++ b/runatlantis.io/docs/access-credentials.md @@ -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) +

An example comment coming from the @atlantisbot user

+ +## 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). diff --git a/runatlantis.io/docs/configuring-webhooks.md b/runatlantis.io/docs/configuring-webhooks.md new file mode 100644 index 000000000..8de7d1138 --- /dev/null +++ b/runatlantis.io/docs/configuring-webhooks.md @@ -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** +Bitbucket Webhook + +## 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**Bitbucket Webhook + +## Next Steps +* Now you're finally ready to use Atlantis! Open up a Terraform pull request + and you should see Atlantis respond. diff --git a/runatlantis.io/docs/customizing-atlantis.md b/runatlantis.io/docs/customizing-atlantis.md new file mode 100644 index 000000000..d7f6cf0cb --- /dev/null +++ b/runatlantis.io/docs/customizing-atlantis.md @@ -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) diff --git a/runatlantis.io/docs/deployment.md b/runatlantis.io/docs/deployment.md index de06315dc..982ceb86a 100644 --- a/runatlantis.io/docs/deployment.md +++ b/runatlantis.io/docs/deployment.md @@ -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** -Bitbucket Webhook +### 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**Bitbucket Webhook +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 -``` - -### 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 `` in `image: runatlantis/atlantis:` with the most recent version from https://github.com/runatlantis/atlantis/releases/latest. +1. Replace `` in `image: runatlantis/atlantis:` 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 `` 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 `` 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
Show... @@ -339,7 +170,7 @@ spec: name: atlantis-vcs key: webhook-secret ### End GitLab Config ### - + ### Bitbucket Config ### - name: ATLANTIS_BITBUCKET_USER value: # 5i. If you're using Bitbucket replace with the username of your Atlantis Bitbucket user without the `@`. @@ -409,7 +240,7 @@ spec:
-### Deployment Manifest +#### Deployment Manifest
Show... @@ -520,7 +351,7 @@ spec: ```
-### 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). diff --git a/runatlantis.io/docs/how-atlantis-works.md b/runatlantis.io/docs/how-atlantis-works.md new file mode 100644 index 000000000..261a9fb9e --- /dev/null +++ b/runatlantis.io/docs/how-atlantis-works.md @@ -0,0 +1,5 @@ +# How Atlantis Works +This section of docs talks about how Atlantis at deeper level. + +* [Locking](locking.html) +* [Autoplanning](autoplanning.html) diff --git a/runatlantis.io/docs/images/example-comment.png b/runatlantis.io/docs/images/example-comment.png new file mode 100644 index 000000000..6b8e4e03f Binary files /dev/null and b/runatlantis.io/docs/images/example-comment.png differ diff --git a/runatlantis.io/docs/installation-guide.md b/runatlantis.io/docs/installation-guide.md new file mode 100644 index 000000000..10310c2f5 --- /dev/null +++ b/runatlantis.io/docs/installation-guide.md @@ -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). diff --git a/runatlantis.io/guide/requirements.md b/runatlantis.io/docs/requirements.md similarity index 65% rename from runatlantis.io/guide/requirements.md rename to runatlantis.io/docs/requirements.md index c7db09168..f15dadd81 100644 --- a/runatlantis.io/guide/requirements.md +++ b/runatlantis.io/docs/requirements.md @@ -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 diff --git a/runatlantis.io/docs/server-configuration.md b/runatlantis.io/docs/server-configuration.md index cffd53078..d4fe5e8ad 100644 --- a/runatlantis.io/docs/server-configuration.md +++ b/runatlantis.io/docs/server-configuration.md @@ -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='*'` diff --git a/runatlantis.io/docs/pull-request-commands.md b/runatlantis.io/docs/using-atlantis.md similarity index 95% rename from runatlantis.io/docs/pull-request-commands.md rename to runatlantis.io/docs/using-atlantis.md index 2bed29c9f..c23f380fd 100644 --- a/runatlantis.io/docs/pull-request-commands.md +++ b/runatlantis.io/docs/using-atlantis.md @@ -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`. + diff --git a/runatlantis.io/docs/webhook-secrets.md b/runatlantis.io/docs/webhook-secrets.md new file mode 100644 index 000000000..0fa34689c --- /dev/null +++ b/runatlantis.io/docs/webhook-secrets.md @@ -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) diff --git a/runatlantis.io/guide/README.md b/runatlantis.io/guide/README.md index d0994eb99..27d9fce99 100644 --- a/runatlantis.io/guide/README.md +++ b/runatlantis.io/guide/README.md @@ -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). \ No newline at end of file +* If you're wondering if Atlantis supports how you run Terraform, read [Requirements](/docs/requirements.html). diff --git a/runatlantis.io/guide/getting-started.md b/runatlantis.io/guide/getting-started.md index 2968df707..5c2dd9c06 100644 --- a/runatlantis.io/guide/getting-started.md +++ b/runatlantis.io/guide/getting-started.md @@ -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