add new terraform docs #34221

jubrad · 2025-11-19T19:43:53Z

Preview:
https://preview.materialize.com/materialize/34221/self-managed-deployments/

Motivation

Revival of Jun's Pr to shift the cloud specific terraform install and upgrade structure +docs for the new terraform.

SangJunBak · 2025-11-19T19:53:53Z

@jubrad thanks for reviving this!

kay-kim

Hey ... won't have time to add a patch to this today (double-checking the upgrade)... so, am leaving some comments for now in case people have a window free.
Depending on when, I'll continue reviewing or patching. Heads up ... I'm out starting Monday next week.

kay-kim · 2025-11-19T20:15:52Z

doc/user/content/installation/install-on-aws/_index.md

-  {{</ tip >}}
+| Guide | Description |
+|-------|-------------|
+| [Terraform Provider](/installation/install-on-aws/terraform-module/) | Install Materialize on AWS using our new Unified Terraform Provider  |


In the Description for the new Unified .... Do we want to add Recommended annotation? like
| Recommended. Install Materialize ...

kay-kim · 2025-11-19T20:16:26Z

doc/user/content/installation/install-on-aws/_index.md

+| Guide | Description |
+|-------|-------------|
+| [Terraform Provider](/installation/install-on-aws/terraform-module/) | Install Materialize on AWS using our new Unified Terraform Provider  |
+| [Terraform Provider (legacy)](/installation/install-on-aws/legacy-terraform-module/) | Install Materialize on AWS using our Terraform Provider (legacy) |


The description "using our Terraform..." -> "using our legacy Terraform Provider"

doc/user/content/installation/install-on-aws/appendix-deployment-guidelines.md

doc/user/content/installation/install-on-aws/terraform-module/_index.md

kay-kim · 2025-11-19T20:42:35Z

doc/user/content/installation/install-on-aws/terraform-module/_index.md

+
+```hcl
+name_prefix = "simple-demo"
+aws_region  = "us-east-1"


should we mention as a comment that they can change the aws_region?

doc/user/content/installation/install-on-aws/terraform-module/_index.md

kay-kim · 2025-11-20T02:06:28Z

doc/user/content/installation/upgrading.md

@@ -0,0 +1,187 @@
+---
+title: "Upgrade Overview"


Oh ... this was incorporated into the landing page https://github.com/MaterializeInc/materialize/pull/34221/files#diff-eac74265be1711fcdccf99e1c740cdcc0054ab604c658782a67e6aa26daad915L15

So, I think this can go away?

Oh yeah, I did just notice that, and I'm not sure I agree.
I knid of want the landing page portion to go away and think we should move back to an upgrade overview doc 😆

Probably best to chat through this through on zoom.

It's only because of the current organization that it's included at the top. That is, for the upgrade landing page, we would want to reorg the other files.
Currently, as it stands, we have:

Self-Managed Deployments

Install on kind

Upgrade

Install on AWS

TF

TF Legacy

Install

Upgrade

Req Config

Install on Azure

TF

TF Legacy

Install

Upgrade

Req Config

...

Upgrading

So ... we might want to go:

Self-Managed Deployments

Install

Install on kind

Install on AWS

...

Upgrade <-- This can be the separate landing page overview.

Upgrade on kind

Upgrade on AWS

...

doc/user/content/installation/upgrading.md

- Moves the install, upgrade, and configuration docs into a subdirectory called Terraform Provider (Legacy) - Creates aliases for each of the moved pages - `Installation > Install on GCP `-> `Installation > Install on GCP > Terraform Provider (Legacy) > Install` - Removed terraform references from the Deployment guideline appendix and pushed them into the Configuration appendix - Changed from "Required configuration" to just "configuration" docs: Relabel AWS guides as legacy Terraform guides - Does the same work as the GCP commit docs: Relabel Azure guides as legacy Terraform guides - Does the same thing as the GCP commit - Removes terraform configuation values given they weren't rendered. e.g. enable_disk_support Update doc links Add docs for new terraform modules.

kay-kim · 2025-12-09T19:48:50Z

doc/user/content/self-managed-deployments/_index.md

@@ -0,0 +1,353 @@
+---
+title: "Self-Managed Deployments"


https://preview.materialize.com/materialize/34221/self-managed-deployments/

kay-kim · 2025-12-09T19:49:49Z

doc/user/content/self-managed-deployments/_index.md

+
+1. **Connect to the instance**: Use the Materialize Console on port 8080 to
+   connecto to the `console` service endpoint or SQL client on port 6875 to
+   connect to the `balancerd` service endpoint.


👉 this had previous said environmentd, but I think it's balancerd?

kay-kim · 2025-12-09T19:50:37Z

doc/user/content/self-managed-deployments/faq.md

+
+## How can I downgrade Self-Managed Materialize?
+
+{{< include-from-yaml data="self_managed/upgrades"


Oh ... let me know if you want me to include this you can't downgrade also in our upgrade guides.

kay-kim · 2025-12-09T19:55:30Z

doc/user/content/self-managed-deployments/installation/install-on-aws.md

+        terraform apply
+        ```
+
+    - To deploy with <red>**public NLB**</red> for Materialize access:


