docs: document the v1 Materialize CRD and installV1CRD opt-in by alex-hunt-materialize · Pull Request #35508 · MaterializeInc/materialize

alex-hunt-materialize · 2026-03-16T15:53:55Z

Docs follow up for #35418

Motivation

Separate PR so we don't update the docs until we're ready to release.

Description

This branch is based on #35418; only the commits on top of it are the docs changes.

Documents the new v1 CRD version (hash-based rollouts, no requestRollout), which is opt-in twice over:

The operator only installs the v1 CRD and its conversion webhook when the operator.args.installV1CRD helm value is set. cert-manager (or a user-provided certificate) and API-server ingress to port 8001 are only required when opting in.
Existing v1alpha1 CRs keep working unchanged; instances are switched individually by applying a v1 CR.

Also regenerates the CRD field description data from the v1 schema and updates the crd-writer/bump-version tooling for the version rename.

github-actions · 2026-03-16T15:54:06Z

Thanks for opening this PR! Here are a few tips to help make the review process smooth for everyone.

PR title guidelines

Use imperative mood: "Fix X" not "Fixed X" or "Fixes X"
Be specific: "Fix panic in catalog sync when controller restarts" not "Fix bug" or "Update catalog code"
Prefix with area if helpful: compute: , storage: , adapter: , sql:

Pre-merge checklist

The PR title is descriptive and will make sense in the git log.
This PR has adequate test coverage / QA involvement has been duly considered. (trigger-ci for additional test/nightly runs)
If this PR includes major user-facing behavior changes, I have pinged the relevant PM to schedule a changelog post.
This PR has an associated up-to-date design doc, is a design doc (template), or is sufficiently small to not require a design.
If this PR evolves an existing $T ⇔ Proto$T mapping (possibly in a backwards-incompatible way), then it is tagged with a T-proto label.
If this PR will require changes to cloud orchestration or tests, there is a companion cloud PR to account for those changes that is tagged with the release-blocker label (example).

alex-hunt-materialize · 2026-03-16T16:28:34Z

@kay-kim I'm keeping this as a draft so we don't accidentally merge it, but it is ready for review.

I may need to rebase if something comes up in the original PR, but I think the docs commit shouldn't change.

kay-kim · 2026-03-16T16:43:35Z

Thank you!!!

alex-hunt-materialize · 2026-03-19T14:18:16Z

Note to self, we need to document how to run the new orchestratord with webhooks if they aren't using our terraform.

maheshwarip · 2026-04-06T17:59:01Z

@@ -0,0 +1,70 @@
+- v26.19.0 introduces a new `v1alpha2` version of the Materialize CRD


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.

maheshwarip · 2026-04-06T18:03:44Z

+
+{{< important >}}
+
+v26.19 requires infrastructure changes to support migration to v1alpha2 resources.


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.

maheshwarip · 2026-04-06T18:08:15Z

+
+{{< /important >}}
+
+The Materialize Operator now hosts conversion webhooks to convert between


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.

maheshwarip · 2026-04-06T18:08:52Z

+`8001` from the API server to pods with the label
+`app.kubernetes.io/name: materialize-operator`.
+
+**Kubernetes NetworkPolicy:** Add a policy that allows ingress on port


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).

The new CRD version is now called v1 instead of v1alpha2, and the operator only installs the v1 CRD and its conversion webhook when the operator.args.installV1CRD helm value is set. Update the version docs to v26.29, regenerate the CRD field descriptions from the v1 schema, and pick up the newer rollout-cancellation instructions on the v1alpha1 page. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

alex-hunt-materialize requested a review from kay-kim March 16, 2026 16:27

alex-hunt-materialize force-pushed the v1alpha2_crd_only_docs branch from d7820a1 to 731208e Compare March 17, 2026 10:56

alex-hunt-materialize mentioned this pull request Mar 17, 2026

Introduce v1 of the Materialize CRD #35418

Open

alex-hunt-materialize force-pushed the v1alpha2_crd_only_docs branch from 731208e to 5066939 Compare March 25, 2026 14:31

alex-hunt-materialize requested a review from maheshwarip March 25, 2026 14:32

alex-hunt-materialize force-pushed the v1alpha2_crd_only_docs branch from 5066939 to e7c2da3 Compare March 26, 2026 09:53

jubrad mentioned this pull request Mar 30, 2026

Add support for v1alpha2 CRD API version MaterializeInc/materialize-terraform-self-managed#179

Merged

4 tasks

maheshwarip reviewed Apr 6, 2026

View reviewed changes

maheshwarip requested changes Apr 6, 2026

View reviewed changes

alex-hunt-materialize requested a review from maheshwarip April 7, 2026 11:35

alex-hunt-materialize and others added 11 commits June 11, 2026 10:49

Materialize CRD changes to use hash of the spec

cf1ace4

Re-register CRDs when CA changes, and use intermediate issuer

b1b669a

change to v1 instead of v1alpha2 for new version of CRD

8ec3a45

Make v1 CRD and conversion webhook optional

bf9e7ba

update docs for v1alpha2

4b26a00

bump v1alpha2 release version to v27.18

d32b224

Upgrade notes about network policy and certificate changes

0c84d4b

update sm upgrade docs to provide more detail on crd version migration

e510192

Attempt to address feedback

89ff876

Separate tabs for supported terraform, legacy tf, and manual

caf8351

alex-hunt-materialize force-pushed the v1alpha2_crd_only_docs branch from 02dcdd7 to ef7d339 Compare June 11, 2026 13:08

alex-hunt-materialize changed the title ~~V1alpha2 crd only docs~~ docs: document the v1 Materialize CRD and installV1CRD opt-in Jun 11, 2026

		@@ -0,0 +1,70 @@
		- v26.19.0 introduces a new `v1alpha2` version of the Materialize CRD


		{{< important >}}

		v26.19 requires infrastructure changes to support migration to v1alpha2 resources.


		{{< /important >}}

		The Materialize Operator now hosts conversion webhooks to convert between

Conversation

alex-hunt-materialize commented Mar 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Motivation

Description

Uh oh!

github-actions Bot commented Mar 16, 2026

PR title guidelines

Pre-merge checklist

Uh oh!

alex-hunt-materialize commented Mar 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

kay-kim commented Mar 16, 2026

Uh oh!

alex-hunt-materialize commented Mar 19, 2026

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!

alex-hunt-materialize Apr 7, 2026 • 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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

alex-hunt-materialize commented Mar 16, 2026 •

edited

Loading

alex-hunt-materialize commented Mar 16, 2026 •

edited

Loading

alex-hunt-materialize Apr 7, 2026 •

edited

Loading