Skip to content

Commit 8ca7a79

Browse files
lmkerbey-mdblmkerbey-mdb
authored
(DOCSP-44437) Modify DB User and Deployment resources. (#152)
* (DOCSP-44437) Modify DB User and Deployment resources. * (DOCSP-44437) Incidental typo fix. * (DOCSP-44437) General descriptions Create the Independent CRD page, set up refs to it where necessary in the general docs. * (DOCSP-44437) Finalize first draft. Flesh out Independent CRD page, add info about spec.connectionSecretRef.name to both modified resources. * (DOCSP-44437) Tech review, part 1 * (DOCSP-44437) Technical review, part 2 * (DOCSP-44437) Technical review, part 3 * (DOCSP-44437) Technical review, part 4 * Technical review, part 5 + Copy review * Technical review, part 6 * (DOCSP-44437) Technical review, part 7 * (DOCSP-44437) * (DOCSP-44437) * (DOCSP-44437) Technical review, part 8 * (DOCSP-44437) Tech review, part 9 * (DOCSP-44437) Technical review, part 10 * (DOCSP-44437) Technical review, part 11 * (DOCSP-44437) Formatting fix.
1 parent e6f32f3 commit 8ca7a79

File tree

6 files changed

+303
-10
lines changed

6 files changed

+303
-10
lines changed

‎source/ak8so-get-started.txt‎

Lines changed: 14 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,18 @@ in the |service-fullname| for Government documentation.
4040
The :ref:`ak8so-for-gov-ref` page describes how to configure |ak8so| to
4141
manage resources in |service| for Government.
4242

43+
Independent Custom Resource Definitions
44+
---------------------------------------
45+
46+
You can use |ak8so| to manage specific resources within an |service|
47+
project without configuring |ak8so| to manage the project itself. This
48+
allows you to use different programmatic infrastructure management
49+
systems for your projects, while you use |ak8so| to manage more
50+
frequently-altered resources such as database users or individual
51+
deployments.
52+
53+
To learn more, see :ref:`ak8so-independent-crd`.
54+
4355
Compatibility
4456
-------------
4557

@@ -56,5 +68,6 @@ To learn more, see :ref:`ak8so-compatibility-ref`.
5668
Verify Integrity of Packages </ak8so-verify-packages>
5769
Helm Charts Quick Start </ak8so-quick-start-helm>
5870
Atlas for Government </ak8so-for-gov>
71+
Independent Custom Resource Definitions </ak8so-independent-crd>
5972
Compatibility </ak8so-compatibility>
60-
73+

‎source/ak8so-independent-crd.txt‎

Lines changed: 174 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,174 @@
1+
.. _ak8so-independent-crd:
2+
3+
=======================================
4+
Independent Custom Resource Definitions
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+
You can use |ak8so| to manage resources in an |service| project
16+
without using |ak8so| to manage the project itself. In this
17+
independent custom resource definition ("independent CRD") model, you
18+
associate resources such as :ref:`atlasdeployment-custom-resource` and
19+
:ref:`atlasdatabaseuser-custom-resource` with an |service| project
20+
directly by its |service| :atlas:`ID <project-id>`.
21+
22+
Independent CRDs allow you to use different programmatic
23+
infrastructure management systems for your projects, while you use
24+
|ak8so| to manage more frequently-altered resources such as database
25+
users or individual deployments.
26+
27+
By separating the management of the |service| project from the
28+
management of subresources such as users and deployments, independent
29+
CRDs allow you to allocate these responsibilities to different
30+
personnel or different teams within your organization as suits your
31+
needs.
32+
33+
.. _ak8so-independent-crd-considerations:
34+
35+
Considerations
36+
--------------
37+
38+
When you use |ak8so| to manage a project, you can either configure
39+
{+atlas-admin-api+} authentication using the
40+
``spec.connectionSecretRef.name`` parameter of the ``atlasProject``
41+
resource, or leave this parameter unset to default to global |service|
42+
:ref:`credentials <ak8so-secrets>`. When using independent CRDs, you
43+
can specify a ``spec.connectionSecret.name`` for each resource. This
44+
parameter, if set, takes precedence over
45+
``spec.connectionSecretRef.name`` or global |service|
46+
credentials.
47+
48+
Setting this parameter is required for any resource whose parent
49+
resource is referenced using an |service| :atlas:`project ID
50+
<project-id>`, and optional otherwise.
51+
52+
.. example::
53+
54+
You define an ``atlasDeployment`` CRD that references its parent
55+
project by |service| ID instead of an ``atlasProject``
56+
``spec.name`` parameter. You must define a
57+
``spec.connectSecret.name`` for the ``atlasDeployment``
58+
resource, as in the following:
59+
60+
.. code-block::
61+
62+
apiVersion: atlas.mongodb.com/v1
63+
kind: AtlasDeployment
64+
metadata:
65+
name: test-cluster-name
66+
namespace: mongodb-atlas-system
67+
spec:
68+
externalProjectRef:
69+
id: 671998971c8520583f24f411
70+
connectionSecret:
71+
name: my-atlas-key
72+
deploymentSpec:
73+
clusterType: REPLICASET
74+
name: service-name
75+
tags:
76+
- key: "environment"
77+
value: "production"
78+
backupEnabled: true
79+
replicationSpecs:
80+
- zoneName: US-Zone
81+
numShards: 3
82+
regionConfigs:
83+
- regionName: CENTRAL_US
84+
providerName: GCP
85+
backingProviderName: GCP
86+
priority: 7
87+
electableSpecs:
88+
instanceSize: M10
89+
nodeCount: 3
90+
91+
.. _ak8so-independent-crd-migrate:
92+
93+
Migration to Independent CRD
94+
----------------------------
95+
96+
To migrate existing CRDs from ``atlasProject``-level management to
97+
independent management:
98+
99+
.. procedure::
100+
:style: normal
101+
102+
.. step:: Disable project reconciliation and edit subresource
103+
references
104+
105+
1. Add the ``mongodb.com/atlas-reconciliation-policy: "skip"``
106+
annotation to the parent resource's ``metadata``. This
107+
prevents |ak8so| from attempting to reconcile the parent
108+
resource and its subresources. Consider the following:
109+
110+
.. code-block::
111+
:emphasize-lines: 5-6
112+
113+
apiVersion: atlas.mongodb.com/v1
114+
kind: AtlasProject
115+
metadata:
116+
name: my-project
117+
annotations:
118+
mongodb.com/atlas-reconciliation-policy: "skip"
119+
spec:
120+
name: Test project
121+
connectionSecretRef:
122+
name: my-atlas-key
123+
projectIpAccessList:
124+
- cidrBlock: "203.0.113.0/24"
125+
comment: "CIDR block for Application Server B - D"
126+
127+
.. warning::
128+
129+
If you do not apply this annotation, |ak8so| will continue
130+
to attempt reconciliation as you modify your other
131+
resources. For users with :ref:`<deletion-protection>`
132+
disabled, this can result in |ak8so| removing the
133+
|service| project when you remove the ``atlasProject``
134+
resource, or entering a blocked state attempting to remove
135+
a project with active subresources such as database users
136+
or deployments.
137+
138+
#. Modify the project reference to point to an |service|
139+
:atlas:`project ID <project-id>` instead of an
140+
``atlasProject`` name.
141+
142+
For example, to decouple an ``atlasDatabaseUser`` resource:
143+
144+
.. code-block::
145+
:emphasize-lines: 9-10
146+
147+
apiVersion: atlas.mongodb.com/v1
148+
kind: AtlasDatabaseUser
149+
metadata:
150+
name: my-database-user
151+
spec:
152+
roles:
153+
- roleName: readWriteAnyDatabase
154+
databaseName: admin
155+
externalProjectRef:
156+
id: 671998971c8520583f24f411
157+
username: theuser
158+
passwordSecretRef:
159+
name: the-user-password
160+
161+
.. step:: Wait for |ak8so| to sync the new resource status.
162+
163+
.. step:: (Conditional) Remove the ``atlasProject`` CRD.
164+
165+
To stop managing your project with |ak8so|, you can now remove
166+
the ``atlasProject`` CRD. To continue managing your project and
167+
attached subresources with |ak8so|, skip to the next step.
168+
169+
.. step:: (Conditional) Remove the reconciliation policy annotation
170+
171+
If you want to continue managing your project with |ak8so|, as in
172+
a scenario where you still have resources subordinate to your
173+
``atlasProject``, reactivate reconciliation by removing the
174+
reconciliation policy annotation from the ``atlasProject`` CRD.

‎source/ak8so-unified-access.txt‎

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,15 @@ Set Up Unified Cloud Provider Integrations
1717
You can use |ak8so| to set up unified access for an |aws| |iam| role
1818
in the :ref:`atlasproject-custom-resource`.
1919

20+
.. important::
21+
22+
If you operate |ak8so| under an :ref:`independent CRD model
23+
<ak8so-independent-crd>`, you cannot configure |aws| |iam|
24+
authentication using ``atlasProject`` parameters. To configure
25+
|aws| |iam| authentication for your |service| project directly,
26+
please see :ref:`aws-iam-authentication <Set Up Authentication with
27+
AWS IAM>`.
28+
2029
Prerequisites
2130
-------------
2231

@@ -167,4 +176,4 @@ Procedure
167176
but you have not specified the
168177
``spec.cloudProviderIntegrations.iamAssumedRoleArn``.
169178
- If the status is ``READY``, |service| has created the role
170-
and you have authorized it within |aws|.
179+
and you have authorized it within |aws|.

‎source/atlasdatabaseuser-custom-resource.txt‎

Lines changed: 53 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -331,6 +331,27 @@ to customize your specifications.
331331
* - ROLE
332332
- User who authenticates with the |aws| |iam| credentials associated with the user's role.
333333

334+
.. setting:: spec.connectionSecret.name
335+
336+
*Type*: string
337+
338+
*Conditional*
339+
340+
Name of the opaque |k8s-secret| that contains the organization ID
341+
and :ref:`API keys <about-org-api-keys>` that |ak8so| uses to
342+
:ref:`connect <ak8so-access-to-atlas-ref>` to |service|. If
343+
unspecified, |ak8so| falls back to either:
344+
345+
- The ``spec.connectionSecretRef.name`` parameter of the parent
346+
``atlasProject``
347+
- The default ``global`` secret, if ``spec.connectionSecretRef.name``
348+
is undefined for the parent ``atlasProject``
349+
350+
This parameter is mandatory for :ref:`independent CRDs
351+
<ak8so-independent-crd>`.
352+
353+
.. include:: /includes/fact-ak8so-label-secret.rst
354+
334355
.. setting:: spec.databaseName
335356

336357
*Type*: string
@@ -347,6 +368,24 @@ to customize your specifications.
347368
If the database user authenticates with :ref:`X.509 <ak8so-x509>`,
348369
this value must be ``\$external``.
349370

371+
.. setting:: spec.externalProjectRef.id
372+
373+
*Type*: string
374+
375+
*Conditional*
376+
377+
ID of the project to which the database user belongs. You must
378+
specify the project ID of an existing :ref:`Atlas Project
379+
<manage-projects>`. This parameter is required for database users
380+
who belong to projects managed by either:
381+
382+
- A different instance of |ak8so|
383+
- Tooling other than |ak8so|
384+
385+
For database users who belong to projects managed by
386+
the same instance of |ak8so|, use ``spec.projectRef.name`` if you
387+
do not use ``spec.externalProjectRef.id``.
388+
350389
.. setting:: spec.oidcAuthType
351390

352391
*Type*: string
@@ -369,13 +408,23 @@ to customize your specifications.
369408
:manual:`SCRAM-SHA </core/security-scram>` authentication method
370409
requires this parameter.
371410

372-
:setting:`spec.projectRef.name`
411+
.. setting:: spec.projectRef.name
412+
373413
*Type*: string
374414

375-
*Required*
415+
*Conditional*
416+
417+
Name of the project to which the database user belongs. You must
418+
specify an existing :ref:`atlasproject-custom-resource`. This
419+
parameter applies only to database users who belong to projects
420+
managed by the same instance |ak8so|.
421+
422+
For database users who belong to projects managed by either:
423+
424+
- a different instance of |ak8so|
425+
- tooling other than |ak8so|
376426

377-
Name of the project where the database user belongs. You must
378-
specify an existing :ref:`atlasproject-custom-resource`.
427+
use ``spec.externalProjectRef.name``.
379428

380429
.. setting:: spec.roles
381430

‎source/atlasdeployment-custom-resource.txt‎

Lines changed: 51 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -460,6 +460,27 @@ examples, and the |api| documentation.
460460
:ref:`atlasbackupschedule-custom-resource` for the backup schedule
461461
that you want to apply.
462462

463+
.. setting:: spec.connectionSecret.name
464+
465+
*Type*: string
466+
467+
*Conditional*
468+
469+
Name of the opaque |k8s-secret| that contains the organization ID
470+
and :ref:`API keys <about-org-api-keys>` that |ak8so| uses to
471+
:ref:`connect <ak8so-access-to-atlas-ref>` to |service|. If
472+
unspecified, |ak8so| falls back to either:
473+
474+
- The ``spec.connectionSecretRef.name`` parameter of the parent
475+
``atlasProject``
476+
- The default ``global`` secret, if ``spec.connectionSecretRef.name``
477+
is undefined for the parent ``atlasProject``
478+
479+
This parameter is mandatory for :ref:`independent CRDs
480+
<ak8so-independent-crd>`.
481+
482+
.. include:: /includes/fact-ak8so-label-secret.rst
483+
463484
.. setting:: spec.deploymentSpec
464485

465486
*Type*: array
@@ -1350,6 +1371,24 @@ examples, and the |api| documentation.
13501371
If you set this parameter to ``CONTINUOUS``, you must omit the
13511372
:setting:`spec.deploymentSpec.mongoDBMajorVersion` parameter.
13521373

1374+
.. setting:: spec.externalProjectRef.id
1375+
1376+
*Type*: string
1377+
1378+
*Conditional*
1379+
1380+
ID of the project to which the deployment belongs. You must
1381+
specify the project ID of an existing :ref:`Atlas Project
1382+
<manage-projects>`. This parameter is required for deployments
1383+
who belong to projects managed by either:
1384+
1385+
- A different instance of |ak8so|
1386+
- Tooling other than |ak8so|
1387+
1388+
For deployments who belong to projects managed by
1389+
the same instance of |ak8so|, use ``spec.projectRef.name`` if you
1390+
do not use ``spec.externalProjectRef.id``.
1391+
13531392
.. setting:: spec.processArgs
13541393

13551394
*Type*: object
@@ -1488,11 +1527,20 @@ examples, and the |api| documentation.
14881527

14891528
*Type*: string
14901529

1491-
*Required*
1530+
*Conditional*
1531+
1532+
Name of the project to which the deployment belongs. You must
1533+
specify an existing :ref:`atlasproject-custom-resource`. This
1534+
parameter applies only to deployments that belong to projects
1535+
managed by the same instance |ak8so|.
14921536

1493-
Name of the project where the {+cluster+} belongs. You must specify
1494-
an existing :ref:`atlasproject-custom-resource`.
1537+
For deployments that belong to projects managed by either:
14951538

1539+
- a different instance of |ak8so|
1540+
- tooling other than |ak8so|
1541+
1542+
use ``spec.externalProjectRef.name``.
1543+
14961544
.. setting:: spec.serverlessSpec
14971545

14981546
*Type*: array

‎source/includes/unified-access-intro.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@ Some |service| features, including :ref:`Data Federation
22
<atlas-data-federation>` and :ref:`Encryption at Rest
33
<security-aws-kms>`, authenticate with |aws| `IAM roles
44
<https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use.html>`__.
5-
When |service| accesses |aws| services,
5+
When |service| accesses |aws| services, it
66
`assumes an IAM role
77
<https://docs.aws.amazon.com/IAM/latest/UserGuide/using-service-linked-roles.html>`__.
88

0 commit comments

Comments
 (0)