Skip to content

Commit eb34dd1

Browse files
EMcWhinnEMcWhinn
authored
Adding rollout policies to RHEM doc (ansible#3334) (ansible#3362)
* Adding `rollout policies` to RHEM doc Add "Rollout policies" section to Chapter 8 https://issues.redhat.com/browse/AAP-44689 Affects `titles/edge-manager-user-guide` * Fixing title format * Fixing grammar error * Fixing line breaks in assembly
1 parent 47e7ce3 commit eb34dd1

10 files changed

+179
-3
lines changed

‎downstream/assemblies/platform/assembly-edge-manager-device-fleets.adoc‎

Lines changed: 19 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -36,5 +36,23 @@ A device cannot be a member of more than one fleet at the same time.
3636
For more information, see xref:edge-manager-labels[Labels and label selectors].
3737

3838
include::platform/ref-edge-manager-device-selection.adoc[leveloffset=+1]
39+
3940
include::platform/ref-edge-manager-device-templates.adoc[leveloffset=+1]
40-
include::platform/proc-edge-manager-select-devices.adoc[leveloffset=+1]
41+
42+
include::platform/proc-edge-manager-add-devices-ui.adoc[leveloffset=+1]
43+
44+
include::platform/proc-edge-manager-add-devices-cli.adoc[leveloffset=+1]
45+
46+
include::platform/con-edge-manager-rollout-device-selection.adoc[leveloffset=+1]
47+
48+
include::platform/con-edge-manager-device-targeting.adoc[leveloffset=+2]
49+
50+
include::platform/con-edge-manager-device-selection-strat.adoc[leveloffset=+2]
51+
52+
include::platform/con-edge-manager-limit-device.adoc[leveloffset=+2]
53+
54+
include::platform/ref-edge-manager-success-threshold.adoc[leveloffset=+2]
55+
56+
include::platform/con-edge-manager-rollout-disruption.adoc[leveloffset=+1]
57+
58+
include::platform/ref-edge-manager-disruption-parameters.adoc[leveloffset=+2]

‎downstream/modules/platform/con-edge-manager-device-selection-strat.adoc‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
[id="edge-manager-device-selection-strat"]
2+
3+
= Device selection strategy
4+
5+
The {RedHatEdge} supports only the `BatchSequence` strategy for device selection.
6+
This strategy defines a stepwise rollout process where devices are added in batches based on specific criteria.
7+
Batches are executed sequentially.
8+
After each batch completes, execution proceeds to the next batch only if the success rate of the previous batch meets or exceeds the configured success threshold.
9+
10+
The success rate is determined as:
11+
12+
[literal, options="nowrap" subs="+attributes"]
13+
----
14+
# of successful rollouts in the batch / # of devices in the batch >= success threshold
15+
----
16+
17+
In a batch sequence, the final batch is an implicit batch and it is not specified in the batch sequence.
18+
It selects all devices in a fleet that have not been selected by the explicit batches in the sequence.

‎downstream/modules/platform/con-edge-manager-device-targeting.adoc‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
[id="edge-manager-device-targeting"]
2+
3+
= Device targeting
4+
5+
A rollout applies only to devices that belong to a fleet.
6+
Each device can belong to only a single fleet.
7+
Since rollout definitions are done at the fleet level, the selection process determines which devices within a fleet that participate in a batch rollout based on label criteria.
8+
After processing all batches, all fleet devices are rolled out.
9+
10+
* *Labels*: Devices with specific metadata labels can be targeted for rollouts.
11+
* *Fleet membership*: Rollouts apply only to devices within the specified fleet.

‎downstream/modules/platform/con-edge-manager-limit-device.adoc‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
[id="edge-manager-limit-device"]
2+
3+
= Limit in device selection
4+
5+
Each batch in the `BatchSequence` strategy might use an optional `limit` parameter to define how many devices should be included in the batch.
6+
You can specify the limit can in two ways:
7+
8+
* *Absolute number*: A fixed number of devices to be selected.
9+
* *Percentage*: The percentage of the total matching device population to be selected.
10+
11+
** If you provide a `selector` with labels, the percentage is calculated based on the number of devices that match the label criteria within the fleet.
12+
** If you do not provide a `selector`, the percentage is applied to all devices in the fleet.

‎downstream/modules/platform/con-edge-manager-rollout-device-selection.adoc‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
[id="edge-manager-device-rollout-device-selection"]
2+
3+
= Rollout device selection
4+
5+
When performing a rollout by using `flightctl`, you must manage which devices participate in the rollout and how much disruption is acceptable.
6+
The device selection process and the rollout disruption budget concept ensure controlled and predictable rollouts.
7+
8+
The process and configuration for selecting devices during a rollout includes targeting strategies, batch sequencing, and success criteria for controlled software deployment.

‎downstream/modules/platform/con-edge-manager-rollout-disruption.adoc‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
[id="edge-manager-rollout-disruption"]
2+
3+
= Rollout disruption budget
4+
5+
A rollout disruption budget defines the acceptable level of service impact during a rollout.
6+
This ensures that a deployment does not take down too many devices at once, maintaining overall system stability.

‎downstream/modules/platform/proc-edge-manager-select-devices.adoc‎ renamed to ‎downstream/modules/platform/proc-edge-manager-add-devices-cli.adoc‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
1-
[id="edge-manager-select-devices"]
1+
[id="edge-manager-add-devices-cli"]
22

3-
= Selecting devices into a fleet by using the CLI
3+
= Adding devices to a fleet on the CLI
44

55
Define the label selector to add devices into a fleet.
66

‎downstream/modules/platform/proc-edge-manager-add-devices-ui.adoc‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
[id="edge-manager-add-devices-ui"]
2+
3+
= Adding devices to a fleet on the web UI
4+
5+
Define the label selector to add devices into a fleet on the web UI.
6+
7+
Complete the following tasks:
8+
9+
.Procedure
10+
11+
. From the navigation panel, select menu:Application Links[Edge Manager].
12+
This opens the external Edge Manager instance.
13+
. From the navigation panel, select *Fleets*.
14+
Select the fleet that you want to add devices to.
15+
. Click btn:[Actions] and select *Edit fleet*.
16+
. In the *General info* tab, click *Add label* under the *Device selector* option.
17+
. Add the label to select devices for your fleet.
18+
Any devices with that label are added to the fleet.
19+

‎downstream/modules/platform/ref-edge-manager-disruption-parameters.adoc‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
[id="edge-manager-disruption-parameters"]
2+
3+
= Disruption budget parameters
4+
5+
* `groupBy`: Defines how devices are grouped when applying the disruption budget.
6+
The grouping is done by label keys.
7+
* `minAvailable`: Specifies the minimum number of devices that must remain available during a rollout.
8+
* `maxUnavailable`: Limits the number of devices that can be unavailable at the same time.
9+
10+
.Example
11+
12+
The following shows an example YAML configuration for a fleet specification:
13+
14+
[literal, options="nowrap" subs="+attributes"]
15+
----
16+
apiVersion: v1alpha1
17+
kind: Fleet
18+
metadata:
19+
name: default
20+
spec:
21+
selector:
22+
matchLabels:
23+
fleet: default
24+
rolloutPolicy:
25+
disruptionBudget:
26+
groupBy: ['site', 'function']
27+
minAvailable: 1
28+
maxUnavailable: 10
29+
----
30+
31+
In this example, the grouping is performed on 2 label keys: *site* and *function*.
32+
A group for disruption budget consists of all devices in a fleet having the same label values for the preceding label keys.
33+
For every such group the conditions defined in this specification are continuously enforced.

‎downstream/modules/platform/ref-edge-manager-success-threshold.adoc‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
[id="edge-manager-success-threshold"]
2+
3+
= Success threshold
4+
5+
The `successThreshold` defines the percentage of successfully updated devices required to continue the rollout.
6+
If the success rate falls below this threshold, the rollout might be paused to prevent further failures.
7+
8+
.Example
9+
10+
The following shows an example YAML configuration for a fleet specification:
11+
12+
[literal, options="nowrap" subs="+attributes"]
13+
----
14+
apiVersion: v1alpha1
15+
kind: Fleet
16+
metadata:
17+
name: default
18+
spec:
19+
selector:
20+
matchLabels:
21+
fleet: default
22+
rolloutPolicy:
23+
deviceSelection:
24+
strategy: 'BatchSequence'
25+
sequence:
26+
- selector:
27+
matchLabels:
28+
site: madrid
29+
limit: 1 # Absolute number
30+
- selector:
31+
matchLabels:
32+
site: madrid
33+
limit: 80% # Percentage of devices matching the label criteria within the fleet
34+
- limit: 50% # Percentage of all devices in the fleet
35+
- selector:
36+
matchLabels:
37+
site: paris
38+
- limit: 80%
39+
- limit: 100%
40+
successThreshold: 95%
41+
----
42+
43+
In this example, there are 6 explicit batches and 1 implicit batch:
44+
45+
* The first batch selects 1 device having a label *site:madrid*.
46+
* With the second batch 80% of all devices having the label *site:madrid* are either selected for rollout in the current batch or were previously selected for rollout.
47+
* With the third batch 50% of all devices are either selected for rollout in the current batch or were previously selected for rollout.
48+
* With the fourth batch all devices that were not previously selected and have the label *site:paris* are selected.
49+
* With the fifth batch 80% of all devices are either selected for rollout in the current batch or were previously selected for rollout.
50+
* With the sixth batch 100% of all devices are either selected for rollout in the current batch or were previously selected for rollout.
51+
* The last implicit batch selects all devices that have not been selected in any previous batch (might be none).

0 commit comments

Comments
 (0)