Skip to content

Commit 2ec7885

Browse files
jvincent-mongodbjvincent-mongodb
authored
DOCSP-52230 -- Dry Run Diff Feature Docs (#13141)
* DOCSP-52230 -- Dry Run Diff Feature Docs * DOCSP-52230 -- WIP * DOCSP-52230 -- WIP * DOCSP-52230 -- external review revisions * DOCSP-52230 -- external review revisions * DOCSP-52230 -- external review revision * DOCSP-52230 -- copy review revisions * DOCSP-52230 -- copy review revisions * DOCSP-52230 -- copy review revisions * DOCSP-52230 -- copy review revisions
1 parent cc0abf0 commit 2ec7885

File tree

3 files changed

+137
-6
lines changed

3 files changed

+137
-6
lines changed

‎content/atlas-operator/upcoming/source/ak8so-dry-run.txt‎

Lines changed: 91 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -23,10 +23,10 @@ Prerequisites
2323

2424
In order to use the |ak8so| Dry Run feature, you need to:
2525

26-
- Have access to a **new Kubernetes or Open Shift {+cluster+}**.
27-
- Apply |ak8so| custom resources to your **new Kubernetes {+cluster+}**.
26+
- Have access to a **new Kubernetes or OpenShift cluster**.
27+
- Apply |ak8so| custom resources to your **new Kubernetes cluster**.
2828
When you apply your resources, make sure you provide a `secret with credentials <https://www.mongodb.com/docs/atlas/operator/stable/ak8so-quick-start/#create-a-secret-with-your-api-keys-and-organization-id>`__.
29-
You need a new {+cluster+}, because upgrading CRDs on your existing |k8s| {+cluster+}
29+
You need a new cluster, because upgrading CRDs on your existing |k8s| cluster
3030
might leave |ak8so| unable to reconcile existing custom resources. Moreover,
3131
the CRDs that are applied can be a newer version with potential breaking changes.
3232

@@ -37,8 +37,8 @@ In order to use the |ak8so| Dry Run feature, you need to:
3737
need to deploy a new |k8s| cluster (possibly a temporary cluster) to
3838
execute the dry run.
3939

40-
- Install CRDs to your {+cluster+} for the version of the |ak8so| you want to execute dry-run for.
41-
- Create a ``mongodb-atlas-operator`` service account in your |k8s| {+cluster+}.
40+
- Install CRDs to your cluster for the version of the |ak8so| you want to execute dry-run for.
41+
- Create a ``mongodb-atlas-operator`` service account in your |k8s| cluster.
4242
- Create a `role <https://github.com/mongodb/mongodb-atlas-kubernetes/blob/main/config/rbac/clusterwide/role.yaml>`__
4343
and `rolebinding <https://github.com/mongodb/mongodb-atlas-kubernetes/blob/main/config/rbac/clusterwide/role_binding.yaml>`__
4444
for your `service account <https://github.com/mongodb/mongodb-atlas-kubernetes/blob/main/config/rbac/service_account.yaml>`__
@@ -87,7 +87,7 @@ Procedure
8787
.. step:: Apply the following |k8s| Job.
8888

8989
Save the following example in a file called ``dry-run-job.yaml``
90-
and apply it to your {+cluster+} by running ``kubectl apply -f dry-run-job.yaml``.
90+
and apply it to your cluster by running ``kubectl apply -f dry-run-job.yaml``.
9191
This will start |ak8so| as a |k8s| Job with the ``--dry-run`` parameter.
9292
Every reconciliation in the |ak8so| will run only once, emitting
9393
events for each resource if there are changes between the resource
@@ -161,3 +161,88 @@ Procedure
161161
LAST SEEN TYPE REASON OBJECT MESSAGE
162162
103s Normal DryRun atlasproject/my-project Would delete (DELETE) /api/atlas/v1.0/groups/6558f184beba40022cbb2043/integrations/SLACK
163163
101s Warning DryRun atlasproject/my-project finished dry run
164+
165+
166+
Log Resource Diffs
167+
------------------
168+
169+
When ``--log-level`` is set to ``debug``, the |ak8so| provides a detailed diff of
170+
the changes that you make to |service| resources that are managed by the |ak8so|.
171+
This diff is particularly useful when used in conjunction with the Dry Run
172+
feature, as it allows you to see the differences between the current state of
173+
your |ak8so| custom resources and the state that the |ak8so| would apply to your
174+
|service| environment.
175+
176+
This diff feature is informed by comparing the result of any PUT or PATCH
177+
requests sent to |service| with the current state of the |ak8so|
178+
custom resources in your |service| environment.
179+
180+
.. note::
181+
182+
To facilitate this comparison, the |ak8so| makes a GET request to |service| to
183+
learn the current state of resources in |service|. As such, we recommend
184+
that you only set the log level to debug in non-production environments,
185+
as this feature can increase the load on |service|.
186+
187+
To see the differences, you need to set the ``--log-level=debug`` flag when
188+
running the |ak8so| command. Because the |ak8so| uses structured
189+
logging, we recommend analyzing the JSON diff in a structured logging viewer
190+
for better human readability. The following example shows a rendered |ak8so|
191+
``DEBUG`` log line in YAML format, as displayed in a structured logging viewer:
192+
193+
.. io-code-block::
194+
195+
.. input::
196+
:language: yaml
197+
198+
apiVersion: atlas.mongodb.com/v1
199+
kind: AtlasDeployment
200+
metadata:
201+
name: test
202+
namespace: flex
203+
spec:
204+
flexSpec:
205+
name: test
206+
providerSettings:
207+
backingProviderName: AWS
208+
regionName: US_EAST_1
209+
terminationProtectionEnabled: true -> false
210+
projectRef:
211+
name: test
212+
213+
214+
.. output::
215+
:visible: false
216+
217+
1 | diff: |
218+
2 | {
219+
3 | - "backupSettings": {
220+
4 | - "enabled": true
221+
5 | - },
222+
6 | - "clusterType": "REPLICASET",
223+
7 | - "connectionStrings": {
224+
8 | - "standard": "...",
225+
9 | - "standardSrv": "..."
226+
10 | - },
227+
11 | - "createDate": "2025-07-21T09:52:06Z",
228+
12 | - "groupId": "687e0db8823af91...",
229+
13 | - "id": "687e0dc6426db7026...",
230+
14 | - "mongoDBVersion": "8.0.11",
231+
15 | - "name": "test",
232+
16 | - "providerSettings": {
233+
17 | - "backingProviderName": "AWS",
234+
18 | - "diskSizeGB": 5,
235+
19 | - "providerName": "FLEX",
236+
20 | - "regionName": "US_EAST_1"
237+
21 | - },
238+
22 | - "stateName": "IDLE",
239+
23 | "tags": [
240+
24 | ],
241+
25 | - "terminationProtectionEnabled": false,
242+
26 | + "terminationProtectionEnabled": true,
243+
27 | - "versionReleaseSystem": "LTS"
244+
28 | }
245+
29 | level: DEBUG
246+
30 | msg: JSON diff
247+
31 | time: 2025-07-22T18:07:01.163+0200
248+
32 | url: https://...

‎content/atlas-operator/upcoming/source/includes/ak8so-diff-input-example.yaml‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
apiVersion: atlas.mongodb.com/v1
2+
kind: AtlasDeployment
3+
metadata:
4+
name: test
5+
namespace: flex
6+
spec:
7+
flexSpec:
8+
name: test
9+
providerSettings:
10+
backingProviderName: AWS
11+
regionName: US_EAST_1
12+
terminationProtectionEnabled: true -> false
13+
projectRef:
14+
name: test

‎content/atlas-operator/upcoming/source/includes/ak8so-diff-output-example.out‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
1 | diff: |
2+
2 | {
3+
3 | - "backupSettings": {
4+
4 | - "enabled": true
5+
5 | - },
6+
6 | - "clusterType": "REPLICASET",
7+
7 | - "connectionStrings": {
8+
8 | - "standard": "...",
9+
9 | - "standardSrv": "..."
10+
10 | - },
11+
11 | - "createDate": "2025-07-21T09:52:06Z",
12+
12 | - "groupId": "687e0db8823af91...",
13+
13 | - "id": "687e0dc6426db7026...",
14+
14 | - "mongoDBVersion": "8.0.11",
15+
15 | - "name": "test",
16+
16 | - "providerSettings": {
17+
17 | - "backingProviderName": "AWS",
18+
18 | - "diskSizeGB": 5,
19+
19 | - "providerName": "FLEX",
20+
20 | - "regionName": "US_EAST_1"
21+
21 | - },
22+
22 | - "stateName": "IDLE",
23+
23 | "tags": [
24+
24 | ],
25+
25 | - "terminationProtectionEnabled": false,
26+
26 | + "terminationProtectionEnabled": true,
27+
27 | - "versionReleaseSystem": "LTS"
28+
28 | }
29+
29 | level: DEBUG
30+
30 | msg: JSON diff
31+
31 | time: 2025-07-22T18:07:01.163+0200
32+
32 | url: https://...

0 commit comments

Comments
 (0)