From 52025b07d433bbed916d98e981605b192039a7d9 Mon Sep 17 00:00:00 2001 From: David Mattia <8922077+dmattia@users.noreply.github.com> Date: Mon, 25 Jan 2021 13:34:37 -0600 Subject: [PATCH] Update docs for plug and play usage (#105) Co-authored-by: dmattia --- README.md | 113 ++++++++++++++++++++++++++++-------------------------- 1 file changed, 58 insertions(+), 55 deletions(-) diff --git a/README.md b/README.md index 78c6deb3..90073049 100644 --- a/README.md +++ b/README.md @@ -22,37 +22,45 @@ This tool creates Atlantis YAML configurations for Terragrunt projects by: This is especially useful for organizations that use monorepos for their Terragrunt config (as we do at Transcend), and have thousands of lines of config. -## Installation and Usage +## Integrate into your Atlantis Server -Recommended: Install any version via go get: - -```bash -cd && GO111MODULE=on go get github.com/transcend-io/terragrunt-atlantis-config@master && cd - -``` +The recommended way to use this tool is to install it onto your Atlantis server, and then use a [Pre-Workflow hook](https://www.runatlantis.io/docs/pre-workflow-hooks.html#pre-workflow-hooks) to run it after every clone. This way, Atlantis can automatically determine what modules should be planned/applied for any change to your repository. -Alternative: Install a stable versions via Homebrew: +To get started, add a `pre_workflow_hooks` field to your `repos` section of your [server-side repo config](https://www.runatlantis.io/docs/server-side-repo-config.html#do-i-need-a-server-side-repo-config-file): -```bash -brew install transcend-io/tap/terragrunt-atlantis-config +```json +"repos": { + "id": "", + "workflow": "default", + "pre_workflow_hooks": [{ + "run": "terragrunt-atlantis-config generate --output atlantis.yaml --autoplan --parallel --create-workspace" + }] +} ``` -This module officially supports golang versions v1.13, v1.14, and v1.15, tested on CircleCI with each build -This module also officially supports both Windows and Nix-based file formats, tested on CircleCI with each build - -Usage Examples (see below sections for all options): - -```bash -# From the root of your repo -terragrunt-atlantis-config generate +Then, make sure `terragrunt-atlantis-config` is present on your Atlantis server. There are many different ways to configure a server, but this example in [Packer](https://www.packer.io/) should show the bash commands you'll need just about anywhere: -# or from anywhere -terragrunt-atlantis-config generate --root /some/path/to/your/repo/root +```go +variable terragrunt_atlantis_config_version { + default = "1.0.0" +} -# output to a file -terragrunt-atlantis-config generate --autoplan --output ./atlantis.yaml +build { + // ... + provisioner "shell" { + inline = [ + "wget https://github.com/transcend-io/terragrunt-atlantis-config/releases/download/v${var.terragrunt_atlantis_config_version}/terragrunt-atlantis-config_0.13.0_linux_amd64.tar.gz", + "sudo tar xf terragrunt-atlantis-config_${var.terragrunt_atlantis_config_version}_linux_amd64.tar.gz", + "sudo mv terragrunt-atlantis-config_${var.terragrunt_atlantis_config_version}_linux_amd64/terragrunt-atlantis-config_${var.terragrunt_atlantis_config_version}_linux_amd64 terragrunt-atlantis-config", + "sudo install terragrunt-atlantis-config /usr/local/bin", + ] + inline_shebang = "/bin/bash -e" + } + // ... +} ``` -Finally, check the log output (or your output file) for the YAML. +and just like that, your developers should never have to worry about an `atlantis.yaml` file, or even need to know what it is. ## Extra dependencies @@ -125,39 +133,6 @@ Another way to customize the output is to use `locals` values in your terragrunt | `atlantis_skip` | If true on a child module, that module will not appear in the output.
If true on a parent module, none of that parent's children will appear in the output. | bool | | `extra_atlantis_dependencies` | See [Extra dependencies](https://github.com/transcend-io/terragrunt-atlantis-config#extra-dependencies) | list(string) | -## Auto Enforcement with Github Actions - -It's a best practice to require that `atlantis.yaml` stays up to date on each Pull Request. - -To make this easy, there is an open-source Github Action that will fail a status check on your PR if the `atlantis.yaml` file is out of date. - -To use it, add this yaml to a new github action file in your repo: - -```yaml -name: terragrunt-atlantis-config -on: - push: - paths: - - '**.hcl' - - '**.tf' - - '**.hcl.json' - -jobs: - terragrunt_atlantis_config: - runs-on: ubuntu-latest - name: Validate atlantis.yaml - steps: - - uses: actions/checkout@v2 - - name: Ensure atlantis.yaml is up to date using terragrunt-atlantis-config - id: atlantis_validator - uses: transcend-io/terragrunt-atlantis-config-github-action@v0.0.3 - with: - version: v0.13.0 - extra_args: '--autoplan --parallel=false -``` - -You can customize the version and flags you typically pass to the `generate` command in those final two lines. - ## Separate workspace for parallel plan and apply Atlantis added support for running plan and apply parallel in [v0.13.0](https://github.com/runatlantis/atlantis/releases/tag/v0.13.0). @@ -176,6 +151,34 @@ Enabling this feature may consume more resources like cpu, memory, network, and As when defining the workspace this info is also needed when running `atlantis plan/apply -d ${git_root}/stage/app -w stage_app` to run the command on specific directory, you can also use the `atlantis plan/apply -p stage_app` in case you have enabled the `create-project-name` cli argument (it is `false` by default). +## Local Installation and Usage + +You can install this tool locally to checkout what kinds of config it will generate for your repo, though in production it is recommended to [install this tool directly onto your Atlantis server](##integrate-into-your-atlantis-server) + +Recommended: Install any version via go get: + +```bash +cd && GO111MODULE=on go get github.com/transcend-io/terragrunt-atlantis-config@v1.0.0 && cd - +``` + +This module officially supports golang versions v1.13, v1.14, and v1.15, tested on CircleCI with each build +This module also officially supports both Windows and Nix-based file formats, tested on CircleCI with each build + +Usage Examples (see below sections for all options): + +```bash +# From the root of your repo +terragrunt-atlantis-config generate + +# or from anywhere +terragrunt-atlantis-config generate --root /some/path/to/your/repo/root + +# output to a file +terragrunt-atlantis-config generate --autoplan --output ./atlantis.yaml +``` + +Finally, check the log output (or your output file) for the YAML. + ## Contributing To test any changes you've made, run `make test`.