Skip to content

docs: Add instructions for cancelling an in-progress rollout #34226

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
+22 −0
Open

docs: Add instructions for cancelling an in-progress rollout #34226

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
ab76972
docs: Add instructions for cancelling an in-progress rollout
SangJunBak Nov 20, 2025
0283767
docs: Clarify instructions for cancelling an in-progress rollout
SangJunBak Nov 21, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 23 additions & 0 deletions doc/user/content/installation/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -175,6 +175,29 @@ kubectl get materialize -n materialize-environment -w
# Check the logs of the operator
kubectl logs -l app.kubernetes.io/name=materialize-operator -n materialize
```

### Cancelling the Upgrade
To cancel an in-progress rollout and revert to the last completed rollout state, first retrieve the last rollout request ID from your Materialize CR. You can do this with the following command:

```shell
kubectl get materialize <instance-name> -n materialize-environment -o jsonpath='{.status.lastCompletedRolloutRequest}'
```

Next, get the previous `environmentdImageRef` from the `last-applied-configuration` annotation:
```shell
kubectl get materialize <instance-name> -n materialize-environment -o jsonpath='{.metadata.annotations.kubectl\.kubernetes\.io/last-applied-configuration}'
```
Finally, run the following command using the values obtained above:

```shell
kubectl patch materialize <instance-name> \
-n materialize-environment \
--type='merge' \
-p "{\"spec\": {\"requestRollout\": \"<lastCompletedRolloutRequest-value>\", \"environmentdImageRef\": \"<previous-environmentdImageRef>\" }}"
```
Comment on lines 179 to 196
Copy link
Contributor

@jubrad jubrad Nov 20, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In general I like the idea of having examples, but I also think we need to also make sure we're providing adequate context on the interfaces we're providing. People are going to deploy this through terraform, kustomize, pulumi, and who knows what else.

I would keep what we have here, but also talk about this a bit more in the context of the Materialize spec, when in the rollout one might want to use this (and why). I also am not sure about this process. We don't support downgrade so we need to make sure we're not rolling back a completed upgrade.

Copy link
Contributor Author

@SangJunBak SangJunBak Nov 20, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I also am not sure about this process. We don't support downgrade so we need to make sure we're not rolling back a completed upgrade.

This makes sense to me! Given the rollout request goes back to the one for the last successful upgrade however, wouldn't it not try to initiate a new rollout?

Copy link
Contributor Author

@SangJunBak SangJunBak Nov 20, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I also am not sure about this process.

These are the instructions @doy-materialize gave me too. But what's the correct process here?

Copy link
Contributor

@doy-materialize doy-materialize Nov 20, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

i think i would probably just not try to restore environmentdImageRef or anything like that - there are a lot of different things that could have changed other than the version, and the specific changes don't really have anything to do with cancelling the rollout. i would just give instructions on how to restore the requestRollout field and leave it at that.

Copy link
Contributor

@jubrad jubrad Nov 21, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think if someone wanted to revert to the prior version the only way it would be safe is to first revert requestRollout then revert the environmentdImageRef, but it's probably fine to just show how to cancel without reverting this.

Copy link
Contributor

@doy-materialize doy-materialize Nov 21, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

not reverting environmentdImageRef wouldn't be unsafe - it won't try doing the upgrade again unless they explicitly trigger it

Copy link
Contributor Author

@SangJunBak SangJunBak Nov 21, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Change is here 0283767. However I think I added this instruction because if you were to just reset the requestRollout field in upgrade-materialize.yaml but keep the environmentdImageRef you tried to update with, then it doesn't fully go back to the original state. Notably the balancerd pods don't get cleaned up:

Screenshot 2025-11-21 at 4 39 36 PM

But this might just be a bug w/ orchestratord

Copy link
Contributor

@doy-materialize doy-materialize Nov 21, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

oh, yeah, that's just a bug - i'm currently rewriting how balancerd gets deployed, i'll make sure to fix that as part of this




### Version Specific Upgrade Notes

#### Upgrading to `v26.0`
Expand Down