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

Document the changes introduced in #35418.

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

Adds a new `v1` version of the Materialize CRD, and a conversion webhook in orchestratord to convert between `v1` and `v1alpha1`. The `v1` CRD removes the `requestRollout` field in favor of calculating a hash over a subset of spec fields to determine when a rollout is needed. `v1alpha1` remains the storage version, and orchestratord still reconciles `v1alpha1`, so this is backwards compatible with existing automation. When a `v1` CR is applied, the conversion webhook converts it to `v1alpha1`, injecting a `requestRollout` UUID derived deterministically (UUIDv5) from the spec hash: when the hash changes a rollout is triggered immediately (the intended `v1` behavior), and when it hasn't, the same UUID is produced and no unintended rollout occurs. The whole thing is opt-in: - The `v1` CRD and the conversion webhook are only installed when the `operator.args.installV1CRD` helm value is set (`--install-v1-crd`). Without it, only `v1alpha1` is registered, no webhook serving certificate or service is created, and cert-manager is not required. - Even with `installV1CRD` set, existing `v1alpha1` CRs behave exactly as before; users switch individual instances by applying a `v1` CR. The webhook serving certificate is issued from a long-lived root CA (via an intermediate cert-manager issuer), so routine serving-certificate rotations don't invalidate the CA bundle registered in the CRD. orchestratord periodically reloads the certificate from disk (`--webhook-cert-reload-interval`) and re-registers the CRDs with the new CA bundle if the CA itself ever changes. Separate documentation PR is at #35508 Cloud companion PR is at MaterializeInc/cloud#12275 ### Motivation Simplifying rollout behavior. Part of https://linear.app/materializeinc/issue/DEP-7/design-simplifying-upgrade-rollouts-node-rolls-converted-to-project ### Verification Added orchestratord nightly tests for the `v1` opt-in flow, webhook certificate rotation (including CA rotation and CRD re-registration), manual promotion, and CRD version checks asserting that `v1` and the conversion webhook are installed if and only if `installV1CRD` is set. Verified the existing `v1alpha1` tests still pass. Deployed MaterializeInc/cloud#12275 in a personal stack to validate that this works for SaaS at `v1alpha1`.

alex-hunt-materialize · 2026-06-23T11:55:53Z

