Skip to content

Commit 7e114fb

Browse files
haoqing0110claude
haoqing0110
and
claude
authored
docs: enhance ManifestWorkReplicaSet documentation with rollout mechanism (#524)
Signed-off-by: Qing Hao <[email protected]> Co-authored-by: Claude <[email protected]>
1 parent b110444 commit 7e114fb

File tree

1 file changed

+204
-73
lines changed

1 file changed

+204
-73
lines changed

‎content/en/docs/concepts/work-distribution/manifestworkreplicaset.md‎

Lines changed: 204 additions & 73 deletions
Original file line numberDiff line numberDiff line change
@@ -10,9 +10,69 @@ aliases:
1010

1111
## What is `ManifestWorkReplicaSet`
1212

13-
`ManifestWorkReplicaSet` is an aggregator API that uses [Manifestwork](https://github.com/open-cluster-management-io/open-cluster-management-io.github.io/blob/main/content/en/concepts/manifestwork.md) and [Placement](https://github.com/open-cluster-management-io/open-cluster-management-io.github.io/blob/main/content/en/concepts/placement.md) to create manifestwork for the placement-selected clusters.
13+
`ManifestWorkReplicaSet` is an aggregator API that uses [ManifestWork](https://open-cluster-management.io/docs/concepts/work-distribution/manifestwork/) and [Placement](https://open-cluster-management.io/docs/concepts/content-placement/placement/) to automatically create `ManifestWork` resources for clusters selected by `Placement`. It simplifies multi-cluster workload distribution by eliminating the need to manually create individual ManifestWork resources for each target cluster.
1414

15-
View an example of `ManifestWorkReplicaSet` to deploy a CronJob and Namespace for a group of clusters selected by placements.
15+
## Feature Enablement
16+
17+
`ManifestWorkReplicaSet` is in **alpha release** and is not enabled by default. To enable this feature, you must configure the cluster-manager instance on the hub cluster.
18+
19+
Edit the cluster-manager CR:
20+
21+
```shell
22+
$ oc edit ClusterManager cluster-manager
23+
```
24+
25+
Add the `workConfiguration` field to enable the ManifestWorkReplicaSet feature gate:
26+
27+
```yaml
28+
kind: ClusterManager
29+
metadata:
30+
name: cluster-manager
31+
spec:
32+
...
33+
workConfiguration:
34+
featureGates:
35+
- feature: ManifestWorkReplicaSet
36+
mode: Enable
37+
```
38+
39+
Verify the feature is enabled successfully:
40+
41+
```shell
42+
$ oc get ClusterManager cluster-manager -o yaml
43+
```
44+
45+
Confirm that the `cluster-manager-work-controller` deployment appears in the status under `status.generations`:
46+
47+
```yaml
48+
kind: ClusterManager
49+
metadata:
50+
name: cluster-manager
51+
spec:
52+
...
53+
status:
54+
...
55+
generations:
56+
...
57+
- group: apps
58+
lastGeneration: 2
59+
name: cluster-manager-work-webhook
60+
namespace: open-cluster-management-hub
61+
resource: deployments
62+
version: v1
63+
- group: apps
64+
lastGeneration: 1
65+
name: cluster-manager-work-controller
66+
namespace: open-cluster-management-hub
67+
resource: deployments
68+
version: v1
69+
```
70+
71+
## Overview
72+
73+
Here's a simple example to get started with `ManifestWorkReplicaSet`.
74+
75+
This example deploys a `CronJob` and `Namespace` to a group of clusters selected by `Placement`.
1676

1777
```yaml
1878
apiVersion: work.open-cluster-management.io/v1alpha1
@@ -25,22 +85,6 @@ spec:
2585
- name: placement-rollout-all # Name of a created Placement
2686
rolloutStrategy:
2787
type: All
28-
- name: placement-rollout-progressive # Name of a created Placement
29-
rolloutStrategy:
30-
type: Progressive
31-
progressive:
32-
minSuccessTime: 5m
33-
progressDeadline: 10m
34-
maxFailures: 5%
35-
mandatoryDecisionGroups:
36-
- groupName: "prod-canary-west"
37-
- groupName: "prod-canary-east"
38-
- name: placement-rollout-progressive-per-group # Name of a created Placement
39-
rolloutStrategy:
40-
type: ProgressivePerGroup
41-
progressivePerGroup:
42-
progressDeadline: 10m
43-
maxFailures: 2
4488
manifestWorkTemplate:
4589
deleteOption:
4690
propagationPolicy: SelectivelyOrphan
@@ -91,13 +135,150 @@ spec:
91135
- '-c'
92136
- date; echo Hello from the Kubernetes cluster
93137
```
94-
The **PlacementRefs** uses the Rollout Strategy [API](https://github.com/open-cluster-management-io/api/blob/main/cluster/v1alpha1/types_rolloutstrategy.go) to apply the manifestWork to the selected clusters.
95-
In the example above; the placementRefs refers to three placements; placement-rollout-all, placement-rollout-progressive and placement-rollout-progressive-per-group. For more info regarding the rollout strategies check the Rollout Strategy section at the [placement](https://github.com/open-cluster-management-io/open-cluster-management-io.github.io/blob/main/content/en/concepts/placement.md) document.
96-
**Note:** The placement reference must be in the same namespace as the manifestWorkReplicaSet.
138+
The `placementRefs` field uses the Rollout Strategy [API](https://github.com/open-cluster-management-io/api/blob/main/cluster/v1alpha1/types_rolloutstrategy.go) to control how `ManifestWork` resources are applied to the selected clusters.
139+
140+
In the example above, the `placementRefs` references `placement-rollout-all` with a `rolloutStrategy` of `All`, which means the workload will be deployed to all selected clusters simultaneously.
141+
142+
## Rollout Strategy
143+
144+
`ManifestWorkReplicaSet` supports three rollout strategy types to control how workloads are distributed across clusters. For detailed rollout strategy documentation, see the [Placement rollout strategy section](https://open-cluster-management.io/docs/concepts/content-placement/placement/#rollout-strategy).
145+
146+
**Note:** The placement reference must be in the same namespace as the `ManifestWorkReplicaSet`.
147+
148+
1. **All**: Deploy to all selected clusters simultaneously
149+
```yaml
150+
placementRefs:
151+
- name: placement-rollout-all # Name of a created Placement
152+
rolloutStrategy:
153+
type: All
154+
```
155+
156+
2. **Progressive**: Gradual rollout with configurable parameters
157+
```yaml
158+
placementRefs:
159+
- name: placement-rollout-progressive # Name of a created Placement
160+
rolloutStrategy:
161+
type: Progressive
162+
progressive:
163+
minSuccessTime: 5m
164+
progressDeadline: 10m
165+
maxFailures: 5%
166+
mandatoryDecisionGroups:
167+
- groupName: "prod-canary-west"
168+
- groupName: "prod-canary-east"
169+
```
170+
171+
3. **ProgressivePerGroup**: Progressive rollout per decision group
172+
```yaml
173+
placementRefs:
174+
- name: placement-rollout-progressive-per-group # Name of a created Placement
175+
rolloutStrategy:
176+
type: ProgressivePerGroup
177+
progressivePerGroup:
178+
progressDeadline: 10m
179+
maxFailures: 2
180+
```
181+
182+
## Rollout Mechanism
183+
184+
The `ManifestWorkReplicaSet` rollout process is based on the `Progressing` and `Degraded` conditions of each `ManifestWork`. These conditions are not built-in but must be defined using [Custom CEL Expressions](https://open-cluster-management.io/docs/concepts/work-distribution/manifestwork/#custom-cel-expressions) in the `manifestConfigs` section.
185+
186+
### Condition Requirements
187+
188+
- **Progressing condition (required)**: Tracks whether the ManifestWork is currently being applied to the cluster. The rollout controller uses this condition to determine if a cluster deployment is in progress or completed.
189+
- For rollout strategies `Progressive` and `ProgressivePerGroup`, this is a **required** condition to determine if the rollout can proceed to the next cluster.
190+
- When the `Progressing` condition is `False`, the deployment is considered complete and succeeded, and the rollout will continue to the next cluster based on `minSuccessTime`.
191+
- If this condition is not defined, the rollout will never proceed to the next cluster (it will remain stuck waiting for the condition).
192+
193+
- **Degraded condition (optional)**: Indicates if the ManifestWork has failed or encountered issues.
194+
- This is an **optional** condition used only to determine failure states.
195+
- If the `Degraded` condition status is `True`, the rollout may stop or count towards `maxFailures`.
196+
- If this condition is not defined, the workload is assumed to never be degraded.
197+
198+
**Rollout Status Determination:**
199+
200+
The rollout controller determines the status of each ManifestWork based on the combination of `Progressing` and `Degraded` condition values:
201+
202+
| Progressing | Degraded | Rollout Status | Description |
203+
|-------------|----------|----------------|-------------|
204+
| `True` | `True` | **Failed** | Work is progressing but degraded |
205+
| `True` | `False` or not set | **Progressing** | Work is being applied and is healthy |
206+
| `False` | `False` or not set | **Succeeded** | Work has been successfully applied |
207+
| Unknown/Not set | Any | **Progressing** | Conservative fallback: treat as still progressing |
208+
209+
### Example: Progressive Rollout with Custom Conditions
210+
211+
This example demonstrates a progressive rollout with custom CEL expressions that define `Progressing` and `Degraded` conditions for a Deployment:
212+
213+
```yaml
214+
apiVersion: work.open-cluster-management.io/v1alpha1
215+
kind: ManifestWorkReplicaSet
216+
metadata:
217+
name: mwrset
218+
namespace: default
219+
spec:
220+
placementRefs:
221+
- name: placement-test # Name of a created Placement
222+
rolloutStrategy:
223+
type: Progressive
224+
progressive:
225+
minSuccessTime: 1m
226+
progressDeadline: 10m
227+
maxFailures: 5%
228+
maxConcurrency: 1
229+
manifestWorkTemplate:
230+
workload:
231+
manifests:
232+
- apiVersion: apps/v1
233+
kind: Deployment
234+
metadata:
235+
name: hello
236+
namespace: default
237+
spec:
238+
selector:
239+
matchLabels:
240+
app: hello
241+
template:
242+
metadata:
243+
labels:
244+
app: hello
245+
spec:
246+
containers:
247+
- name: hello
248+
image: busybox
249+
command:
250+
["sh", "-c", 'echo "Hello, Kubernetes!" && sleep 36000']
251+
manifestConfigs:
252+
- resourceIdentifier:
253+
group: apps
254+
resource: deployments
255+
namespace: default
256+
name: hello
257+
conditionRules:
258+
- condition: Progressing
259+
type: CEL
260+
celExpressions:
261+
- |
262+
!(
263+
(object.metadata.generation == object.status.observedGeneration) &&
264+
has(object.status.conditions) &&
265+
object.status.conditions.exists(c, c.type == 'Progressing' && c.status == 'True' && c.reason == 'NewReplicaSetAvailable')
266+
)
267+
messageExpression: |
268+
result ? "Applying" : "Completed"
269+
- condition: Degraded
270+
type: CEL
271+
celExpressions:
272+
- |
273+
(object.metadata.generation == object.status.observedGeneration) &&
274+
(has(object.status.readyReplicas) && has(object.status.replicas) && object.status.readyReplicas < object.status.replicas)
275+
messageExpression: |
276+
result ? "Degraded" : "Healthy"
277+
```
97278

98279
## Status tracking
99280

100-
The ManifestWorkReplicaSet example above refers to three placements each one will have its placementSummary in ManifestWorkReplicaSet status. The PlacementSummary shows the number of manifestWorks applied to the placement's clusters based on the placementRef's rolloutStrategy and total number of clusters.
281+
The PlacementSummary shows the number of manifestWorks applied to the placement's clusters based on the placementRef's rolloutStrategy and total number of clusters.
101282
The manifestWorkReplicaSet Summary aggregate the placementSummaries showing the total number of applied manifestWorks to all clusters.
102283

103284
The manifestWorkReplicaSet has three status conditions;
@@ -173,54 +354,4 @@ status:
173354
progressing: 0
174355
degraded: 0
175356
total: 45
176-
```
177-
## Release and Enable Feature
178-
179-
ManifestWorkReplicaSet is in alpha release and it is not enabled by default. In order to enable the ManifestWorkReplicaSet feature, it has to be enabled in the cluster-manager instance in the hub. Use the following command to edit the cluster-manager CR (custom resource) in the hub cluster.
180-
181-
```shell
182-
$ oc edit ClusterManager cluster-manager
183-
```
184-
Add the workConfiguration field to the cluster-manager CR as below and save.
185-
186-
```yaml
187-
kind: ClusterManager
188-
metadata:
189-
name: cluster-manager
190-
spec:
191-
...
192-
workConfiguration:
193-
featureGates:
194-
- feature: ManifestWorkReplicaSet
195-
mode: Enable
196-
```
197-
In order to ensure the ManifestWorkReplicaSet has been enabled successfully, check the cluster-manager using the command below
198-
199-
```shell
200-
$ oc get ClusterManager cluster-manager -o yml
201-
```
202-
You should find under the status->generation the cluster-manager-work-controller deployment has been added as below
203-
204-
```yaml
205-
kind: ClusterManager
206-
metadata:
207-
name: cluster-manager
208-
spec:
209-
...
210-
status:
211-
...
212-
generations:
213-
...
214-
- group: apps
215-
lastGeneration: 2
216-
name: cluster-manager-work-webhook
217-
namespace: open-cluster-management-hub
218-
resource: deployments
219-
version: v1
220-
- group: apps
221-
lastGeneration: 1
222-
name: cluster-manager-work-controller
223-
namespace: open-cluster-management-hub
224-
resource: deployments
225-
version: v1
226-
```
357+
```

0 commit comments

Comments
 (0)