Simplified rollout triggers and CRD design doc by alex-hunt-materialize · Pull Request #34959 · MaterializeInc/materialize

alex-hunt-materialize · 2026-02-09T16:52:54Z

Simplified rollout triggers and CRD design doc

Motivation

This PR adds a known-desirable feature.
Part of https://linear.app/materializeinc/issue/DEP-7/design-simplifying-upgrade-rollouts-node-rolls-converted-to-project

Tips for reviewer

Checklist

This PR has adequate test coverage / QA involvement has been duly considered. (trigger-ci for additional test/nightly runs)
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).
If this PR includes major user-facing behavior changes, I have pinged the relevant PM to schedule a changelog post.

doc/developer/design/20260209_simplified_rollout_triggers_and_crd.md

bobbyiliev · 2026-02-16T18:41:38Z

doc/developer/design/20260209_simplified_rollout_triggers_and_crd.md

+###### v1alpha1 to v1alpha2:
+- Spec fields:
+    - `forcePromote: Uuid` becomes `forcePromote: Option<String>` (nil UUID becomes None)
+    - `requestRollout` is removed.
+- Status fields:
+    - `lastCompletedRolloutRequest` and `resourcesHash` are removed.
+    - If `lastCompletedRolloutRequest` and `spec.requestRollout` match:
+        - This means we weren't in the middle of a rollout.
+        - `lastCompletedRolloutHash` and `requestedRolloutHash` should both be set to the calculated hash (after conversion). This should avoid triggering a rollout during the migration.
+    - Else:
+        - `lastCompletedRolloutHash` should be set to `None` and `requestedRolloutHash` should be set to the calculated hash (after conversion). In this case, we likely have an in-progress rollout, which we will destroy and replace.


If I'm reading this right, when lastCompletedRolloutRequest != spec.requestRollout, the conversion sets lastCompletedRolloutHash to None, which would restart the rollout from scratch. What we might want to consider is what happens if the existing rollout is already partway through promoting when the orchestratord upgrade happens?

If we're in promoting status, we unconditionally call the promotion for the current rollout. After updating the status after completing promotion, if anything is changed, it should trigger another rollout.

I'm pretty sure this does the right thing as-is, but this is probably something we want to write a test for.

I'll update the doc to call this out.

@doy-materialize I've just pushed an update that addresses Bobby's feedback. As I was working my way through the promoting status scenario, I realized that maybe we need to have status.requestedRolloutHash be an Option. In cases where we're converting and the v1alpha1 is mid-rollout and already promoting, we don't want to set status.requestedRolloutHash to the current calculated hash. We have no way of knowing the hash of the spec that reached promoting status, so we should set it to None.

doc/developer/design/20260209_simplified_rollout_triggers_and_crd.md

…moting"

bobbyiliev

This looks good to me! Will leave the final check to @doy-materialize, though.

maheshwarip · 2026-02-20T15:04:44Z

doc/developer/design/20260209_simplified_rollout_triggers_and_crd.md

+Introduce a new `v1alpha2` version of the Materialize CRD with the following changes:
+
+**Spec changes:**
+- Remove `requestRollout` (`Uuid`) - Rollouts are now triggered automatically when the spec hash changes.


Nice! this has always bugged me

maheshwarip · 2026-02-20T15:08:09Z

doc/developer/design/20260209_simplified_rollout_triggers_and_crd.md

+
+The `forcePromote` field is excluded, since it is used to promote the existing generation, and we don't want to tear that down every time it changes.
+
+Fields **included** in the hash (changes trigger rollout):


We know this, so just commenting for completeness sake: whenever we build this, we should add this info into the docs

Simplified rollout triggers and CRD design doc ### Motivation * This PR adds a known-desirable feature. Part of https://linear.app/materializeinc/issue/DEP-7/design-simplifying-upgrade-rollouts-node-rolls-converted-to-project ### Tips for reviewer  ### Checklist - [x] This PR has adequate test coverage / QA involvement has been duly considered. ([trigger-ci for additional test/nightly runs](https://trigger-ci.dev.materialize.com/)) - [x] This PR has an associated up-to-date [design doc](https://github.com/MaterializeInc/materialize/blob/main/doc/developer/design/README.md), is a design doc ([template](https://github.com/MaterializeInc/materialize/blob/main/doc/developer/design/00000000_template.md)), or is sufficiently small to not require a design.  - [x] If this PR evolves [an existing `$T ⇔ Proto$T` mapping](https://github.com/MaterializeInc/materialize/blob/main/doc/developer/command-and-response-binary-encoding.md) (possibly in a backwards-incompatible way), then it is tagged with a `T-proto` label. - [x] 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](MaterializeInc/cloud#5021)).  - [x] If this PR includes major [user-facing behavior changes](https://github.com/MaterializeInc/materialize/blob/main/doc/developer/guide-changes.md#what-changes-require-a-release-note), I have pinged the relevant PM to schedule a changelog post.

Simplified rollout triggers and CRD design doc

cbba659

alex-hunt-materialize requested review from bobbyiliev, def-, doy-materialize, jubrad, maheshwarip and sjwiesman February 9, 2026 16:53

doy-materialize reviewed Feb 10, 2026

View reviewed changes

alex-hunt-materialize added 5 commits February 11, 2026 11:51

rename fields to not contain "Spec", and requestedRolloutHash non-option

8b16d45

note utility of certs for other uses.

91b508f

Add step to replace existing objects to update their stored version.

5c8c6b0

Update open questions to be more certain after feedback

1f754c8

notes about promoting, serviceAccountAnnotations, roundtriping

1533029

bobbyiliev reviewed Feb 16, 2026

View reviewed changes

address more feedback and add example scenarios

913ee37

alex-hunt-materialize requested review from bobbyiliev and doy-materialize February 17, 2026 11:37

Update requestedRoloutHash to Option, note about migrating while "pro…

52707df

…moting"

bobbyiliev approved these changes Feb 19, 2026

View reviewed changes

maheshwarip reviewed Feb 20, 2026

View reviewed changes

maheshwarip approved these changes Feb 20, 2026

View reviewed changes

doy-materialize approved these changes Feb 21, 2026

View reviewed changes

alex-hunt-materialize merged commit 126a556 into MaterializeInc:main Feb 23, 2026
5 checks passed

alex-hunt-materialize deleted the simplified_rollout_triggers_design_doc branch February 23, 2026 09:44


		The `forcePromote` field is excluded, since it is used to promote the existing generation, and we don't want to tear that down every time it changes.

		Fields included in the hash (changes trigger rollout):

Conversation

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

Uh oh!

Motivation

Tips for reviewer

Checklist

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

bobbyiliev Feb 16, 2026

Choose a reason for hiding this comment

Uh oh!

alex-hunt-materialize Feb 17, 2026

Choose a reason for hiding this comment

Uh oh!

alex-hunt-materialize Feb 17, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

bobbyiliev left a comment

Choose a reason for hiding this comment

Uh oh!

maheshwarip Feb 20, 2026

Choose a reason for hiding this comment

Uh oh!

maheshwarip Feb 20, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

alex-hunt-materialize commented Feb 9, 2026 •

edited

Loading