Skip to content

Commit 9c8ed07

Browse files
jvincent-mongodbjvincent-mongodb
authored
DOCSP-47759 -- Create Dry Run Page (#208)
* DOCSP-47759 -- Create Dry Run Page; WIP * DOCSP-47759 -- add public preview banner * DOCSP-47759 -- add dry run docs * DOCSP-47759 -- add rerunable notes * DOCSP-47759 -- display tabs * DOCSP-47759 -- fix typo * DOCSP-47759 -- add bulleted list of verbs * DOCSP-47759 -- add bulleted list of verbs * DOCSP-47759 -- external review * DOCSP-47759 -- external review * DOCSP-47759 -- fix steps * DOCSP-47759 -- fix typos * DOCSP-47759 -- external review
1 parent a4d1b2a commit 9c8ed07

File tree

3 files changed

+209
-0
lines changed

3 files changed

+209
-0
lines changed

‎snooty.toml

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -327,3 +327,8 @@ vercel = "`Vercel <https://www.vercel.com/>`__"
327327
vercel-mdb = "`MongoDB Atlas Integration in Vercel <https://www.vercel.com/integrations/mongodbatlas>`__"
328328
vercel-dynamic = "`dynamic IP addresses <https://www.vercel.com/support/articles/how-to-allowlist-deployment-ip-address>`__"
329329

330+
[[banners]]
331+
# service accounts public preview
332+
targets = ["ak8so-dry-run.txt"]
333+
variant = "warning"
334+
value = "The Atlas Kubernetes Operator Dry Run feature is in public preview. The feature and the corresponding documentation might change at any time during the Preview period."

‎source/ak8so-dry-run.txt

Lines changed: 203 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,203 @@
1+
.. _ak8so-dry-run:
2+
3+
================
4+
|ak8so| Dry Run
5+
================
6+
7+
.. default-domain:: mongodb
8+
9+
.. contents:: On this page
10+
:local:
11+
:backlinks: none
12+
:depth: 1
13+
:class: singlecol
14+
15+
With the |ak8so| Dry Run feature, you can see what |ak8so| is going to change in
16+
|service|, with those custom resources applied to the K8S cluster. The |ak8so|
17+
emits events for every resource that it is going to create/update/delete in
18+
|service|. Events emitted by the |ak8so| running in Dry Run mode can be
19+
filtered by "Dry Run" reason. This feature is particularly useful for upgrading
20+
your |ak8so| resources from `v1.9 to v2.x <(for example from 1.9 to 2.x: https://www.mongodb.com/docs/atlas/operator/v2.0/upgrade-ako-v1-to-v2/)>`__.
21+
22+
Prerequisites
23+
-------------
24+
25+
In order to use the |ak8so| Dry Run feature, you need to:
26+
27+
- have access to a |k8s| or Open Shift {+cluster+}.
28+
- install CRDs to your {+cluster+} for the version of the |ak8so| you want to execute dry-run for.
29+
- create a ``mongodb-atlas-operator`` service account in your |k8s| {+cluster+}.
30+
- either manually or with the :ref:`Atlas CLI <ak8so-quick-start-ref>`, create a
31+
`role <https://github.com/mongodb/mongodb-atlas-kubernetes/blob/main/config/rbac/clusterwide/role.yaml>`__ and `rolebinding <https://github.com/mongodb/mongodb-atlas-kubernetes/blob/main/config/rbac/clusterwide/role_binding.yaml>`__ for your `service account <https://github.com/mongodb/mongodb-atlas-kubernetes/blob/main/config/rbac/service_account.yaml>`__ with the following permissions
32+
related to your |ak8so| custom resources:
33+
34+
- ``list``
35+
- ``get``
36+
- ``create``
37+
- ``update``
38+
- ``delete``
39+
40+
- apply |ak8so| custom resources to your new |k8s| {+cluster+}.
41+
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>`__.
42+
You need a new {+cluster+}, because upgrading CRDs on your existing |k8s| {+cluster+}
43+
might leave |ak8so| unable to reconcile existing custom resources. Moreover,
44+
the CRDs that are applied can be a newer version with potential breaking changes.
45+
46+
.. note::
47+
48+
Only one version of the AKO CRDs can exist in a specific |k8s| cluster.
49+
This means that to test upgrading to a new version of the |ak8so|, you
50+
need to deploy a new |k8s| cluster (possibly a temporary cluster) to
51+
execute the dry run.
52+
53+
Dry Run Events
54+
--------------
55+
56+
The Dry Run process emits either the following message types, each of which
57+
can be either of the type ``Normal`` or ``Warning``:
58+
59+
- ``Would [verb] ([HTTP-Method]) [Atlas resource URL]``
60+
61+
- A description of a given |ak8so| resource and the |k8s| required |k8s|
62+
process should the change be applied to your |service| environment. When in
63+
Dry Run mode, |ak8so| only emits dry-run events for HTTP verbs
64+
that would create/update/delete resources in |service|, such as
65+
``POST``, ``PATCH``, ``PUT``, ``DELETE``.
66+
67+
- ``Done``
68+
69+
- No further dry-run events will be reported.
70+
71+
- ``Finished``
72+
73+
- The |k8s| Job running the dry-run process has completed.
74+
75+
Procedure
76+
---------
77+
78+
.. tabs::
79+
80+
.. tab:: kubectl
81+
:tabid: kubectl-dry-run
82+
83+
.. procedure::
84+
:style: normal
85+
86+
.. step:: Apply the following |k8s| Job.
87+
88+
Save the following example in a file called ``dry-run-job.yaml``
89+
and apply it to your {+cluster+} by running ``kubectl apply -f dry-run-job.yaml``.
90+
This will start |ak8so| as a |k8s| Job with the ``--dry-run`` parameter.
91+
Every reconciliation in the |ak8so| will run only once, emitting
92+
events for each resource if there are changes between the resource
93+
spec and its state in |service|.
94+
95+
You can run this command multiple times without making any changes
96+
to your |service| resources.
97+
98+
.. code-block:: yaml
99+
:linenos:
100+
:copyable:
101+
102+
apiVersion: batch/v1
103+
kind: Job
104+
metadata:
105+
name: ako-dry-run
106+
namespace: mongodb-atlas-system
107+
spec:
108+
backoffLimit: 1
109+
template:
110+
spec:
111+
containers:
112+
- args:
113+
- --atlas-domain=https://cloud.mongodb.com/
114+
- --log-level=info
115+
- --log-encoder=json
116+
- --dry-run
117+
command:
118+
- /manager
119+
env:
120+
- name: OPERATOR_POD_NAME
121+
value: ako-dry-run
122+
- name: OPERATOR_NAMESPACE
123+
value: mongodb-atlas-system
124+
- name: WATCH_NAMESPACE
125+
value: mongodb-atlas-system
126+
- name: JOB_NAME
127+
value: ako-dry-run
128+
image: quay.io/mongodb/atlas-kubernetes-operator:2.8.0
129+
imagePullPolicy: Always
130+
livenessProbe:
131+
failureThreshold: 3
132+
httpGet:
133+
path: /healthz
134+
port: 8081
135+
scheme: HTTP
136+
initialDelaySeconds: 15
137+
periodSeconds: 20
138+
successThreshold: 1
139+
timeoutSeconds: 1
140+
name: ako-dry-run
141+
restartPolicy: Never
142+
serviceAccountName: mongodb-atlas-operator
143+
144+
.. step:: List the dry-run output.
145+
146+
When the |k8s| Job is finished, you can list the events emitted
147+
by running the following command:
148+
149+
.. code-block:: bash
150+
151+
kubectl -n mongodb-atlas-system get events --field-selector reason=DryRun
152+
153+
This command will return output similar to the following:
154+
155+
.. code-block:: bash
156+
157+
LAST SEEN TYPE REASON OBJECT MESSAGE
158+
103s Normal DryRun atlasproject/my-project Would delete (DELETE) /api/atlas/v1.0/groups/6558f184beba40022cbb2043/integrations/SLACK
159+
101s Warning DryRun atlasproject/my-project finished dry run
160+
161+
.. tab:: Atlas CLI
162+
:tabid: atlas-cli-dry-run
163+
164+
.. procedure::
165+
:style: normal
166+
167+
.. step:: Install the |ak8so| CRDs, RBAC and Service Account resources.
168+
169+
.. code-block:: bash
170+
171+
atlas kubernetes operator install --targetNamespace=mongodb-atlas-system --config-only
172+
173+
.. step:: Run the following Atlas CLI command.
174+
175+
Run the following |service| CLI command to start the dry run process.
176+
You can run this command multiple times without making any changes
177+
to your |service| resources.
178+
179+
.. code-block:: bash
180+
181+
atlas kubernetes dry-run --targetNamespace=mongodb-atlas-system --watch
182+
183+
.. note::
184+
185+
If the ``--watch`` flag is not provided, the |service| CLI exits
186+
after completing the installation.
187+
188+
.. step:: List the dry-run output.
189+
190+
When the |k8s| Job is finished, you can list the events emitted
191+
by running the following command:
192+
193+
.. code-block:: bash
194+
195+
kubectl -n mongodb-atlas-system get events --field-selector reason=DryRun
196+
197+
This command will return output similar to the following:
198+
199+
.. code-block:: bash
200+
201+
LAST SEEN TYPE REASON OBJECT MESSAGE
202+
103s Normal DryRun atlasproject/my-project Would delete (DELETE) /api/atlas/v1.0/groups/6558f184beba40022cbb2043/integrations/SLACK
203+
101s Warning DryRun atlasproject/my-project finished dry run

‎source/index.txt

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -201,6 +201,7 @@ Get Hands-On Experience with |ak8so|
201201
Overview </index>
202202
Get Started </ak8so-get-started>
203203
Atlas Access </configure-ak8so-access-to-atlas>
204+
Dry Run </ak8so-dry-run>
204205
Import Projects </ak8so-import-projects>
205206
Data Federation </ak8so-set-up-data-federation>
206207
Atlas Search </ak8so-create-atlas-search-index>

0 commit comments

Comments
 (0)