From ec1c8dfc90e4afa232fe7588014d3fda657ae070 Mon Sep 17 00:00:00 2001 From: Josh Padnick Date: Fri, 5 Sep 2025 13:00:29 -0700 Subject: [PATCH 1/9] Add a Library principle for supporting smooth OpenTofu adoption. --- .../concepts/principles/opentofu-adoption.md | 48 +++++++++++++++++++ sidebars/docs.js | 5 ++ 2 files changed, 53 insertions(+) create mode 100644 docs/2.0/docs/library/concepts/principles/opentofu-adoption.md diff --git a/docs/2.0/docs/library/concepts/principles/opentofu-adoption.md b/docs/2.0/docs/library/concepts/principles/opentofu-adoption.md new file mode 100644 index 0000000000..0a3928d06d --- /dev/null +++ b/docs/2.0/docs/library/concepts/principles/opentofu-adoption.md @@ -0,0 +1,48 @@ +# Support Smooth OpenTofu Adoption + +Gruntwork is a co-founder and active maintainer of [OpenTofu](https://opentofu.org/), the open source successor to HashiCorp Terraform. We proudly support OpenTofu because we believe that core infrastructure is too critical to run on anything but proven open source technology. In line with this philosophy, Gruntwork IaC Library aims to provide first-class OpenTofu support. + + But in the real world, platform engineers face endless module and tooling upgrades, [yak shaves](https://softwareengineering.stackexchange.com/a/388236) and competiting priorities. This means we must balance our desire to embrace the latest OpenTofu functionality with our separate principle of [being judicious with new features](be-judicious-with-new-features.md). + +## Core principle + +Given our need to balance embracing the latest OpenTofu functionality while keeping real-world maintenance as easy as possible, we must make it easy for customers to transition from Terraform to OpenTofu without requiring them to learn new syntax or extensively modify their existing configurations. + +## Implementation + +### High-level approach + +1. We support modern OpenTofu versions in our modules. +2. However, we strongly prefer language features that work identically in both OpenTofu and Terraform. +4. We avoid OpenTofu-specific syntax unless there is a compelling reason and clear customer benefit. + +### OpenTofu/Terraform version support + +- **OpenTofu**: We support OpenTofu 1.9 for new features that provide significant customer value. +- **Terraform**: We maintain compatibility with Terraform versions that support the same language features we use, but do not explicitly test or support Terraform versions beyond 1.5.7 + +When we upgrade a module to require a newer version of OpenTofu, we explicitly require that version in the `terraform` block of the module, publish a major module version release in the related git repo, and include clear migration guidance, if applicable. + +### OpenTofu feature adoption + +When evaluating new OpenTofu language features for use in Gruntwork modules: + +1. **Dual-compatible features (Preferred)**: Features that work identically in both OpenTofu and Terraform should be placed in `.tf` files. (e.g. see [cross-variable validation](#cross-variable-validation) below.) +2. **OpenTofu-specific Features (Discouraged)**: Features that only work in OpenTofu should be placed in `.tofu` files and used sparingly. This way, Terraform users will ignore these files, while OpenTofu users will automatically use them instead of the corresponding `.tf` files. But doing this means extra mintenance, so we will use this approach sparingly, if at all. +3. **Terraform-specific Features**: We do not support Terraform-specific features. + +## Current feature adoption + +### Cross-variable validation + +We now support cross-variable validation (the ability to reference the values of other variables in `variable` validation blocks) because: +- It significantly improves module usability by preventing invalid input combinations +- It works identically in both OpenTofu 1.9+ and Terraform 1.9+ +- It addresses direct customer feedback about configuration errors + +## Future evolution + +Theis principle will evolve as the Terraform and OpenTofu ecosystems develop. We will: +- Regularly review compatibility requirements based on customer needs +- Update our supported feature list as new stable releases become available +- Maintain clear communication about any changes to our compatibility strategy \ No newline at end of file diff --git a/sidebars/docs.js b/sidebars/docs.js index 5831b4a4cd..5e67bab558 100644 --- a/sidebars/docs.js +++ b/sidebars/docs.js @@ -657,6 +657,11 @@ const sidebar = [ type: "doc", id: "2.0/docs/library/concepts/principles/quality-in-depth", }, + { + label: "Support SmoothOpenTofu Adoption", + type: "doc", + id: "2.0/docs/library/concepts/principles/opentofu-adoption", + }, ], }, ], From 62336c1ba13f1395843f23b6f0e688546ea9c959 Mon Sep 17 00:00:00 2001 From: Josh Padnick Date: Fri, 5 Sep 2025 13:57:10 -0700 Subject: [PATCH 2/9] Apply coderabbit changes. What can I say, the AI had good feedback! --- .../concepts/principles/opentofu-adoption.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/2.0/docs/library/concepts/principles/opentofu-adoption.md b/docs/2.0/docs/library/concepts/principles/opentofu-adoption.md index 0a3928d06d..f44485a570 100644 --- a/docs/2.0/docs/library/concepts/principles/opentofu-adoption.md +++ b/docs/2.0/docs/library/concepts/principles/opentofu-adoption.md @@ -2,7 +2,7 @@ Gruntwork is a co-founder and active maintainer of [OpenTofu](https://opentofu.org/), the open source successor to HashiCorp Terraform. We proudly support OpenTofu because we believe that core infrastructure is too critical to run on anything but proven open source technology. In line with this philosophy, Gruntwork IaC Library aims to provide first-class OpenTofu support. - But in the real world, platform engineers face endless module and tooling upgrades, [yak shaves](https://softwareengineering.stackexchange.com/a/388236) and competiting priorities. This means we must balance our desire to embrace the latest OpenTofu functionality with our separate principle of [being judicious with new features](be-judicious-with-new-features.md). + But in the real world, platform engineers face endless module and tooling upgrades, [yak shaves](https://softwareengineering.stackexchange.com/a/388236) and competing priorities. This means we must balance our desire to embrace the latest OpenTofu functionality with our separate principle of [being judicious with new features](be-judicious-with-new-features.md). ## Core principle @@ -13,8 +13,8 @@ Given our need to balance embracing the latest OpenTofu functionality while keep ### High-level approach 1. We support modern OpenTofu versions in our modules. -2. However, we strongly prefer language features that work identically in both OpenTofu and Terraform. -4. We avoid OpenTofu-specific syntax unless there is a compelling reason and clear customer benefit. +1. However, we strongly prefer language features that work identically in both OpenTofu and Terraform. +1. We avoid OpenTofu-specific syntax unless there is a compelling reason and clear customer benefit. ### OpenTofu/Terraform version support @@ -28,7 +28,7 @@ When we upgrade a module to require a newer version of OpenTofu, we explicitly r When evaluating new OpenTofu language features for use in Gruntwork modules: 1. **Dual-compatible features (Preferred)**: Features that work identically in both OpenTofu and Terraform should be placed in `.tf` files. (e.g. see [cross-variable validation](#cross-variable-validation) below.) -2. **OpenTofu-specific Features (Discouraged)**: Features that only work in OpenTofu should be placed in `.tofu` files and used sparingly. This way, Terraform users will ignore these files, while OpenTofu users will automatically use them instead of the corresponding `.tf` files. But doing this means extra mintenance, so we will use this approach sparingly, if at all. +2. **OpenTofu-specific Features (Discouraged)**: Features that only work in OpenTofu should be placed in `.tofu` files and used sparingly. Terraform ignores `.tofu` files, while OpenTofu reads both `.tf` and `.tofu`. Avoid duplicating the same blocks across both extensions; prefer additive enhancements in `.tofu`. This approach increases maintenance cost, so we will use it only when the user benefit is clear. 3. **Terraform-specific Features**: We do not support Terraform-specific features. ## Current feature adoption @@ -42,7 +42,7 @@ We now support cross-variable validation (the ability to reference the values of ## Future evolution -Theis principle will evolve as the Terraform and OpenTofu ecosystems develop. We will: -- Regularly review compatibility requirements based on customer needs -- Update our supported feature list as new stable releases become available -- Maintain clear communication about any changes to our compatibility strategy \ No newline at end of file +-This principle will evolve as the Terraform and OpenTofu ecosystems develop. We will: +-- Regularly review compatibility and our support policy based on customer needs +-- Update our supported feature list as new stable releases become available +-- Clearly communicate any changes to our compatibility strategy \ No newline at end of file From 70522cbd7cf980bf26927e0ad806ea230317d179 Mon Sep 17 00:00:00 2001 From: Josh Padnick Date: Tue, 9 Sep 2025 09:38:13 -0700 Subject: [PATCH 3/9] Tighten up the ideas and language. --- .../concepts/principles/opentofu-adoption.md | 27 +++++++++---------- 1 file changed, 12 insertions(+), 15 deletions(-) diff --git a/docs/2.0/docs/library/concepts/principles/opentofu-adoption.md b/docs/2.0/docs/library/concepts/principles/opentofu-adoption.md index f44485a570..05cba18048 100644 --- a/docs/2.0/docs/library/concepts/principles/opentofu-adoption.md +++ b/docs/2.0/docs/library/concepts/principles/opentofu-adoption.md @@ -1,27 +1,24 @@ -# Support Smooth OpenTofu Adoption +# Prefer OpenTofu; Minimize Friction -Gruntwork is a co-founder and active maintainer of [OpenTofu](https://opentofu.org/), the open source successor to HashiCorp Terraform. We proudly support OpenTofu because we believe that core infrastructure is too critical to run on anything but proven open source technology. In line with this philosophy, Gruntwork IaC Library aims to provide first-class OpenTofu support. +Gruntwork is a co-founder and active maintainer of [OpenTofu](https://opentofu.org/), the open source successor to HashiCorp Terraform. We proudly support OpenTofu because we believe that core infrastructure should run on proven open source technology. In line with this philosophy, Gruntwork IaC Library aims to provide first-class OpenTofu support. - But in the real world, platform engineers face endless module and tooling upgrades, [yak shaves](https://softwareengineering.stackexchange.com/a/388236) and competing priorities. This means we must balance our desire to embrace the latest OpenTofu functionality with our separate principle of [being judicious with new features](be-judicious-with-new-features.md). +But we also know that platform teams may be on very early versions of Terraform (pre-1.0) or still on Terraform 1.5.7, and that upgrading to the latest OpenTofu is yet another item on their plate of competing priorities. This means we must balance the benefits of embracing the latest OpenTofu functionality with the real-world costs of migration. ## Core principle -Given our need to balance embracing the latest OpenTofu functionality while keeping real-world maintenance as easy as possible, we must make it easy for customers to transition from Terraform to OpenTofu without requiring them to learn new syntax or extensively modify their existing configurations. +We prefer OpenTofu over Terraform but design our modules to work seamlessly with both, ensuring customers can adopt OpenTofu without syntax changes or configuration rewrites. ## Implementation -### High-level approach +### Approach -1. We support modern OpenTofu versions in our modules. -1. However, we strongly prefer language features that work identically in both OpenTofu and Terraform. -1. We avoid OpenTofu-specific syntax unless there is a compelling reason and clear customer benefit. +1. We design our modules to work with both OpenTofu and Terraform, prioritizing features that work identically in both tools. +2. When we do adopt OpenTofu-specific features, we use `.tofu` files and provide clear migration guidance. ### OpenTofu/Terraform version support - **OpenTofu**: We support OpenTofu 1.9 for new features that provide significant customer value. -- **Terraform**: We maintain compatibility with Terraform versions that support the same language features we use, but do not explicitly test or support Terraform versions beyond 1.5.7 - -When we upgrade a module to require a newer version of OpenTofu, we explicitly require that version in the `terraform` block of the module, publish a major module version release in the related git repo, and include clear migration guidance, if applicable. +- **Terraform**: We maintain compatibility with Terraform versions that support the same OpenTofu language features we use, but do not explicitly test or support Terraform versions beyond 1.5.7. ### OpenTofu feature adoption @@ -42,7 +39,7 @@ We now support cross-variable validation (the ability to reference the values of ## Future evolution --This principle will evolve as the Terraform and OpenTofu ecosystems develop. We will: --- Regularly review compatibility and our support policy based on customer needs --- Update our supported feature list as new stable releases become available --- Clearly communicate any changes to our compatibility strategy \ No newline at end of file +This principle will evolve as the Terraform and OpenTofu ecosystems develop. We will: +- Regularly review compatibility and our support policy based on customer needs +- Update our supported feature list as new stable releases become available +- Clearly communicate any changes to our compatibility strategy \ No newline at end of file From 0fe31ee10e7309c815ccd70fa233bd5adde6ee6e Mon Sep 17 00:00:00 2001 From: Josh Padnick Date: Mon, 29 Sep 2025 10:28:22 -0700 Subject: [PATCH 4/9] Fix typo --- sidebars/docs.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sidebars/docs.js b/sidebars/docs.js index 5e67bab558..c45594b2dc 100644 --- a/sidebars/docs.js +++ b/sidebars/docs.js @@ -658,7 +658,7 @@ const sidebar = [ id: "2.0/docs/library/concepts/principles/quality-in-depth", }, { - label: "Support SmoothOpenTofu Adoption", + label: "Support Smooth OpenTofu Adoption", type: "doc", id: "2.0/docs/library/concepts/principles/opentofu-adoption", }, From 18204135f8cba80bdc83b3c8c987e4201283a119 Mon Sep 17 00:00:00 2001 From: Josh Padnick Date: Mon, 29 Sep 2025 10:29:44 -0700 Subject: [PATCH 5/9] Apply suggestion from @yhakbar Co-authored-by: Yousif Akbar <11247449+yhakbar@users.noreply.github.com> --- docs/2.0/docs/library/concepts/principles/opentofu-adoption.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/2.0/docs/library/concepts/principles/opentofu-adoption.md b/docs/2.0/docs/library/concepts/principles/opentofu-adoption.md index 05cba18048..395c9a63d9 100644 --- a/docs/2.0/docs/library/concepts/principles/opentofu-adoption.md +++ b/docs/2.0/docs/library/concepts/principles/opentofu-adoption.md @@ -6,7 +6,7 @@ But we also know that platform teams may be on very early versions of Terraform ## Core principle -We prefer OpenTofu over Terraform but design our modules to work seamlessly with both, ensuring customers can adopt OpenTofu without syntax changes or configuration rewrites. +We prefer OpenTofu over Terraform but design our modules to work seamlessly with both whenever possible, ensuring customers can adopt OpenTofu without syntax changes or configuration rewrites. ## Implementation From b9d850dd33d8f96bb2ca55bfb63ddcc2664e885e Mon Sep 17 00:00:00 2001 From: Josh Padnick Date: Mon, 29 Sep 2025 10:29:53 -0700 Subject: [PATCH 6/9] Apply suggestion from @yhakbar Co-authored-by: Yousif Akbar <11247449+yhakbar@users.noreply.github.com> --- docs/2.0/docs/library/concepts/principles/opentofu-adoption.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/2.0/docs/library/concepts/principles/opentofu-adoption.md b/docs/2.0/docs/library/concepts/principles/opentofu-adoption.md index 395c9a63d9..140e821e6d 100644 --- a/docs/2.0/docs/library/concepts/principles/opentofu-adoption.md +++ b/docs/2.0/docs/library/concepts/principles/opentofu-adoption.md @@ -25,7 +25,7 @@ We prefer OpenTofu over Terraform but design our modules to work seamlessly with When evaluating new OpenTofu language features for use in Gruntwork modules: 1. **Dual-compatible features (Preferred)**: Features that work identically in both OpenTofu and Terraform should be placed in `.tf` files. (e.g. see [cross-variable validation](#cross-variable-validation) below.) -2. **OpenTofu-specific Features (Discouraged)**: Features that only work in OpenTofu should be placed in `.tofu` files and used sparingly. Terraform ignores `.tofu` files, while OpenTofu reads both `.tf` and `.tofu`. Avoid duplicating the same blocks across both extensions; prefer additive enhancements in `.tofu`. This approach increases maintenance cost, so we will use it only when the user benefit is clear. +2. **OpenTofu-only Features (Discouraged)**: Features that only work in OpenTofu should be placed in `.tofu` files and used sparingly. Terraform ignores `.tofu` files, while OpenTofu reads both `.tf` and `.tofu`. Avoid duplicating the same blocks across both extensions; prefer additive enhancements in `.tofu`. This approach increases maintenance cost, so we will use it only when the user benefit is clear. 3. **Terraform-specific Features**: We do not support Terraform-specific features. ## Current feature adoption From d471e2bad9e4940c62f0ef7d786da4f9d2396d04 Mon Sep 17 00:00:00 2001 From: Josh Padnick Date: Mon, 29 Sep 2025 10:30:05 -0700 Subject: [PATCH 7/9] Apply suggestion from @yhakbar Co-authored-by: Yousif Akbar <11247449+yhakbar@users.noreply.github.com> --- docs/2.0/docs/library/concepts/principles/opentofu-adoption.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/2.0/docs/library/concepts/principles/opentofu-adoption.md b/docs/2.0/docs/library/concepts/principles/opentofu-adoption.md index 140e821e6d..ec86282aee 100644 --- a/docs/2.0/docs/library/concepts/principles/opentofu-adoption.md +++ b/docs/2.0/docs/library/concepts/principles/opentofu-adoption.md @@ -26,7 +26,7 @@ When evaluating new OpenTofu language features for use in Gruntwork modules: 1. **Dual-compatible features (Preferred)**: Features that work identically in both OpenTofu and Terraform should be placed in `.tf` files. (e.g. see [cross-variable validation](#cross-variable-validation) below.) 2. **OpenTofu-only Features (Discouraged)**: Features that only work in OpenTofu should be placed in `.tofu` files and used sparingly. Terraform ignores `.tofu` files, while OpenTofu reads both `.tf` and `.tofu`. Avoid duplicating the same blocks across both extensions; prefer additive enhancements in `.tofu`. This approach increases maintenance cost, so we will use it only when the user benefit is clear. -3. **Terraform-specific Features**: We do not support Terraform-specific features. +3. **Terraform-only Features**: We do not support Terraform-specific features. ## Current feature adoption From 038568c30a2aae2a19d35809ba390230d2125964 Mon Sep 17 00:00:00 2001 From: Josh Padnick Date: Mon, 29 Sep 2025 10:30:14 -0700 Subject: [PATCH 8/9] Apply suggestion from @yhakbar Co-authored-by: Yousif Akbar <11247449+yhakbar@users.noreply.github.com> --- docs/2.0/docs/library/concepts/principles/opentofu-adoption.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/2.0/docs/library/concepts/principles/opentofu-adoption.md b/docs/2.0/docs/library/concepts/principles/opentofu-adoption.md index ec86282aee..349e2ccc23 100644 --- a/docs/2.0/docs/library/concepts/principles/opentofu-adoption.md +++ b/docs/2.0/docs/library/concepts/principles/opentofu-adoption.md @@ -39,7 +39,7 @@ We now support cross-variable validation (the ability to reference the values of ## Future evolution -This principle will evolve as the Terraform and OpenTofu ecosystems develop. We will: +This principle will evolve as the OpenTofu and Terraform ecosystems develop. We will: - Regularly review compatibility and our support policy based on customer needs - Update our supported feature list as new stable releases become available - Clearly communicate any changes to our compatibility strategy \ No newline at end of file From aa47a3bc636ed7662e8c74f9fb96bcef2108c607 Mon Sep 17 00:00:00 2001 From: Josh Padnick Date: Mon, 29 Sep 2025 10:30:20 -0700 Subject: [PATCH 9/9] Apply suggestion from @yhakbar Co-authored-by: Yousif Akbar <11247449+yhakbar@users.noreply.github.com> --- docs/2.0/docs/library/concepts/principles/opentofu-adoption.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/2.0/docs/library/concepts/principles/opentofu-adoption.md b/docs/2.0/docs/library/concepts/principles/opentofu-adoption.md index 349e2ccc23..860190405a 100644 --- a/docs/2.0/docs/library/concepts/principles/opentofu-adoption.md +++ b/docs/2.0/docs/library/concepts/principles/opentofu-adoption.md @@ -42,4 +42,5 @@ We now support cross-variable validation (the ability to reference the values of This principle will evolve as the OpenTofu and Terraform ecosystems develop. We will: - Regularly review compatibility and our support policy based on customer needs - Update our supported feature list as new stable releases become available -- Clearly communicate any changes to our compatibility strategy \ No newline at end of file +- Clearly communicate any changes to our compatibility strategy +- Regularly review any customer request for adoption of new features \ No newline at end of file