Create TF 0.13 upgrade guide

_posts/2020-12-16-how-to-update-to-terraform-13.adoc

@@ -0,0 +1,238 @@
+---
+title: How to update to Terraform 13
+categories: Upgrades
+image: /assets/img/guides/refresh_icon.png
+excerpt: Learn how to update the Gruntwork Reference Architecture and your infrastructure code that depends on the Gruntwork Infrastructure as Code Library to Terraform 0.13.
+tags: ["aws", "terraform", "terragrunt"]
+cloud: ["aws"]
+redirect_from: /static/guides/upgrades/how-to-update-to-terraform-13/
+---
+:page-type: guide
+:page-layout: post
+
+:toc:
+:toc-placement!:
+
+// GitHub specific settings. See https://gist.github.com/dcode/0cfbf2699a1fe9b46ff04c41721dda74 for details.
+ifdef::env-github[]
+:tip-caption: :bulb:
+:note-caption: :information_source:
+:important-caption: :heavy_exclamation_mark:
+:caution-caption: :fire:
+:warning-caption: :warning:
+toc::[]
+endif::[]
+
+== Intro
+
+This guide will walk you through how to update the https://gruntwork.io/reference-architecture/[Gruntwork Reference
+Architecture] and any code that depends on the
+https://gruntwork.io/infrastructure-as-code-library/[Gruntwork Infrastructure as Code Library] to
+https://www.terraform.io/upgrade-guides/0-13.html[Terraform 0.13]. Terraform 0.13 introduces a number of new features
+and fixes, but it also has a number of backwards incompatibilities that have to be incorporated into your codebase.
+
+=== What you'll learn in this guide
+
+This guide consists of three main sections:
+
+<<core_concepts>>::
+  An overview of Terraform 0.13 and why it is important to update your code for compatibility.
+
+<<deployment_walkthrough>>::
+  The steps you need to take to update your code relying on the Gruntwork Infrastructure as Code library and your
+  version of the Gruntwork Reference Architecture to work with Terraform 0.13. Includes a
+  <<compatibility_table,version compatibility table>> you can use as a reference to know which Gruntwork Repo version
+  tag is compatible with Terraform 0.13.
+
+
+[[core_concepts]]
+== Core Concepts
+
+=== Background
+
+https://www.hashicorp.com/blog/announcing-hashicorp-terraform-0-13[Terraform 0.13 was released on August 10th, 2020].
+Some of the major new features in 0.13 include:
+
+. The ability to use `count`, `for_each`, and `depends_on` with modules.
+. A new `required_providers` block that makes it much easier to work with third-party providers.
+. Custom variable validation.
+
+For more info, check out the https://www.hashicorp.com/blog/announcing-hashicorp-terraform-0-13[announcement blog post].
+
+0.13 is a major new release for Terraform, which means it includes a number of backwards incompatible changes. We have
+gone through all the Terraform modules in the https://gruntwork.io/infrastructure-as-code-library/[Gruntwork
+Infrastructure as Code Library] and updated them to work with Terraform 0.13. In order to use 0.13, you will need to
+update to these new versions and make other changes to your code, as described in the following section.
+
+
+
+[[deployment_walkthrough]]
+== Deployment walkthrough
+
+=== Step 1: update your code to be compatible with Terraform 0.12
+
+If you haven't already, you need to:
+
+. Update your code to work with Terraform 0.12. Do NOT skip from, say, 0.11, straight to 0.13. You MUST update to
+  0.12.26 or above first! If you're still on Terraform 0.11 or older, see our
+  https://docs.gruntwork.io/guides/upgrading-to-tf12-tg19/[Terraform 0.12 upgrade guide] for instructions.
+. Update all your Gruntwork modules to the latest versions just _before_ the TF 0.13 versions in the compatibility
+  table below. The upgrade will be much easier and less error prone if you keep the number of version jumps as small
+  as possible.
+
+=== Step 2: update your code to be compatible with Terraform 0.13
+
+The first step is to update your own code (e.g., the code that lives in your `infrastructure-modules` repo) to be
+compatible with Terraform 0.13 by following HashiCorp's https://www.terraform.io/upgrade-guides/0-13.html[Terraform 0.13
+Upgrade Guide].
+
+=== Step 3: update references to the Gruntwork Infrastructure as Code Library
+
+In order to take advantage of the Terraform 0.13, you need to update your references to the Gruntwork
+Infrastructure as Code Library to use a compatible version. We (Gruntwork) have gone through all our modules in the
+library to test and update the code to be compatible with Terraform 0.13. As a customer, you need to update to
+the proper versions of the Gruntwork library to pick up the fixes/changes that were made to be compatible. Refer to
+https://gruntwork.io/guides/foundations/how-to-use-gruntwork-infrastructure-as-code-library/#updating[the
+"Updating" section of "How to use the Gruntwork Infrastructure as Code Library"] for instructions on how to update the
+versions in your code.
+
+For the vast majority of the repos, the only change that will be necessary is a version number bump, but several repos
+require more extensive code changes and state migrations. To upgrade without downtime and data loss, **you MUST follow
+the migration instructions in the release notes in each repo to know what changes need to be made to update to the new
+version.** The repo most affected by the 0.13 backward incompatibilities was `terraform-aws-eks`, so if you are an EKS
+user, pay special attention to the release notes!
+
+[.exceptional]
+IMPORTANT: Gruntwork follows
+https://gruntwork.io/guides/foundations/how-to-use-gruntwork-infrastructure-as-code-library/#versioning[semantic
+versioning]. For any pre-1.0 modules, this means that version updates to the minor version are considered backwards
+incompatible releases for any version updates prior to 1.0.0 release. Make sure to read the release notes for the
+relevant modules any time you are updating minor versions! Note that you will want to read the release notes for each
+minor version that is updated (e.g., if you are going from v0.5.x to v0.9.x, you will want to read the notes for v0.6.0,
+v0.7.0, v0.8.0, and v0.9.0 to get the full list of backwards incompatible updates).
+
+The following table provides a summary of all the relevant Gruntwork AWS modules and the respective versions that are
+compatible with Terraform 0.13:
+
+[[compatibility_table]]
+[cols="1,1h"]
+|===
+|Gruntwork Repo |Minimum version with Terraform 0.13 support
+
+|Terratest
+|https://github.com/gruntwork-io/terratest/releases/tag/v0.30.0[v0.30.0]
+
+|Terragrunt
+|https://github.com/gruntwork-io/terragrunt/releases/tag/v0.25.4[v0.25.4]
+
+|package-terraform-utilities
+|https://github.com/gruntwork-io/package-terraform-utilities/releases/tag/v0.3.0[v0.3.0]
+
+|terraform-aws-vpc
+|https://github.com/gruntwork-io/terraform-aws-vpc/releases/tag/v0.10.0[v0.10.0]
+
+|module-asg
+|https://github.com/gruntwork-io/module-asg/releases/tag/v0.11.0[v0.11.0]
+
+|module-server
+|https://github.com/gruntwork-io/module-server/releases/tag/v0.9.0[v0.9.0]
+
+|package-lambda
+|https://github.com/gruntwork-io/package-lambda/releases/tag/v0.9.0[v0.9.0]
+
+|module-security
+|https://github.com/gruntwork-io/module-security/releases/tag/v0.37.0[v0.37.0]
+
+|module-load-balancer
+|https://github.com/gruntwork-io/module-load-balancer/releases/tag/v0.21.0[v0.21.0]
+
+|module-data-storage
+|https://github.com/gruntwork-io/module-data-storage/releases/tag/v0.16.0[v0.16.0]
+
+|module-cache
+|https://github.com/gruntwork-io/module-cache/releases/tag/v0.10.0[v0.10.0]
+
+|package-messaging
+|https://github.com/gruntwork-io/package-messaging/releases/tag/v0.4.0[v0.4.0]
+
+|package-static-assets
+|https://github.com/gruntwork-io/package-static-assets/releases/tag/v0.7.0[v0.7.0]
+
+|terraform-aws-monitoring
+|https://github.com/gruntwork-io/terraform-aws-monitoring/releases/tag/v0.23.0[v0.23.0]
+
+|package-openvpn
+|https://github.com/gruntwork-io/package-openvpn/releases/tag/v0.12.0[v0.12.0]
+
+|module-ecs
+|https://github.com/gruntwork-io/module-ecs/releases/tag/v0.23.0[v0.23.0]
+
+|module-ci
+|https://github.com/gruntwork-io/module-ci/releases/tag/v0.29.0[v0.29.0]
+
+|terraform-aws-eks
+|https://github.com/gruntwork-io/terraform-aws-eks/releases/tag/v0.30.0[v0.30.0]
+
+|package-zookeeper
+|https://github.com/gruntwork-io/package-zookeeper/releases/tag/v0.7.0[v0.7.0]
+
+|package-kafka
+|https://github.com/gruntwork-io/package-kafka/releases/tag/v0.7.0[v0.7.0]
+
+|package-elk
+|https://github.com/gruntwork-io/package-elk/releases/tag/v0.7.0[v0.7.0]
+
+|terraform-kubernetes-helm
+|Deprecated. Migrate to `terraform-kubernetes-namespace` instead.
+
+|terraform-kubernetes-namespace
+|https://github.com/gruntwork-io/terraform-kubernetes-namespace/releases/tag/v0.1.0[v0.1.0]
+
+|cis-compliance-aws
+|https://github.com/gruntwork-io/cis-compliance-aws/releases/tag/v0.9.0[v0.9.0]
+
+|package-sam
+|https://github.com/gruntwork-io/package-sam/releases/tag/v0.3.0[v0.3.0]
+
+|terraform-aws-couchbase
+|https://github.com/gruntwork-io/terraform-aws-couchbase/releases/tag/v0.4.0[v0.4.0]
+
+|terraform-aws-influx
+|https://github.com/gruntwork-io/terraform-aws-influx/releases/tag/v0.2.0[v0.2.0]
+
+|terraform-aws-consul
+|https://github.com/hashicorp/terraform-aws-consul/releases/tag/v0.8.0[v0.8.0]
+
+|terraform-aws-vault
+|https://github.com/hashicorp/terraform-aws-vault/releases/tag/v0.14.0[v0.14.0]
+
+|terraform-aws-nomad
+|https://github.com/hashicorp/terraform-aws-nomad/releases/tag/v0.7.0[v0.7.0]
+
+|===
+
+
+=== Updating the Gruntwork Reference Architecture to Terraform 0.13
+
+If you purchased the Gruntwork Reference Architecture, you will have a copy of the `infrastructure-live` and
+`infrastructure-modules` repositories that contain the infrastructure code for deploying the Reference Architecture. You
+will need to update the relevant code in `infrastructure-modules` to use a compatible version of the
+Gruntwork Infrastructure as Code Library, as per <<compatibility_table,the compatibility table>> above.
+
+
+To help guide you through the upgrade process, we have updated the Acme Reference Architecture examples to support
+Terraform 0.13. You can refer to the pull requests to see an example of the updates you'lll need to do to make your
+Reference Architecture work with Terraform 0.13:
+
+Standard Reference Architecture::
+  See the https://github.com/gruntwork-io/infrastructure-modules-multi-account-acme/pull/46[infrastructure-modules PR]
+  and the https://github.com/gruntwork-io/infrastructure-live-multi-account-acme/pull/44[infrastructure-live PR] for
+  an example of a Terraform 0.13 update.
+
+CIS Reference Architecture::
+  See the https://github.com/gruntwork-io/cis-infrastructure-modules-acme/pull/5[infrastructure-modules PR]
+  and the https://github.com/gruntwork-io/cis-infrastructure-live-acme/pull/7[infrastructure-live PR] for
+  an example of a Terraform 0.13 update for the CIS components of the Reference Architecture. For all other components,
+  refer to PRs in the Standard Reference Architecture section above.
+
+