Merge pull request #6 from Ibotta/adhoc/allow-ignore-web-acl-id-and-m…

…aster-updates

ADHOC: TLC for fork, and ignore web acl id

.github/CONTRIBUTING.md

@@ -0,0 +1,97 @@
+# Contributing
+
+### Prerequisites
+
+Install the following:
+
+- [terraform-docs](https://terraform-docs.io/)
+- [asdf-vm](https://asdf-vm.com/)
+
+#### MacOS
+
+```sh
+brew install npm
+npm install -g yo
+asdf plugin-add terraform-docs
+asdf install
+```
+
+## Important Notes
+* Module versions should follow best practices for [Semantic Versioning](https://semver.org/).
+
+## Creating a new AND latest version of a module
+
+These steps are for creating a new version of the module that is **based off of the latest version of the module**.  This is the most common use case for creating a new module version. If you are updating a previously released module that is not currently the latest version of the module, see [Patching Released Tags](#patching-released-tags) instead. The main difference being patches to previous versions should not be merged into `main` and should be tagged with the previous version number and closed unmerged instead.
+
+  1. Create a branch off of `main`
+  1. Make changes to the module
+  1. Update the [CHANGELOG.md](./CONTRIBUTING.md) file with the new version and changes
+  1. Run the formatting and docs script [Documentation and Formatting](#documentation-and-formatting)
+  1. Test your changes with [Module Testing](#module-testing)
+  1. Create a PR for review
+  1. Once approved, merge the PR into `main` 
+  1. Follow the steps below to create a new tag using the Github Release process.
+
+### Using Github Releases to create a new tag
+
+Follow these steps to create a new tag and release in Github.  This can also be used for patched released tags.  The benefit of the release process is to notify subscribers of the new tag.
+
+1. After merging your branch into `main`, navigate to the [Releases page for this module](https://github.com/Ibotta/terraform-module-route53-domain-redirect/releases).
+1. Click `Draft a new release`.
+1. Click `Choose a tag`, and type in the _new_ tag version you want to create.  You'll see an option for "Create new tag: **<TAG_NAME>** on publish".
+  1. For updates to the latest version of a module, keep the `Target` as `main`.
+  1. For patching released tags (backporting), change the `Target` to the tag that you branched from.
+1. Use the tag name as the `Release title`.
+1. Create your own Release Notes.  You can use your CHANGELOG notes as an easy option, or click `Generate release notes`.  This will generate notes based on the latest merged PRs but can sometimes create extra noise for merged PRs without associated releases. The goal is having a descriptive message with what features are being added, changed, or deprecated.
+1. Keep the `Set as the latest release`.
+1. Click `Publish Release`.
+
+## Patching Released Tags
+
+It is sometimes necessary to make changes to previously released module tags (also known as "backporting") for a repository that may not be able to update to newer versions of Terraform or the Terraform AWS Provider. Introducing a patch version of a previously released tag can allow fixes and even new features to help maintain the infrastructure.
+
+You can follow the Release process detailed above after the tag is created and pushed to notify users of the new tag being available.
+
+### Review Process and Creating a new tag
+
+Proceed with making commits, adhering to the style of the repository at the time (in some cases, we may not have had `CHANGELOG` documents or `terraform-docs` for formatting yet).  Once done, push up your branch to create a pull request for review.  Follow the guide below on [Module Testing](#module-testing) to make sure the changes work as expected.
+
+**⚠️ IMPORTANT ⚠️:** Instead of merging the PR after the review process, you will create a new tag locally and push that up.  Once it is available on GitHub, you can close your PR without merging. Finally, follow the [Github Releases](#using-github-releases-to-create-a-new-tag) process to publish the tag to subscribers.
+
+```
+git tag -a <VERSION-TAG> -m "<CHANGELOG-MESSAGE>"
+git push origin <VERSION-TAG>
+```
+
+## Module Testing
+
+After pushing up changes in a new branch and creating a PR, you can reference the branch in the module definition:
+
+```hcl
+module "module_name" {
+  source = "git::ssh://git@github.com/Ibotta/terraform-module-route53-domain-redirect.git?ref=<branch>"
+}
+```
+
+## Documentation and Formatting
+
+This module is configured through [terraform-docs](https://github.com/terraform-docs/terraform-docs) and can be updated by adjusting either `docs-header.md` or the variable/output descriptions and re-running the following:
+
+Short version: Run `./scripts/tf-gen.sh`.
+
+This script runs `terraform fmt` and `terraform-docs` on the module.
+
+### Details
+This module utilizes `terraform-docs` to generate the `README.md` file.
+
+A few important points:
+* You can see the terraform docs config file in [.terraform-docs.yml](../.terraform-docs.yml)
+* You can see the version of `terraform-docs` and `terraform` in the [.tool-versions](../.tool-versions) asdf config at the root of the repository.
+
+In order to update the documentation the following steps should be taken:
+1. Update code as required.
+1. Update the `docs-header.md` file if needed to provide updated usage instructions or new examples.
+1. In `variables.tf` all `variables` should have a complete `description` field. 
+1. All `output` attributes should include a comment immediately preceding the output defintion; this comment becomes the description of the attribute in the documentation. 
+1. Add a `CHANGELOG.md` record indicating the change and the new version.
+1. Run `./scripts/tf-gen.sh`.

.github/workflows/build.yml

@@ -0,0 +1,38 @@
+name: Build
+
+on:
+  push:
+    branches:
+      # Build on main too.
+      # This helps with cache performance:
+      #   https://github.com/actions/cache/blob/main/tips-and-workarounds.md#use-cache-across-feature-branches
+      - main
+  workflow_dispatch:  # Allows to trigger workflow manually
+  pull_request:
+
+jobs:
+  terraform_check:
+    runs-on: ubuntu-latest
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v3
+
+    - name: Get changed files
+      id: changed-files
+      uses: tj-actions/changed-files@v39.2.0
+      with:
+        files: |
+          service/**
+        fetch_depth: 2
+
+    - name: Cache ASDF
+      if: steps.changed-files.outputs.any_changed == 'true'
+      id: cache-asdf
+      uses: actions/cache@v3
+      with:
+        path: ~/.asdf
+        key: ${{ runner.os }}-asdf
+
+    - name: Check Terraform Formatting and Docs
+      if: steps.changed-files.outputs.any_changed == 'true'
+      run: ./scripts/terraform_format_and_docs.sh

.gitignore

@@ -1 +1,2 @@
 .idea
+.vscode

.tool-versions

@@ -0,0 +1,2 @@
+terraform-docs 0.16.0
+terraform 1.3.9

CHANGELOG.md

@@ -1,5 +1,10 @@
 ## Changelog
 
+### `1.2.6`
+
+- ignore `web_acl_id` in Cloudfront
+- add github action for formatting terraform and docs
+
 ### `1.2.5`
 
 - Move s3 website configuration to it's own resource `aws_s3_bucket_website_configuration`.

README.md

@@ -9,11 +9,8 @@ Both www and apex A records are created and pointed to a CloudFront distribution
 **Requirements:** DNS Zone in Route53
 
 ## To Deploy
-* Merge new version into `master`
-* `git checkout master`
-* `git pull`
-* `git tag <version-tag>`
-* `git push origin <version-tag>`
+
+Please review our [Contributing docs](./.github/CONTRIBUTING.md) for the review and release process.
 
 ## Requirements
 
@@ -67,6 +64,11 @@ No outputs.
 
 ## Changelog
 
+### `1.2.6`
+
+- ignore `web_acl_id` in Cloudfront
+- add github action for formatting terraform and docs
+
 ### `1.2.5`
 
 - Move s3 website configuration to it's own resource `aws_s3_bucket_website_configuration`.

cloudfront.tf

@@ -54,4 +54,8 @@ resource "aws_cloudfront_distribution" "redirect" {
 
   wait_for_deployment = false
   depends_on          = [aws_acm_certificate_validation.validation]
+
+  lifecycle {
+    ignore_changes = [web_acl_id]
+  }
 }

docs-header.md

@@ -9,8 +9,5 @@ Both www and apex A records are created and pointed to a CloudFront distribution
 **Requirements:** DNS Zone in Route53
 
 ## To Deploy
-* Merge new version into `master`
-* `git checkout master`
-* `git pull`
-* `git tag <version-tag>`
-* `git push origin <version-tag>`
+
+Please review our [Contributing docs](./.github/CONTRIBUTING.md) for the review and release process.

scripts/terraform_format_and_docs.sh

@@ -0,0 +1,60 @@
+#!/usr/bin/env bash
+
+# error in case of asdf install issues
+set -e
+
+# install (or update) asdf and plugins
+if [[ -f "${HOME}/.asdf/asdf.sh" ]]; then
+  source "${HOME}/.asdf/asdf.sh"
+  asdf update
+  asdf plugin update --all
+else
+  git clone https://github.com/asdf-vm/asdf.git "${HOME}/.asdf" --branch v0.9.0
+  source "${HOME}/.asdf/asdf.sh"
+fi
+echo 'legacy_version_file = yes' > ~/.asdfrc
+asdf plugin list | grep -q terraform || asdf plugin add terraform
+asdf plugin list | grep -q terraform-docs || asdf plugin add terraform-docs
+
+# Don't fail immediately any more -- we'll depend on the final git status now
+set +e
+
+# run the test
+./scripts/tf-gen.sh
+generate_status=$?
+
+echo
+echo "=============================================="
+echo "Terraform format and docs generation complete!"
+echo "Results can be seen below. "
+echo "=============================================="
+echo
+
+if [[ ${generate_status} == 0 ]]; then
+  # generate succeeded, any changes?
+  if git status | grep -q 'nothing to commit, working tree clean'; then
+    echo "========================================================"
+    echo "SUCCESS: Terraform is formatted and docs are up to date."
+    echo "========================================================"
+  else
+    echo "===================================================================="
+    echo "ERROR: Terraform files are not formatted or docs are not up to date!"
+    echo "Below is the output of 'git status'. Any 'modified' files need to"
+    echo "be updated. The simplest method to update them is to run the"
+    echo "/scripts/tf-gen.sh script."
+    echo "===================================================================="
+    echo
+    git status
+    exit 1
+  fi
+else
+  # generate failed
+  echo "==================================================="
+  echo "ERROR: Unknown error occurred while generating docs"
+  echo "Build logs will need to be read to understand the"
+  echo "error that occurred."
+  echo "==================================================="
+  echo
+  git status
+  exit 1
+fi

scripts/tf-gen.sh

@@ -0,0 +1,78 @@
+#!/usr/bin/env bash
+
+# track the number of errors that occur...
+NUM_ERRORS=0
+function track-errors() {
+  # shellcheck disable=SC2181
+  if [[ $? -gt 0 ]]; then
+    ((NUM_ERRORS+=1))
+    echo "ERROR: Unknown error occurred. See above for the full error output."
+    return 1
+  fi
+}
+
+function tfgen() {
+  local desired_tf_ver
+  desired_tf_ver=$(asdf current terraform 2>&1 | awk '{print $2}')
+  echo "Installing Terraform (${desired_tf_ver})..."
+  if [[ $(uname) == Darwin && $(uname -m) == arm64 ]]; then
+    if verlte "1.0.1" ${desired_tf_ver}; then
+      echo "M1 Mac support: Forcing installation of amd64 binary for older Terraform version."
+      export ASDF_HASHICORP_OVERWRITE_ARCH="amd64"
+    fi
+  fi
+  asdf install terraform
+  track-errors || return
+
+  echo "Formatting..."
+  terraform fmt .
+  track-errors || return
+
+  if [[ -f docs-header.md ]]; then
+    echo "Generating docs..."
+    terraform-docs -c "${TFDOCS_CONFIG_FILE}" . > README.md
+    track-errors
+  else
+    echo "Skip generating docs: no 'docs-header.md' found."
+  fi
+}
+
+# stolen from https://github.com/rbenv/ruby-build/pull/631/files#diff-fdcfb8a18714b33b07529b7d02b54f1dR942
+function sort_versions() {
+  sed 'h; s/[+-]/./g; s/.p\([[:digit:]]\)/.z\1/; s/$/.z/; G; s/\n/ /' | \
+    LC_ALL=C sort -t. -k 1,1 -k 2,2n -k 3,3n -k 4,4n -k 5,5n | awk '{print $2}'
+}
+
+function verlte() {
+  # Used in the official asdf-nodejs plugin.
+  #   https://github.com/asdf-vm/asdf-nodejs/blob/c0f37e2d14c630b04bace43c79bb361334723216/bin/install#L313-L316
+  # See also:
+  #   https://stackoverflow.com/questions/4023830/how-compare-two-strings-in-dot-separated-version-format-in-bash/4024263#4024263
+  # Note however, that we look at the _tail_ of the list rather than the head because our sort is backwards
+  [  "$1" = "$(echo -e "$1\n$2" | sort_versions | tail -n1)" ]
+}
+
+##
+# Main
+##
+
+START_DIR=$(pwd)
+BASE_DIR="$(git rev-parse --show-toplevel)"
+
+echo "Installing Terraform Docs..."
+asdf install terraform-docs || { echo "ERROR: installing terraform-docs failed."; exit 1; }
+
+TFDOCS_CONFIG_FILE="${BASE_DIR}/.terraform-docs.yml"
+
+if [[ $# == 0 ]]; then
+  dir=$1
+  if [[ ${dir} == "." || ${dir} == "./" ]]; then
+    dir=${START_DIR}
+  fi
+  # shellcheck disable=SC2164
+  cd "${dir}"
+  tfgen
+fi
+
+# exit code indicates error count
+exit "${NUM_ERRORS}"

variables.tf

@@ -21,5 +21,5 @@ variable "allow_overwrite" {
 }
 
 variable "tags" {
-  type    = map(string)
+  type = map(string)
 }