Skip to content

Introduce v1alpha2 of the Materialize CRD#35418

Open
alex-hunt-materialize wants to merge 1 commit intoMaterializeInc:mainfrom
alex-hunt-materialize:v1alpha2_crd_only
Open

Introduce v1alpha2 of the Materialize CRD#35418
alex-hunt-materialize wants to merge 1 commit intoMaterializeInc:mainfrom
alex-hunt-materialize:v1alpha2_crd_only

Conversation

@alex-hunt-materialize
Copy link
Contributor

@alex-hunt-materialize alex-hunt-materialize commented Mar 11, 2026

Adds a new v1alpha2 version of the Materialize CRD, and a conversion webhook in orchestratord to convert between the two versions.

This new CRD version removes the requestRollout field, in favor of calculating a hash of a subset of fields to determine when we need to trigger a rollout.

We still keep v1alpha1 as the storage version, and still reconcile v1alpha1 in orchestratord. This should be backwards compatible with most existing automation.

The new v1alpha2 behavior is opt-in when applying using a v1alpha2 CR. Since v1alpha1 is the storage and reconciliation version, it gets converted to v1alpha1 by the conversion webhook. By injecting the requestRollout field using a v5 (deterministic) UUID based on the hash during the conversion, we can immediately trigger a rollout (v1alpha2 intended behavior) in v1alpha1 when the hash changes, while applying the same value (avoiding unintended rollouts) when the hash has not changed.

The only user-visible change in behavior is if they attempt to get CRs without specifying the version. They will get back the v1alpha2 CR in that case, as it is the highest version. They can work around this by requesting the v1alpha1 CR specifically instead.

Separate documentation PR is at #35508

Cloud companion PR is at https://github.com/MaterializeInc/cloud/pull/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 a new Orchestratord v1alpha2 opt-in test to the orchestratord nightlies, and verified the existing v1alpha1 tests still worked.

Deployed https://github.com/MaterializeInc/cloud/pull/12275 in a personal stack to validate that this works for SaaS at v1alpha1.

@github-actions
Copy link

github-actions bot commented Mar 11, 2026

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 alex-hunt-materialize force-pushed the v1alpha2_crd_only branch 16 times, most recently from d7820a1 to 7714f2e Compare March 16, 2026 15:54
This was referenced Mar 16, 2026
@alex-hunt-materialize alex-hunt-materialize marked this pull request as ready for review March 17, 2026 11:41
@alex-hunt-materialize alex-hunt-materialize requested review from a team as code owners March 17, 2026 11:41
@alex-hunt-materialize alex-hunt-materialize changed the title V1alpha2 crd only Introduce v1alpha2 of the Materialize CRD Mar 17, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant