You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
9
+
10
10
11
11
### Pinned Versions
12
12
13
-
When you use the code from the Gruntwork Infrastructure as Code Library, you pin
14
-
yourself to a specific version of the code. That way, you are not accidentally affected by any subsequent changes in
15
-
the Gruntwork Infrastructure as Code Library until you explicitly choose to pull those changes in. And when you do want to pull the
16
-
changes in, it’s just a matter of bumping the version number!
13
+
When you use the code from the Gruntwork IaC Library, you pin yourself to a specific version of the code. That way
14
+
you are not accidentally affected by any subsequent changes in the Gruntwork IaC Library until you explicitly choose to
15
+
pull those changes in. When you do want to pull the changes in, be sure to read through the release notes for any
16
+
migration steps you need to take and then bump the version number accordingly.
17
17
18
18
### Semantic Versioning
19
19
20
20
We use version numbers of the form `MAJOR.MINOR.PATCH` (e.g., `1.2.3`), following the principles of
21
21
_[semantic versioning](https://semver.org)_. In traditional semantic versioning, you increment the:
22
22
23
-
1. MAJOR version when you make incompatible API changes,
24
-
2. MINOR version when you add functionality in a backwards compatible manner, and
25
-
3. PATCH version when you make backwards compatible bug fixes.
23
+
1. MAJOR version when you make backward incompatible API changes,
24
+
2. MINOR version when you add functionality in a backward compatible manner, and
25
+
3. PATCH version when you make backward compatible bug fixes.
26
26
27
-
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:
27
+
However, much of the Gruntwork IaC Library is still pre-`1.0.0`. Most of the Gruntwork IaC Library uses
28
+
`0.MINOR.PATCH` version numbers. With `0.MINOR.PATCH`, the rules are a bit different, where you increment the:
28
29
29
-
1. MINOR version when you make incompatible API changes
30
-
2. PATCH version when you add backwards compatible functionality or bug fixes.
30
+
1. MINOR version when you make backward incompatible API changes, and
31
+
2. PATCH version when you add backward compatible functionality or bug fixes.
32
+
33
+
### What changes are backward incompatible?
34
+
35
+
In the world of DevOps, we've inherited our view of toil, and that continues to describe what DevOps engineers expect
36
+
as part of their daily grunt work. However with IaC, we can liberate ourselves from that thinking and automate more of
37
+
the toil than before, and as automation and infrastructure APIs improve, we can expect much more of DevOps grunt work
38
+
to become automated. What we think of as necessary toil is constantly evolving, so how we define our releases (i.e.,
39
+
backward compatible or not) is also subject to this evolution.
40
+
41
+
We (Gruntwork) currently consider the following types of updates backward incompatible:
42
+
43
+
1. Any update that requires some toil by the user. This is a moving target. At the moment, actions like bumping a
44
+
version number are not considered toil, but actions like running migration steps that modify Terraform state are
45
+
considered toil. In the near future, bumping a version number could be toil, and we are working to remove the need
46
+
for users to do that.
47
+
48
+
2. Any update that requires configuration changes by the user. When we release a new MINOR version in pre-`1.0.0`, we
49
+
include a migration guide with explicit steps you can take to resolve the backward incompatibilities, such that the
50
+
update becomes backward compatible for you.
51
+
52
+
3. Any update that incurs downtime for you. This includes changes that require recreating a resource that may be in
53
+
use. Even if the update attempts to first create the new resource and then destroy the existing resource, the order of
54
+
apply may not be guaranteed, and there could still be downtime during the hand-off.
55
+
56
+
4. Most updates that destroy resources. There are some cases where destroying resources is necessary and will not incur
57
+
downtime, such as `null_resource`s that only exist as a stop-gap for something missing in the AWS API or the Terraform
58
+
AWS provider API.
59
+
60
+
We try to err on the side of caution. Sometimes we release an update as MINOR even if it is functionally backward
61
+
compatible. For example, the [AWS Provider v4 update](/guides/stay-up-to-date/terraform/how-to-update-to-aws-provider-v4)
62
+
requires no configuration changes in Gruntwork module usage. It requires unlocking the provider version maintained in
63
+
the `terraform.lock.hcl` file, which makes it somewhat backward incompatible. Additionally it may still require you to
64
+
update any infrastructure code which does not use Gruntwork modules. Because this upgrade requires some vigilance, we
65
+
released it as a MINOR version increase to signal importance.
66
+
67
+
We're working to provide automatic resolution with patches, i.e., scripts that you can run when bumping your versions,
68
+
so that `terraform plan` and `terraform apply` result in clean updates. These releases would still be considered
69
+
backward incompatible because they require running a patch, could cause downtime, or could change resources
70
+
significantly.
31
71
32
72
## Updating to new versions
33
73
74
+
:::caution
75
+
76
+
In general, update one MINOR at a time, paying close attention to the release notes for migration steps. A MINOR
77
+
version number increase (e.g., `v0.18.0` → `v0.19.0`) signals a backward incompatible change, and the release
78
+
notes will contain a migration guide explaining what you need to do (e.g., update the configuration by adding,
79
+
removing, or changing variables you pass to the module).
80
+
81
+
:::
82
+
34
83
Follow the steps below to keep your code up to date:
35
84
36
-
1. Make sure you're following our monthly [Gruntwork Newsletter](https://blog.gruntwork.io/tagged/gruntwork-newsletter) to be notified
37
-
of all updates to the Gruntwork Infrastructure as Code Library. Alternatively, you can "watch" repos in GitHub that you’re
38
-
interested in.
85
+
1. Make sure you're following our [Gruntwork Newsletter](https://blog.gruntwork.io/tagged/gruntwork-newsletter)
86
+
to be notified of all updates to the Gruntwork IaC Library. Alternatively, you can watch repos in GitHub that
87
+
you’re interested in. If you use the Reference Architecture, you could watch the Service Catalog repos.
39
88
40
-
2. When you find an update you’d like for a specific module, update any code using that module in
41
-
`infrastructure-modules` to the new version number. For example, if you were using `terraform-aws-vpc` at `v0.18.5` and you
42
-
wanted to update to `v0.7.3`, you would change from:
89
+
2. When you find an update you’d like for a specific module, update module sources referencing that module in your
90
+
Terraform code to the new version number. For example, if you were using `terraform-aws-vpc` at `v0.18.5` and you
91
+
wanted to update to `v0.18.6`, you would change from:
43
92
44
93
```hcl
45
94
module "vpc" {
@@ -57,11 +106,12 @@ Follow the steps below to keep your code up to date:
57
106
}
58
107
```
59
108
60
-
3. Pay close attention to the release notes for any additional instructions. In particular, if the MINOR version number
61
-
was increased (e.g., `v0.18.0` → `v0.19.0`), that implies a backwards incompatible change, and the release notes will
62
-
explain what you need to do (e.g., you might have to add, remove, or change arguments you pass to the module).
109
+
One way you can do this quickly is by stringing together commands using `ripgrep`, `xargs`, and `sed`, or any other
110
+
method that allows find-and-replace operations within a directory.
63
111
64
-
4. Test your changes locally. You do this using the same process outlined in [Manual tests for Terraform code](/intro/first-deployment/testing#manual-tests-for-terraform-code) and
112
+
3. Optionally, test your changes locally. Use the same process outlined in
113
+
[Manual tests for Terraform code](/intro/first-deployment/testing#manual-tests-for-terraform-code) and
65
114
[Automated tests for Terraform code](/intro/first-deployment/testing#automated-tests-for-terraform-code).
66
115
67
-
5. Deploy your changes to each environment. You do this using the same process outlined in [Deploying Terraform code](#deploy_terraform).
116
+
4. Deploy your changes to each environment. Use `terraform plan` to sanity-check the changes before `terraform apply`.
117
+
Use the same process outlined in [Deploying Terraform code](#deploy_terraform).
![docs-sourcer[bot]](https://avatars.githubusercontent.com/u/17118990?v=4&size=40){kind=avatar}
0 commit comments