Skip to content

Commit b7fd384

Browse files
michaelawyumichaelawyu
authored
docs: add the report diff mode how-to doc (preview) (#968)
1 parent 1893de1 commit b7fd384

File tree

1 file changed

+175
-0
lines changed

1 file changed

+175
-0
lines changed

‎docs/howtos/reportdiff.md‎

Lines changed: 175 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,175 @@
1+
# How-to Guide: Using the `ReportDiff` Apply Mode
2+
3+
This guide provides an overview on how to use the `ReportDiff` apply mode, which allows one to
4+
easily evaluate how things will change in the system without the risk of incurring unexpected
5+
changes. In this mode, Fleet will check for configuration differences between the hub cluster
6+
resource templates and their corresponding resources on the member clusters, but will not
7+
perform any apply op. This is most helpful in cases of experimentation and drift/diff analysis.
8+
9+
# How the `ReportDiff` mode can help
10+
11+
To use this mode, simply set the `type` field in the apply strategy part of the CRP API
12+
from `ClientSideApply` (the default) or `ServerSideApply` to `ReportDiff`. Configuration
13+
differences are checked per `comparisonOption` setting, in consistency with the behavior
14+
documented in the drift detection how-to guide; see the document for more information.
15+
16+
The steps below might help explain the workflow better; it assumes that you have a fleet
17+
of two member clusters, `member-1` and `member-2`:
18+
19+
* Switch to the hub cluster and create a namespace, `work-3`, with some labels.
20+
21+
```sh
22+
kubectl config use-context hub-admin
23+
kubectl create ns work-3
24+
kubectl label ns work-3 app=work-3
25+
kubectl label ns work-3 owner=leon
26+
```
27+
28+
* Create a CRP object that places the namespace to all member clusters:
29+
30+
```sh
31+
cat <<EOF | kubectl apply -f -
32+
# The YAML configuration of the CRP object.
33+
apiVersion: placement.kubernetes-fleet.io/v1beta1
34+
kind: ClusterResourcePlacement
35+
metadata:
36+
name: work-3
37+
spec:
38+
resourceSelectors:
39+
- group: ""
40+
kind: Namespace
41+
version: v1
42+
# Select all namespaces with the label app=work.
43+
labelSelector:
44+
matchLabels:
45+
app: work-3
46+
policy:
47+
placementType: PickAll
48+
strategy:
49+
# For simplicity reasons, the CRP is configured to roll out changes to
50+
# all member clusters at once. This is not a setup recommended for production
51+
# use.
52+
type: RollingUpdate
53+
rollingUpdate:
54+
maxUnavailable: 100%
55+
unavailablePeriodSeconds: 1
56+
EOF
57+
```
58+
59+
* In a few seconds, Fleet will complete the placement. Verify that the CRP is available by checking its status.
60+
61+
* After the CRP becomes available, edit its apply strategy and set it to use the ReportDiff mode:
62+
63+
```sh
64+
cat <<EOF | kubectl apply -f -
65+
# The YAML configuration of the CRP object.
66+
apiVersion: placement.kubernetes-fleet.io/v1beta1
67+
kind: ClusterResourcePlacement
68+
metadata:
69+
name: work-3
70+
spec:
71+
resourceSelectors:
72+
- group: ""
73+
kind: Namespace
74+
version: v1
75+
# Select all namespaces with the label app=work.
76+
labelSelector:
77+
matchLabels:
78+
app: work-3
79+
policy:
80+
placementType: PickAll
81+
strategy:
82+
# For simplicity reasons, the CRP is configured to roll out changes to
83+
# all member clusters at once. This is not a setup recommended for production
84+
# use.
85+
type: RollingUpdate
86+
rollingUpdate:
87+
maxUnavailable: 100%
88+
unavailablePeriodSeconds: 1
89+
applyStrategy:
90+
type: ReportDiff
91+
EOF
92+
```
93+
94+
* The CRP should remain available, as currently there is no configuration difference at all.
95+
Check the `Applied` condition in the status; it should report no error:
96+
97+
```sh
98+
kubectl get clusterresourceplacement.v1beta1.placement.kubernetes-fleet.io work-3 -o jsonpath='{.status.placementStatuses[?(@.clusterName=="member-2")].conditions[?(@.type=="Applied")]}' | jq
99+
# The command above uses JSON paths to query the drift details directly and
100+
# uses the jq utility to pretty print the output JSON.
101+
#
102+
# jq might not be available in your environment. You may have to install it
103+
# separately, or omit it from the command.
104+
#
105+
# If the output is empty, the status might have not been populated properly
106+
# yet. You can switch the output type from jsonpath to yaml to see the full
107+
# object.
108+
```
109+
110+
```json
111+
{
112+
"lastTransitionTime": "2024-11-19T12:23:47Z",
113+
"message": "...",
114+
"observedGeneration": ...,
115+
"reason": "AllWorkHaveBeenApplied",
116+
"status": "True",
117+
"type": "Applied"
118+
}
119+
```
120+
121+
* Now, switch to the second member cluster and make a label change on the applied namespace.
122+
After the change is done, switch back to the hub cluster.
123+
124+
```sh
125+
kubectl config use-context member-2-admin
126+
kubectl label ns work-3 owner=krauser --overwrite
127+
#
128+
kubectl config use-context hub-admin
129+
```
130+
131+
* Fleet will detect this configuration difference shortly (w/in 15 seconds).
132+
Verify that the diff details have been added to the CRP status:
133+
134+
```sh
135+
kubectl get clusterresourceplacement.v1beta1.placement.kubernetes-fleet.io work-3 -o jsonpath='{.status.placementStatuses[?(@.clusterName=="member-2")].diffedPlacements}' | jq
136+
# The command above uses JSON paths to query the drift details directly and
137+
# uses the jq utility to pretty print the output JSON.
138+
#
139+
# jq might not be available in your environment. You may have to install it
140+
# separately, or omit it from the command.
141+
#
142+
# If the output is empty, the status might have not been populated properly
143+
# yet. You can switch the output type from jsonpath to yaml to see the full
144+
# object.
145+
```
146+
147+
```json
148+
[
149+
{
150+
"firstDiffedObservedTime": "2024-11-19T14:55:39Z",
151+
"group": "",
152+
"version": "v1",
153+
"kind": "Namespace",
154+
"name": "work-3",
155+
"observationTime": "2024-11-19T14:55:39Z",
156+
"observedDiffs": [
157+
{
158+
"path": "/metadata/labels/owner",
159+
"valueInHub": "leon",
160+
"valueInMember": "krauser"
161+
}
162+
],
163+
"targetClusterObservedGeneration": 0
164+
}
165+
]
166+
```
167+
168+
## More information on the ReportDiff mode
169+
170+
* As mentioned earlier, with this mode no apply op will be run at all; it is up to the user to
171+
decide the best way to handle found configuration differences (if any).
172+
* Fleet will report an apply error (with diff details) in this mode if configuration
173+
differences are found on any resource. If a resource has not been applied yet, an apply error
174+
would also be returned with a message that configuration differences cannot be reported; in
175+
this case there would be no diff details.

0 commit comments

Comments
 (0)