Skip to content

Commit 9d7ca08

Browse files
MoonMoon1919MoonMoon1919
authored
Feat(CORE-976): add terragrunt and _envcommon update and version guides (#835)
* Feat: add terragrunt and _envcommon update and version guides
1 parent f795078 commit 9d7ca08

File tree

4 files changed

+372
-2
lines changed

4 files changed

+372
-2
lines changed

‎_docs-sources/iac/stay-up-to-date/updating.md‎

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,6 @@
1+
import Tabs from '@theme/Tabs';
2+
import TabItem from '@theme/TabItem';
3+
14
# Updating
25

36
Updating a module or service requires changing the tagged version in the `source` attribute of the module block. For backwards compatible changes, this is as simple as incrementing the version number. For backwards incompatible changes, refer to the release notes for a migration guide in each module's Github repository release page.
@@ -6,6 +9,9 @@ We recommend updating module versions in your development environment first, fol
69

710
## Example: Update a version
811

12+
<Tabs groupId="tool-choice">
13+
<TabItem value="Terraform" label="Terraform" default>
14+
915
Below is a module block referencing version `0.15.3` of the `single-server` submodule from the `terraform-aws-server` module.
1016

1117
To update to version `0.15.4`, you update the value to the right of `ref=` in the source attribute. Since the version number denotes that this update is backwards compatible, it should not require any other changes.
@@ -29,6 +35,97 @@ module "my_instance" {
2935
```
3036

3137
After making the change, run `terraform plan`, inspect the output to ensure it looks as you expect, then run `terraform apply`.
38+
</TabItem>
39+
<TabItem value="Terragrunt" label="Terragrunt">
40+
41+
Below is a module block referencing version `0.15.3` of the `single-server` submodule from the `terraform-aws-server` module.
42+
43+
To update to version `0.15.4`, you update the value to the right of `ref=` in the source attribute. Since the version number denotes that this update is backwards compatible, it should not require any other changes.
44+
45+
```hcl
46+
terraform {
47+
# Old
48+
# source = "github.com:gruntwork-io/terraform-aws-server.git//modules/single-server?ref=v0.15.3"
49+
# New
50+
source = "git::[email protected]:gruntwork-io/terraform-aws-server.git//modules/single-server?ref=v0.15.4"
51+
}
52+
53+
generate "provider" {
54+
path = "provider.tf"
55+
if_exists = "overwrite_terragrunt"
56+
contents = <<EOF
57+
provider "aws" {
58+
region = "us-west-2"
59+
}
60+
EOF
61+
}
62+
63+
inputs = {
64+
name = "my_instance"
65+
ami = "ami-99999999999999999"
66+
instance_type = "t2.medium"
67+
keypair_name = ""
68+
vpc_id = "vpc-1234567890123456"
69+
subnet_id = "subnet-23456789012345678"
70+
attach_eip = false
71+
}
72+
```
73+
74+
After making the change, run `terragrunt plan`, inspect the output to ensure it looks as you expect, then run `terragrunt apply`.
75+
76+
</TabItem>
77+
<TabItem value="Terragrunt with _envcommon" label="_envcommon (Terragrunt)">
78+
79+
When following the `_envcommon` pattern, there are two places that reference the git tag created by the release — the `.hcl` file with the reference to the module in the `_envcommon` directory and the environment and region specific references to the _envcommon file.
80+
81+
Below is an example using the `_envcommon` pattern to reference version `0.15.3` of the `single-server` submodule from the `terraform-aws-server` module. To update to version `0.15.4`, you update the value to the right of `ref=` in the source attribute. Since the version number denotes that this update is backwards compatible, it should not require any other changes.
82+
83+
```hcl title=_envcommon/services/single_ec2_instance.hcl
84+
terraform {
85+
# Old
86+
# source = "${local.source_base_url}?ref=v0.15.3"
87+
# New
88+
source = "${local.source_base_url}?ref=v0.15.4"
89+
}
90+
91+
locals {
92+
source_base_url = "git::[email protected]:gruntwork-io/terraform-aws-server.git//modules/single-server"
93+
}
94+
```
95+
96+
```hcl title=/<your-environment>/<your-region>/services/single_ec2_instance/terragrunt.hcl
97+
terraform {
98+
# Old
99+
# source = "${include.envcommon.locals.source_base_url}?ref=v0.15.3"
100+
# New
101+
source = "${include.envcommon.locals.source_base_url}?ref=v0.15.4"
102+
}
103+
104+
include "root" {
105+
path = find_in_parent_folders()
106+
}
107+
108+
include "envcommon" {
109+
path = "${dirname(find_in_parent_folders())}/_envcommon/services/single_ec2_instance.hcl"
110+
merge_strategy = "deep"
111+
expose = true
112+
}
113+
114+
inputs = {
115+
name = "my_instance"
116+
ami = "ami-99999999999999999"
117+
instance_type = "t2.medium"
118+
keypair_name = ""
119+
vpc_id = "vpc-1234567890123456"
120+
subnet_id = "subnet-23456789012345678"
121+
attach_eip = false
122+
}
123+
```
124+
125+
After making the change, run `terragrunt plan`, inspect the output to ensure it looks as you expect, then run `terragrunt apply`.
126+
127+
</TabItem>
128+
</Tabs>
32129

33130
## Patcher
34131

‎_docs-sources/iac/stay-up-to-date/versioning.md‎

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,6 @@
1+
import Tabs from '@theme/Tabs';
2+
import TabItem from '@theme/TabItem';
3+
14
# Versioning
25

36
Gruntwork versions the IaC library using [Semantic Versioning](https://semver.org/) (SemVer). Since much of the Gruntwork IaC Library is still pre-1.0.0, most of the Gruntwork IaC Library uses 0.MINOR.PATCH version numbers. With 0.MINOR.PATCH, the rules are a bit different, where we increment the:
@@ -13,6 +16,9 @@ We release new module versions using GitHub releases, refer to the release notes
1316

1417
## Example: Reference a version
1518

19+
<Tabs groupId="tool-choice">
20+
<TabItem value="Terraform" label="Terraform" default>
21+
1622
The git tag created by the release can then be referenced in the source argument for a module block sourcing from a git URL.
1723

1824
For example, below is a module block referencing version `0.15.4` of the `single-server` submodule from the `terraform-aws-server` module.
@@ -31,6 +37,88 @@ module "my_instance" {
3137
}
3238
```
3339

40+
</TabItem>
41+
<TabItem value="Terragrunt" label="Terragrunt">
42+
43+
The git tag created by the release can then be referenced in the `source` argument for the `terraform` block in a `terragrunt.hcl` file.
44+
45+
For example, below is a module block referencing version `0.15.4` of the `single-server` submodule from the `terraform-aws-server` module.
46+
47+
```hcl
48+
terraform {
49+
source = "git::[email protected]:gruntwork-io/terraform-aws-server.git//modules/single-server?ref=v0.15.4"
50+
}
51+
52+
generate "provider" {
53+
path = "provider.tf"
54+
if_exists = "overwrite_terragrunt"
55+
contents = <<EOF
56+
provider "aws" {
57+
region = "us-west-2"
58+
}
59+
EOF
60+
}
61+
62+
inputs = {
63+
name = "my_instance"
64+
ami = "ami-99999999999999999"
65+
instance_type = "t2.medium"
66+
keypair_name = ""
67+
vpc_id = "vpc-1234567890123456"
68+
subnet_id = "subnet-23456789012345678"
69+
attach_eip = false
70+
}
71+
```
72+
73+
</TabItem>
74+
<TabItem value="Terragrunt with _envcommon" label="_envcommon (Terragrunt)">
75+
76+
When following the `_envcommon` pattern, there are two places that reference the git tag created by the release.
77+
78+
First, locate the file in which you are referencing the module in your `_envcommon` directory. Then, reference the git tag in the `source` argument for the `terraform` block in the file.
79+
80+
For example, if you were referencing the `single-server` module, your file path might look like the following:
81+
```hcl title=_envcommon/services/single_ec2_instance.hcl
82+
terraform {
83+
source = "${local.source_base_url}?ref=v0.15.4"
84+
}
85+
86+
locals {
87+
source_base_url = "git::[email protected]:gruntwork-io/terraform-aws-server.git//modules/single-server"
88+
}
89+
```
90+
91+
Then, reference the git tag in the `source` argument for the `terraform` block in the `terragrunt.hcl` environment and region specific files that reference the file in the `_envcommon` directory. For example, if you were using this module to create a single EC2 instance in your development environment in the us-west-2 region of AWS, your file path would be `/dev/us-west-2/services/single_ec2_instance/terragrunt.hcl`.
92+
93+
```hcl title=/dev/us-west-2/services/single_ec2_instance/terragrunt.hcl
94+
terraform {
95+
source = "${include.envcommon.locals.source_base_url}?ref=v0.15.4"
96+
}
97+
98+
include "root" {
99+
path = find_in_parent_folders()
100+
}
101+
102+
include "envcommon" {
103+
path = "${dirname(find_in_parent_folders())}/_envcommon/services/single_ec2_instance.hcl"
104+
merge_strategy = "deep"
105+
expose = true
106+
}
107+
108+
inputs = {
109+
name = "my_instance"
110+
ami = "ami-99999999999999999"
111+
instance_type = "t2.medium"
112+
keypair_name = ""
113+
vpc_id = "vpc-1234567890123456"
114+
subnet_id = "subnet-23456789012345678"
115+
attach_eip = false
116+
}
117+
```
118+
119+
</TabItem>
120+
</Tabs>
121+
34122
## What’s next
35123

36124
Once you start using versioned modules, it’s important to keep the modules up to date. Refer to the [Updating](./updating.md) guide to learn more.

‎docs/iac/stay-up-to-date/updating.md‎

Lines changed: 98 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,6 @@
1+
import Tabs from '@theme/Tabs';
2+
import TabItem from '@theme/TabItem';
3+
14
# Updating
25

36
Updating a module or service requires changing the tagged version in the `source` attribute of the module block. For backwards compatible changes, this is as simple as incrementing the version number. For backwards incompatible changes, refer to the release notes for a migration guide in each module's Github repository release page.
@@ -6,6 +9,9 @@ We recommend updating module versions in your development environment first, fol
69

710
## Example: Update a version
811

12+
<Tabs groupId="tool-choice">
13+
<TabItem value="Terraform" label="Terraform" default>
14+
915
Below is a module block referencing version `0.15.3` of the `single-server` submodule from the `terraform-aws-server` module.
1016

1117
To update to version `0.15.4`, you update the value to the right of `ref=` in the source attribute. Since the version number denotes that this update is backwards compatible, it should not require any other changes.
@@ -29,6 +35,97 @@ module "my_instance" {
2935
```
3036

3137
After making the change, run `terraform plan`, inspect the output to ensure it looks as you expect, then run `terraform apply`.
38+
</TabItem>
39+
<TabItem value="Terragrunt" label="Terragrunt">
40+
41+
Below is a module block referencing version `0.15.3` of the `single-server` submodule from the `terraform-aws-server` module.
42+
43+
To update to version `0.15.4`, you update the value to the right of `ref=` in the source attribute. Since the version number denotes that this update is backwards compatible, it should not require any other changes.
44+
45+
```hcl
46+
terraform {
47+
# Old
48+
# source = "github.com:gruntwork-io/terraform-aws-server.git//modules/single-server?ref=v0.15.3"
49+
# New
50+
source = "git::[email protected]:gruntwork-io/terraform-aws-server.git//modules/single-server?ref=v0.15.4"
51+
}
52+
53+
generate "provider" {
54+
path = "provider.tf"
55+
if_exists = "overwrite_terragrunt"
56+
contents = <<EOF
57+
provider "aws" {
58+
region = "us-west-2"
59+
}
60+
EOF
61+
}
62+
63+
inputs = {
64+
name = "my_instance"
65+
ami = "ami-99999999999999999"
66+
instance_type = "t2.medium"
67+
keypair_name = ""
68+
vpc_id = "vpc-1234567890123456"
69+
subnet_id = "subnet-23456789012345678"
70+
attach_eip = false
71+
}
72+
```
73+
74+
After making the change, run `terragrunt plan`, inspect the output to ensure it looks as you expect, then run `terragrunt apply`.
75+
76+
</TabItem>
77+
<TabItem value="Terragrunt with _envcommon" label="_envcommon (Terragrunt)">
78+
79+
When following the `_envcommon` pattern, there are two places that reference the git tag created by the release — the `.hcl` file with the reference to the module in the `_envcommon` directory and the environment and region specific references to the _envcommon file.
80+
81+
Below is an example using the `_envcommon` pattern to reference version `0.15.3` of the `single-server` submodule from the `terraform-aws-server` module. To update to version `0.15.4`, you update the value to the right of `ref=` in the source attribute. Since the version number denotes that this update is backwards compatible, it should not require any other changes.
82+
83+
```hcl title=_envcommon/services/single_ec2_instance.hcl
84+
terraform {
85+
# Old
86+
# source = "${local.source_base_url}?ref=v0.15.3"
87+
# New
88+
source = "${local.source_base_url}?ref=v0.15.4"
89+
}
90+
91+
locals {
92+
source_base_url = "git::[email protected]:gruntwork-io/terraform-aws-server.git//modules/single-server"
93+
}
94+
```
95+
96+
```hcl title=/<your-environment>/<your-region>/services/single_ec2_instance/terragrunt.hcl
97+
terraform {
98+
# Old
99+
# source = "${include.envcommon.locals.source_base_url}?ref=v0.15.3"
100+
# New
101+
source = "${include.envcommon.locals.source_base_url}?ref=v0.15.4"
102+
}
103+
104+
include "root" {
105+
path = find_in_parent_folders()
106+
}
107+
108+
include "envcommon" {
109+
path = "${dirname(find_in_parent_folders())}/_envcommon/services/single_ec2_instance.hcl"
110+
merge_strategy = "deep"
111+
expose = true
112+
}
113+
114+
inputs = {
115+
name = "my_instance"
116+
ami = "ami-99999999999999999"
117+
instance_type = "t2.medium"
118+
keypair_name = ""
119+
vpc_id = "vpc-1234567890123456"
120+
subnet_id = "subnet-23456789012345678"
121+
attach_eip = false
122+
}
123+
```
124+
125+
After making the change, run `terragrunt plan`, inspect the output to ensure it looks as you expect, then run `terragrunt apply`.
126+
127+
</TabItem>
128+
</Tabs>
32129

33130
## Patcher
34131

@@ -39,6 +136,6 @@ Keeping track of all references to modules and services is a complicated, error
39136
<!-- ##DOCS-SOURCER-START
40137
{
41138
"sourcePlugin": "local-copier",
42-
"hash": "78b5c5aa8004b13951f8590f8f5b0029"
139+
"hash": "a0fa04509b1ed2127041b7aa4ef9dbeb"
43140
}
44141
##DOCS-SOURCER-END -->

0 commit comments

Comments
 (0)