(DOCSP-5465): Further split the configuration page up. (#43)

jdestefano-mongo · jwilliams-mongo · commit ae64e8182743 · 2025-04-14T17:11:14.000-05:00
* (DOCSP-5465): Further split the configuration page up. * (DOCSP-5465): Copy review edits.
diff --git a/source/configuration.txt b/source/configuration.txt
@@ -12,254 +12,14 @@ Configure the |k8s-op-short|
    :depth: 1
    :class: singlecol
 
-After
-:doc:`installing the {+k8s-op-short+} </tutorial/install-k8s-operator>`,
-you will need to perform both of the following configurations before 
-deploying MongoDB database resources:
+.. include:: /includes/toc/dfn-list-configuration.rst
 
-- :ref:`create-k8s-project`
+.. include:: /includes/toc/configuration.rst
 
-- :ref:`create-k8s-credentials`
+.. class:: hidden
 
-.. _create-k8s-project:
+   .. toctree::
+      :titlesonly:
 
-Create your |onprem| Project using a |k8s| |k8s-configmap|
-----------------------------------------------------------
-
-The |k8s-op-full| uses a |k8s| |k8s-configmap| to link to your
-|onprem| :opsmgr:`Project </tutorial/manage-projects>`. To create a
-|k8s-op-short| ConfigMap, you need to edit 4 lines of the
-:ref:`example ConfigMap <example-k8s-configmap>` |yaml| file and apply
-the ConfigMap:
-
-1. Copy the following :ref:`example ConfigMap <example-k8s-configmap>`.
-
-   .. _example-k8s-configmap:
-
-   .. literalinclude:: /reference/k8s/example-configmap.yaml
-      :language: yaml
-      :emphasize-lines: 5-6, 8-10
-
-#. Open your preferred text editor and paste the example
-   |k8s-configmap| into a new text file.
-
-#. Change the following four lines:
-
-   .. list-table::
-      :widths: 20 20 40 20
-      :header-rows: 1
-
-      * - Key
-        - Type
-        - Description
-        - Example
-
-      * - ``metadata.name``
-        - string
-        - Label for a |k8s| |k8s-obj|.
-
-          .. seealso::
-
-             - :setting:`metadata.name`
-             - |k8s| documentation on `names <https://kubernetes.io/docs/concepts/overview/working-with-objects/names/>`__.
-               This name must follow :rfc:`RFC1123 <1123>` naming
-               conventions, using only lowercase alphanumeric
-               characters, '-' or '.', and must start and end with an
-               alphanumeric character.
-
-        - ``myconfigmap``
-
-      * - ``metadata.namespace``
-        - string
-        - Scope of object names. Used to limit what can be managed to
-          a subset of all |k8s-objs|. The default value is ``mongodb``.
-
-          .. important::
-             The |k8s-op-short|, |k8s-secret|, and |k8s-mdbrsc|\s
-             *must* be created in the same |k8s-ns|.
-
-          .. seealso::
-
-             - :setting:`metadata.namespace`
-             - |k8s| documentation on |k8s-nss|
-
-        - ``mongodb``
-
-      * - ``data.projectName``
-        - string
-        - Label for your |mms|
-          :opsmgr:`Project </tutorial/manage-projects>`.
-
-          .. admonition:: Let |k8s-op-short| create the Project
-             :class: important
-
-             The |k8s-op-short| creates the |mms| Project if it does
-             not exist. It is **strongly recommended** to use the
-             Operator to create a new Project for |k8s| to manage. The
-             Operator adds additional internal information to Projects
-             that it creates.
-
-          If you need or want to use an existing Project, you can find
-          the ``projectName`` by clicking the :guilabel:`All Clusters`
-          link at the top left of the screen, then either search by
-          name in the :guilabel:`Search` box or scroll to find the
-          name in the list. Each card in this list represents the
-          combination of one **Organization** and **Project**.
-
-        - ``Development``
-
-      * - ``data.orgId``
-        - string
-        - 24 character hex string that uniquely identifies your
-          MongoDB :opsmgr:`Organization </tutorial/manage-organizations>`.
-          You can find the ``orgId`` in your |onprem| |url|:
-
-          1. Click the :guilabel:`Context` menu.
-          2. Select your Organization.
-          3. View the current |url| in your
-             browser and copy the value
-             displayed in the ``<orgId>``
-             placeholder below:
-
-             | ``https://ops.example.com:8443/``
-             | ``v2#/org/<orgId>/projects``
-
-          .. important::
-
-             This field is *optional*. If you omit the ``orgId``,
-             |onprem| creates an Organization called ``projectName``
-             that contains a Project also called ``projectName``.
-
-             You must have the :authrole:`Organization Project Creator`
-             role to create a new project
-             *within an existing organization*.
-
-             .. admonition:: Limited to Cloud or Ops Manager Organizations
-
-                If you set this value, it can be for a Cloud Manager or
-                an Ops Manager organization only. If you try to use an
-                Atlas organization, the |k8s-op-short| may not work as
-                intended.
-
-        - | ``5cc9b333dd3e384a625a6615``
-
-      * - ``data.baseUrl``
-        - string
-        - |url| to your |application| including the |fqdn| and port
-          number.
-
-          .. note::
-
-             You may use |cloud-short| for the ``data.baseUrl`` value.
-
-        - ``https://ops.example.com:8443``
-
-#. Save this file with a ``.yaml`` file extension.
-
-#. Invoke the following |k8s| command to create your |k8s-configmap|:
-
-   .. code-block:: sh
-
-      kubectl apply -f <myconfigmap.yaml>
-
-   .. important::
-
-      All subsequent ``kubectl`` commands you invoke must add the
-      ``-n`` option with the :setting:`metadata.namespace` you
-      specified in your |k8s-configmap|.
-
-#. Invoke the following |k8s| command to verify your |k8s-configmap|:
-
-   .. code-block:: sh
-
-      kubectl describe configmaps <myconfigmap> -n <metadata.namespace>
-
-   .. admonition:: *Always include the namespace option with* ``kubectl``
-         :class: important
-
-         |kubectl| defaults to an empty namespace if you do not specify
-         the ``-n`` option, resulting in deployment failures. You must
-         specify the value of the ``<metadata.namespace>`` field.
-         The |k8s-op-short|, |k8s-secret|, and |k8s-mdbrsc|\s should
-         run in the same unique namespace.
-
-   This command returns a ConfigMap description in the shell:
-
-   .. code-block:: sh
-
-      Name:           <myconfigmap>
-      Namespace:      <metadata.namespace>
-      Labels:         <none>
-      Annotations:    <none>
-
-.. _create-k8s-credentials:
-.. _create-k8s-secret:
-
-Create a |k8s| Secret to Allow the Operator to Manage the Project
------------------------------------------------------------------
-
-For the |k8s-op-short| to create or update |k8s-objs| in your |onprem|
-Project, you need to store your username and
-:ref:`Public API Key <generate-public-api-key>` as a |k8s|
-|k8s-secret|. Creating a secret stores authentication credentials so
-only |k8s| can access them.
-
-Multiple secrets can exist in the same namespace. Each user should
-have their own secret.
-
-To create your |k8s| secret:
-
-1. Make sure you have your |onprem| username and Public API Key.
-
-   If you do not have your Public API Key, you need to generate a new
-   :ref:`Public API Key <generate-public-api-key>`.
-
-2. Invoke the following |k8s| command to create your secret:
-
-   .. code-block:: sh
-
-      kubectl -n <metadata.namespace> \
-        create secret generic <myCredentials> \
-        --from-literal="user=<first.last@example.com>" \
-        --from-literal="publicApiKey=<my-public-api-key>"
-
-   .. note::
-
-      The ``-n`` flag limits the |k8s-ns| to which this secret
-      applies. All MongoDB |k8s| resources must be in the same
-      namespace with the |k8s-secrets| and |k8s-configmaps|. The
-      |k8s-op-short| does not use either the secrets or ConfigMaps.
-
-3. Invoke the following |k8s| command to verify your secret:
-
-   .. code-block:: sh
-
-      kubectl describe secrets/<myCredentials> -n <metadata.namespace>
-
-   This command returns a secret description in the shell:
-
-   .. code-block:: sh
-
-      Name:         <myCredentials>
-      Namespace:    <metadata.namespace>
-      Labels:       <none>
-      Annotations:  <none>
-
-      Type:  Opaque
-
-      Data
-      ====
-      publicApiKey:  31 bytes
-      user:          22 bytes
-
-Next Steps
-----------
-
-Now that you installed the |k8s-op-full|, created your |com| project and
-|k8s| |k8s-configmap|, and created your credentials, you are ready to
-deploy MongoDB resources. For more information on deploying MongoDB
-resources, see:
-
-- :doc:`/tutorial/deploy-standalone`
-- :doc:`/tutorial/deploy-replica-set`
-- :doc:`/tutorial/deploy-sharded-cluster`
+      /tutorial/create-project-using-configmap
+      /tutorial/create-operator-credentials
diff --git a/source/includes/prereqs-deploy-resource.rst b/source/includes/prereqs-deploy-resource.rst
@@ -1,6 +1,8 @@
-To deploy a |deployment| using a |k8s-obj|, you need to complete the
+To deploy a |deployment| using an |k8s-obj|, you need to complete the
 following procedures:
 
 - :doc:`Install Kubernetes Operator </tutorial/install-k8s-operator>`
 
-- :doc:`/configuration`
+- :ref:`create-k8s-project`
+
+- :ref:`create-k8s-credentials`
diff --git a/source/includes/toc-configuration.yaml b/source/includes/toc-configuration.yaml
@@ -0,0 +1,10 @@
+file: /tutorial/create-project-using-configmap
+description: |
+  Create a |k8s-configmap| to link the |k8s-op-short| to your |com|
+  Project.
+---
+file: /tutorial/create-operator-credentials
+description: |
+  Create a |k8s| secret so the |k8s-op-short| can create and update
+  |k8s-objs| in your |com| Project.
+...
diff --git a/source/tutorial/create-operator-credentials.txt b/source/tutorial/create-operator-credentials.txt
@@ -0,0 +1,68 @@
+.. _create-k8s-credentials:
+.. _create-k8s-secret:
+
+=========================================
+Create Credentials for the |k8s-op-short|
+=========================================
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+For the |k8s-op-short| to create or update |k8s-objs| in your |com|
+Project, you need to store your username and
+:ref:`Public API Key <generate-public-api-key>` as a |k8s|
+|k8s-secret|. Creating a secret stores authentication credentials so
+only |k8s| can access them.
+
+Multiple secrets can exist in the same namespace. Each user should
+have their own secret.
+
+To create your |k8s| secret:
+
+1. Make sure you have your |onprem| username and Public API Key.
+
+   If you do not have your Public API Key, you need to generate a new
+   :ref:`Public API Key <generate-public-api-key>`.
+
+2. Invoke the following |k8s| command to create your secret:
+
+   .. code-block:: sh
+
+      kubectl -n <metadata.namespace> \
+        create secret generic <myCredentials> \
+        --from-literal="user=<first.last@example.com>" \
+        --from-literal="publicApiKey=<my-public-api-key>"
+
+   .. note::
+
+      The ``-n`` flag limits the |k8s-ns| to which this secret
+      applies. All MongoDB |k8s| resources must be in the same
+      namespace with the |k8s-secrets| and |k8s-configmaps|. The
+      |k8s-op-short| does not use either the secrets or ConfigMaps.
+
+3. Invoke the following |k8s| command to verify your secret:
+
+   .. code-block:: sh
+
+      kubectl describe secrets/<myCredentials> -n <metadata.namespace>
+
+   This command returns a secret description in the shell:
+
+   .. code-block:: sh
+
+      Name:         <myCredentials>
+      Namespace:    <metadata.namespace>
+      Labels:       <none>
+      Annotations:  <none>
+
+      Type:  Opaque
+
+      Data
+      ====
+      publicApiKey:  31 bytes
+      user:          22 bytes
diff --git a/source/tutorial/create-project-using-configmap.txt b/source/tutorial/create-project-using-configmap.txt
