I'd recommend phrasing this as something like this:

--
v26.19.0 introduces a new version of the Materialize CRD,v1alpha2. The new CRD simplifies rollouts by automatically detecting changes. This means you will no longer need to manually rotate a UUID to trigger a rollout.

Before, on v1alpha1:

yamlapiVersion: materialize.cloud/v1alpha1
kind: Materialize
metadata:
  name: 12345678-1234-1234-1234-123456789012
  namespace: materialize-environment
spec:
  environmentdImageRef: materialize/environmentd:v26.16.0
  requestRollout: 22222222-2222-2222-2222-222222222222  # ← MUST set a new UUID every upgrade
# forceRollout: 33333333-3333-3333-3333-333333333333   # ← for forced rollouts
  rolloutStrategy: WaitUntilReady
  backendSecretName: materialize-backend

After, on v1alpha2:

apiVersion: materialize.cloud/v1alpha2
kind: Materialize
metadata:
  name: 12345678-1234-1234-1234-123456789012
  namespace: materialize-environment
spec:
  environmentdImageRef: materialize/environmentd:v26.16.0  # ← just change this
# forceRollout: 33333333-3333-3333-3333-333333333333       # ← only for forced rollouts
  rolloutStrategy: WaitUntilReady
  backendSecretName: materialize-backend

With the new change, the requestRollout field will be removed, along with all previously deprecated fields.

Switching to v1alpha2 is opt-in. You may continue to apply v1alpha1 CRs and your existing instances will behave exactly as before. We recommend you opt-in to v1alpha2 at your convenience, as we will migrate to the v1alpha2 behavior in the next major release. For step-by-step migration instructions, see Switching from v1alpha1 to v1alpha2.

Do these infrastructure changes need to be made for v26.19 @alex-hunt-materialize ? Or is it only for migrating to v1alpha2?

If it is only to migrate to v1alpha2, I'd actually recommend that we move this into a separate section. At a high level, I'd imagine that the structure can be like this:

• Self-Managed deployments
  • Upgrading page: Give the user basic information about what has changed in v26.19
  • Materialize CRDs Page: Give the user information about v1alpha1 and v1alpha2. Include information about how to migrate from alpha1 to alpha2.

Does that make sense?

This applies regardless of which CRD version you use. I'll rephrase this line to say:

v26.19 requires infrastructure changes to support converting between `v1alpha1` and `v1alpha2` resources.

I'd rephrase this a little:
Materialize uses webhooks to allow you to gracefully migrate from alphav1 to alphav2. To enable these webhooks to be delivered, you need to install cert-manager and allow internal network ingress on port 8001. If you're using our terraform modules, this will be handled for you automatically. If you're not using our terraform, you will need to complete these steps manually before upgrading to v26.19.

• Tab for how to upgrade using our terraform
• Tab for how to upgrade if customers are doing this manually

• Tab for how to upgrade using our terraform

They should already know how to upgrade the terraform code. They should have been doing that for literally every release. Do we really need to tell them how to bump a version number? If they can't handle that, they should not be running self-managed.

• Tab for how to upgrade if customers are doing this manually

That's the stuff directly below this.

They should already know how to upgrade the terraform code. They should have been doing that for literally every release. Do we really need to tell them how to bump a version number? If they can't handle that, they should not be running self-managed.

Yes. Please be explicit here - customers are going to get tripped up otherwise. If I skim this document, I am going to miss the instructions for how to do the upgrade using the MZ terraform.

What I'd recommend doing here is:

• 1 tab for users on our supported terraform
• 1 tab for folks on our legacy terraform. Give them instructions / details for how to migrate to the new terraform.
• 1 tab for manual instructions

Done, please take another look.

Could we explicitly specify that this policy will only allow ingress from within the cluster? And not ingress from public internet?

This example policy allows ingress from everywhere, but they only need to allow it from the Kubernetes API servers. Kubernetes network policies only allow specifying rules based on CIDR blocks or pod labels. The only way to restrict this for the API servers is by CIDR block, which we don't have available here.

Ingress to this port on this pod is safe, there is nothing bad that anyone can do with these endpoints, beyond making orchestratord generate a response.

Additionally, this policy only affects traffic that has reached Kubernetes. They should be running their clusters in an isolated VPC, and the normal cloud firewall rules still apply (ie: security groups for nodes).

Requires MaterializeInc/materialize-terraform-self-managed#242

This comment lists only two strategies, but ManuallyPromote is documented just below. Suggest including it for completeness (the v1 page has the same comment and could be updated to match):

Field-name typo: the field is forceRollout, not forcedRollout/forcedRollouts (confirmed against the CRD schema; the kubectl patch example on line 144 already uses the correct forceRollout). The same typo appears in the note above (lines 122 and 124) and in the section heading on line 135 — worth correcting those too.

Quick check on field names here: forcePromote checks out in the v1 CRD schema, but I couldn't find requestedRolloutHash in the spec — I'm assuming it's a .status field. Can you confirm the exact field name and that it lives under .status (not .spec)? Want to make sure users following this can actually locate the value to match.

Same as on the v1alpha1 page: this comment omits ManuallyPromote, which is documented in the Rollout strategies section below. Suggest including it:

Question on precision: this says the webhook hashes "the spec", and the v1 page says "the spec fields", but #35418 describes the hash as covering a subset of spec fields. Could you confirm which it is? If it's a subset, it'd help to say which fields are (or aren't) included, since that's what determines when a rollout fires (e.g. would changing podAnnotations trigger one?). Happy to make this page and the v1 page consistent once confirmed.