+module "materialize_instance" {
+  source = "../kubernetes/modules/materialize-instance"
+
+  crd_version        = "v1"


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

val's gonna take lead here!

val-materialize

Took a pass through the docs against the rendered preview and the generated v1 CRD schema. Overall this is a clear, well-structured set of pages — splitting v1 / v1alpha1 / switching is a real improvement.

I left 6 inline comments: 2 small fixes with suggestions (the rolloutStrategy comment missing ManuallyPromote on both pages, and a forceRollout field-name typo on the v1alpha1 page), and 3 questions to confirm before merge (hash-over-spec wording, whether the kubectl patch apiVersion switch actually works, and the requestedRolloutHash status field name). Verified separately and looking good: the v1 spec correctly drops requestRollout/inPlaceRollout, the anchor links resolve, and the legacy-Terraform migration links all resolve.

(Note: this review was prepared with Claude assistance.)

val-materialize · 2026-06-23T21:14:35Z

+  requestRollout: 22222222-2222-2222-2222-222222222222    # Use a new UUID
+  forceRollout: 33333333-3333-3333-3333-333333333333      # Optional: for forced rollouts
+  inPlaceRollout: false                                   # In Place rollout is deprecated and ignored. Please use rolloutStrategy
+  rolloutStrategy: WaitUntilReady                         # The mechanism to use when rolling out the new version. Can be WaitUntilReady or ImmediatelyPromoteCausingDowntime


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

Suggested change

rolloutStrategy: WaitUntilReady # The mechanism to use when rolling out the new version. Can be WaitUntilReady or ImmediatelyPromoteCausingDowntime

rolloutStrategy: WaitUntilReady # The mechanism to use when rolling out the new version. Can be WaitUntilReady, ImmediatelyPromoteCausingDowntime, or ManuallyPromote

val-materialize · 2026-06-23T21:17:26Z

+Specify a new `UUID` value for `forcedRollout` to roll out even when there are
+no changes to the instance. Use `forcedRollout` with `requestRollout`.


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.

Suggested change

Specify a new `UUID` value for `forcedRollout` to roll out even when there are

no changes to the instance. Use `forcedRollout` with `requestRollout`.

Specify a new `UUID` value for `forceRollout` to roll out even when there are

no changes to the instance. Use `forceRollout` with `requestRollout`.

val-materialize · 2026-06-23T21:18:31Z

+
+To minimize downtime, wait until the new generation has fully hydrated and caught up to the prior generation before promoting. To check hydration status, inspect the `UpToDate` condition in the Materialize resource status. When hydration completes, the condition will be `ReadyToPromote`.
+
+To promote, update the `forcePromote` field to match the `requestedRolloutHash` field in the Materialize status. If you need to promote before hydration completes, you can set `forcePromote` immediately, but clients may experience downtime.


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.

val-materialize · 2026-06-23T21:19:27Z

+spec:
+  environmentdImageRef: materialize/environmentd:{{< self-managed/versions/get-latest-version >}} # Update version as needed
+  forceRollout: 33333333-3333-3333-3333-333333333333      # Optional: for forced rollouts
+  rolloutStrategy: WaitUntilReady                         # The mechanism to use when rolling out the new version. Can be WaitUntilReady or ImmediatelyPromoteCausingDowntime


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

Suggested change

rolloutStrategy: WaitUntilReady # The mechanism to use when rolling out the new version. Can be WaitUntilReady or ImmediatelyPromoteCausingDowntime

rolloutStrategy: WaitUntilReady # The mechanism to use when rolling out the new version. Can be WaitUntilReady, ImmediatelyPromoteCausingDowntime, or ManuallyPromote

val-materialize · 2026-06-23T21:21:36Z

+
+### How it works
+
+The v1alpha1 CRD remains the storage version. When you submit a v1 CR, the operator's conversion webhook automatically converts it to v1alpha1 for storage. During conversion, the webhook computes a SHA256 hash of the spec and derives a deterministic `requestRollout` UUID from it. This means:


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.

val-materialize · 2026-06-23T21:22:49Z

+EOF
+```
+
+Or patch the API version on an existing CR:


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.

kay-kim · 2026-06-23T18:22:23Z

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


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.

kay-kim · 2026-06-24T02:27:58Z

 - **More efficient source ingestion batching**: Sources now batch writes more effectively. This can result in improved freshness and lower resource utilization, especially when a source is doing a large number of writes.
 - **CloudSQL HA failover support** (<red>*Materialize Self-Managed only*</red>): Materialize Self-Managed now offers better support for handling failovers in CloudSQL HA sources, without downtime. [Contact our support team](/support/) to enable this in your environment.
- **Manual Promotion** (<red>*Materialize Self-Managed only*</red>): [Rollout strategies](/self-managed-deployments/upgrading/#rollout-strategies) allow you control how Materialize transitions from the current generation to a new generation during an upgrade. We've added a new rollout strategy called `ManuallyPromote` which allows you to choose when to promote the new generation. This means that you can minimize the impact of potential downtime.
+- **Manual Promotion** (<red>*Materialize Self-Managed only*</red>): [Rollout strategies](/self-managed-deployments/upgrading/materialize-instances/v1/#rollout-strategies) allow you control how Materialize transitions from the current generation to a new generation during an upgrade. We've added a new rollout strategy called `ManuallyPromote` which allows you to choose when to promote the new generation. This means that you can minimize the impact of potential downtime.


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.

kay-kim · 2026-06-24T02:30:44Z

       Materialize instances.

- name: upgrade-materialize-instance
+- name: upgrade-materialize-instance-v1alpha1


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)

…ions Addresses the latest review round (Val, Kay, def-) on MaterializeInc#35508. Correctness fixes: - Rollout hash covers a subset of spec fields (not the whole spec); document which fields are included/excluded (balancerd/console reconcile in place). - Note that adopting v1 on an existing v1alpha1 instance typically triggers one rollout (the hash-derived requestRollout differs from the prior hand-set one). - Fix ManuallyPromote/forcePromote guidance: forcePromote matches status.requestedRolloutHash in v1, requestRollout in v1alpha1. Fixed in the shared MaterializeRolloutStrategy doc comment and regenerated the CRD description JSON for both versions. - Drop the kubectl-patch-apiVersion "switch" example (a no-op; the stored version stays v1alpha1) in favor of full applies. - Use `terraform init` instead of `terraform init -upgrade` to avoid bumping unrelated providers/modules. Restructure: - Consolidate the per-version Upgrading Materialize Instances pages back onto the Upgrading landing page (concepts: adopting v1, rollout configuration, rollout strategies, verifying, cancelling) and into the per-environment guides (Kind, AWS, Azure, GCP), matching main's structure. Delete the v1/v1alpha1 instance subpages and repoint all inbound links to the landing anchors. Consistency: - Reorder/relabel all v1alpha1/v1 tabs (v1alpha1 first, no version parentheses) and factor the repeated blurb into a shared partial/shortcode. - Add optional v1-enablement tabs to the Kind install and the operator-upgrade step (Kind + cloud guides); make cert-manager a regular Kind install step. - Bump hardcoded image versions to the version shortcode; rename the "switching" section to "Adopting the v1 CRD". Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

alex-hunt-materialize · 2026-06-24T15:57:44Z

@kay-kim and @val-materialize I think I've addressed all your comments. I've done a significant refactor, moving almost everything into tabs or into the root upgrade page.

kay-kim

Hey Alex -- thanks ever so much for this. ❤️❤️❤️

I don't see any of our terraform install tutorials optionally turning this on. I can take over from here to make that and any other changes. But, before I do ... 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?)

alex-hunt-materialize · 2026-06-25T10:36:00Z

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.

I figured we'd also follow up quickly with a major bump of the TF to change the default for that variable. Then all they would need to do is update to the latest TF code.

val-materialize

Reviewed this round (install/upgrade pages + shortcodes) against the rendered preview. Reads well for customers and the FE templates are clean — the variable tables, relabeled "CRD v1alpha1"/"CRD v1" tabs, simplified local-kind flow, and clearer cert-manager step are all nice improvements, and the new anchors (#adopting-the-v1-crd, #install-cert-manager) resolve.

Three small things, none blocking: a version-gating sanity check on the local-kind helm example, a suggestion to reassure readers that the Terraform module handles cert-manager when they pick v1, and a one-click grammar fix. Details inline.

(Note: this review was prepared with Claude assistance.)

…ions Addresses the latest review round (Val, Kay, def-) on MaterializeInc#35508. Correctness fixes: - Rollout hash covers a subset of spec fields (not the whole spec); document which fields are included/excluded (balancerd/console reconcile in place). - Note that adopting v1 on an existing v1alpha1 instance typically triggers one rollout (the hash-derived requestRollout differs from the prior hand-set one). - Fix ManuallyPromote/forcePromote guidance: forcePromote matches status.requestedRolloutHash in v1, requestRollout in v1alpha1. Fixed in the shared MaterializeRolloutStrategy doc comment and regenerated the CRD description JSON for both versions. - Drop the kubectl-patch-apiVersion "switch" example (a no-op; the stored version stays v1alpha1) in favor of full applies. - Use `terraform init` instead of `terraform init -upgrade` to avoid bumping unrelated providers/modules. Restructure: - Consolidate the per-version Upgrading Materialize Instances pages back onto the Upgrading landing page (concepts: adopting v1, rollout configuration, rollout strategies, verifying, cancelling) and into the per-environment guides (Kind, AWS, Azure, GCP), matching main's structure. Delete the v1/v1alpha1 instance subpages and repoint all inbound links to the landing anchors. Consistency: - Reorder/relabel all v1alpha1/v1 tabs (v1alpha1 first, no version parentheses) and factor the repeated blurb into a shared partial/shortcode. - Add optional v1-enablement tabs to the Kind install and the operator-upgrade step (Kind + cloud guides); make cert-manager a regular Kind install step. - Bump hardcoded image versions to the version shortcode; rename the "switching" section to "Adopting the v1 CRD". Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

…-kind.md Co-authored-by: val-materialize <valerie.chiang@materialize.com>

kay-kim · 2026-06-26T19:41:20Z

   name_prefix         = "simple-demo"
   location            = "westus2"
   license_key         = "your-materialize-license-key"
+   crd_version = "v1"   # Recommended. Default is v1alpha1; v1 is available starting in Materialize v26.30.


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" {

kay-kim · 2026-06-26T19:46:47Z

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


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

kay-kim · 2026-06-26T19:50:02Z

+handled for you automatically.
+
+Update each module's `source` to point to the new release tag (v3.0.15 or
+greater), then run `terraform init && terraform plan && terraform apply`. To


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

kay-kim · 2026-06-26T19:58:52Z

+<div class="tab-content">
+<div class="tab-pane" title="Supported Terraform" id="upgrade-supported-terraform">
+
+If you are using the [supported Terraform


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

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

kay-kim · 2026-06-26T19:59:34Z

+
+## Using Terraform
+
+If you are managing your Materialize instance with the [Materialize Terraform


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

kay-kim · 2026-06-26T20:01:03Z

+
+```hcl
+crd_version     = "v1"
+request_rollout = null


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" {

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

Merged

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 previously requested changes Apr 6, 2026

View reviewed changes

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

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

alex-hunt-materialize force-pushed the v1alpha2_crd_only_docs branch 7 times, most recently from be46642 to 05ccb69 Compare June 23, 2026 11:45

alex-hunt-materialize marked this pull request as ready for review June 23, 2026 11:51

alex-hunt-materialize requested review from a team as code owners June 23, 2026 11:51

alex-hunt-materialize requested a review from bobbyiliev June 23, 2026 11:51

alex-hunt-materialize commented Jun 23, 2026

View reviewed changes

val-materialize reviewed Jun 23, 2026

View reviewed changes

kay-kim reviewed Jun 24, 2026

View reviewed changes

def- reviewed Jun 24, 2026

View reviewed changes

Comment thread doc/user/data/self_managed/materialize_crd_descriptions_v1.json Outdated

alex-hunt-materialize marked this pull request as draft June 24, 2026 14:45

alex-hunt-materialize force-pushed the v1alpha2_crd_only_docs branch from 77d4a86 to f317ff0 Compare June 24, 2026 15:43

alex-hunt-materialize marked this pull request as ready for review June 24, 2026 15:54

alex-hunt-materialize requested review from kay-kim and val-materialize June 24, 2026 15:55

kay-kim reviewed Jun 25, 2026

View reviewed changes

val-materialize reviewed Jun 25, 2026

View reviewed changes

Comment thread doc/user/content/self-managed-deployments/upgrading/upgrade-on-kind.md Outdated

Comment thread doc/user/data/self_managed/installation.yml

alex-hunt-materialize and others added 4 commits June 25, 2026 17:47

update docs for Materialize CRD v1

d9714d0

Tweaks to install and upgrade guides

b279f04

Update doc/user/content/self-managed-deployments/upgrading/upgrade-on…

4127a12

…-kind.md Co-authored-by: val-materialize <valerie.chiang@materialize.com>

kay-kim force-pushed the v1alpha2_crd_only_docs branch from ff812ab to 4127a12 Compare June 25, 2026 21:49

kay-kim added 2 commits June 25, 2026 20:37

small reorg

183b8fb

reorg of v1 prereqs

605d2b8

kay-kim reviewed Jun 26, 2026

View reviewed changes

		@@ -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

	rolloutStrategy: WaitUntilReady # The mechanism to use when rolling out the new version. Can be WaitUntilReady or ImmediatelyPromoteCausingDowntime
	rolloutStrategy: WaitUntilReady # The mechanism to use when rolling out the new version. Can be WaitUntilReady, ImmediatelyPromoteCausingDowntime, or ManuallyPromote

		Specify a new `UUID` value for `forcedRollout` to roll out even when there are
		no changes to the instance. Use `forcedRollout` with `requestRollout`.


		To minimize downtime, wait until the new generation has fully hydrated and caught up to the prior generation before promoting. To check hydration status, inspect the `UpToDate` condition in the Materialize resource status. When hydration completes, the condition will be `ReadyToPromote`.

		To promote, update the `forcePromote` field to match the `requestedRolloutHash` field in the Materialize status. If you need to promote before hydration completes, you can set `forcePromote` immediately, but clients may experience downtime.


		### How it works

		The v1alpha1 CRD remains the storage version. When you submit a v1 CR, the operator's conversion webhook automatically converts it to v1alpha1 for storage. During conversion, the webhook computes a SHA256 hash of the spec and derives a deterministic `requestRollout` UUID from it. This means:


		## Using Terraform

		If you are managing your Materialize instance with the [Materialize Terraform

Uh oh!

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!

Choose a reason for hiding this comment

Uh oh!

val-materialize 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!

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 Jun 24, 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!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

alex-hunt-materialize Jun 24, 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!

Choose a reason for hiding this comment

Uh oh!

kay-kim Jun 24, 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!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

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

alex-hunt-materialize Jun 24, 2026 •

edited

Loading

alex-hunt-materialize Jun 24, 2026 •

edited

Loading

kay-kim Jun 24, 2026 •

edited

Loading

kay-kim Jun 26, 2026 •

edited

Loading