docs(tutorials): add progressive rollout strategies tutorial#997
docs(tutorials): add progressive rollout strategies tutorial#997unixsurfer wants to merge 3 commits into
Conversation
karmada-bot
added
kind/documentation
|
[APPROVALNOTIFIER] This PR is NOT APPROVED This pull-request has been approved by: The full list of commands accepted by this bot can be found here. DetailsNeeds approval from an approver in each of these files:Approvers can indicate their approval by writing |
|
Welcome @unixsurfer! It looks like this is your first PR to karmada-io/website 🎉 |
karmada-bot
added
the
size/XXL
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces a new tutorial document, karmada-primitive-rollout-strategies.md, which provides a detailed guide on implementing Canary, Rolling Upgrade, and Wave Rollout strategies using Karmada's native PropagationPolicy and OverridePolicy. The changes also include an update to sidebars.js to integrate the new tutorial into the documentation site. The review feedback focuses on improving the tutorial's completeness by adding missing prerequisites (git, python3) and dependency installation steps for the dashboard, enhancing long-term maintainability by suggesting the use of official image repositories, and ensuring linguistic consistency by standardizing on American English spelling for terms like 'finalize'.
karmada-bot
added
the
do-not-merge/invalid-commit-message
karmada-bot
removed
the
do-not-merge/work-in-progress
unixsurfer
force-pushed
the
tutorial/primitive-rollout-strategies
branch
from
b170b7d to
4b5bbe1
Compare
karmada-bot
removed
the
do-not-merge/invalid-commit-message
|
Thanks for the PR, @unixsurfer — really appreciate it. |
zhzhuang-zju
left a comment
zhzhuang-zju
left a comment
There was a problem hiding this comment.
Thanks @unixsurfer , this is a huge and valuable piece of work. I’ve also learned a lot during the review process. It’s amazing that we can combine PropagationPolicy and OverridePolicy to implement so many interesting capabilities.
I’ve left a few comments, and I hope we can keep discussing further :)
|
@zhzhuang-zju Thank you for taking the time to review and provide actionable feedback. To make reviewing the fixes easier, I have made distinct commits for each review point and linked the commit URLs in the relevant threads. I will squash all of these commits as soon as you confirm that they address your feedback. Additionally, to address this comment, I need to refactor the file locations. Therefore, I will push one more commit shortly. |
zhzhuang-zju
left a comment
zhzhuang-zju
left a comment
There was a problem hiding this comment.
Thanks, others LGTM
|
@zhzhuang-zju I have addressed all your latest review comments. |
RainbowMango
left a comment
RainbowMango
left a comment
There was a problem hiding this comment.
Good Job @unixsurfer ! We've been planning to summarize the rollout strategies in the industry and figure out how to provide better support for them within Karmada.
I've done a quick first pass today and will continue reviewing in more detail. In the meantime, would you be interested in presenting this at one of our community meetings? It would be great to share these strategies with the broader community.
Great idea:-) I would be more than happy to present this, along with the upcoming PR for Argo Rollouts integration with Karmada, at a community meeting. Let me know what the next steps are to get this scheduled. |
|
@unixsurfer, we have bi-weekly community meetings. You can pick whichever time slot works best for you and add an agenda item to the meeting notes. Feel free to join anytime, looking forward to seeing you again there! |
|
Hi @unixsurfer, thanks for your work. I have no other comments. Please fix the DCO CI failure and squash your commit~ |
…torial Add a new "Progressive Rollout Strategies" sidebar category under Tutorials, together with the overview landing page and the first strategy tutorial — Side-by-Side Testing (Canary). The sidebar category (sidebars.js) groups rollout strategy pages under tutorials/rollout/ and will be extended by follow-up commits. The overview page (tutorials/rollout/overview) introduces all three strategies, lists shared prerequisites (Karmada control plane, kubectl, git, python3), explains how version changes are simulated via the ROLLOUT_LABEL environment variable, and documents the shared setup steps: ingress-nginx installation across member clusters, http-probe-app deployment with divided replica scheduling, port-forward setup for local traffic access, and optional karmada-multicluster-dashboard launch for real-time observation. The canary tutorial (tutorials/rollout/canary) covers three demos: - Demo 1: single-cluster canary on member1, promote the base Deployment via OverridePolicy, region-wide finalization with zero pod churn on the already-promoted cluster. - Demo 2: region-wide canary across all three clusters, per-cluster promotion by progressively expanding the OverridePolicy clusterNames list, finalization with zero churn across the region. - Demo 3: selective canary on member1 and member2 (member3 skipped), canary rollback on member2, redeploy, promote member2 only, roll back the promotion, roll back all remaining canaries — exercising every primitive operation. Each demo includes a Mermaid sequence diagram, inline YAML manifests inside collapsible <details> blocks, kubectl commands with expected output, and dashboard observation notes for the replica and traffic panels. A dashboard screenshot (static/img/tutorials/rollout/dashboard-initial-state.png) is added to accompany the overview setup section. Signed-off-by: Pavlos Parissis <pavlos.parissis@gmail.com>
Add the second progressive rollout strategy tutorial — In-place Updates (Rolling Upgrade) — and extend the sidebar category to include it. The rolling upgrade tutorial (tutorials/rollout/rolling-upgrade) demonstrates how to upgrade the base Deployment cluster by cluster using an OverridePolicy named http-probe-rolling-upgrade, leveraging native Kubernetes rolling update semantics (maxUnavailable: 0, maxSurge: 1) without deploying a separate canary Deployment. The key distinction from the canary strategy is that no additional Deployment is created — the base Deployment is patched in place on each target cluster. The OverridePolicy name differs from the canary promote policy (http-probe-promote-override) so both strategies can coexist and be applied to different clusters simultaneously. Two demos are provided: - Demo 1: apply a rolling-upgrade OverridePolicy to member1 and observe the in-place roll, extend the policy to member2 and then to all three clusters, finalize by updating the base manifest to v2 and deleting the OverridePolicy (zero pod churn on clusters already at v2). - Demo 2: apply the rolling-upgrade OverridePolicy to member1, then roll back by deleting the OverridePolicy before extending to other clusters — the base Deployment on member1 reverts to v1 with no impact on member2 or member3. Each demo includes a Mermaid sequence diagram, inline YAML manifests, kubectl commands with expected output, and dashboard observation notes for the replica and traffic panels. Signed-off-by: Pavlos Parissis <pavlos.parissis@gmail.com>
Add the third and final progressive rollout strategy tutorial — Percentage-based Shifting (Wave Rollout) — and extend the sidebar category to include it, completing the Progressive Rollout Strategies section. The wave rollout tutorial (tutorials/rollout/wave-rollout) demonstrates how to shift traffic progressively between two Deployments (the stable base and a new wave Deployment) by adjusting replica counts via OverridePolicy, achieving approximate percentage-based traffic migration without ingress weight annotations. The orchestration is handled by hack/wave-rollout.sh (from the companion karmada-io/karmada PR #7425). A shell script is used rather than static manifests because the OverridePolicy replica counts must be computed at runtime from the target percentage and the replicas-per-cluster value. The script accepts a target cluster list and a comma-separated list of percentage steps (e.g. 25,50,100) and prints every manifest it applies so the operator can follow each step in real time. Two demos are provided: - Demo 1: wave rollout on member1 through steps 25% → 50% → 100%, then finalize — updates the base manifest to v2 and propagates it to all clusters, causing member2 and member3 to roll in place via a standard rolling update while member1 transitions cleanly from the wave Deployment to the updated base. - Demo 2: wave rollout across all three clusters simultaneously through steps 25% → 50% → 100%, then abort — restores the base replica count and removes all wave resources, returning the region to v1 without changing the base manifest version. Each demo includes a Mermaid sequence diagram, hack/wave-rollout.sh invocations, and dashboard observation notes for each percentage step and for the finalize/abort operations. Signed-off-by: Pavlos Parissis <pavlos.parissis@gmail.com>
unixsurfer
force-pushed
the
tutorial/primitive-rollout-strategies
branch
from
03b3b46 to
74a13c9
Compare
I have fixed the DCO CI failure and pushed 3 commits (one per tutorial). Please note that this PR depends on files introduced in PR #7425, so that PR will need to be merged before this one can go in |
4 participants
What type of PR is this?
/kind documentation
What this PR does / why we need it:
Adds a new tutorial covering three progressive rollout strategies for multi-cluster deployments using Karmada primitives (PropagationPolicy and OverridePolicy) — no additional controllers required.
Strategy 1 — Side-by-Side Testing (Canary):
Strategy 2 — In-place Updates (Rolling Upgrade):
Strategy 3 — Percentage-based Shifting (Wave Rollout):
Each strategy includes inline YAML manifests, plain kubectl commands, Mermaid sequence diagrams, and dashboard observation notes describing what readers should see in the replica and traffic panels at each step.
The wave rollout strategy is orchestrated by hack/wave-rollout.sh (in the karmada repo PR) — a shell script rather than static manifests because the OverridePolicy replica counts must be computed at runtime from the target percentage and replicas-per-cluster value. All other strategies use only static YAML files from samples/progressive-rollout/.
Manifests referenced in this tutorial are submitted in a companion PR to karmada-io/karmada under samples/progressive-rollout directory.
Which issue(s) this PR fixes:
None
Special notes for your reviewer: