(DOCSP-45955) migrate parameters to CRDs page (#172)

lmkerbey-mdb · jwilliams-mongo · web-flow · commit ac42fee9f674 · 2024-12-16T19:21:24.000-06:00
* (DOCSP-45955) First draft. * tech review * fix crds * various fixes for build issues * remaining build fixes * one more typo * bad find and replace * last link fix --------- Co-authored-by: John Williams <john.williams@mongodb.com>
diff --git a/config/redirects b/config/redirects
@@ -1,8 +1,8 @@
 define: base https://www.mongodb.com/docs/atlas/operator
 define: old_bucket_prefix docs/atlas/atlas-operator
-define: versions v1.9 v2.0 v2.1 v2.2 v2.3 master
+define: versions v1.9 v2.0 v2.1 v2.2 v2.3 v2.4 v2.5 master
 symlink: upcoming -> master
-symlink: current -> v2.3
+symlink: current -> v2.5
 
 # old_bucket_prefix represents the old path to these docs that we had to change to get embedded versioning to work
 
@@ -121,3 +121,7 @@ raw: docs/atlas/operator/stable/configure-ak8so-access-to-atlas/ -> ${base}/curr
 raw: docs/atlas/operator/stable/custom-resources/ -> ${base}/current/custom-resources/
 raw: docs/atlas/operator/stable/production-notes/ -> ${base}/current/production-notes/
 raw: docs/atlas/operator/stable/ak8so-stream-processing/ -> ${base}/current/ak8so-stream-processing/
+
+# new migration from parameters to crds page
+
+[*-v2.5]: docs/atlas/operator/${version}/migrate-parameter-to-resource/ -> https://www.mongodb.com/docs/unavailable-version/
diff --git a/source/ak8so-configure-teams.txt b/source/ak8so-configure-teams.txt
@@ -33,7 +33,7 @@ update the following custom resources:
    * - :ref:`atlasproject-custom-resource`
      - Defines the team's access roles for this project. You
        must set the :setting:`spec.teams.teamRef.name` field to match the 
-       :setting:`metadata.name` of the :ref:`atlasteam-custom-resource` to assign 
+       ``metadata.name`` of the :ref:`atlasteam-custom-resource` to assign 
        the team to this project.
 
 Each time you change any of the supported custom resources, such as updating or 
@@ -74,7 +74,7 @@ projects:
    .. step:: Create the team.
 
      Create an :ref:`atlasteam-custom-resource` for each team using the following 
-     example. Specify a :setting:`metadata.name` so that you can reference this 
+     example. Specify a ``metadata.name`` so that you can reference this 
      file from the :ref:`atlasproject-custom-resource` and a ``spec.name`` so you 
      can differentiate this team from other teams in your organization.
      
@@ -105,7 +105,7 @@ projects:
 
       To assign this team to a project, set the :setting:`spec.teams.teamRef.name` 
       field in the :ref:`atlasproject-custom-resource` to match the 
-      :setting:`metadata.name` from the previous step.
+      ``metadata.name`` from the previous step.
 
       In the :setting:`spec.teams.teamRef.roles` field, specify the team's 
       :ref:`user-roles` for this project.
diff --git a/source/ak8so-get-started.txt b/source/ak8so-get-started.txt
@@ -69,5 +69,6 @@ To learn more, see :ref:`ak8so-compatibility-ref`.
    Helm Charts Quick Start </ak8so-quick-start-helm>
    Atlas for Government </ak8so-for-gov>
    Independent Custom Resource Definitions </ak8so-independent-crd>
+   Migrate Parameters to CRDs </migrate-parameter-to-resource>
    Compatibility </ak8so-compatibility>
    
diff --git a/source/ak8so-unified-access.txt b/source/ak8so-unified-access.txt
@@ -23,8 +23,7 @@ in the :ref:`atlasproject-custom-resource`.
    <ak8so-independent-crd>`, you cannot configure |aws| |iam|
    authentication using ``atlasProject`` parameters. To configure
    |aws| |iam| authentication for your |service| project directly,
-   please see :ref:`aws-iam-authentication <Set Up Authentication with
-   AWS IAM>`.
+   please see :atlas:`Set Up Authentication with AWS IAM </security/aws-iam-authentication>`.
 
 Prerequisites
 -------------
diff --git a/source/atlascustomrole-custom-resource.txt b/source/atlascustomrole-custom-resource.txt
@@ -1,3 +1,4 @@
+.. _ak8so-configure-custom-database-roles:
 .. _atlascustomrole-custom-resource:
 
 =======================================
@@ -35,7 +36,7 @@ To create this custom role within a given project, you must either:
 - Updates an existing custom database role.
 
 Examples
--------
+--------
 
 .. _atlascustomrole-example-basic:
 
@@ -133,8 +134,7 @@ Parameters
 
 This section describes the ``AtlasTeam`` custom resource parameters available. 
 
-.. setting:: metadata.name
-
+``metadata.name``
    *Type*: string
 
    *Required*
@@ -278,7 +278,7 @@ This section describes the ``AtlasTeam`` custom resource parameters available.
 
       This parameter is mutually exclusive with the
       :setting:`spec.role.actions.resources.collection` and
-      :setting:`spec.role.actions.resources.db` parameters.
+      :setting:`spec.role.actions.resources.database` parameters.
 
 .. setting:: spec.role.actions.resources.collection
 
@@ -289,7 +289,7 @@ This section describes the ``AtlasTeam`` custom resource parameters available.
    Human-readable label that identifies the collection on which the 
    action is granted. If this value is an empty string, the action is 
    granted on all collections within the database specified in the 
-   :setting:`spec.role.actions.resources.db` parameter.
+   :setting:`spec.role.actions.resources.database` parameter.
 
    .. note::
 
diff --git a/source/atlasprivateendpoint-custom-resource.txt b/source/atlasprivateendpoint-custom-resource.txt
@@ -94,8 +94,7 @@ Parameters
 
 This section describes the ``AtlasPrivateEndpoint`` custom resource parameters available. 
 
-.. setting:: metadata.name
-
+``metadata.name``
    *Type*: string
 
    *Required*
@@ -112,7 +111,7 @@ This section describes the ``AtlasPrivateEndpoint`` custom resource parameters a
    ``atlasPrivateEndpoint`` custom resource. If you define a custom
    namespace, you must add it to the
    :ref:`atlasproject-custom-resource` in the
-   :setting:`spec.privateEndpoint.privateEndpointRef.namespace` field.
+   ``spec.privateEndpoint.privateEndpointRef.namespace`` field.
 
 .. setting:: spec.awsConfiguration.id
 
diff --git a/source/atlasproject-custom-resource.txt b/source/atlasproject-custom-resource.txt
@@ -1990,7 +1990,7 @@ This section describes the ``AtlasProject`` custom resource parameters:
    *Conditional*
 
    Human-readable label from the :ref:`atlasteam-custom-resource` in the 
-   :setting:`metadata.name` field. If you want to assign a :ref:`team <ak8so-team>` 
+   ``metadata.name`` field. If you want to assign a :ref:`team <ak8so-team>` 
    to this project, you must specify this setting.
 
 .. setting:: spec.teams.teamRef.namespace
diff --git a/source/atlasteam-custom-resource.txt b/source/atlasteam-custom-resource.txt
@@ -53,8 +53,7 @@ Parameters
 
 This section describes the ``AtlasTeam`` custom resource parameters available. 
 
-.. setting:: metadata.name
-
+``metadata.name``
    *Type*: string
 
    *Required*
diff --git a/source/configure-ak8so-access-to-atlas.txt b/source/configure-ak8so-access-to-atlas.txt
@@ -158,7 +158,6 @@ steps.
    Network Peering </ak8so-network-peering>
    Private Endpoints </ak8so-private-link>
    Cloud Provider Integrations </ak8so-unified-access>
-   Custom Database Roles </ak8so-configure-custom-database-roles>
    X.509 </ak8so-x509>
    Encrypt Data </ak8so-encryption-at-rest-customer-keys>
    Federated Authentication </ak8so-configure-federated-authentication>
diff --git a/source/includes/steps-ak8so-helm-quick-start.yaml b/source/includes/steps-ak8so-helm-quick-start.yaml
@@ -31,7 +31,7 @@ content: |
   
   - If you want |ak8so| to watch a particular set of |k8s-nss|, set the 
     ``--watchNamespaces`` flag to a comma-separated list of |k8s-nss| to be watched.
-    For example, run the following command to watch only the ``atlas-operator``namespace:
+    For example, run the following command to watch only the ``atlas-operator`` namespace:
 
     .. code-block:: sh
 
@@ -155,7 +155,7 @@ content: |
      .. input:: 
         :language: sh
 
-        kubectl get secret -n my-cluster my-project-cluster-name-dbadmin  -ojson | jq -r '.data | with_entries(.value |= @base64d)';
+        kubectl get secret -n my-cluster my-project-cluster-name-dbadmin  -o json | jq -r '.data | with_entries(.value |= @base64d)';
 
      .. output:: 
         :language: json
diff --git a/source/includes/steps-ak8so-quick-start.yaml b/source/includes/steps-ak8so-quick-start.yaml
@@ -18,8 +18,7 @@ content: |
      organization ID information to configure |ak8so| access to 
      |service|.
 
-  :ref:`create-org-api-key` and configure the :guilabel:`API 
-  Access List`.
+  :ref:`create-org-api-key` and configure the :guilabel:`API Access List`.
 
   .. include:: /includes/fact-ak8so-api-key-permission.rst
 
diff --git a/source/migrate-parameter-to-resource.txt b/source/migrate-parameter-to-resource.txt
@@ -0,0 +1,204 @@
+.. _ak8so-migrate-ptr:
+
+=================================================
+Migrate Parameters to Custom Resource Definitions
+=================================================
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+Beginning with |ak8so| version 2.6, various resource configurations
+that previously took the form of parameters have transitioned to CRDs
+of their own. Support for the parameter-based parent resource
+configuration is deprecated. Existing parameter-based parent resource 
+configurations will continue to work, but support for these 
+configurations will be removed in a future release. 
+
+To continue managing these resources
+through |ak8so| in the future, migrate to the appropriate CRD.
+
+.. _ak8so-migrate-ptr-affected-list:
+
+Affected Configurations
+-----------------------
+
+The following configurations are affected:
+
+.. list-table::
+   :widths: 50 50
+   :header-rows: 1
+
+   * - Parameter
+     - CRD
+
+   * - :setting:`spec.customRoles`
+     - :ref:`atlascustomrole-custom-resource`
+
+   * - :setting:`spec.privateEndpoints`
+     - :ref:`atlasprivateendpoint-custom-resource`
+
+.. _ak8so-migrate-ptr-procedure:
+
+Migration Procedure
+-------------------
+
+To migrate from parameter-level resource management to CRD management:
+
+.. procedure::
+   :style: normal
+
+   .. step:: Disable project reconciliation and edit subresource
+      references.
+
+      a. Add the ``mongodb.com/atlas-reconciliation-policy: "skip"``
+         annotation to the parent resource's ``metadata``. This
+         prevents |ak8so| from attempting to reconcile the parent
+         resource and its subresources. 
+         
+      #. To prevent conflicts with the new CRD you create, you must
+         delete the parameters corresponding to the resource you want to
+         migrate from the parent resource.
+         
+      Consider the following example
+      of an ``atlasProject`` with a ``customRoles`` configuration:
+
+      .. code-block::
+         :copyable: false
+
+         apiVersion: atlas.mongodb.com/v1
+         kind: AtlasProject
+         metadata:
+           name: my-project
+         spec:
+           name: Test project
+           connectionSecretRef:
+             name: my-atlas-key
+           customRoles:
+             role:
+               name: my-role
+               actions:
+                 - name: getShardMap
+                   resources:
+                     cluster: true
+                 - name: shardingState
+                   resources:
+                     cluster: true
+                 - name: connPoolStats
+                   resources:
+                     cluster: true
+                 - name: getLog
+                   resources:
+                     cluster: true
+                 inheritedRoles:
+                   - name: operator-role-1
+                     role: backup
+            projectIpAccessList:
+              - cidrBlock: "203.0.113.0/24"
+                comment: "CIDR block for Application Server B - D"
+
+      Ensure that you have added the ``annotations`` block in lines 5 and 6 and remove the 
+      ``customRoles`` block shown in the previous example.
+
+      .. code-block::
+         :emphasize-lines: 5-6
+
+         apiVersion: atlas.mongodb.com/v1
+         kind: AtlasProject
+         metadata:
+           name: my-project
+         annotations: 
+           mongodb.com/atlas-reconciliation-policy: "skip"
+         spec:
+           name: Test project
+           connectionSecretRef:
+             name: my-atlas-key
+           projectIpAccessList:
+             - cidrBlock: "203.0.113.0/24"
+               comment: "CIDR block for Application Server B - D"
+
+      .. warning::
+
+         If you do not apply this annotation, |ak8so| will continue
+         to attempt reconciliation as you modify your other
+         resources. For users with :ref:`<deletion-protection>`
+         disabled, this can result in |ak8so| removing the
+         |service| project when you remove the ``atlasProject``
+         resource, or entering a blocked state attempting to remove
+         a project with active subresources such as database users
+         or deployments.
+
+   .. step:: Delete the parameters from the parent CRD.
+
+      To prevent conflicts with the new CRD you create, you must first
+      delete the parameters corresponding to the resource you want to
+      migrate from the parent resource. For example, remove the
+      ``customRoles`` parameter from the ``atlasProject`` CRD shown
+      previously:
+
+      .. code-block::
+
+        apiVersion: atlas.mongodb.com/v1
+        kind: AtlasProject
+        metadata:
+         name: my-project
+         annotations: 
+           mongodb.com/atlas-reconciliation-policy: "skip"
+        spec:
+          name: Test project
+          connectionSecretRef:
+            name: my-atlas-key
+          projectIpAccessList:
+            - cidrBlock: "203.0.113.0/24"
+          comment: "CIDR block for Application Server B - D"          
+
+   .. step:: Create the new CRD.
+
+      Create a CRD of the appropriate ``kind`` for the parameter you
+      want to migrate, according to its syntax. For example, to
+      migrate the ``customRoles`` parameter of the ``atlasProject``
+      CRD shown previously, create a
+      :ref:`atlascustomrole-custom-resource`.
+
+      .. code-block::
+
+         apiVersion: atlas.mongodb.com/v1
+         kind: AtlasCustomRole
+         metadata:
+           name: shard-operator-role
+           namespace: mongodb-atlas-system
+         labels:
+           mongodb.com/atlas-reconciliation-policy: keep
+         spec:
+           projectRef:
+             name: my-project
+             namespace: my-operator-namespace
+         role:
+           name: my-role
+           actions:
+             - name: getShardMap
+               resources:
+                 cluster: true
+             - name: shardingState
+               resources:
+                 cluster: true
+             - name: connPoolStats
+               resources:
+                 cluster: true
+             - name: getLog
+               resources:
+                 cluster: true
+           inheritedRoles:
+             - name: operator-role-1
+               role: backup
+
+   .. step:: Wait for |ak8so| to sync the new resource status.
+
+   .. step:: Remove the ``atlas-reconciliation-policy: "skip"`` annotation.
+
+Additionally, you can now configure this resource as an
+:ref:`Independent CRD <ak8so-independent-crd>`.