Does patching only the apiVersion actually switch the stored/served version and trigger conversion? My understanding is that kubectl patch addresses the object by resource and the stored version stays v1alpha1, so an apiVersion in a merge-patch body may be a no-op (it doesn't re-submit the object through the v1 endpoint). If that's the case, this command wouldn't reliably switch an instance — the kubectl apply of a full v1 manifest above would. Could you verify this works as written, or drop it in favor of the apply approach?

Regardless of the method of apply, the stored version will stay v1alpha1. I think you may be correct, though, that kubectl patch with a changed apiVersion will likely not behave as expected. I'll remove it entirely.

Is this if you have some specific version of the TFs?

I suppose we should specify the version, but I don't have that yet. I'd like to get MaterializeInc/materialize-terraform-self-managed#242 in, and we also need to bump the helm chart to include v26.30.0 of the operator.

I put a placeholder in the next paragraph as v3.0.15 😄 so, can change that once things are bumped and such.

I'm just putting the overarching thought process for my review comments on this page since there's not a good place for me to put it (I'll also include this in the slack message to get PMs to weigh in as well ... or if you and the PMs have already decided some of these are out, feel free to pick and choose):

With the v26.30 release:
👉 Starting point: Everyone is on v1alpha (either previously installed or new 26.30+ installs since v1alpha is the default)
Goal: We want to move everyone in the near future to v1 (this could also get people moving off the legacy TFs) ... and no later than before the next major release.
👉 We have installation guides and upgrade guides. To meet the goal, we don't want people popping in and out of the guides.
Can keep the specific upgrade notes and standalone v1alpha to v1 🗒️

But, I think for the guides, we should include optional steps to enable v1.
For Kind:

• Installation guide currently include the v1 infra prep (make this not optional). We just add an optional step to enable v1 ... so that any new installs starting from now will more than likely use v1.
• Upgrade guide. Add optional steps to include v1 infra prep (if for some reason, they're upgrading from an older version instead of a teardown and restart) and enable v1. For the upgrade, making the infra part also optional seems okay (since a really small subset upgrading from an older version for real)

For our non-legacy TFs

• Installation guides:
  • Add an optional step to adopt v1 -- basically, v1 enablement since the latest TF handles the cert-manager and ingress. If we want, we can blurb about Starting in TF version , the v1 infra prep is automatically handled and maybe link out to the upgrade notes.
• Upgrade guides.
  • Add optional steps to include v1 infra prep if on TF versions and v1 enablement.
  • Update the upgrading materialize instances to have both v1alpha and v1.

I think that should cover:

• Fresh installs (v1alpha or v1)
• Upgrade from older and remain v1alpha
• In one upgrade, switch over to v1 as well
• In one upgrade, do just the infra prep. Then, some time later, switch over to v1 either as part of an upgrade or just the crd version switch.

Also, add content for enabling v1 in the upgrade guides?

And per the overarching comment up top, to the install, an optional step to adopt v1 -- basically, v1 enablement since the latest TF handles the cert-manager and ingress. (We can blurb about Starting in TF version , the v1 infra prep is automatically handled and maybe link out to the upgrade notes)

for turning that on ... if people are using the latest TF (assuming that is the one that has v26.30) ... all one has to do is set the crd_version variable, yes? (since the TFs take care of everything else?)

Yes. I'm still working on getting MaterializeInc/materialize-terraform-self-managed#242 merged, and we'll need to bump the orchestratord helm chart after we release it (Friday?), but otherwise, I think that's all that's required.

Heh ... so, this doesn't work with the latest TF from github main branch (I had it install v26.30.1)
Is there something else that needs to be flipped?

module.materialize_instance.kubectl_manifest.materialize_instance: Creating...
╷
│ Error: materialize-environment/main failed to create kubernetes rest client for update of resource: resource [materialize.cloud/v1/Materialize] isn't valid for cluster, check the APIVersion and Kind fields are valid
│
│   with module.materialize_instance.kubectl_manifest.materialize_instance,
│   on ../../../kubernetes/modules/materialize-instance/main.tf line 29, in resource "kubectl_manifest" "materialize_instance":
│   29: resource "kubectl_manifest" "materialize_instance" {

I put a placeholder in the next paragraph as v3.0.15 😄 so, can change that once things are bumped and such.

... but, pointing the module sources to a new TF version and doing the terraform init && terraform plan && terraform apply upgrades the orchestrator version and not the materialize version.
Should we flag this?

• that you're going to end up upgrading your orchestrator version to whatever default is in new version ?

Q: Do we know how people have been updating their TFs?

That is, are we assuming they do git pull and handle conflicts?

Note: Need the actual version ; otherwise, they would get the undeclared variable message.

Same error as a clean install of v1:

│ Error: materialize-environment/main failed to create kubernetes rest client for update of resource: resource [materialize.cloud/v1/Materialize] isn't valid for cluster, check the APIVersion and Kind fields are valid
│
│  with module.materialize_instance.kubectl_manifest.materialize_instance,
│  on .terraform/modules/materialize_instance/kubernetes/modules/materialize-instance/main.tf line 29, in resource "kubectl_manifest" "materialize_instance":
│  29: resource "kubectl_manifest" "materialize_instance" {