diff --git a/_docs-sources/guides/stay-up-to-date/terraform/1-how-to-update-to-terraform-13/2-deployment-walkthrough/2-step-3-update-references-to-the-gruntwork-infrastructure-as-code-library.md b/_docs-sources/guides/stay-up-to-date/terraform/1-how-to-update-to-terraform-13/2-deployment-walkthrough/2-step-3-update-references-to-the-gruntwork-infrastructure-as-code-library.md
index 9813f498ba..82d78d134e 100644
--- a/_docs-sources/guides/stay-up-to-date/terraform/1-how-to-update-to-terraform-13/2-deployment-walkthrough/2-step-3-update-references-to-the-gruntwork-infrastructure-as-code-library.md
+++ b/_docs-sources/guides/stay-up-to-date/terraform/1-how-to-update-to-terraform-13/2-deployment-walkthrough/2-step-3-update-references-to-the-gruntwork-infrastructure-as-code-library.md
@@ -7,9 +7,7 @@ sidebar_label: Update Gruntwork IaC module references
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
-[the
-"Updating" section of "How to use the Gruntwork Infrastructure as Code Library"](https://gruntwork.io/guides/foundations/how-to-use-gruntwork-infrastructure-as-code-library/#updating) for instructions on how to update the
+the proper versions of the Gruntwork library to pick up the fixes/changes that were made to be compatible. Refer to our ["Updating to new versions"](/docs/guides/stay-up-to-date/versioning#updating-to-new-versions) guide 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
@@ -21,7 +19,7 @@ user, pay special attention to the release notes!
:::caution
Gruntwork follows [semantic
-versioning](https://gruntwork.io/guides/foundations/how-to-use-gruntwork-infrastructure-as-code-library/#versioning).
+versioning](/docs/guides/stay-up-to-date/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
diff --git a/_docs-sources/guides/stay-up-to-date/terraform/2-how-to-update-to-terraform-14/2-deployment-walkthrough/2-step-3-update-references-to-the-gruntwork-infrastructure-as-code-library.md b/_docs-sources/guides/stay-up-to-date/terraform/2-how-to-update-to-terraform-14/2-deployment-walkthrough/2-step-3-update-references-to-the-gruntwork-infrastructure-as-code-library.md
index c9fd2bf451..09687f23eb 100644
--- a/_docs-sources/guides/stay-up-to-date/terraform/2-how-to-update-to-terraform-14/2-deployment-walkthrough/2-step-3-update-references-to-the-gruntwork-infrastructure-as-code-library.md
+++ b/_docs-sources/guides/stay-up-to-date/terraform/2-how-to-update-to-terraform-14/2-deployment-walkthrough/2-step-3-update-references-to-the-gruntwork-infrastructure-as-code-library.md
@@ -7,9 +7,7 @@ sidebar_label: Update Gruntwork IaC module references
In order to take advantage of the Terraform 0.14, 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.14. As a customer, you need to update to
-the proper versions of the Gruntwork library to pick up the fixes/changes that we made to be compatible. Refer to
-[the
-"Updating" section of "How to use the Gruntwork Infrastructure as Code Library"](https://gruntwork.io/guides/foundations/how-to-use-gruntwork-infrastructure-as-code-library/#updating) for instructions on how to update the
+the proper versions of the Gruntwork library to pick up the fixes/changes that we made to be compatible. Refer to our ["Updating to new versions"](/docs/guides/stay-up-to-date/versioning#updating-to-new-versions) guide 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
@@ -20,7 +18,7 @@ version.**
:::caution
Gruntwork follows [semantic
-versioning](https://gruntwork.io/guides/foundations/how-to-use-gruntwork-infrastructure-as-code-library/#versioning).
+versioning](/docs/guides/stay-up-to-date/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
diff --git a/_docs-sources/guides/stay-up-to-date/terraform/3-how-to-update-to-terraform-15/2-deployment-walkthrough/2-step-3-update-references-to-the-gruntwork-infrastructure-as-code-library.md b/_docs-sources/guides/stay-up-to-date/terraform/3-how-to-update-to-terraform-15/2-deployment-walkthrough/2-step-3-update-references-to-the-gruntwork-infrastructure-as-code-library.md
index ff8ab14620..a795d1bc76 100644
--- a/_docs-sources/guides/stay-up-to-date/terraform/3-how-to-update-to-terraform-15/2-deployment-walkthrough/2-step-3-update-references-to-the-gruntwork-infrastructure-as-code-library.md
+++ b/_docs-sources/guides/stay-up-to-date/terraform/3-how-to-update-to-terraform-15/2-deployment-walkthrough/2-step-3-update-references-to-the-gruntwork-infrastructure-as-code-library.md
@@ -7,9 +7,7 @@ sidebar_label: Update Gruntwork IaC module references
In order to take advantage of the Terraform 0.15, 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.15. As a customer, you need to update to
-the proper versions of the Gruntwork library to pick up the fixes/changes that we made to be compatible. Refer to
-[the
-"Updating" section of "How to use the Gruntwork Infrastructure as Code Library"](https://gruntwork.io/guides/foundations/how-to-use-gruntwork-infrastructure-as-code-library/#updating) for instructions on how to update the
+the proper versions of the Gruntwork library to pick up the fixes/changes that we made to be compatible. Refer to our ["Updating to new versions"](/docs/guides/stay-up-to-date/versioning#updating-to-new-versions) guide 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
@@ -20,7 +18,7 @@ version.**
:::caution
Gruntwork follows [semantic
-versioning](https://gruntwork.io/guides/foundations/how-to-use-gruntwork-infrastructure-as-code-library/#versioning).
+versioning](/docs/guides/stay-up-to-date/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
diff --git a/_docs-sources/guides/stay-up-to-date/terraform/4-how-to-update-to-terraform-1-x/2-deployment-walkthrough/1-step-2-update-references-to-the-gruntwork-infrastructure-as-code-library.md b/_docs-sources/guides/stay-up-to-date/terraform/4-how-to-update-to-terraform-1-x/2-deployment-walkthrough/1-step-2-update-references-to-the-gruntwork-infrastructure-as-code-library.md
index bb81a11a95..eb52a2342a 100644
--- a/_docs-sources/guides/stay-up-to-date/terraform/4-how-to-update-to-terraform-1-x/2-deployment-walkthrough/1-step-2-update-references-to-the-gruntwork-infrastructure-as-code-library.md
+++ b/_docs-sources/guides/stay-up-to-date/terraform/4-how-to-update-to-terraform-1-x/2-deployment-walkthrough/1-step-2-update-references-to-the-gruntwork-infrastructure-as-code-library.md
@@ -9,9 +9,8 @@ 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 1.x. As a customer, you need
to update to the proper versions of the Gruntwork library to pick up the
-fixes/changes that we made to be compatible. Refer to [the "Updating" section of
-"How to use the Gruntwork Infrastructure as Code
-Library"](https://gruntwork.io/guides/foundations/how-to-use-gruntwork-infrastructure-as-code-library/#updating)
+fixes/changes that we made to be compatible. Refer to [the "Updating to new versions" section of
+"Stay Up to Date"](/docs/guides/stay-up-to-date/versioning#updating-to-new-versions#updating)
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
@@ -23,7 +22,7 @@ changes need to be made to update to the new version.**
:::caution
Gruntwork follows [semantic
-versioning](https://gruntwork.io/guides/foundations/how-to-use-gruntwork-infrastructure-as-code-library/#versioning).
+versioning](/docs/guides/stay-up-to-date/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
diff --git a/_docs-sources/guides/stay-up-to-date/terraform/5-how-to-update-to-aws-provider-v3/2-deployment-walkthrough.md b/_docs-sources/guides/stay-up-to-date/terraform/5-how-to-update-to-aws-provider-v3/2-deployment-walkthrough.md
index 6d5ef4c54f..5df6306702 100644
--- a/_docs-sources/guides/stay-up-to-date/terraform/5-how-to-update-to-aws-provider-v3/2-deployment-walkthrough.md
+++ b/_docs-sources/guides/stay-up-to-date/terraform/5-how-to-update-to-aws-provider-v3/2-deployment-walkthrough.md
@@ -8,8 +8,7 @@ library to test and update the code to be compatible with AWS provider version 3
the proper versions of the Gruntwork library to pick up the fixes/changes that were made to be compatible. Be sure to
read the release notes to know what changes need to be made to update to that version.
-Refer to [the
-"Updating" section of "How to use the Gruntwork Infrastructure as Code Library"](https://gruntwork.io/guides/foundations/how-to-use-gruntwork-infrastructure-as-code-library/#updating)
+Refer to our ["Updating to new versions"](/docs/guides/stay-up-to-date/versioning#updating-to-new-versions) guide
for instructions on how to update the versions in your code.
The following table provides a summary of all the relevant Gruntwork AWS modules and the respective versions that are
@@ -18,7 +17,7 @@ compatible with AWS provider version 3.
:::caution
Gruntwork follows [semantic
-versioning](https://gruntwork.io/guides/foundations/how-to-use-gruntwork-infrastructure-as-code-library/#versioning).
+versioning](/docs/guides/stay-up-to-date/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
diff --git a/_docs-sources/intro/core-concepts/immutable-infrastructure.md b/_docs-sources/intro/core-concepts/immutable-infrastructure.md
new file mode 100644
index 0000000000..8d5dbc768b
--- /dev/null
+++ b/_docs-sources/intro/core-concepts/immutable-infrastructure.md
@@ -0,0 +1,34 @@
+# Immutable infrastructure
+
+With _mutable infrastructure_, you deploy a set of servers, and you continuously update those servers in place. Every
+new update gets installed on top of the previous updates, either manually (e.g., by SSHing to each server and running
+commands), or via tools like Ansible, Chef, or Puppet. The idea behind _immutable infrastructure_ is that once you
+deploy a server, you never change it again. If you need to roll out an update, you deploy a _new_ server with that
+update, and undeploy the old one. This paradigm is built for use with (a) the cloud, where you can easily spin up or
+tear down servers on-demand and (b) machine images, as every time there’s a change, you can use tools like Packer or
+Docker to build a new, immutable, versioned machine image (e.g., VM image or Docker image), and deploy new servers with
+that image.
+
+The advantages of immutable infrastructure are:
+
+#### Easier to reason about servers
+
+With mutable infrastructure, each server builds up a unique history of changes, so each one is a little different,
+which (a) makes it difficult to reason about what’s actually installed and (b) leads to tricky bugs that only show up
+on some servers, and not on others. With immutable infrastructure, you avoid these sorts of bugs, and you always know
+what’s installed on any server, as you know the exact image each server is running, and that the image never changes.
+
+#### You can run the same images in all environments
+
+Whereas it’s rare to run mutable infrastructure tools such as Ansible, Chef, or Puppet in your local dev environment,
+it’s common to run the same Docker or VM image in all environments, including your laptop, staging, and production.
+This helps to reduce "works on my machine" and environment-specific bugs, and makes it easier to debug those issues
+when they do happen.
+
+#### Easier scaling and rollback
+
+With immutable images, you can quickly and easily spin up 100 or 1,000 servers, with no need to worry about how long
+it’ll take to configure all those servers (e.g., via Ansible, Chef, or Puppet), as all the configuration has already
+happened and is captured in the VM or Docker image. Rollback is easier too, as you can quickly jump back to a
+previous image, without having to wait for and worry about running a bunch of older install commands (which may no
+longer work, e.g., if certain packages have been removed from APT or YUM).
diff --git a/_docs-sources/intro/core-concepts/infrastructure-as-code.md b/_docs-sources/intro/core-concepts/infrastructure-as-code.md
new file mode 100644
index 0000000000..dbf2d6b6e6
--- /dev/null
+++ b/_docs-sources/intro/core-concepts/infrastructure-as-code.md
@@ -0,0 +1,59 @@
+# Infrastructure as code
+
+Everything in the Gruntwork Infrastructure as Code Library is designed to allow you to define your _infrastructure as code (IaC)_.
+That is, instead of deploying infrastructure _manually_ (e.g., by clicking around a web page), the idea behind IaC is
+to write code to define, provision, and manage your infrastructure. This has a number of benefits:
+
+
+
+#### Self-service
+
+Most teams that deploy code manually have a small number of sysadmins (often, just one) who are the only ones who
+know all the magic incantations to make the deployment work and are the only ones with access to production. This
+becomes a major bottleneck as the company grows. If your infrastructure is defined in code, then the entire
+deployment process can be automated, and developers can kick off their own deployments whenever necessary.
+
+#### Speed and safety
+
+If the deployment process is automated, it’ll be significantly faster, since a computer can carry out the deployment
+steps far faster than a person; and safer, since an automated process will be more consistent, more repeatable, and
+not prone to manual error.
+
+#### Documentation
+
+Instead of the state of your infrastructure being locked away in a single sysadmin’s head, you can represent the
+state of your infrastructure in source files that anyone can read. In other words, IaC acts as documentation,
+allowing everyone in the organization to understand how things work, even if the sysadmin goes on vacation.
+
+#### Version control
+
+You can store your IaC source files in version control, which means the entire history of your infrastructure is now
+captured in the commit log. This becomes a powerful tool for debugging issues, as any time a problem pops up, your
+first step will be to check the commit log and find out what changed in your infrastructure, and your second step may
+be to resolve the problem by simply reverting back to a previous, known-good version of your IaC code.
+
+#### Validation
+
+If the state of your infrastructure is defined in code, then for every single change, you can perform a code review,
+run a suite of automated tests, and pass the code through static analysis tools, all practices that are known to
+significantly reduce the chance of defects.
+
+#### Happiness
+
+Deploying code and managing infrastructure manually is repetitive and tedious. Developers and sysadmins resent this
+type of work, as it involves no creativity, no challenge, and no recognition. You could deploy code perfectly for
+months, and no one will take notice—until that one day when you mess it up. That creates a stressful and unpleasant
+environment. IaC offers a better alternative that allows computers to do what they do best (automation) and
+developers to do what they do best (coding).
+
+#### Reuse
+
+You can package your infrastructure into reusable modules, so that instead of doing every deployment for every
+product in every environment from scratch, you can build on top of known, documented, battle-tested pieces. You
+can build these reusable modules yourself or use an existing collection of modules, such as the Gruntwork
+Infrastructure as Code Library.
+
+Some of the main IaC tools you’ll see used and referenced in the Gruntwork Infrastructure as Code Library are Terraform, Terragrunt,
+Packer, Docker, and Helm, each of which we’ll discuss in the next several sections.
+
+
diff --git a/_docs-sources/intro/first-deployment/deploy.md b/_docs-sources/intro/first-deployment/deploy.md
new file mode 100644
index 0000000000..25d6e88625
--- /dev/null
+++ b/_docs-sources/intro/first-deployment/deploy.md
@@ -0,0 +1,260 @@
+# Deploy Your Module
+
+Now that your module has been thoroughly tested, you can deploy it to your real environments (e.g., staging and
+production). There are many ways to deploy Terraform modules, so in this guide, we’ll focus on using Terraform or Terragrunt.
+
+## Deploy using plain Terraform
+
+One option is to deploy all of your environments using plain-old-Terraform. The approach is nearly identical to the
+way you did manual testing; let’s walk through it for the staging environment.
+
+First, create a `staging/terraform.tfvars` file:
+
+ infrastructure-modules
+ └ networking
+ └ vpc-app
+ └ main.tf
+ └ outputs.tf
+ └ variables.tf
+ └ testing
+ └ terraform.tfvars
+ └ backend.hcl
+ └ staging
+ └ terraform.tfvars
+ └ test
+ └ vpc_app_test.go
+
+Inside the file, set the variables for this module to values appropriate for this environment:
+
+```hcl title=infrastructure-modules/networking/vpc-app/staging/terraform.tfvars
+aws_region = "us-east-2"
+aws_account_id = "888888888888"
+vpc_name = "staging-vpc"
+cidr_block = "10.10.0.0/16"
+num_nat_gateways = 1
+```
+
+Next, create a `staging/backend.hcl` file:
+
+ infrastructure-modules
+ └ networking
+ └ vpc-app
+ └ main.tf
+ └ outputs.tf
+ └ variables.tf
+ └ testing
+ └ terraform.tfvars
+ └ backend.hcl
+ └ staging
+ └ terraform.tfvars
+ └ backend.hcl
+ └ test
+ └ vpc_app_test.go
+
+Inside this file, configure the backend for staging:
+
+```hcl title=infrastructure-modules/networking/vpc-app/staging/backend.hcl
+bucket = ""
+key = "networking/vpc-app/terraform.tfstate"
+region = "us-east-2"
+encrypt = true
+dynamodb_table = ""
+```
+
+And now you can deploy to the staging environment as follows:
+
+```bash
+cd infrastructure-modules/networking/vpc-app/staging
+terraform init -backend-config=backend.hcl ../
+terraform apply ../
+```
+
+To deploy to other environments, create analogous `.tfvars` and `.hcl` files (e.g., `production/terraform.tfvars` and
+`production/backend.hcl`) and run `terraform init` and `terraform apply` with those files.
+
+**Benefits of this approach**
+
+- No external tooling required.
+- Analogous to how you run manual and automated tests.
+- Quick feedback cycle.
+- Completely free and open source.
+
+**Drawbacks to this approach**
+
+- You’re always deploying "latest" from a branch. No versioning or easy rollback.
+- Lots of command-line arguments to pass. Easy to make mistakes. Most teams end up creating hacky wrapper scripts.
+- Lots of backend configuration to copy for each module. Manually setting a unique `key` for each module is repetitive
+ and error prone.
+- From a quick glance at the code, it’s not clear what accounts, environments, or regions you deploy to. Figuring this
+ out requires digging through many folders.
+
+## Deploy using Terragrunt
+
+Another option is to use [Terragrunt](https://github.com/gruntwork-io/terragrunt), an open source wrapper for Terraform
+that helps alleviate some of the drawbacks mentioned in the previous approach.
+
+The first step with Terragrunt is to version your code. You can do this by creating Git tags in
+`infrastructure-modules`:
+
+```bash
+cd infrastructure-modules
+git tag -a "v0.0.1" -m "Created vpc-app module"
+git push --follow-tags
+```
+
+This will allow you to deploy different versions of your module in different environments (e.g., `v0.0.1` in prod and
+`v0.0.2` in stage) and rollback to previous versions if necessary. With Terragrunt, we recommend defining your live
+environments in a separate repo called `infrastructure-live` that uses a folder structure with the following format:
+
+ infrastructure-live
+ └
+ └ terragrunt.hcl
+ └ _global
+ └
+ └ _global
+ └
+ └
+ └ terragrunt.hcl
+
+Where:
+
+
+
+#### `
`
+
+A the top level, you have accounts (e.g., an AWS account).
+
+#### ``
+
+Within each account, there will be one or more regions (e.g., in AWS, `us-east-1`, `eu-west-1`, etc). There may also
+be a `_global` folder that defines resources that are available across all the regions in this account, such as
+IAM users and DNS settings. Each account also has a root `terragrunt.hcl` file that defines common Terraform settings
+that apply to the entire account, such as what backend to use to store Terraform state.
+
+#### ``
+
+Within each region, there will be one or more environments, such as dev, stage, prod, mgmt, etc. There may also be a
+`_global` folder that defines resources that are available across all the environments in this region.
+
+#### ``
+
+Within each environment, you use Terraform modules to deploy one or more resources, such as servers, databases load
+balancers, and so on. Each module is configured via a `terragrunt.hcl` file.
+
+
+
+#### Configure variables
+
+This is similar to the `testing/terraform.tfvars` used in manual testing.
+
+#### Configure the backend
+
+This is similar to the `testing-backend.hcl` used in manual testing.
+
+#### Namespace resources
+
+The code uses ‘random.UniqueId()\` to generate unique identifiers for all the resources in this test. This allows
+multiple tests to run in parallel (e.g., on your computer, your teammates’ computers, CI servers) without running
+into conflicts (e.g., without conflicts over resources that require unique names, such as VPCs).
+
+#### Defer `terraform destroy`
+
+The test code uses `defer` to schedule `terraform.Destroy` to run at the end of the test, whether or not the test
+passes.
+
+#### `terraform init` and `apply`
+
+The test runs `terraform init` and `terraform apply` on the module. If this hits any errors, the test will fail.
+
+
+This is a minimal test that just makes sure your module can deploy and undeploy successfully. This is a great start,
+and will catch a surprising number of bugs, but for production-grade code, you’ll probably want more validation logic.
+Check out the real [module-vpc tests](https://github.com/gruntwork-io/module-vpc/tree/master/test) to see how we validate
+VPCs by, for example, launching EC2 instances in various subnets and making sure that connections between some subnets
+work, and others are blocked, based on the networking settings in that VPC.
+
+To run the test, authenticate to your testing environment and do the following:
+
+```bash
+cd infrastructure-modules/test
+go test -v -timeout 45m
+```
+
+Note the use of the `-timeout 45m` argument with `go test`. By default, Go imposes a time limit of 10 minutes for
+tests, after which it forcibly kills the test run, causing the tests to not only fail, but even preventing the cleanup
+code (i.e., `terraform destroy`) from running. This VPC test should take closer to ten minutes, but whenever running a
+Go test that deploys real infrastructure, it’s safer to set an extra long timeout to avoid the test being killed part
+way through and leaving all sorts of infrastructure still running.
+
+For a lot more information on writing automated tests for Terraform code, see:
+
+1. [Terratest documentation](https://github.com/gruntwork-io/terratest/), especially the many examples and corresponding
+ tests in the `examples` and `test` folders, respectively, and the
+ [testing best practices](https://github.com/gruntwork-io/terratest/#testing-best-practices) section.
+2. _[Terraform: Up & Running](https://www.terraformupandrunning.com)_, 2nd edition, has an entire chapter dedicated to
+ automated testing for Terraform code, including unit tests, integration tests, end-to-end tests, dependency injection,
+ running tests in parallel, test stages, and more.
diff --git a/_docs-sources/intro/first-deployment/using-terraform-modules.md b/_docs-sources/intro/first-deployment/using-terraform-modules.md
new file mode 100644
index 0000000000..f145e08e7d
--- /dev/null
+++ b/_docs-sources/intro/first-deployment/using-terraform-modules.md
@@ -0,0 +1,247 @@
+# Prepare Your Module
+
+This section will show you how to use Terraform modules from the Gruntwork Infrastructure as Code Library. As an illustrative example,
+we’ll deploy the `vpc-app` Terraform module from [terraform-aws-vpc](https://github.com/gruntwork-io/terraform-aws-vpc).
+
+:::caution
+
+You must be a Gruntwork subscriber to access `terraform-aws-vpc`.
+
+:::
+
+You can use this module to deploy a production-grade VPC on AWS. For full background information on VPCs, check
+out [How to deploy a production-grade VPC on AWS](/docs/guides/build-it-yourself/vpc/intro/what-youll-learn-in-this-guide).
+
+## Create a wrapper module
+
+The Terraform modules in the Gruntwork Infrastructure as Code Library are intentionally designed to be unopinionated, so they do not
+configure `provider` or `backend` settings. Moreover, you will often use multiple modules from the Infrastructure as Code Library,
+rather than just one at a time. Therefore, the canonical way to consume a Terraform module from the Gruntwork
+Infrastructure as Code Library is to create a _wrapper module_ in one of your own Git repos.
+
+Let’s assume you have a repo called `infrastructure-modules` and create a `vpc-app` wrapper module in it:
+
+ infrastructure-modules
+ └ networking
+ └ vpc-app
+ └ main.tf
+ └ outputs.tf
+ └ variables.tf
+
+## Configure your providers
+
+Inside of `main.tf`, configure whatever Terraform providers you’re using. Since the `vpc-app` module you’re using in
+this guide is an AWS module, you’ll need to configure the AWS provider:
+
+```hcl title=infrastructure-modules/networking/vpc-app/main.tf
+provider "aws" {
+ # The AWS region in which all resources will be created
+ region = var.aws_region
+
+ # Require a 2.x version of the AWS provider
+ version = "~> 2.6"
+
+ # Only these AWS Account IDs may be operated on by this template
+ allowed_account_ids = [var.aws_account_id]
+}
+```
+
+This configures the AWS provider as follows:
+
+
+
+#### Use a specific AWS region
+
+The AWS region is configured via the `aws_region` input variable (you’ll declare this shortly). This allows you to
+deploy this module in multiple regions.
+
+#### Pin the AWS provider version
+
+The code above ensures that you always get AWS provider version `2.x` and won’t accidentally get version `3.x` in the
+future, which would be backwards incompatible. We recommend pinning the versions for all providers you’re using.
+
+#### Pin AWS account IDs
+
+The code above will only allow you to run it against the AWS account with ID passed in via the `aws_account_id` input
+variable (you’ll declare this shortly). This is an extra safety measure to ensure you don’t accidentally authenticate
+to the wrong AWS account while deploying this code—e.g., so you don’t accidentally deploy changes intended for
+staging to production (for more info on working with multiple AWS accounts, see
+[How to Configure a Production Grade AWS Account Structure](/docs/guides/build-it-yourself/landing-zone/intro/what-youll-learn-in-this-guide)).
+
+
+
+Let’s add the corresponding input variables in `variables.tf`:
+
+```hcl title=infrastructure-modules/networking/vpc-app/variables.tf
+variable "aws_region" {
+ description = "The AWS region in which all resources will be created"
+ type = string
+}
+
+variable "aws_account_id" {
+ description = "The ID of the AWS Account in which to create resources."
+ type = string
+}
+```
+
+## Configure Terraform
+
+Next, configure Terraform itself in `main.tf`:
+
+```hcl title=infrastructure-modules/networking/vpc-app/main.tf
+terraform {
+ # Partial configuration for the backend: https://www.terraform.io/docs/backends/config.html#partial-configuration
+ backend "s3" {}
+
+ # Only allow this Terraform version. Note that if you upgrade to a newer version, Terraform won't allow you to use an
+ # older version, so when you upgrade, you should upgrade everyone on your team and your CI servers all at once.
+ required_version = "= 0.12.6"
+}
+```
+
+This configures Terraform as follows:
+
+
+
+#### Configure a backend
+
+The code above configures a _backend_, which is a shared location where Terraform state can be stored and accessed by
+your team. You can use any of the [supported backends](https://www.terraform.io/docs/backends/types/index.html) (the
+example above uses S3, which is a good choice for AWS users). See
+[How to manage Terraform state](https://blog.gruntwork.io/how-to-manage-terraform-state-28f5697e68fa) for more info.
+
+#### Partial configuration
+
+The backend uses a _[partial configuration](https://www.terraform.io/docs/backends/config.html#partial-configuration)_,
+which means most of the backend configuration (e.g., which S3 bucket and path to use) will be specified from outside
+of the code. You’ll see an example of this soon.
+
+#### Pin the Terraform version
+
+The code above will ONLY allow you to run it with a specific Terraform version. This is a safety measure to ensure
+you don’t accidentally pick up a new version of Terraform until you’re ready. This is important because (a) Terraform
+is a pre 1.0.0 tool, so even patch version number bumps (e.g., `0.12.6` → `0.12.7`) are sometimes backwards
+incompatible or buggy and (b) once you’ve upgraded to a newer version, Terraform will no longer allow you to deploy
+that code with any older version. For example, if a single person on your team upgrades to `0.12.7` and runs `apply`,
+then you’ll no longer be able to use the state file with `0.12.6`, and you’ll be forced to upgrade everyone on your
+team and all your CI servers to `0.12.7`. It’s best to do this explicitly, rather than accidentally, so we recommend
+pinning Terraform versions.
+
+
+
+## Use the modules from the Gruntwork Infrastructure as Code Library
+
+Now you can pull in the Terraform modules you want from the Gruntwork Infrastructure as Code Library as follows:
+
+```hcl title=infrastructure-modules/networking/vpc-app/main.tf
+module "vpc" {
+ # Make sure to replace in this URL with the latest terraform-aws-vpc release
+ source = "git@github.com:gruntwork-io/terraform-aws-vpc.git//modules/vpc-app?ref="
+
+ aws_region = var.aws_region
+ vpc_name = var.vpc_name
+ cidr_block = var.cidr_block
+ num_nat_gateways = var.num_nat_gateways
+}
+```
+
+This code does the following:
+
+
+
+#### Terraform module support
+
+This code pulls in a module using Terraform’s native `module` functionality. For background info, see
+[How to create reusable infrastructure with Terraform modules](https://blog.gruntwork.io/how-to-create-reusable-infrastructure-with-terraform-modules-25526d65f73d).
+
+#### SSH Git URL
+
+The `source` URL in the code above uses a Git URL with SSH authentication (see
+[module sources](https://www.terraform.io/docs/modules/sources.html) for all the types of `source` URLs you can use).
+If you have established your account and linked your GitHub ID according to the instruction in [Accessing the Dev Portal](/docs/intro/dev-portal/create-account), this will allow you to access private repos in the Gruntwork
+Infrastructure as Code Library without having to hard-code a password in your Terraform code.
+
+#### Versioned URL
+
+Note the `?ref=` at the end of the `source` URL. This parameter allows you to pull in a specific version of
+each module so that you don’t accidentally pull in (potentially backwards incompatible code) in the future. You
+should replace `` with the latest version from the releases page of the repo you’re using (e.g., here’s
+[the releases page for terraform-aws-vpc](https://github.com/gruntwork-io/terraform-aws-vpc/releases)).
+
+#### Module arguments
+
+Below the `source` URL, you’ll need to pass in the module-specific arguments. You can find all the required and
+optional variables defined in `vars.tf` (old name) or `variables.tf` (new name) of the module (e.g.,
+here’s [the variables.tf for vpc-app](https://github.com/gruntwork-io/terraform-aws-vpc/blob/master/modules/vpc-app/vars.tf)).
+The code above sets these to input variables (which you’ll define shortly) so that you can use different values in
+different environments.
+
+
+
+Let’s add the new input variables in `variables.tf`:
+
+```hcl title=infrastructure-modules/networking/vpc-app/variables.tf
+variable "vpc_name" {
+ description = "Name of the VPC. Examples include 'prod', 'dev', 'mgmt', etc."
+ type = string
+}
+
+variable "cidr_block" {
+ description = "The IP address range of the VPC in CIDR notation. A prefix of /16 is recommended. Do not use a prefix higher than /27. Example: '10.100.0.0/16'."
+ type = string
+}
+
+variable "num_nat_gateways" {
+ description = "The number of NAT Gateways to launch for this VPC. For production VPCs, multiple NAT Gateways are recommended."
+ type = number
+}
+```
+
+You may also want to add useful output variables in `outputs.tf`:
+
+```hcl title=infrastructure-modules/networking/vpc-app/outputs.tf
+output "vpc_name" {
+ description = "The VPC name"
+ value = module.vpc.vpc_name
+}
+
+output "vpc_id" {
+ description = "The VPC ID"
+ value = module.vpc.vpc_id
+}
+
+output "vpc_cidr_block" {
+ description = "The VPC CIDR block"
+ value = module.vpc.vpc_cidr_block
+}
+
+output "public_subnet_cidr_blocks" {
+ description = "The CIDR blocks of the public subnets"
+ value = module.vpc.public_subnet_cidr_blocks
+}
+
+output "private_app_subnet_cidr_blocks" {
+ description = "The CIDR blocks of the private app subnets"
+ value = module.vpc.private_app_subnet_cidr_blocks
+}
+
+output "private_persistence_subnet_cidr_blocks" {
+ description = "The CIDR blocks of the private persistence subnets"
+ value = module.vpc.private_persistence_subnet_cidr_blocks
+}
+
+output "public_subnet_ids" {
+ description = "The IDs of the public subnets"
+ value = module.vpc.public_subnet_ids
+}
+
+output "private_app_subnet_ids" {
+ description = "The IDs of the private app subnets"
+ value = module.vpc.private_app_subnet_ids
+}
+
+output "private_persistence_subnet_ids" {
+ description = "The IDs of the private persistence subnets"
+ value = module.vpc.private_persistence_subnet_ids
+}
+```
diff --git a/_docs-sources/intro/tool-fundamentals/packer.md b/_docs-sources/intro/tool-fundamentals/packer.md
index 2af0928798..00d69fa217 100644
--- a/_docs-sources/intro/tool-fundamentals/packer.md
+++ b/_docs-sources/intro/tool-fundamentals/packer.md
@@ -5,22 +5,26 @@ images, Docker images) as code. For example, here is how you can use Packer to d
```json
{
- "builders": [{
- "type": "amazon-ebs",
- "region": "us-east-2",
- "source_ami": "ami-0c55b159cbfafe1f0",
- "instance_type": "t2.micro",
- "ssh_username": "ubuntu",
- "ami_name": "packer-example-{{timestamp}}"
- }],
- "provisioners": [{
- "type": "shell",
- "inline": [
- "curl -sL https://deb.nodesource.com/setup_10.x | sudo -E bash -",
- "sudo apt-get update -y",
- "sudo apt-get install -y nodejs"
- ]
- }]
+ "builders": [
+ {
+ "type": "amazon-ebs",
+ "region": "us-east-2",
+ "source_ami": "ami-0c55b159cbfafe1f0",
+ "instance_type": "t2.micro",
+ "ssh_username": "ubuntu",
+ "ami_name": "packer-example-{{timestamp}}"
+ }
+ ],
+ "provisioners": [
+ {
+ "type": "shell",
+ "inline": [
+ "curl -sL https://deb.nodesource.com/setup_10.x | sudo -E bash -",
+ "sudo apt-get update -y",
+ "sudo apt-get install -y nodejs"
+ ]
+ }
+ ]
}
```
@@ -35,6 +39,13 @@ includes an `ssh-grunt` binary you can run on each server to manage SSH access t
IAM users in specific IAM groups will be able to SSH to specific servers using their own usernames and SSH keys).
To get these scripts and binaries onto your virtual servers (e.g., onto EC2 instances in AWS), we recommend using Packer to build VM images that have these scripts and binaries installed. You'll see an
-example of how to do this in [How to use the Gruntwork Infrastructure as Code Library](https://gruntwork.io/guides/foundations/how-to-use-gruntwork-infrastructure-as-code-library/#how_to_use_the_catalog). Note that Gruntwork Infrastructure as Code Library does NOT require that
-you use Packer (e.g., you could also use Ansible or Chef to install the scripts and binaries), but the Gruntwork
-Reference Architecture does use Packer as one of its opinionated tools.
+example of how to do this in our [Deploy Your First Module](/docs/intro/first-deployment/using-terraform-modules) section.
+
+:::note
+
+The Gruntwork Infrastructure as Code Library does NOT require that you use
+Packer (e.g., you could also use Ansible or Chef to install the scripts and
+binaries), but the Gruntwork Reference Architecture does use Packer as one of
+its opinionated tools.
+
+:::
diff --git a/_docs-sources/intro/tool-fundamentals/terraform.md b/_docs-sources/intro/tool-fundamentals/terraform.md
index c79e0c39e6..5174050316 100644
--- a/_docs-sources/intro/tool-fundamentals/terraform.md
+++ b/_docs-sources/intro/tool-fundamentals/terraform.md
@@ -24,3 +24,15 @@ thorough introduction to the language.
A large percentage of the infrastructure code in the Gruntwork Infrastructure as Code Library is defined using Terraform. We even
wrote [the book](https://www.terraformupandrunning.com) on it!
+
+## Terraform Cloud and Terraform Enterprise
+
+[Terraform Cloud](https://www.terraform.io/docs/cloud/index.html) and [Terraform Enterprise](https://www.terraform.io/docs/enterprise/index.html) are HashiCorp’s commercial Terraform products. They include many additional features for Terraform, including plan and apply workflows with approvals, role-based access control for teams, policy as code using Sentinel, and more.
+
+
+
+:::note We're compatible with TFC/TFE
+
+The Gruntwork module library and open source tools are compatible with Terraform Cloud and Terraform Enterprise.
+
+:::
diff --git a/docs/guides/build-it-yourself/2-landing-zone/3-deployment-walkthrough/0-pre-requisites.md b/docs/guides/build-it-yourself/2-landing-zone/3-deployment-walkthrough/0-pre-requisites.md
index 880b61345f..27381b8479 100644
--- a/docs/guides/build-it-yourself/2-landing-zone/3-deployment-walkthrough/0-pre-requisites.md
+++ b/docs/guides/build-it-yourself/2-landing-zone/3-deployment-walkthrough/0-pre-requisites.md
@@ -14,7 +14,7 @@ This walkthrough has the following pre-requisites:
This guide uses code from the [Gruntwork Infrastructure as Code Library](https://gruntwork.io/infrastructure-as-code-library/), as it
implements most of the production-grade design for you out of the box. Make sure to read
-[How to use the Gruntwork Infrastructure as Code Library](https://gruntwork.io/guides/foundations/how-to-use-gruntwork-infrastructure-as-code-library).
+our [Introduction to Gruntwork](/docs/intro/overview/intro-to-gruntwork).
@@ -31,7 +31,7 @@ You must be a Gruntwork subscriber to
This guide uses [Terraform](https://www.terraform.io/) to define and manage all the infrastructure as code. If you’re
not familiar with Terraform, check out [A
Comprehensive Guide to Terraform](https://blog.gruntwork.io/a-comprehensive-guide-to-terraform-b3d32832baca), [A Crash Course on Terraform](https://training.gruntwork.io/p/terraform), and
-[How to use the Gruntwork Infrastructure as Code Library](https://gruntwork.io/guides/foundations/how-to-use-gruntwork-infrastructure-as-code-library).
+our [Introduction to Gruntwork](/docs/intro/overview/intro-to-gruntwork).
#### Terragrunt
@@ -56,5 +56,5 @@ automatically.
diff --git a/docs/guides/build-it-yourself/2-landing-zone/3-deployment-walkthrough/1-prepare-your-infrastructure-live-repository.md b/docs/guides/build-it-yourself/2-landing-zone/3-deployment-walkthrough/1-prepare-your-infrastructure-live-repository.md
index 7d419d534e..1f124f0448 100644
--- a/docs/guides/build-it-yourself/2-landing-zone/3-deployment-walkthrough/1-prepare-your-infrastructure-live-repository.md
+++ b/docs/guides/build-it-yourself/2-landing-zone/3-deployment-walkthrough/1-prepare-your-infrastructure-live-repository.md
@@ -4,9 +4,9 @@
This guide uses [Terragrunt](https://github.com/gruntwork-io/terragrunt) and its associated file and folder
structure to deploy Terraform modules. Please note that **Terragrunt is NOT required for using Terraform modules from
-the Gruntwork Infrastructure as Code Library.** Check out [How to use the Gruntwork Infrastructure as Code Library](https://gruntwork.io/guides/foundations/how-to-use-gruntwork-infrastructure-as-code-library)
+the Gruntwork Infrastructure as Code Library.** Check out our [Introduction to Gruntwork](/docs/intro/overview/intro-to-gruntwork)
for instructions on alternative options, such as
-[deploying with plain Terraform](https://gruntwork.io/guides/foundations/how-to-use-gruntwork-infrastructure-as-code-library#deploy_using_plain_terraform).
+[deploying with plain Terraform](/docs/intro/first-deployment/deploy#deploy-using-plain-terraform).
:::
@@ -176,5 +176,5 @@ locals {
diff --git a/docs/guides/build-it-yourself/3-pipelines/3-deployment-walkthrough/0-pre-requisites.md b/docs/guides/build-it-yourself/3-pipelines/3-deployment-walkthrough/0-pre-requisites.md
index 04d0d9b808..cfb284dd08 100644
--- a/docs/guides/build-it-yourself/3-pipelines/3-deployment-walkthrough/0-pre-requisites.md
+++ b/docs/guides/build-it-yourself/3-pipelines/3-deployment-walkthrough/0-pre-requisites.md
@@ -8,7 +8,7 @@ This walkthrough has the following pre-requisites:
This guide uses code from the [Gruntwork Infrastructure as Code Library](https://gruntwork.io/infrastructure-as-code-library/), as it
implements most of the production-grade design for you out of the box. Make sure to read
-[How to use the Gruntwork Infrastructure as Code Library](https://gruntwork.io/guides/foundations/how-to-use-gruntwork-infrastructure-as-code-library).
+our [Introduction to Gruntwork](/docs/intro/overview/intro-to-gruntwork).
@@ -25,7 +25,7 @@ You must be a Gruntwork subscriber to
This guide uses [Terraform](https://www.terraform.io/) to define and manage all the infrastructure as code. If you’re
not familiar with Terraform, check out [A
Comprehensive Guide to Terraform](https://blog.gruntwork.io/a-comprehensive-guide-to-terraform-b3d32832baca), [A Crash Course on Terraform](https://training.gruntwork.io/p/terraform), and
-[How to Use the Gruntwork Infrastructure as Code Library](https://gruntwork.io/guides/foundations/how-to-use-gruntwork-infrastructure-as-code-library)
+our [Introduction to Gruntwork](/docs/intro/overview/intro-to-gruntwork)
#### CircleCI
@@ -44,12 +44,14 @@ for instructions.
#### Repository structure
-This guide assumes your infrastructure code is organized in a manner similar to that covered in the
-[Using
-Terraform Modules section of the How to Use the Gruntwork Infrastructure as Code Library](https://gruntwork.io/guides/foundations/how-to-use-gruntwork-infrastructure-as-code-library/#using_terraform_modules) guide. This means that you
-should have two repositories for your infrastructure code, `infrastructure-modules` and `infrastructure-live`. Make
-sure that the `infrastructure-live` repository is locked down as recommended in [Lock down VCS systems](../2-production-grade-design/7-lock-down-vcs-systems.md). This guide
-will assume that `master` is the protected branch where infrastructure is deployed from.
+This guide assumes your infrastructure code is organized in a manner similar to
+that covered in the [Prepare Your Module](/docs/intro/first-deployment/using-terraform-modules) introduction section. This means
+that you should have two repositories for your infrastructure code,
+`infrastructure-modules` and `infrastructure-live`. Make sure that the
+`infrastructure-live` repository is locked down as recommended in [Lock down VCS
+systems](../2-production-grade-design/7-lock-down-vcs-systems.md). This guide
+will assume that `master` is the protected branch where infrastructure is
+deployed from.
@@ -58,13 +60,13 @@ will assume that `master` is the protected branch where infrastructure is deploy
This guide will use [Terragrunt](https://github.com/gruntwork-io/terragrunt) and its associated file and folder
structure to deploy Terraform modules. Please note that **Terragrunt is NOT required for using Terraform modules from
the Gruntwork Infrastructure as Code Library.** Check out
-[How to Use the Gruntwork Infrastructure as Code Library](https://gruntwork.io/guides/foundations/how-to-use-gruntwork-infrastructure-as-code-library/) for instructions
+our [Introduction to Gruntwork](/docs/intro/overview/intro-to-gruntwork) for instructions
on alternative options, such as how to
-[Deploy using plain Terraform](https://gruntwork.io/guides/foundations/how-to-use-gruntwork-infrastructure-as-code-library/#deploy_using_plain_terraform).
+[Deploy using plain Terraform](/docs/intro/first-deployment/deploy#deploy-using-plain-terraform).
:::
diff --git a/docs/guides/build-it-yourself/3-pipelines/3-deployment-walkthrough/2-deploy-the-ecs-deploy-runner.md b/docs/guides/build-it-yourself/3-pipelines/3-deployment-walkthrough/2-deploy-the-ecs-deploy-runner.md
index b4a5816cee..b102d71f47 100644
--- a/docs/guides/build-it-yourself/3-pipelines/3-deployment-walkthrough/2-deploy-the-ecs-deploy-runner.md
+++ b/docs/guides/build-it-yourself/3-pipelines/3-deployment-walkthrough/2-deploy-the-ecs-deploy-runner.md
@@ -125,9 +125,9 @@ output "url" {
```
At this point, you’ll want to test your code. See
-[Manual tests for Terraform code](https://gruntwork.io/guides/foundations/how-to-use-gruntwork-infrastructure-as-code-library#manual_tests_terraform)
+[Manual tests for Terraform code](/docs/intro/first-deployment/testing#manual-tests-for-terraform-code)
and
-[Automated tests for Terraform code](https://gruntwork.io/guides/foundations/how-to-use-gruntwork-infrastructure-as-code-library#automated_tests_terraform)
+[Automated tests for Terraform code](/docs/intro/first-deployment/testing#automated-tests-for-terraform-code)
for instructions.
Once your `ecr-repo` module is working the way you want, submit a pull request, get your changes merged into the
@@ -751,5 +751,5 @@ Repeat for each environment that you want to support the ECS Deploy Runner stack
diff --git a/docs/guides/build-it-yourself/4-vpc/3-deployment-walkthrough/0-pre-requisites.md b/docs/guides/build-it-yourself/4-vpc/3-deployment-walkthrough/0-pre-requisites.md
index 3e436c7358..a68c253d5c 100644
--- a/docs/guides/build-it-yourself/4-vpc/3-deployment-walkthrough/0-pre-requisites.md
+++ b/docs/guides/build-it-yourself/4-vpc/3-deployment-walkthrough/0-pre-requisites.md
@@ -12,7 +12,7 @@ This walkthrough has the following pre-requisites:
This guide uses code from the [Gruntwork Infrastructure as Code Library](https://gruntwork.io/infrastructure-as-code-library/), as it
implements most of the production-grade design for you out of the box. Make sure to read
-[How to use the Gruntwork Infrastructure as Code Library](https://gruntwork.io/guides/foundations/how-to-use-gruntwork-infrastructure-as-code-library).
+our [Introduction to Gruntwork](/docs/intro/overview/intro-to-gruntwork).
@@ -29,7 +29,7 @@ You must be a Gruntwork subscriber to
This guide uses [Terraform](https://www.terraform.io/) to define and manage all the infrastructure as code. If you’re
not familiar with Terraform, check out [A
Comprehensive Guide to Terraform](https://blog.gruntwork.io/a-comprehensive-guide-to-terraform-b3d32832baca), [A Crash Course on Terraform](https://training.gruntwork.io/p/terraform), and
-[How to Use the Gruntwork Infrastructure as Code Library](https://gruntwork.io/guides/foundations/how-to-use-gruntwork-infrastructure-as-code-library)
+our [Introduction to Gruntwork](/docs/intro/overview/intro-to-gruntwork)
#### AWS accounts
@@ -43,5 +43,5 @@ for instructions.
diff --git a/docs/guides/build-it-yourself/4-vpc/3-deployment-walkthrough/1-deploy-a-management-vpc.md b/docs/guides/build-it-yourself/4-vpc/3-deployment-walkthrough/1-deploy-a-management-vpc.md
index b6056cd806..6a30b10f32 100644
--- a/docs/guides/build-it-yourself/4-vpc/3-deployment-walkthrough/1-deploy-a-management-vpc.md
+++ b/docs/guides/build-it-yourself/4-vpc/3-deployment-walkthrough/1-deploy-a-management-vpc.md
@@ -103,8 +103,8 @@ file for reference.
## Test your wrapper module
-At this point, you’ll want to test your code. See [Manual tests for Terraform code](https://gruntwork.io/guides/foundations/how-to-use-gruntwork-infrastructure-as-code-library#manual_tests_terraform)
-and [Automated tests for Terraform code](https://gruntwork.io/guides/foundations/how-to-use-gruntwork-infrastructure-as-code-library#automated_tests_terraform)
+At this point, you’ll want to test your code. See [Manual tests for Terraform code](/docs/intro/first-deployment/testing#manual-tests-for-terraform-code)
+and [Automated tests for Terraform code](/docs/intro/first-deployment/testing#automated-tests-for-terraform-code)
for instructions.
## Merge and release your wrapper module
@@ -149,9 +149,9 @@ route table entries, more bastion hosts, and more credentials.
This guide will use [Terragrunt](https://github.com/gruntwork-io/terragrunt) and its associated file and folder
structure to deploy Terraform modules. Please note that **Terragrunt is NOT required for using Terraform modules from
-the Gruntwork Infrastructure as Code Library.** Check out [How to Use the Gruntwork Infrastructure as Code Library](https://gruntwork.io/guides/foundations/how-to-use-gruntwork-infrastructure-as-code-library)
+the Gruntwork Infrastructure as Code Library.** Check out our [Introduction to Gruntwork](/docs/intro/overview/intro-to-gruntwork)
for instructions on alternative options, such as how to
-[deploy using plain terraform](https://gruntwork.io/guides/foundations/how-to-use-gruntwork-infrastructure-as-code-library#deploy_using_plain_terraform).
+[deploy using plain terraform](/docs/intro/first-deployment/deploy#deploy-using-plain-terraform).
:::
@@ -214,5 +214,5 @@ terragrunt apply
diff --git a/docs/guides/build-it-yourself/4-vpc/3-deployment-walkthrough/2-deploy-application-vp-cs.md b/docs/guides/build-it-yourself/4-vpc/3-deployment-walkthrough/2-deploy-application-vp-cs.md
index 5578710194..b78c5e889e 100644
--- a/docs/guides/build-it-yourself/4-vpc/3-deployment-walkthrough/2-deploy-application-vp-cs.md
+++ b/docs/guides/build-it-yourself/4-vpc/3-deployment-walkthrough/2-deploy-application-vp-cs.md
@@ -171,8 +171,8 @@ file for reference.
## Test your wrapper module
-At this point, you’ll want to test your code. See [Manual tests for Terraform code](https://gruntwork.io/guides/foundations/how-to-use-gruntwork-infrastructure-as-code-library#manual_tests_terraform)
-and [Automated tests for Terraform code](https://gruntwork.io/guides/foundations/how-to-use-gruntwork-infrastructure-as-code-library#automated_tests_terraform)
+At this point, you’ll want to test your code. See [Manual tests for Terraform code](/docs/intro/first-deployment/testing#manual-tests-for-terraform-code)
+and [Automated tests for Terraform code](/docs/intro/first-deployment/testing#automated-tests-for-terraform-code)
for instructions.
## Merge and release your wrapper module
@@ -245,5 +245,5 @@ terragrunt apply
diff --git a/docs/guides/build-it-yourself/5-kubernetes-cluster/3-deployment-walkthrough/0-pre-requisites.md b/docs/guides/build-it-yourself/5-kubernetes-cluster/3-deployment-walkthrough/0-pre-requisites.md
index 7cdfbe985f..f48357c90d 100644
--- a/docs/guides/build-it-yourself/5-kubernetes-cluster/3-deployment-walkthrough/0-pre-requisites.md
+++ b/docs/guides/build-it-yourself/5-kubernetes-cluster/3-deployment-walkthrough/0-pre-requisites.md
@@ -14,7 +14,7 @@ This walkthrough has the following pre-requisites:
This guide uses code from the [Gruntwork Infrastructure as Code Library](https://gruntwork.io/infrastructure-as-code-library/), as it
implements most of the production-grade design for you out of the box. Make sure to read
-[How to use the Gruntwork Infrastructure as Code Library](https://gruntwork.io/guides/foundations/how-to-use-gruntwork-infrastructure-as-code-library).
+our [Introduction to Gruntwork](/docs/intro/overview/intro-to-gruntwork).
@@ -31,7 +31,7 @@ You must be a Gruntwork subscriber to
This guide uses [Terraform](https://www.terraform.io/) to define and manage all the infrastructure as code. If you’re
not familiar with Terraform, check out [A
Comprehensive Guide to Terraform](https://blog.gruntwork.io/a-comprehensive-guide-to-terraform-b3d32832baca), [A Crash Course on Terraform](https://training.gruntwork.io/p/terraform), and
-[How to Use the Gruntwork Infrastructure as Code Library](https://gruntwork.io/guides/foundations/how-to-use-gruntwork-infrastructure-as-code-library).
+our [Introduction to Gruntwork](/docs/intro/overview/intro-to-gruntwork).
#### Python and Kubergrunt
@@ -44,7 +44,7 @@ Python and `kubergrunt` installed on any computer where you will be running Terr
This guide assumes you are deploying a Kubernetes cluster for use with [Docker](https://www.docker.com). The guide also
uses [Packer](https://www.packer.io) to build VM images. If you’re not familiar with Docker or Packer, check out
[A Crash Course on Docker and Packer](https://training.gruntwork.io/p/a-crash-course-on-docker-packer) and
-[How to Use the Gruntwork Infrastructure as Code Library](https://gruntwork.io/guides/foundations/how-to-use-gruntwork-infrastructure-as-code-library).
+our [Introduction to Gruntwork](/docs/intro/overview/intro-to-gruntwork).
#### AWS accounts
@@ -58,5 +58,5 @@ for instructions.
diff --git a/docs/guides/build-it-yourself/5-kubernetes-cluster/3-deployment-walkthrough/1-deploy-the-vpc.md b/docs/guides/build-it-yourself/5-kubernetes-cluster/3-deployment-walkthrough/1-deploy-the-vpc.md
index 319eb6b141..b0dd2ce762 100644
--- a/docs/guides/build-it-yourself/5-kubernetes-cluster/3-deployment-walkthrough/1-deploy-the-vpc.md
+++ b/docs/guides/build-it-yourself/5-kubernetes-cluster/3-deployment-walkthrough/1-deploy-the-vpc.md
@@ -107,9 +107,9 @@ module "dns_mgmt_to_app" {
```
At this point, you’ll want to test your code. See
-[Manual tests for Terraform code](https://gruntwork.io/guides/foundations/how-to-use-gruntwork-infrastructure-as-code-library#manual_tests_terraform)
+[Manual tests for Terraform code](/docs/intro/first-deployment/testing#manual-tests-for-terraform-code)
and
-[Automated tests for Terraform code](https://gruntwork.io/guides/foundations/how-to-use-gruntwork-infrastructure-as-code-library#automated_tests_terraform)
+[Automated tests for Terraform code](/docs/intro/first-deployment/testing#automated-tests-for-terraform-code)
for instructions.
Once your updated `vpc-app` wrapper module is working the way you want, submit a pull request, get your changes merged
@@ -126,9 +126,9 @@ git push --follow-tags
This guide will use [Terragrunt](https://github.com/gruntwork-io/terragrunt) and its associated file and folder
structure to deploy Terraform modules. Please note that **Terragrunt is NOT required for using Terraform modules from
the Gruntwork Infrastructure as Code Library.** Check out
-[How to Use the Gruntwork Infrastructure as Code Library](https://gruntwork.io/guides/foundations/how-to-use-gruntwork-infrastructure-as-code-library) for instructions
+our [Introduction to Gruntwork](/docs/intro/overview/intro-to-gruntwork) for instructions
on alternative options, such as how to
-[Deploy using plain Terraform](https://gruntwork.io/guides/foundations/how-to-use-gruntwork-infrastructure-as-code-library#deploy_using_plain_terraform).
+[Deploy using plain Terraform](/docs/intro/first-deployment/deploy#deploy-using-plain-terraform).
:::
@@ -149,5 +149,5 @@ terragrunt apply
diff --git a/docs/guides/build-it-yourself/6-achieve-compliance/2-production-grade-design/0-intro.md b/docs/guides/build-it-yourself/6-achieve-compliance/2-production-grade-design/0-intro.md
index 8dd5626007..f623f666a0 100644
--- a/docs/guides/build-it-yourself/6-achieve-compliance/2-production-grade-design/0-intro.md
+++ b/docs/guides/build-it-yourself/6-achieve-compliance/2-production-grade-design/0-intro.md
@@ -6,7 +6,7 @@ pagination_label: Production-grade Design
In [core concepts](../1-core-concepts/0-intro.md) we discussed the basics of the AWS Foundations Benchmark. Although it's possible to achieve
compliance with the Benchmark by manually configuring each setting in the web console or entering the CLI commands, we
-strongly discourage this approach. It precludes [the myriad benefits of using code to manage infrastructure](https://gruntwork.io/guides/foundations/how-to-use-gruntwork-infrastructure-as-code-library/#infrastructure-as-code).
+strongly discourage this approach. It precludes [the myriad benefits of using code to manage infrastructure](/docs/intro/core-concepts/infrastructure-as-code).
Instead, we advise using [Terraform](https://www.terraform.io) (or similar tools, such as
[CloudFormation](https://aws.amazon.com/cloudformation/) or [Pulumi](https://www.pulumi.com/) to configure cloud
@@ -18,5 +18,5 @@ edition of Terraform Up & Running](https://blog.gruntwork.io/terraform-up-runnin
diff --git a/docs/guides/build-it-yourself/6-achieve-compliance/3-deployment-walkthrough/0-pre-requisites.md b/docs/guides/build-it-yourself/6-achieve-compliance/3-deployment-walkthrough/0-pre-requisites.md
index bba5cd8687..8849469e39 100644
--- a/docs/guides/build-it-yourself/6-achieve-compliance/3-deployment-walkthrough/0-pre-requisites.md
+++ b/docs/guides/build-it-yourself/6-achieve-compliance/3-deployment-walkthrough/0-pre-requisites.md
@@ -13,7 +13,7 @@ This walkthrough has the following pre-requisites:
This guide uses code from the [Gruntwork Infrastructure as Code Library](https://gruntwork.io/infrastructure-as-code-library/), as it
implements most of the production-grade design for you out of the box. Make sure to read
-[How to use the Gruntwork Infrastructure as Code Library](https://gruntwork.io/guides/foundations/how-to-use-gruntwork-infrastructure-as-code-library).
+our [Introduction to Gruntwork](/docs/intro/overview/intro-to-gruntwork).
## Gruntwork Compliance for CIS AWS Foundations Benchmark
@@ -37,8 +37,7 @@ This guide uses [Terraform](https://www.terraform.io/) to define and manage all
you’re not familiar with Terraform, check out
[A Comprehensive Guide to Terraform](https://blog.gruntwork.io/a-comprehensive-guide-to-terraform-b3d32832baca),
[A Crash Course on Terraform](https://training.gruntwork.io/p/terraform), and
-[How to Use the Gruntwork
-Infrastructure as Code Library](https://gruntwork.ioguides/foundations/how-to-use-gruntwork-infrastructure-as-code-library).
+our [Introduction to Gruntwork](/docs/intro/overview/intro-to-gruntwork).
## Terragrunt
@@ -56,5 +55,5 @@ automatically.
diff --git a/docs/guides/build-it-yourself/6-achieve-compliance/3-deployment-walkthrough/1-the-gruntwork-solution.md b/docs/guides/build-it-yourself/6-achieve-compliance/3-deployment-walkthrough/1-the-gruntwork-solution.md
index 2d5fdcb0b9..a5ee2e71eb 100644
--- a/docs/guides/build-it-yourself/6-achieve-compliance/3-deployment-walkthrough/1-the-gruntwork-solution.md
+++ b/docs/guides/build-it-yourself/6-achieve-compliance/3-deployment-walkthrough/1-the-gruntwork-solution.md
@@ -55,10 +55,9 @@ You can use this approach on each AWS account. In many cases, you’ll only need
same methodology can be applied to pre-production accounts as well.
If you need to brush up on how the IaC Library works, read the
-[How to use
-the Gruntwork Infrastructure as Code Library](https://gruntwork.io/guides/foundations/how-to-use-gruntwork-infrastructure-as-code-library/) guide.
+our [Introduction to Gruntwork](/docs/intro/overview/intro-to-gruntwork) section.
diff --git a/docs/guides/build-it-yourself/6-achieve-compliance/3-deployment-walkthrough/8-deploy-landing-zone-solution/0-apply-account-baseline-root-to-root-account.md b/docs/guides/build-it-yourself/6-achieve-compliance/3-deployment-walkthrough/8-deploy-landing-zone-solution/0-apply-account-baseline-root-to-root-account.md
index fc389f51c9..018092fef5 100644
--- a/docs/guides/build-it-yourself/6-achieve-compliance/3-deployment-walkthrough/8-deploy-landing-zone-solution/0-apply-account-baseline-root-to-root-account.md
+++ b/docs/guides/build-it-yourself/6-achieve-compliance/3-deployment-walkthrough/8-deploy-landing-zone-solution/0-apply-account-baseline-root-to-root-account.md
@@ -58,9 +58,9 @@ We’ll be using the `landingzone/account-baseline-root` module from [terraform-
:::info
This guide will use [Terragrunt](https://github.com/gruntwork-io/terragrunt) and its associated file and folder
-structure to deploy Terraform modules. Please note that **Terragrunt is NOT required for using Terraform modules from the Gruntwork Infrastructure as Code Library.** Check out [How to use the Gruntwork Infrastructure as Code Library](https://gruntwork.ioguides/foundations/how-to-use-gruntwork-infrastructure-as-code-library)
+structure to deploy Terraform modules. Please note that **Terragrunt is NOT required for using Terraform modules from the Gruntwork Infrastructure as Code Library.** Check out our [Introduction to Gruntwork](/docs/intro/overview/intro-to-gruntwork) section
for instructions on alternative options, such as how to
-[deploying how to use plain terraform](https://gruntwork.ioguides/foundations/how-to-use-gruntwork-infrastructure-as-code-library#deploy_using_plain_terraform).
+[deploying how to use plain terraform](/docs/intro/first-deployment/deploy#deploy-using-plain-terraform).
:::
@@ -587,5 +587,5 @@ those root users again.
diff --git a/docs/guides/reference-architecture/01-overview/overview.md b/docs/guides/reference-architecture/01-overview/overview.md
index c46ab7ebe6..de67d69302 100644
--- a/docs/guides/reference-architecture/01-overview/overview.md
+++ b/docs/guides/reference-architecture/01-overview/overview.md
@@ -37,7 +37,7 @@ All of the infrastructure in this repo is managed as **code** using [Terragrunt]
[Gruntwork Service Catalog](https://github.com/gruntwork-io/terraform-aws-service-catalog/).
For more info on Infrastructure as Code and Terraform, check out [A Comprehensive Guide to
-Terraform](https://blog.gruntwork.io/a-comprehensive-guide-to-terraform-b3d32832baca) and our guide on [How to use the Gruntwork Infrastructure as Code Library](https://gruntwork.io/guides/foundations/how-to-use-gruntwork-infrastructure-as-code-library/).
+Terraform](https://blog.gruntwork.io/a-comprehensive-guide-to-terraform-b3d32832baca) and our our [Introduction to Gruntwork](/docs/intro/overview/intro-to-gruntwork) section.
## AWS accounts
@@ -159,5 +159,5 @@ Next up, let's have a look at [how to authenticate](../authenticate/intro).
diff --git a/docs/guides/stay-up-to-date/01-versioning.md b/docs/guides/stay-up-to-date/01-versioning.md
new file mode 100644
index 0000000000..3f9c9aaf22
--- /dev/null
+++ b/docs/guides/stay-up-to-date/01-versioning.md
@@ -0,0 +1,72 @@
+# How we version code
+
+## Versioning
+
+All of the code in the Gruntwork Infrastructure as Code Library is _versioned_. Every time we make a change, we put out a new
+versioned release, and announce it in the monthly
+[Gruntwork Newsletter](https://blog.gruntwork.io/tagged/gruntwork-newsletter).
+
+
+
+### Pinned Versions
+
+When you use the code from the Gruntwork Infrastructure as Code Library, you pin
+yourself to a specific version of the code. That way, you are not accidentally affected by any subsequent changes in
+the Gruntwork Infrastructure as Code Library until you explicitly choose to pull those changes in. And when you do want to pull the
+changes in, it’s just a matter of bumping the version number!
+
+### Semantic Versioning
+
+We use version numbers of the form `MAJOR.MINOR.PATCH` (e.g., `1.2.3`), following the principles of
+_[semantic versioning](https://semver.org)_. In traditional semantic versioning, you increment the:
+
+1. MAJOR version when you make incompatible API changes,
+2. MINOR version when you add functionality in a backwards compatible manner, and
+3. PATCH version when you make backwards compatible bug fixes.
+
+However, much of the Gruntwork Infrastructure as Code Library is still not at version `1.0.0`. Most of the Gruntwork Infrastructure as Code Library is using `0.MINOR.PATCH` version numbers. With `0.MINOR.PATCH`, the rules are a bit different, where you increment the:
+
+1. MINOR version when you make incompatible API changes
+2. PATCH version when you add backwards compatible functionality or bug fixes.
+
+## Updating to new versions
+
+Follow the steps below to keep your code up to date:
+
+1. Make sure you're following our monthly [Gruntwork Newsletter](https://blog.gruntwork.io/tagged/gruntwork-newsletter) to be notified
+ of all updates to the Gruntwork Infrastructure as Code Library. Alternatively, you can "watch" repos in GitHub that you’re
+ interested in.
+
+2. When you find an update you’d like for a specific module, update any code using that module in
+ `infrastructure-modules` to the new version number. For example, if you were using `terraform-aws-vpc` at `v0.18.5` and you
+ wanted to update to `v0.7.3`, you would change from:
+
+ ```hcl
+ module "vpc" {
+ source = "git@github.com:gruntwork-io/terraform-aws-vpc.git//modules/vpc-app?ref=v0.18.5"
+ # ...
+ }
+ ```
+
+ to:
+
+ ```hcl
+ module "vpc" {
+ source = "git@github.com:gruntwork-io/terraform-aws-vpc.git//modules/vpc-app?ref=v0.18.6"
+ # ...
+ }
+ ```
+
+3. Pay close attention to the release notes for any additional instructions. In particular, if the MINOR version number
+ was increased (e.g., `v0.18.0` → `v0.19.0`), that implies a backwards incompatible change, and the release notes will
+ explain what you need to do (e.g., you might have to add, remove, or change arguments you pass to the module).
+
+4. Test your changes locally. You do this using the same process outlined in [Manual tests for Terraform code](/docs/intro/first-deployment/testing#manual-tests-for-terraform-code) and
+ [Automated tests for Terraform code](/docs/intro/first-deployment/testing#automated-tests-for-terraform-code).
+
+5. Deploy your changes to each environment. You do this using the same process outlined in [Deploying Terraform code](#deploy_terraform).
+
+
+
diff --git a/docs/guides/stay-up-to-date/1-cis/0-how-to-update-to-cis-14/2-deployment-walkthrough/0-step-1-update-references-to-the-gruntwork-infrastructure-as-code-library.md b/docs/guides/stay-up-to-date/1-cis/0-how-to-update-to-cis-14/2-deployment-walkthrough/0-step-1-update-references-to-the-gruntwork-infrastructure-as-code-library.md
index a44dd1ddfb..2682e15624 100644
--- a/docs/guides/stay-up-to-date/1-cis/0-how-to-update-to-cis-14/2-deployment-walkthrough/0-step-1-update-references-to-the-gruntwork-infrastructure-as-code-library.md
+++ b/docs/guides/stay-up-to-date/1-cis/0-how-to-update-to-cis-14/2-deployment-walkthrough/0-step-1-update-references-to-the-gruntwork-infrastructure-as-code-library.md
@@ -7,14 +7,12 @@ sidebar_label: Update references to the Gruntwork Infrastructure as Code Library
To update to the CIS AWS Foundations Benchmark v1.4.0, you need to update your references to the Gruntwork
Infrastructure as Code Library to use compatible versions. We (Gruntwork) have reviewed and updated all the library
modules for compatibility with the new version of the benchmark. As a customer, you need to update to
-the proper versions of the Gruntwork library to pick up the fixes/changes made to be compatible. Refer to
-[the
-"Updating" section of "How to use the Gruntwork Infrastructure as Code Library"](https://gruntwork.io/guides/foundations/how-to-use-gruntwork-infrastructure-as-code-library/#updating) for instructions on how to update the
+the proper versions of the Gruntwork library to pick up the fixes/changes made to be compatible. Refer to our ["Updating to new versions"](/docs/guides/stay-up-to-date/versioning#updating-to-new-versions) guide for instructions on how to update the
versions in your code.
Gruntwork follows
[semantic
-versioning](https://gruntwork.io/guides/foundations/how-to-use-gruntwork-infrastructure-as-code-library/#versioning). For any pre-1.0 modules, this means that version updates to the minor version are considered backward
+versioning](/docs/guides/stay-up-to-date/versioning#semantic-versioning). For any pre-1.0 modules, this means that version updates to the minor version are considered backward
incompatible releases for any version updates before the 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,
@@ -24,6 +22,7 @@ The following table provides a summary of all the relevant Gruntwork AWS modules
compatible with CIS AWS v1.4.0:
+
@@ -83,5 +82,5 @@ compatible with CIS AWS v1.4.0:
diff --git a/docs/guides/stay-up-to-date/1-cis/1-how-to-update-to-cis-13/2-deployment-walkthrough/0-step-1-update-references-to-the-gruntwork-infrastructure-as-code-library.md b/docs/guides/stay-up-to-date/1-cis/1-how-to-update-to-cis-13/2-deployment-walkthrough/0-step-1-update-references-to-the-gruntwork-infrastructure-as-code-library.md
index 6a94020d27..f85cf92e97 100644
--- a/docs/guides/stay-up-to-date/1-cis/1-how-to-update-to-cis-13/2-deployment-walkthrough/0-step-1-update-references-to-the-gruntwork-infrastructure-as-code-library.md
+++ b/docs/guides/stay-up-to-date/1-cis/1-how-to-update-to-cis-13/2-deployment-walkthrough/0-step-1-update-references-to-the-gruntwork-infrastructure-as-code-library.md
@@ -18,7 +18,7 @@ To update to the CIS AWS Foundations Benchmark v1.3.0, you need to update your r
Infrastructure as Code Library to use compatible versions. We (Gruntwork) have reviewed and updated all the library modules for compatibility with the new version of the Benchmark. As a customer, you need to update to
the proper versions of the Gruntwork library to pick up the fixes/changes made to be compatible. Refer to
[the
-"Updating" section of "How to use the Gruntwork Infrastructure as Code Library"](https://gruntwork.io/guides/foundations/how-to-use-gruntwork-infrastructure-as-code-library/#updating) for instructions on how to update the
+"Updating to new versions" section of "Stay Up to Date"](/docs/guides/stay-up-to-date/versioning#updating-to-new-versions) 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
@@ -30,7 +30,7 @@ version.**
Gruntwork follows
[semantic
-versioning](https://gruntwork.io/guides/foundations/how-to-use-gruntwork-infrastructure-as-code-library/#versioning). For any pre-1.0 modules, this means that version updates to the minor version are considered backward
+versioning](/docs/guides/stay-up-to-date/versioning#semantic-versioning). For any pre-1.0 modules, this means that version updates to the minor version are considered backward
incompatible releases for any version updates before the 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,
@@ -42,6 +42,7 @@ The following table provides a summary of all the relevant Gruntwork AWS modules
compatible with CIS AWS v1.3.0:
+
@@ -186,5 +187,5 @@ compatible with CIS AWS v1.3.0:
diff --git a/docs/guides/stay-up-to-date/terraform/1-how-to-update-to-terraform-13/2-deployment-walkthrough/2-step-3-update-references-to-the-gruntwork-infrastructure-as-code-library.md b/docs/guides/stay-up-to-date/terraform/1-how-to-update-to-terraform-13/2-deployment-walkthrough/2-step-3-update-references-to-the-gruntwork-infrastructure-as-code-library.md
index f12bd0b2e2..fa8c59a77a 100644
--- a/docs/guides/stay-up-to-date/terraform/1-how-to-update-to-terraform-13/2-deployment-walkthrough/2-step-3-update-references-to-the-gruntwork-infrastructure-as-code-library.md
+++ b/docs/guides/stay-up-to-date/terraform/1-how-to-update-to-terraform-13/2-deployment-walkthrough/2-step-3-update-references-to-the-gruntwork-infrastructure-as-code-library.md
@@ -7,9 +7,7 @@ sidebar_label: Update Gruntwork IaC module references
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
-[the
-"Updating" section of "How to use the Gruntwork Infrastructure as Code Library"](https://gruntwork.io/guides/foundations/how-to-use-gruntwork-infrastructure-as-code-library/#updating) for instructions on how to update the
+the proper versions of the Gruntwork library to pick up the fixes/changes that were made to be compatible. Refer to our ["Updating to new versions"](/docs/guides/stay-up-to-date/versioning#updating-to-new-versions) guide 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
@@ -21,7 +19,7 @@ user, pay special attention to the release notes!
:::caution
Gruntwork follows [semantic
-versioning](https://gruntwork.io/guides/foundations/how-to-use-gruntwork-infrastructure-as-code-library/#versioning).
+versioning](/docs/guides/stay-up-to-date/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
@@ -173,5 +171,5 @@ compatible with Terraform 0.13:
diff --git a/docs/guides/stay-up-to-date/terraform/2-how-to-update-to-terraform-14/2-deployment-walkthrough/2-step-3-update-references-to-the-gruntwork-infrastructure-as-code-library.md b/docs/guides/stay-up-to-date/terraform/2-how-to-update-to-terraform-14/2-deployment-walkthrough/2-step-3-update-references-to-the-gruntwork-infrastructure-as-code-library.md
index 05c37601a0..e2e912f623 100644
--- a/docs/guides/stay-up-to-date/terraform/2-how-to-update-to-terraform-14/2-deployment-walkthrough/2-step-3-update-references-to-the-gruntwork-infrastructure-as-code-library.md
+++ b/docs/guides/stay-up-to-date/terraform/2-how-to-update-to-terraform-14/2-deployment-walkthrough/2-step-3-update-references-to-the-gruntwork-infrastructure-as-code-library.md
@@ -7,9 +7,7 @@ sidebar_label: Update Gruntwork IaC module references
In order to take advantage of the Terraform 0.14, 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.14. As a customer, you need to update to
-the proper versions of the Gruntwork library to pick up the fixes/changes that we made to be compatible. Refer to
-[the
-"Updating" section of "How to use the Gruntwork Infrastructure as Code Library"](https://gruntwork.io/guides/foundations/how-to-use-gruntwork-infrastructure-as-code-library/#updating) for instructions on how to update the
+the proper versions of the Gruntwork library to pick up the fixes/changes that we made to be compatible. Refer to our ["Updating to new versions"](/docs/guides/stay-up-to-date/versioning#updating-to-new-versions) guide 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
@@ -20,7 +18,7 @@ version.**
:::caution
Gruntwork follows [semantic
-versioning](https://gruntwork.io/guides/foundations/how-to-use-gruntwork-infrastructure-as-code-library/#versioning).
+versioning](/docs/guides/stay-up-to-date/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
@@ -172,5 +170,5 @@ compatible with Terraform 0.14:
diff --git a/docs/guides/stay-up-to-date/terraform/3-how-to-update-to-terraform-15/2-deployment-walkthrough/2-step-3-update-references-to-the-gruntwork-infrastructure-as-code-library.md b/docs/guides/stay-up-to-date/terraform/3-how-to-update-to-terraform-15/2-deployment-walkthrough/2-step-3-update-references-to-the-gruntwork-infrastructure-as-code-library.md
index a4f66cdfea..36bc8e54ef 100644
--- a/docs/guides/stay-up-to-date/terraform/3-how-to-update-to-terraform-15/2-deployment-walkthrough/2-step-3-update-references-to-the-gruntwork-infrastructure-as-code-library.md
+++ b/docs/guides/stay-up-to-date/terraform/3-how-to-update-to-terraform-15/2-deployment-walkthrough/2-step-3-update-references-to-the-gruntwork-infrastructure-as-code-library.md
@@ -7,9 +7,7 @@ sidebar_label: Update Gruntwork IaC module references
In order to take advantage of the Terraform 0.15, 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.15. As a customer, you need to update to
-the proper versions of the Gruntwork library to pick up the fixes/changes that we made to be compatible. Refer to
-[the
-"Updating" section of "How to use the Gruntwork Infrastructure as Code Library"](https://gruntwork.io/guides/foundations/how-to-use-gruntwork-infrastructure-as-code-library/#updating) for instructions on how to update the
+the proper versions of the Gruntwork library to pick up the fixes/changes that we made to be compatible. Refer to our ["Updating to new versions"](/docs/guides/stay-up-to-date/versioning#updating-to-new-versions) guide 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
@@ -20,7 +18,7 @@ version.**
:::caution
Gruntwork follows [semantic
-versioning](https://gruntwork.io/guides/foundations/how-to-use-gruntwork-infrastructure-as-code-library/#versioning).
+versioning](/docs/guides/stay-up-to-date/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
@@ -172,5 +170,5 @@ compatible with Terraform 0.15:
diff --git a/docs/guides/stay-up-to-date/terraform/4-how-to-update-to-terraform-1-x/2-deployment-walkthrough/1-step-2-update-references-to-the-gruntwork-infrastructure-as-code-library.md b/docs/guides/stay-up-to-date/terraform/4-how-to-update-to-terraform-1-x/2-deployment-walkthrough/1-step-2-update-references-to-the-gruntwork-infrastructure-as-code-library.md
index 075f2c6148..4af14103c0 100644
--- a/docs/guides/stay-up-to-date/terraform/4-how-to-update-to-terraform-1-x/2-deployment-walkthrough/1-step-2-update-references-to-the-gruntwork-infrastructure-as-code-library.md
+++ b/docs/guides/stay-up-to-date/terraform/4-how-to-update-to-terraform-1-x/2-deployment-walkthrough/1-step-2-update-references-to-the-gruntwork-infrastructure-as-code-library.md
@@ -9,9 +9,8 @@ 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 1.x. As a customer, you need
to update to the proper versions of the Gruntwork library to pick up the
-fixes/changes that we made to be compatible. Refer to [the "Updating" section of
-"How to use the Gruntwork Infrastructure as Code
-Library"](https://gruntwork.io/guides/foundations/how-to-use-gruntwork-infrastructure-as-code-library/#updating)
+fixes/changes that we made to be compatible. Refer to [the "Updating to new versions" section of
+"Stay Up to Date"](/docs/guides/stay-up-to-date/versioning#updating-to-new-versions#updating)
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
@@ -23,7 +22,7 @@ changes need to be made to update to the new version.**
:::caution
Gruntwork follows [semantic
-versioning](https://gruntwork.io/guides/foundations/how-to-use-gruntwork-infrastructure-as-code-library/#versioning).
+versioning](/docs/guides/stay-up-to-date/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
@@ -175,5 +174,5 @@ and the respective versions that are compatible with Terraform 1.x:
diff --git a/docs/guides/stay-up-to-date/terraform/5-how-to-update-to-aws-provider-v3/2-deployment-walkthrough.md b/docs/guides/stay-up-to-date/terraform/5-how-to-update-to-aws-provider-v3/2-deployment-walkthrough.md
index d44e9a3133..93fa27f996 100644
--- a/docs/guides/stay-up-to-date/terraform/5-how-to-update-to-aws-provider-v3/2-deployment-walkthrough.md
+++ b/docs/guides/stay-up-to-date/terraform/5-how-to-update-to-aws-provider-v3/2-deployment-walkthrough.md
@@ -8,8 +8,7 @@ library to test and update the code to be compatible with AWS provider version 3
the proper versions of the Gruntwork library to pick up the fixes/changes that were made to be compatible. Be sure to
read the release notes to know what changes need to be made to update to that version.
-Refer to [the
-"Updating" section of "How to use the Gruntwork Infrastructure as Code Library"](https://gruntwork.io/guides/foundations/how-to-use-gruntwork-infrastructure-as-code-library/#updating)
+Refer to our ["Updating to new versions"](/docs/guides/stay-up-to-date/versioning#updating-to-new-versions) guide
for instructions on how to update the versions in your code.
The following table provides a summary of all the relevant Gruntwork AWS modules and the respective versions that are
@@ -18,7 +17,7 @@ compatible with AWS provider version 3.
:::caution
Gruntwork follows [semantic
-versioning](https://gruntwork.io/guides/foundations/how-to-use-gruntwork-infrastructure-as-code-library/#versioning).
+versioning](/docs/guides/stay-up-to-date/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
@@ -183,5 +182,5 @@ on how to update your components to be compatible with AWS provider v3.
diff --git a/docs/intro/core-concepts/immutable-infrastructure.md b/docs/intro/core-concepts/immutable-infrastructure.md
new file mode 100644
index 0000000000..69c8db9074
--- /dev/null
+++ b/docs/intro/core-concepts/immutable-infrastructure.md
@@ -0,0 +1,39 @@
+# Immutable infrastructure
+
+With _mutable infrastructure_, you deploy a set of servers, and you continuously update those servers in place. Every
+new update gets installed on top of the previous updates, either manually (e.g., by SSHing to each server and running
+commands), or via tools like Ansible, Chef, or Puppet. The idea behind _immutable infrastructure_ is that once you
+deploy a server, you never change it again. If you need to roll out an update, you deploy a _new_ server with that
+update, and undeploy the old one. This paradigm is built for use with (a) the cloud, where you can easily spin up or
+tear down servers on-demand and (b) machine images, as every time there’s a change, you can use tools like Packer or
+Docker to build a new, immutable, versioned machine image (e.g., VM image or Docker image), and deploy new servers with
+that image.
+
+The advantages of immutable infrastructure are:
+
+#### Easier to reason about servers
+
+With mutable infrastructure, each server builds up a unique history of changes, so each one is a little different,
+which (a) makes it difficult to reason about what’s actually installed and (b) leads to tricky bugs that only show up
+on some servers, and not on others. With immutable infrastructure, you avoid these sorts of bugs, and you always know
+what’s installed on any server, as you know the exact image each server is running, and that the image never changes.
+
+#### You can run the same images in all environments
+
+Whereas it’s rare to run mutable infrastructure tools such as Ansible, Chef, or Puppet in your local dev environment,
+it’s common to run the same Docker or VM image in all environments, including your laptop, staging, and production.
+This helps to reduce "works on my machine" and environment-specific bugs, and makes it easier to debug those issues
+when they do happen.
+
+#### Easier scaling and rollback
+
+With immutable images, you can quickly and easily spin up 100 or 1,000 servers, with no need to worry about how long
+it’ll take to configure all those servers (e.g., via Ansible, Chef, or Puppet), as all the configuration has already
+happened and is captured in the VM or Docker image. Rollback is easier too, as you can quickly jump back to a
+previous image, without having to wait for and worry about running a bunch of older install commands (which may no
+longer work, e.g., if certain packages have been removed from APT or YUM).
+
+
+
diff --git a/docs/intro/core-concepts/infrastructure-as-code.md b/docs/intro/core-concepts/infrastructure-as-code.md
new file mode 100644
index 0000000000..4f9029d9a9
--- /dev/null
+++ b/docs/intro/core-concepts/infrastructure-as-code.md
@@ -0,0 +1,64 @@
+# Infrastructure as code
+
+Everything in the Gruntwork Infrastructure as Code Library is designed to allow you to define your _infrastructure as code (IaC)_.
+That is, instead of deploying infrastructure _manually_ (e.g., by clicking around a web page), the idea behind IaC is
+to write code to define, provision, and manage your infrastructure. This has a number of benefits:
+
+
+
+#### Self-service
+
+Most teams that deploy code manually have a small number of sysadmins (often, just one) who are the only ones who
+know all the magic incantations to make the deployment work and are the only ones with access to production. This
+becomes a major bottleneck as the company grows. If your infrastructure is defined in code, then the entire
+deployment process can be automated, and developers can kick off their own deployments whenever necessary.
+
+#### Speed and safety
+
+If the deployment process is automated, it’ll be significantly faster, since a computer can carry out the deployment
+steps far faster than a person; and safer, since an automated process will be more consistent, more repeatable, and
+not prone to manual error.
+
+#### Documentation
+
+Instead of the state of your infrastructure being locked away in a single sysadmin’s head, you can represent the
+state of your infrastructure in source files that anyone can read. In other words, IaC acts as documentation,
+allowing everyone in the organization to understand how things work, even if the sysadmin goes on vacation.
+
+#### Version control
+
+You can store your IaC source files in version control, which means the entire history of your infrastructure is now
+captured in the commit log. This becomes a powerful tool for debugging issues, as any time a problem pops up, your
+first step will be to check the commit log and find out what changed in your infrastructure, and your second step may
+be to resolve the problem by simply reverting back to a previous, known-good version of your IaC code.
+
+#### Validation
+
+If the state of your infrastructure is defined in code, then for every single change, you can perform a code review,
+run a suite of automated tests, and pass the code through static analysis tools, all practices that are known to
+significantly reduce the chance of defects.
+
+#### Happiness
+
+Deploying code and managing infrastructure manually is repetitive and tedious. Developers and sysadmins resent this
+type of work, as it involves no creativity, no challenge, and no recognition. You could deploy code perfectly for
+months, and no one will take notice—until that one day when you mess it up. That creates a stressful and unpleasant
+environment. IaC offers a better alternative that allows computers to do what they do best (automation) and
+developers to do what they do best (coding).
+
+#### Reuse
+
+You can package your infrastructure into reusable modules, so that instead of doing every deployment for every
+product in every environment from scratch, you can build on top of known, documented, battle-tested pieces. You
+can build these reusable modules yourself or use an existing collection of modules, such as the Gruntwork
+Infrastructure as Code Library.
+
+Some of the main IaC tools you’ll see used and referenced in the Gruntwork Infrastructure as Code Library are Terraform, Terragrunt,
+Packer, Docker, and Helm, each of which we’ll discuss in the next several sections.
+
+
+
+
+
diff --git a/docs/intro/environment-setup/recommended_tools.md b/docs/intro/environment-setup/recommended_tools.md
index 465e708d03..cbd5692134 100644
--- a/docs/intro/environment-setup/recommended_tools.md
+++ b/docs/intro/environment-setup/recommended_tools.md
@@ -86,5 +86,5 @@ docker run -it -v $(pwd):/work gruntwork /bin/bash
diff --git a/docs/intro/first-deployment/deploy.md b/docs/intro/first-deployment/deploy.md
new file mode 100644
index 0000000000..bd411271fe
--- /dev/null
+++ b/docs/intro/first-deployment/deploy.md
@@ -0,0 +1,265 @@
+# Deploy Your Module
+
+Now that your module has been thoroughly tested, you can deploy it to your real environments (e.g., staging and
+production). There are many ways to deploy Terraform modules, so in this guide, we’ll focus on using Terraform or Terragrunt.
+
+## Deploy using plain Terraform
+
+One option is to deploy all of your environments using plain-old-Terraform. The approach is nearly identical to the
+way you did manual testing; let’s walk through it for the staging environment.
+
+First, create a `staging/terraform.tfvars` file:
+
+ infrastructure-modules
+ └ networking
+ └ vpc-app
+ └ main.tf
+ └ outputs.tf
+ └ variables.tf
+ └ testing
+ └ terraform.tfvars
+ └ backend.hcl
+ └ staging
+ └ terraform.tfvars
+ └ test
+ └ vpc_app_test.go
+
+Inside the file, set the variables for this module to values appropriate for this environment:
+
+```hcl title=infrastructure-modules/networking/vpc-app/staging/terraform.tfvars
+aws_region = "us-east-2"
+aws_account_id = "888888888888"
+vpc_name = "staging-vpc"
+cidr_block = "10.10.0.0/16"
+num_nat_gateways = 1
+```
+
+Next, create a `staging/backend.hcl` file:
+
+ infrastructure-modules
+ └ networking
+ └ vpc-app
+ └ main.tf
+ └ outputs.tf
+ └ variables.tf
+ └ testing
+ └ terraform.tfvars
+ └ backend.hcl
+ └ staging
+ └ terraform.tfvars
+ └ backend.hcl
+ └ test
+ └ vpc_app_test.go
+
+Inside this file, configure the backend for staging:
+
+```hcl title=infrastructure-modules/networking/vpc-app/staging/backend.hcl
+bucket = ""
+key = "networking/vpc-app/terraform.tfstate"
+region = "us-east-2"
+encrypt = true
+dynamodb_table = ""
+```
+
+And now you can deploy to the staging environment as follows:
+
+```bash
+cd infrastructure-modules/networking/vpc-app/staging
+terraform init -backend-config=backend.hcl ../
+terraform apply ../
+```
+
+To deploy to other environments, create analogous `.tfvars` and `.hcl` files (e.g., `production/terraform.tfvars` and
+`production/backend.hcl`) and run `terraform init` and `terraform apply` with those files.
+
+**Benefits of this approach**
+
+- No external tooling required.
+- Analogous to how you run manual and automated tests.
+- Quick feedback cycle.
+- Completely free and open source.
+
+**Drawbacks to this approach**
+
+- You’re always deploying "latest" from a branch. No versioning or easy rollback.
+- Lots of command-line arguments to pass. Easy to make mistakes. Most teams end up creating hacky wrapper scripts.
+- Lots of backend configuration to copy for each module. Manually setting a unique `key` for each module is repetitive
+ and error prone.
+- From a quick glance at the code, it’s not clear what accounts, environments, or regions you deploy to. Figuring this
+ out requires digging through many folders.
+
+## Deploy using Terragrunt
+
+Another option is to use [Terragrunt](https://github.com/gruntwork-io/terragrunt), an open source wrapper for Terraform
+that helps alleviate some of the drawbacks mentioned in the previous approach.
+
+The first step with Terragrunt is to version your code. You can do this by creating Git tags in
+`infrastructure-modules`:
+
+```bash
+cd infrastructure-modules
+git tag -a "v0.0.1" -m "Created vpc-app module"
+git push --follow-tags
+```
+
+This will allow you to deploy different versions of your module in different environments (e.g., `v0.0.1` in prod and
+`v0.0.2` in stage) and rollback to previous versions if necessary. With Terragrunt, we recommend defining your live
+environments in a separate repo called `infrastructure-live` that uses a folder structure with the following format:
+
+ infrastructure-live
+ └
+ └ terragrunt.hcl
+ └ _global
+ └
+ └ _global
+ └
+ └
+ └ terragrunt.hcl
+
+Where:
+
+
+
+#### `
`
+
+A the top level, you have accounts (e.g., an AWS account).
+
+#### ``
+
+Within each account, there will be one or more regions (e.g., in AWS, `us-east-1`, `eu-west-1`, etc). There may also
+be a `_global` folder that defines resources that are available across all the regions in this account, such as
+IAM users and DNS settings. Each account also has a root `terragrunt.hcl` file that defines common Terraform settings
+that apply to the entire account, such as what backend to use to store Terraform state.
+
+#### ``
+
+Within each region, there will be one or more environments, such as dev, stage, prod, mgmt, etc. There may also be a
+`_global` folder that defines resources that are available across all the environments in this region.
+
+#### ``
+
+Within each environment, you use Terraform modules to deploy one or more resources, such as servers, databases load
+balancers, and so on. Each module is configured via a `terragrunt.hcl` file.
+
+
+
+#### Configure variables
+
+This is similar to the `testing/terraform.tfvars` used in manual testing.
+
+#### Configure the backend
+
+This is similar to the `testing-backend.hcl` used in manual testing.
+
+#### Namespace resources
+
+The code uses ‘random.UniqueId()\` to generate unique identifiers for all the resources in this test. This allows
+multiple tests to run in parallel (e.g., on your computer, your teammates’ computers, CI servers) without running
+into conflicts (e.g., without conflicts over resources that require unique names, such as VPCs).
+
+#### Defer `terraform destroy`
+
+The test code uses `defer` to schedule `terraform.Destroy` to run at the end of the test, whether or not the test
+passes.
+
+#### `terraform init` and `apply`
+
+The test runs `terraform init` and `terraform apply` on the module. If this hits any errors, the test will fail.
+
+
+This is a minimal test that just makes sure your module can deploy and undeploy successfully. This is a great start,
+and will catch a surprising number of bugs, but for production-grade code, you’ll probably want more validation logic.
+Check out the real [module-vpc tests](https://github.com/gruntwork-io/module-vpc/tree/master/test) to see how we validate
+VPCs by, for example, launching EC2 instances in various subnets and making sure that connections between some subnets
+work, and others are blocked, based on the networking settings in that VPC.
+
+To run the test, authenticate to your testing environment and do the following:
+
+```bash
+cd infrastructure-modules/test
+go test -v -timeout 45m
+```
+
+Note the use of the `-timeout 45m` argument with `go test`. By default, Go imposes a time limit of 10 minutes for
+tests, after which it forcibly kills the test run, causing the tests to not only fail, but even preventing the cleanup
+code (i.e., `terraform destroy`) from running. This VPC test should take closer to ten minutes, but whenever running a
+Go test that deploys real infrastructure, it’s safer to set an extra long timeout to avoid the test being killed part
+way through and leaving all sorts of infrastructure still running.
+
+For a lot more information on writing automated tests for Terraform code, see:
+
+1. [Terratest documentation](https://github.com/gruntwork-io/terratest/), especially the many examples and corresponding
+ tests in the `examples` and `test` folders, respectively, and the
+ [testing best practices](https://github.com/gruntwork-io/terratest/#testing-best-practices) section.
+2. _[Terraform: Up & Running](https://www.terraformupandrunning.com)_, 2nd edition, has an entire chapter dedicated to
+ automated testing for Terraform code, including unit tests, integration tests, end-to-end tests, dependency injection,
+ running tests in parallel, test stages, and more.
+
+
+
diff --git a/docs/intro/first-deployment/using-terraform-modules.md b/docs/intro/first-deployment/using-terraform-modules.md
new file mode 100644
index 0000000000..389ca0d990
--- /dev/null
+++ b/docs/intro/first-deployment/using-terraform-modules.md
@@ -0,0 +1,252 @@
+# Prepare Your Module
+
+This section will show you how to use Terraform modules from the Gruntwork Infrastructure as Code Library. As an illustrative example,
+we’ll deploy the `vpc-app` Terraform module from [terraform-aws-vpc](https://github.com/gruntwork-io/terraform-aws-vpc).
+
+:::caution
+
+You must be a Gruntwork subscriber to access `terraform-aws-vpc`.
+
+:::
+
+You can use this module to deploy a production-grade VPC on AWS. For full background information on VPCs, check
+out [How to deploy a production-grade VPC on AWS](/docs/guides/build-it-yourself/vpc/intro/what-youll-learn-in-this-guide).
+
+## Create a wrapper module
+
+The Terraform modules in the Gruntwork Infrastructure as Code Library are intentionally designed to be unopinionated, so they do not
+configure `provider` or `backend` settings. Moreover, you will often use multiple modules from the Infrastructure as Code Library,
+rather than just one at a time. Therefore, the canonical way to consume a Terraform module from the Gruntwork
+Infrastructure as Code Library is to create a _wrapper module_ in one of your own Git repos.
+
+Let’s assume you have a repo called `infrastructure-modules` and create a `vpc-app` wrapper module in it:
+
+ infrastructure-modules
+ └ networking
+ └ vpc-app
+ └ main.tf
+ └ outputs.tf
+ └ variables.tf
+
+## Configure your providers
+
+Inside of `main.tf`, configure whatever Terraform providers you’re using. Since the `vpc-app` module you’re using in
+this guide is an AWS module, you’ll need to configure the AWS provider:
+
+```hcl title=infrastructure-modules/networking/vpc-app/main.tf
+provider "aws" {
+ # The AWS region in which all resources will be created
+ region = var.aws_region
+
+ # Require a 2.x version of the AWS provider
+ version = "~> 2.6"
+
+ # Only these AWS Account IDs may be operated on by this template
+ allowed_account_ids = [var.aws_account_id]
+}
+```
+
+This configures the AWS provider as follows:
+
+
+
+#### Use a specific AWS region
+
+The AWS region is configured via the `aws_region` input variable (you’ll declare this shortly). This allows you to
+deploy this module in multiple regions.
+
+#### Pin the AWS provider version
+
+The code above ensures that you always get AWS provider version `2.x` and won’t accidentally get version `3.x` in the
+future, which would be backwards incompatible. We recommend pinning the versions for all providers you’re using.
+
+#### Pin AWS account IDs
+
+The code above will only allow you to run it against the AWS account with ID passed in via the `aws_account_id` input
+variable (you’ll declare this shortly). This is an extra safety measure to ensure you don’t accidentally authenticate
+to the wrong AWS account while deploying this code—e.g., so you don’t accidentally deploy changes intended for
+staging to production (for more info on working with multiple AWS accounts, see
+[How to Configure a Production Grade AWS Account Structure](/docs/guides/build-it-yourself/landing-zone/intro/what-youll-learn-in-this-guide)).
+
+
+
+Let’s add the corresponding input variables in `variables.tf`:
+
+```hcl title=infrastructure-modules/networking/vpc-app/variables.tf
+variable "aws_region" {
+ description = "The AWS region in which all resources will be created"
+ type = string
+}
+
+variable "aws_account_id" {
+ description = "The ID of the AWS Account in which to create resources."
+ type = string
+}
+```
+
+## Configure Terraform
+
+Next, configure Terraform itself in `main.tf`:
+
+```hcl title=infrastructure-modules/networking/vpc-app/main.tf
+terraform {
+ # Partial configuration for the backend: https://www.terraform.io/docs/backends/config.html#partial-configuration
+ backend "s3" {}
+
+ # Only allow this Terraform version. Note that if you upgrade to a newer version, Terraform won't allow you to use an
+ # older version, so when you upgrade, you should upgrade everyone on your team and your CI servers all at once.
+ required_version = "= 0.12.6"
+}
+```
+
+This configures Terraform as follows:
+
+
+
+#### Configure a backend
+
+The code above configures a _backend_, which is a shared location where Terraform state can be stored and accessed by
+your team. You can use any of the [supported backends](https://www.terraform.io/docs/backends/types/index.html) (the
+example above uses S3, which is a good choice for AWS users). See
+[How to manage Terraform state](https://blog.gruntwork.io/how-to-manage-terraform-state-28f5697e68fa) for more info.
+
+#### Partial configuration
+
+The backend uses a _[partial configuration](https://www.terraform.io/docs/backends/config.html#partial-configuration)_,
+which means most of the backend configuration (e.g., which S3 bucket and path to use) will be specified from outside
+of the code. You’ll see an example of this soon.
+
+#### Pin the Terraform version
+
+The code above will ONLY allow you to run it with a specific Terraform version. This is a safety measure to ensure
+you don’t accidentally pick up a new version of Terraform until you’re ready. This is important because (a) Terraform
+is a pre 1.0.0 tool, so even patch version number bumps (e.g., `0.12.6` → `0.12.7`) are sometimes backwards
+incompatible or buggy and (b) once you’ve upgraded to a newer version, Terraform will no longer allow you to deploy
+that code with any older version. For example, if a single person on your team upgrades to `0.12.7` and runs `apply`,
+then you’ll no longer be able to use the state file with `0.12.6`, and you’ll be forced to upgrade everyone on your
+team and all your CI servers to `0.12.7`. It’s best to do this explicitly, rather than accidentally, so we recommend
+pinning Terraform versions.
+
+
+
+## Use the modules from the Gruntwork Infrastructure as Code Library
+
+Now you can pull in the Terraform modules you want from the Gruntwork Infrastructure as Code Library as follows:
+
+```hcl title=infrastructure-modules/networking/vpc-app/main.tf
+module "vpc" {
+ # Make sure to replace in this URL with the latest terraform-aws-vpc release
+ source = "git@github.com:gruntwork-io/terraform-aws-vpc.git//modules/vpc-app?ref="
+
+ aws_region = var.aws_region
+ vpc_name = var.vpc_name
+ cidr_block = var.cidr_block
+ num_nat_gateways = var.num_nat_gateways
+}
+```
+
+This code does the following:
+
+
+
+#### Terraform module support
+
+This code pulls in a module using Terraform’s native `module` functionality. For background info, see
+[How to create reusable infrastructure with Terraform modules](https://blog.gruntwork.io/how-to-create-reusable-infrastructure-with-terraform-modules-25526d65f73d).
+
+#### SSH Git URL
+
+The `source` URL in the code above uses a Git URL with SSH authentication (see
+[module sources](https://www.terraform.io/docs/modules/sources.html) for all the types of `source` URLs you can use).
+If you have established your account and linked your GitHub ID according to the instruction in [Accessing the Dev Portal](/docs/intro/dev-portal/create-account), this will allow you to access private repos in the Gruntwork
+Infrastructure as Code Library without having to hard-code a password in your Terraform code.
+
+#### Versioned URL
+
+Note the `?ref=` at the end of the `source` URL. This parameter allows you to pull in a specific version of
+each module so that you don’t accidentally pull in (potentially backwards incompatible code) in the future. You
+should replace `` with the latest version from the releases page of the repo you’re using (e.g., here’s
+[the releases page for terraform-aws-vpc](https://github.com/gruntwork-io/terraform-aws-vpc/releases)).
+
+#### Module arguments
+
+Below the `source` URL, you’ll need to pass in the module-specific arguments. You can find all the required and
+optional variables defined in `vars.tf` (old name) or `variables.tf` (new name) of the module (e.g.,
+here’s [the variables.tf for vpc-app](https://github.com/gruntwork-io/terraform-aws-vpc/blob/master/modules/vpc-app/vars.tf)).
+The code above sets these to input variables (which you’ll define shortly) so that you can use different values in
+different environments.
+
+
+
+Let’s add the new input variables in `variables.tf`:
+
+```hcl title=infrastructure-modules/networking/vpc-app/variables.tf
+variable "vpc_name" {
+ description = "Name of the VPC. Examples include 'prod', 'dev', 'mgmt', etc."
+ type = string
+}
+
+variable "cidr_block" {
+ description = "The IP address range of the VPC in CIDR notation. A prefix of /16 is recommended. Do not use a prefix higher than /27. Example: '10.100.0.0/16'."
+ type = string
+}
+
+variable "num_nat_gateways" {
+ description = "The number of NAT Gateways to launch for this VPC. For production VPCs, multiple NAT Gateways are recommended."
+ type = number
+}
+```
+
+You may also want to add useful output variables in `outputs.tf`:
+
+```hcl title=infrastructure-modules/networking/vpc-app/outputs.tf
+output "vpc_name" {
+ description = "The VPC name"
+ value = module.vpc.vpc_name
+}
+
+output "vpc_id" {
+ description = "The VPC ID"
+ value = module.vpc.vpc_id
+}
+
+output "vpc_cidr_block" {
+ description = "The VPC CIDR block"
+ value = module.vpc.vpc_cidr_block
+}
+
+output "public_subnet_cidr_blocks" {
+ description = "The CIDR blocks of the public subnets"
+ value = module.vpc.public_subnet_cidr_blocks
+}
+
+output "private_app_subnet_cidr_blocks" {
+ description = "The CIDR blocks of the private app subnets"
+ value = module.vpc.private_app_subnet_cidr_blocks
+}
+
+output "private_persistence_subnet_cidr_blocks" {
+ description = "The CIDR blocks of the private persistence subnets"
+ value = module.vpc.private_persistence_subnet_cidr_blocks
+}
+
+output "public_subnet_ids" {
+ description = "The IDs of the public subnets"
+ value = module.vpc.public_subnet_ids
+}
+
+output "private_app_subnet_ids" {
+ description = "The IDs of the private app subnets"
+ value = module.vpc.private_app_subnet_ids
+}
+
+output "private_persistence_subnet_ids" {
+ description = "The IDs of the private persistence subnets"
+ value = module.vpc.private_persistence_subnet_ids
+}
+```
+
+
+
diff --git a/docs/intro/tool-fundamentals/packer.md b/docs/intro/tool-fundamentals/packer.md
index 3bb86d90d0..f043798a8e 100644
--- a/docs/intro/tool-fundamentals/packer.md
+++ b/docs/intro/tool-fundamentals/packer.md
@@ -5,22 +5,26 @@ images, Docker images) as code. For example, here is how you can use Packer to d
```json
{
- "builders": [{
- "type": "amazon-ebs",
- "region": "us-east-2",
- "source_ami": "ami-0c55b159cbfafe1f0",
- "instance_type": "t2.micro",
- "ssh_username": "ubuntu",
- "ami_name": "packer-example-{{timestamp}}"
- }],
- "provisioners": [{
- "type": "shell",
- "inline": [
- "curl -sL https://deb.nodesource.com/setup_10.x | sudo -E bash -",
- "sudo apt-get update -y",
- "sudo apt-get install -y nodejs"
- ]
- }]
+ "builders": [
+ {
+ "type": "amazon-ebs",
+ "region": "us-east-2",
+ "source_ami": "ami-0c55b159cbfafe1f0",
+ "instance_type": "t2.micro",
+ "ssh_username": "ubuntu",
+ "ami_name": "packer-example-{{timestamp}}"
+ }
+ ],
+ "provisioners": [
+ {
+ "type": "shell",
+ "inline": [
+ "curl -sL https://deb.nodesource.com/setup_10.x | sudo -E bash -",
+ "sudo apt-get update -y",
+ "sudo apt-get install -y nodejs"
+ ]
+ }
+ ]
}
```
@@ -35,11 +39,18 @@ includes an `ssh-grunt` binary you can run on each server to manage SSH access t
IAM users in specific IAM groups will be able to SSH to specific servers using their own usernames and SSH keys).
To get these scripts and binaries onto your virtual servers (e.g., onto EC2 instances in AWS), we recommend using Packer to build VM images that have these scripts and binaries installed. You'll see an
-example of how to do this in [How to use the Gruntwork Infrastructure as Code Library](https://gruntwork.io/guides/foundations/how-to-use-gruntwork-infrastructure-as-code-library/#how_to_use_the_catalog). Note that Gruntwork Infrastructure as Code Library does NOT require that
-you use Packer (e.g., you could also use Ansible or Chef to install the scripts and binaries), but the Gruntwork
-Reference Architecture does use Packer as one of its opinionated tools.
+example of how to do this in our [Deploy Your First Module](/docs/intro/first-deployment/using-terraform-modules) section.
+
+:::note
+
+The Gruntwork Infrastructure as Code Library does NOT require that you use
+Packer (e.g., you could also use Ansible or Chef to install the scripts and
+binaries), but the Gruntwork Reference Architecture does use Packer as one of
+its opinionated tools.
+
+:::
diff --git a/docs/intro/tool-fundamentals/terraform.md b/docs/intro/tool-fundamentals/terraform.md
index ad226dd0d2..18827e2317 100644
--- a/docs/intro/tool-fundamentals/terraform.md
+++ b/docs/intro/tool-fundamentals/terraform.md
@@ -25,7 +25,19 @@ thorough introduction to the language.
A large percentage of the infrastructure code in the Gruntwork Infrastructure as Code Library is defined using Terraform. We even
wrote [the book](https://www.terraformupandrunning.com) on it!
+## Terraform Cloud and Terraform Enterprise
+
+[Terraform Cloud](https://www.terraform.io/docs/cloud/index.html) and [Terraform Enterprise](https://www.terraform.io/docs/enterprise/index.html) are HashiCorp’s commercial Terraform products. They include many additional features for Terraform, including plan and apply workflows with approvals, role-based access control for teams, policy as code using Sentinel, and more.
+
+
+
+:::note We're compatible with TFC/TFE
+
+The Gruntwork module library and open source tools are compatible with Terraform Cloud and Terraform Enterprise.
+
+:::
+
diff --git a/sidebars.js b/sidebars.js
index e302b3be56..9ea28d2bb9 100644
--- a/sidebars.js
+++ b/sidebars.js
@@ -27,6 +27,12 @@ const sidebars = {
"intro/overview/getting-started",
],
},
+ {
+ "Core Concepts": [
+ "intro/core-concepts/infrastructure-as-code",
+ "intro/core-concepts/immutable-infrastructure",
+ ],
+ },
{
"Accessing the Dev Portal": [
"intro/dev-portal/create-account",
@@ -47,6 +53,13 @@ const sidebars = {
"intro/tool-fundamentals/terragrunt",
],
},
+ {
+ "Deploy Your First Module": [
+ "intro/first-deployment/using-terraform-modules",
+ "intro/first-deployment/testing",
+ "intro/first-deployment/deploy",
+ ],
+ },
{
type: "doc",
id: "intro/next-steps",
diff --git a/static/img/guides/stay-up-to-date/newsletter.png b/static/img/guides/stay-up-to-date/newsletter.png
new file mode 100644
index 0000000000..d80ed57aef
Binary files /dev/null and b/static/img/guides/stay-up-to-date/newsletter.png differ
diff --git a/static/img/intro/tool-fundamentals/tfc.png b/static/img/intro/tool-fundamentals/tfc.png
new file mode 100644
index 0000000000..2a3be6f420
Binary files /dev/null and b/static/img/intro/tool-fundamentals/tfc.png differ