From aca861d903be1111fd22b4b65dfcb750439cf438 Mon Sep 17 00:00:00 2001 From: Michael Thamm Date: Fri, 10 Apr 2026 16:37:47 -0400 Subject: [PATCH 1/2] feat: ADR - TF tagging --- .../2026-04-02--terraform-module-tagging.md | 68 +++++++++++++++++++ 1 file changed, 68 insertions(+) create mode 100644 decision-records/2026-04-02--terraform-module-tagging.md diff --git a/decision-records/2026-04-02--terraform-module-tagging.md b/decision-records/2026-04-02--terraform-module-tagging.md new file mode 100644 index 00000000..af022bac --- /dev/null +++ b/decision-records/2026-04-02--terraform-module-tagging.md @@ -0,0 +1,68 @@ +**Date:** 2026-04-02
+**Author:** Michael Thamm (@crucible) + +## Context and Problem Statement + +Prior discussion was conducted in this GitHub issue: +- https://github.com/canonical/observability/issues/427 + +with 2 Observability team Cafes to come to an agreement. This document will summarize the agreed direction for tagging Terraform charm and product modules. + +## Decision: use separate full-SemVer tag dedicated to Terraform + +Design goals: +- Clear Terraform mapping to solution track / charm workload version +- Strict pinning (precise reproducibility) +- Tagging must be compatible with Terrareg + +In the context of __Terraform-first Juju operations__, +facing __the friction between track-first and SemVer-first tagging__, +we decided for __Separate full-SemVer tag dedicated to Terraform__, +and rejected __Major.minor, metadata__, +to achieve __strict reproducability__, +accepting __version opaqueness__. + +## User experience +1. First deployment + - *terraform apply* +2. In-track refresh + - No change to source e.g., ?ref=1.0.0 + - Update the risk or revision input; TF validation guides the user + - *terraform apply* +3. Cross-track refresh + - Update the source e.g., ?ref=2.0.0 + - Update the channel or revision input; TF validation guides the user + - Read the module’s docs for extra guidance + - *terraform apply* +4. Revert failed deployment + - Revert to the most recently used (working) version + - *terraform apply* + +## Implementation +1. OBC-1544 “26.04 LTS prep and dogfooding” will address: + - Implementing the tagging rework of our TF modules (charms and products) + - Implement tagging CI on version bump +2. OBC-1760 “Terraform-first end-to-end charm lifecycle” will address: + - Ensuring users can upgrade/downgrade in-track/cross-track our products with tagging + +## Appendix - extra context + +We need to conform to the [CC008](https://docs.google.com/document/d/1k1psLCfcf0Nr5KeVtWGFi9wmzhcg5AP9GVZTsRyVQSQ/edit?tab=t.0) spec and our solution must: +- have friendly UX for our users +- be extendible to product modules +- be automatable: tagging the repo and releasing to the TF registry + +### Maintenance scenarios +| Upstream | Track | Cycle | Event | Tag | +|---|---|---|---|---| +| `3.6.7` | `3.6` | `26.04` | | `1.0.0` | +| | | | A TF endpoint added to track `3.6` | `1.1.0` | +| | | | A TF endpoint added to previous track e.g., `2.9` | `n-1.n+1.0` or `n.n+1.0` | +| `3.6.7` | `3.6` | `26.10` | We consciously decide not to track bump (to `3.7.0`) across cycles | `1.1.0` | +| `4.1.0` | `4.1` | `27.04` | We time a breaking change with `27.04` | `2.0.0` | +| | | | We decide to make a breaking change mid-cycle | `3.0.0` | + +### Shortcomings of our decision +- ❗️Tags are opaque to charm-tracks e.g., `1.0.0` is specific to track `2`. + - A user needs to search release notes / module docs to understand what tracks are allowed. +- We have to manage a `VERSION` file for tagging CI. From 60fe9a6afb7c035a507ca16d5b125f43ae863756 Mon Sep 17 00:00:00 2001 From: Michael Thamm Date: Mon, 13 Apr 2026 16:51:25 -0400 Subject: [PATCH 2/2] chore --- decision-records/2026-04-02--terraform-module-tagging.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/decision-records/2026-04-02--terraform-module-tagging.md b/decision-records/2026-04-02--terraform-module-tagging.md index af022bac..5e4df4b2 100644 --- a/decision-records/2026-04-02--terraform-module-tagging.md +++ b/decision-records/2026-04-02--terraform-module-tagging.md @@ -19,19 +19,21 @@ In the context of __Terraform-first Juju operations__, facing __the friction between track-first and SemVer-first tagging__, we decided for __Separate full-SemVer tag dedicated to Terraform__, and rejected __Major.minor, metadata__, -to achieve __strict reproducability__, +to achieve __strict reproducibility__, accepting __version opaqueness__. ## User experience +Note: The *channel* input is validated by Terraform for the track and by the Juju client for the risk; guiding the user. No validation can be done on the *revision* (currently not feasible with the Terraform Juju provider), so we say "incorrect config is user error". + 1. First deployment - *terraform apply* 2. In-track refresh - No change to source e.g., ?ref=1.0.0 - - Update the risk or revision input; TF validation guides the user + - Update the risk and/or revision input - *terraform apply* 3. Cross-track refresh - Update the source e.g., ?ref=2.0.0 - - Update the channel or revision input; TF validation guides the user + - Update the channel or revision input - Read the module’s docs for extra guidance - *terraform apply* 4. Revert failed deployment