👉 This feature is not yet in the TF. Let me know if:
a) this is in progress or
b) you want me to remove this from the docs
c) make the couple of lines PR
d) file an issue

kay-kim · 2025-12-09T19:56:18Z

doc/user/content/self-managed-deployments/installation/install-on-aws.md

+
+   ```bash
+   # aws eks update-kubeconfig --name <your-eks-cluster-name> --region <your-region>
+   aws eks update-kubeconfig --name $(terraform output -raw eks_cluster_name) --region us-east-1


Just wondering ... if we should include the region in the output so that people don't need to manually update the region.

kay-kim · 2025-12-09T20:01:52Z

doc/user/content/self-managed-deployments/installation/install-on-aws.md

+
+## Cleanup
+
+{{% self-managed/cleanup-cloud %}}


👉 As an FYI -- I've now gone past the weird zsh error by using shivam's branch + main ... but even running this terraform destroy four times, I keep getting

│ Error: deleting Security Group (sg-037dbf999aed801cc): operation error EC2: DeleteSecurityGroup, https response error StatusCode: 400, RequestID: d7ea4727-cd42-4021-a87f-3c9e28fc8c6b, api error DependencyViolation: resource sg-037dbf999aed801cc has a dependent object │ │

There's a thread on this.

If we don't sort out, I could add a tip stating the workaround:

aws ec2 describe-network-interfaces \ --region us-east-1 \ --filters Name=group-id,Values=<your_security_group> \ --query "NetworkInterfaces[].{ENI:NetworkInterfaceId,Desc:Description,Status:Status,Attachment:Attachment.InstanceId,Owner:OwnerId,Requester:RequesterId,Subnet:SubnetId,PrivateIp:PrivateIpAddress}"

and delete

aws ec2 delete-network-interface \ --region <your_region> \ --network-interface-id <eni_to_delete>

Oh ... this was fixed with MaterializeInc/materialize-terraform-self-managed#125 🎉🎉🎉

kay-kim · 2025-12-09T20:05:46Z

doc/user/content/self-managed-deployments/installation/install-on-aws.md

+
+   - `mz_system` as the user
+   - Your `<dns_name>` as the host
+   - `6875` as the port:


With auth enabled, mz_system can use 6875 🎉 (We'll need to clarify the troubleshooting section where we have people port forward 6877)

kay-kim · 2025-12-09T20:06:56Z

doc/user/content/self-managed-deployments/installation/install-on-azure.md

+
+{{< /note >}}
+
+#### Connect using the Materialize Console


FYI -- the azure/google simple examples do not have auth enabled like aws's simple example.

kay-kim · 2025-12-09T20:07:51Z

doc/user/content/self-managed-deployments/installation/install-on-gcp.md

+deployment
+guide](/self-managed-deployments/deployment-guidelines/gcp-deployment-guidelines/).
+
+{{< note >}}


👉 Do we want to make this forward-looking statement?
We could

kay-kim · 2025-12-09T20:11:38Z

doc/user/content/self-managed-deployments/installation/install-on-azure.md

+deployment
+guide](/self-managed-deployments/deployment-guidelines/azure-deployment-guidelines/).
+
+{{< note >}}


👉 Do we want to make this forward looking statement? Depending on where we are, we could make it slightly more generic that things might change instead.

kay-kim · 2025-12-09T20:12:57Z

doc/user/content/self-managed-deployments/installation/install-on-gcp.md

+   {{% include-from-yaml data="self_managed/installation"
+   name="installation-verify-status" %}}
+
+### Step 5: Connect to Materialize


FYI -- the azure/google simple examples do not have auth enabled like aws's simple example.

kay-kim · 2025-12-09T20:14:00Z

doc/user/content/self-managed-deployments/upgrading/_index.md

+compatible version of your currently deployed Materialize Operator.
+
+To stage, but **not** rollout, the Materialize instance version upgrade, you can
+use the `kubectl patch` command; for example, if the **App Version** is {{< self-managed/versions/get-latest-version >}}:


👉 am omitting the fact that although the Materialize instances do not upgrade until you requestRollout, the balancerds do upgrade versions.

kay-kim · 2025-12-09T20:15:04Z

doc/user/content/self-managed-deployments/upgrading/_index.md

+
+### Using YAML Definition
+
+Alternatively, you can update your Materialize custom resource definition directly:


Q: Just wondering ... for this (and kind upgrade I suppose) ... should we have it broken into two parts as well? ... One to stage and the other to requestRollout?

One step works as well. This is the same as Staging and applying in a single command

I can also make this a child of that section

kay-kim · 2025-12-09T20:18:14Z

doc/user/data/self_managed/upgrades.yml

+- name: upgrade-order-rule
+  content: |
+    **Always** upgrade the Materialize Operator **before**
+    upgrading the Materialize instances.


Merged the previously 2 bullet point to above:
Always upgrade the operator first and ensure version compatibility between the operator and the Materialize instance you are upgrading to.
Always upgrade your Materialize instances after upgrading the operator to ensure compatibility.

(since I think they're saying the same thing).

kay-kim · 2025-12-09T20:18:41Z

doc/user/shared-content/self-managed/general-rules-for-upgrades.md


- **Always** upgrade the operator first and ensure version compatibility between
-  the operator and the Materialize instance you are upgrading to.
+- **Always** check the [version specific upgrade


Will remove this as folded into the consolidated yaml file in the future

kay-kim · 2025-12-09T20:42:29Z

doc/user/content/self-managed-deployments/upgrading/_index.md

@@ -0,0 +1,271 @@
+---
+title: "Upgrading"


Heh .. I've been going back between Upgrades vs Upgrading ... eh.

jubrad requested review from SangJunBak and kay-kim November 19, 2025 19:43

jubrad requested a review from a team as a code owner November 19, 2025 19:43

kay-kim reviewed Nov 19, 2025

View reviewed changes

kay-kim reviewed Nov 20, 2025

View reviewed changes

jubrad changed the title ~~docs: Relabel GCP guides as legacy Terraform guides~~ add new terraform docs Nov 20, 2025

kay-kim reviewed Nov 20, 2025

View reviewed changes

doc/user/content/installation/upgrading.md Outdated Show resolved Hide resolved

jubrad force-pushed the jubrad/new-terraform-docs-2 branch 5 times, most recently from 09c8029 to 718192a Compare December 3, 2025 15:21

jubrad added 2 commits December 8, 2025 11:02

pr review changes

1a2e83b

kay-kim force-pushed the jubrad/new-terraform-docs-2 branch from 718192a to 1a2e83b Compare December 8, 2025 16:09

kay-kim added 6 commits December 8, 2025 11:15

some reorg + tweaks (part 1: install + broad reorg)

589f1f2

fix change in release file location

d35656f

Update upgrade + move crd + operator configs

d6bb986

fix typos/copy+paste errors/psql connect

86d70c2

linting errors

517a7a2

additional tweaks

52abb4b

kay-kim reviewed Dec 9, 2025

View reviewed changes

accidental removal of note

62fb16b

kay-kim reviewed Dec 9, 2025

View reviewed changes

kay-kim requested review from maheshwarip and sidsaw-mz December 9, 2025 20:19

kay-kim reviewed Dec 9, 2025

View reviewed changes

kay-kim added 2 commits December 10, 2025 13:34

some cleanup/nice-to-haves

7a0b74c

docs: tweak for zsh escaping

789a247


		## How can I downgrade Self-Managed Materialize?

		{{< include-from-yaml data="self_managed/upgrades"


		### Using YAML Definition

		Alternatively, you can update your Materialize custom resource definition directly:

add new terraform docs #34221

Are you sure you want to change the base?

add new terraform docs #34221

Conversation

jubrad commented Nov 19, 2025 • edited by kay-kim Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Motivation

Uh oh!

SangJunBak commented Nov 19, 2025

Uh oh!

kay-kim left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kay-kim Nov 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kay-kim Dec 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

jubrad commented Nov 19, 2025 •

edited by kay-kim

Loading

kay-kim Nov 20, 2025 •

edited

Loading

kay-kim Dec 9, 2025 •

edited

Loading