Separate tabs for supported terraform, legacy tf, and manual

Author: alex-hunt-materialize

doc/user/shared-content/self-managed/upgrade-notes/v26.19.md

@@ -36,16 +36,179 @@ Switching to `v1alpha2` is **opt-in**. You may continue to apply `v1alpha1` CRs
 
 {{< important >}}
 
-v26.19 requires infrastructure changes to support converting between `v1alpha1` and `v1alpha2` resources.
+v26.19 requires infrastructure changes before upgrading.
 
 {{< /important >}}
 
-The Materialize Operator now hosts conversion webhooks to convert between
-`v1alpha1` and `v1alpha2`. These webhooks are **always deployed** with v26.19+,
-even if you continue using `v1alpha1`. If you are using our [new terraform
+Materialize uses conversion webhooks to allow you to gracefully migrate from
+`v1alpha1` to `v1alpha2`. To enable these webhooks to be delivered, you need to
+install cert-manager and allow internal network ingress on port `8001`. These
+webhooks are **always deployed** with v26.19+, even if you continue using
+`v1alpha1`.
+
+Choose the tab that matches your deployment method:
+
+<div class="code-tabs">
+<ul class="nav-tabs"></ul>
+<div class="tab-content">
+<div class="tab-pane" title="Supported Terraform" id="upgrade-supported-terraform">
+
+If you are using the [supported Terraform
+modules](https://github.com/MaterializeInc/materialize-terraform-self-managed),
+the required infrastructure changes (cert-manager and network ingress) will be
+handled for you automatically.
+
+To upgrade, update each module's `source` to point to the new release tag and
+run `terraform init -upgrade && terraform plan && terraform apply`.
+
+The key modules and their dependency chain are shown below. Your configuration
+may include additional modules (networking, storage, database, node pools, etc.)
+— update those to the same release tag as well.
+
+<div class="code-tabs">
+<ul class="nav-tabs"></ul>
+<div class="tab-content">
+<div class="tab-pane" title="AWS" id="upgrade-supported-terraform-aws">
+
+```hcl
+module "eks" {
+  source = "github.com/MaterializeInc/materialize-terraform-self-managed//aws/modules/eks?ref=<RELEASE_TAG>"
+  # ... your existing configuration ...
+}
+
+module "cert_manager" {
+  source = "github.com/MaterializeInc/materialize-terraform-self-managed//kubernetes/modules/cert-manager?ref=<RELEASE_TAG>"
+  # ... your existing configuration ...
+
+  # Your configuration may have additional dependencies here.
+  depends_on = [module.eks]
+}
+
+module "operator" {
+  source = "github.com/MaterializeInc/materialize-terraform-self-managed//aws/modules/operator?ref=<RELEASE_TAG>"
+  # ... your existing configuration ...
+
+  # Your configuration may have additional dependencies here.
+  depends_on = [module.cert_manager]
+}
+
+module "materialize_instance" {
+  source = "github.com/MaterializeInc/materialize-terraform-self-managed//kubernetes/modules/materialize-instance?ref=<RELEASE_TAG>"
+  # ... your existing configuration ...
+
+  # Your configuration may have additional dependencies here.
+  depends_on = [module.operator]
+}
+```
+
+For a complete example, see
+[`aws/examples/simple/main.tf`](https://github.com/MaterializeInc/materialize-terraform-self-managed/blob/main/aws/examples/simple/main.tf).
+
+</div>
+<div class="tab-pane" title="GCP" id="upgrade-supported-terraform-gcp">
+
+```hcl
+module "gke" {
+  source = "github.com/MaterializeInc/materialize-terraform-self-managed//gcp/modules/gke?ref=<RELEASE_TAG>"
+  # ... your existing configuration ...
+}
+
+module "cert_manager" {
+  source = "github.com/MaterializeInc/materialize-terraform-self-managed//kubernetes/modules/cert-manager?ref=<RELEASE_TAG>"
+  # ... your existing configuration ...
+
+  # Your configuration may have additional dependencies here.
+  depends_on = [module.gke]
+}
+
+module "operator" {
+  source = "github.com/MaterializeInc/materialize-terraform-self-managed//gcp/modules/operator?ref=<RELEASE_TAG>"
+  # ... your existing configuration ...
+
+  # Your configuration may have additional dependencies here.
+  depends_on = [module.cert_manager]
+}
+
+module "materialize_instance" {
+  source = "github.com/MaterializeInc/materialize-terraform-self-managed//kubernetes/modules/materialize-instance?ref=<RELEASE_TAG>"
+  # ... your existing configuration ...
+
+  # Your configuration may have additional dependencies here.
+  depends_on = [module.operator]
+}
+```
+
+For a complete example, see
+[`gcp/examples/simple/main.tf`](https://github.com/MaterializeInc/materialize-terraform-self-managed/blob/main/gcp/examples/simple/main.tf).
+
+</div>
+<div class="tab-pane" title="Azure" id="upgrade-supported-terraform-azure">
+
+```hcl
+module "aks" {
+  source = "github.com/MaterializeInc/materialize-terraform-self-managed//azure/modules/aks?ref=<RELEASE_TAG>"
+  # ... your existing configuration ...
+}
+
+module "cert_manager" {
+  source = "github.com/MaterializeInc/materialize-terraform-self-managed//kubernetes/modules/cert-manager?ref=<RELEASE_TAG>"
+  # ... your existing configuration ...
+
+  # Your configuration may have additional dependencies here.
+  depends_on = [module.aks]
+}
+
+module "operator" {
+  source = "github.com/MaterializeInc/materialize-terraform-self-managed//azure/modules/operator?ref=<RELEASE_TAG>"
+  # ... your existing configuration ...
+
+  # Your configuration may have additional dependencies here.
+  depends_on = [module.cert_manager]
+}
+
+module "materialize_instance" {
+  source = "github.com/MaterializeInc/materialize-terraform-self-managed//kubernetes/modules/materialize-instance?ref=<RELEASE_TAG>"
+  # ... your existing configuration ...
+
+  # Your configuration may have additional dependencies here.
+  depends_on = [module.operator]
+}
+```
+
+For a complete example, see
+[`azure/examples/simple/main.tf`](https://github.com/MaterializeInc/materialize-terraform-self-managed/blob/main/azure/examples/simple/main.tf).
+
+</div>
+</div>
+</div>
+
+</div>
+<div class="tab-pane" title="Legacy Terraform" id="upgrade-legacy-terraform">
+
+If you are using the legacy Terraform modules
+([AWS](https://github.com/MaterializeInc/terraform-aws-materialize),
+[GCP](https://github.com/MaterializeInc/terraform-gcp-materialize), or
+[Azure](https://github.com/MaterializeInc/terraform-azure-materialize)),
+we recommend migrating to the [new supported Terraform
 modules](https://github.com/MaterializeInc/materialize-terraform-self-managed)
-these changes will be handled for you, just by applying the new versions,
-otherwise, you **must** complete the following steps before upgrading the Helm chart:
+before upgrading to v26.19.
+
+The new modules include built-in support for the conversion webhooks required
+by v26.19+, including cert-manager installation and network policy
+configuration. The legacy modules do not include these changes, so you would
+need to apply them manually (see the **Manual** tab).
+
+For migration guidance, see the documentation for your cloud provider:
+
+- [AWS migration guide](https://github.com/MaterializeInc/materialize-terraform-self-managed/tree/main/aws/examples/migration)
+- [GCP migration guide](https://github.com/MaterializeInc/materialize-terraform-self-managed/tree/main/gcp/examples/migration)
+- [Azure migration guide](https://github.com/MaterializeInc/materialize-terraform-self-managed/tree/main/azure/examples/migration)
+
+</div>
+<div class="tab-pane" title="Manual" id="upgrade-manual">
+
+If you are not using our Terraform modules, you **must** complete the following
+steps before upgrading the Helm chart:
 
 **1. Install cert-manager**
 
@@ -99,3 +262,7 @@ allowing port `8001` from the GKE control plane CIDR.
 
 For a complete example of the required changes across AWS, Azure, and GCP,
 see [this pull request](https://github.com/MaterializeInc/materialize-terraform-self-managed/pull/160).
+
+</div>
+</div>
+</div>