(DOCSP-20045) Adds includes about secret storage wherever docs talk about K8s secrets (#780)

* (DOCSP-20045) Adds includes about secret storage  wherever docs talk about K8s secrets

* Adds more includes

* Adds tutorial to add secrets to Vault

* Adds link to create vault secret in more places

* Adds include file, updates other pages

* Rebasing

* Adds more changes to TLS pages

* Includes changes from copy review

* Adds YAML steps file for procedure

Author: sarahsimpers

source/includes/facts/fact-if-use-vault.rst

@@ -0,0 +1,2 @@
+If you're using |hashicorp-vault| as your :ref:`secret storage tool <k8s-secret-storage>`, 
+you can :ref:`Create a Vault Secret <create-vault-secret>` instead.

source/includes/facts/fact-learn-more-secret-storage.rst

@@ -0,0 +1,2 @@
+To learn about your options for secret
+storage, see :ref:`Configure Secret Storage <k8s-set-secret-storage-tool>`.

source/includes/list-tables/resource-keys-tls-custom-ca.rst

@@ -31,6 +31,6 @@
        | :setting:`.tls.certsSecretPrefix<spec.security.tls.certsSecretPrefix>`
      - string
      - Optional
-     - If applicable, add the ``<prefix>`` of the |k8s| |k8s-secret| 
+     - If applicable, add the ``<prefix>`` of the secret 
        name that contains your MongoDB deployment's |tls| certificates.
      - ``devDb``

source/includes/list-tables/rs-resource-base-options.rst

@@ -57,7 +57,7 @@
 
    * - :setting:`spec.credentials`
      - string
-     - Name of the |k8s| |k8s-secret| you
+     - Name of the secret you
        :ref:`created <create-k8s-secret>` as |mms| |api|
        authentication credentials for the |k8s-op-short| to
        communicate with |onprem|.

source/includes/prereqs-deploy-resource.rst

@@ -5,10 +5,13 @@ following procedures:
 
 - :ref:`create-k8s-project`
 
-- :ref:`create-k8s-credentials`
+- :ref:`create-k8s-credentials` or 
+  :ref:`configure a different secret storage tool <k8s-set-secret-storage-tool>`
 
 Alternatively, for |cloud|, after installing the Kubernetes Operator, 
 you can use the |cloud-short| :cloudmgr:`UI 
 </tutorial/nav/k8s-config-for-mdb-resource/>` to automatically generate 
 the ConfigMap and Kubernetes secret YAML files, which you can then 
-apply to your Kubernetes environment.
+apply to your Kubernetes environment. 
+
+.. include:: /includes/facts/fact-can-change-secret-storage-tool.rst

source/includes/steps-add-database-user-scram.yaml

@@ -51,7 +51,7 @@ content: |
 
      * - ``spec.passwordSecretKeyRef.name``
        - string
-       - ``metadata.name`` value of the |k8s-secret| that stores the
+       - ``metadata.name`` value of the secret that stores the
          user's password.
        - ``my-resource``
 

source/includes/steps-add-database-user-secret-scram.yaml

@@ -40,6 +40,10 @@ ref: paste-k8s-secret
 content: |
   a. Open your preferred text editor.
   b. Paste this User Secret into a new text file.
+
+  .. include:: /includes/facts/fact-if-use-vault.rst
+
+  .. include:: /includes/facts/fact-learn-more-secret-storage.rst
 ---
 title: "Change the highlighted lines."
 level: 4

source/includes/steps-configure-om-queryable-backups.yaml

@@ -36,6 +36,9 @@ content: |
 
      kubectl create secret generic queryable-pem --from-file=./queryable.pem
 
+  .. include:: /includes/facts/fact-if-use-vault.rst
+
+  .. include:: /includes/facts/fact-learn-more-secret-storage.rst
 ---
 title: "Mount the Secret as a volume that |onprem| custom objects will use."
 stepnum: 4

source/includes/steps-create-vault-secret.yaml

@@ -0,0 +1,91 @@
+---
+stepnum: 1
+level: 4
+ref: have-keys
+title: "Obtain the |onprem| public and private Keys."
+content: |
+
+  Make sure you have the public and private keys for your desired
+  |onprem| |svc-api-key|.
+
+---
+stepnum: 2
+level: 4
+ref: create-vault-secret
+title: "Create the secret in |vault-short|."
+content: |
+
+  Invoke the following |vault-short| command to create your secret, replacing
+  the variables with the values in the table:
+
+   .. list-table::
+       :widths: 30 70
+       :header-rows: 1
+
+       * - Placeholder
+         - Description
+           
+       * - {Namespace}
+         - Label that identifies the namespace where you deployed |k8s-op-short|.
+
+       * - {SecretName}
+         - Human-readable label that identifies the secret you're creating in |vault-short|.
+
+       * - {PublicKey}
+         - The public key for your desired |onprem| |svc-api-key|.
+
+       * - {PrivateKey}
+         - The private key for your desired |onprem| |svc-api-key|.
+
+   .. code-block:: sh
+
+      vault kv put secret/data/mongodbenterprise/operator/{Namespace}/{SecretName} publicKey={PublicKey} privateKey={PrivateKey}
+
+   The path in this command is the default path. You can replace ``mongodbenterprise/operator`` with
+   your base path if you customized your |k8s-op-short| configuration.
+
+---
+stepnum: 3
+level: 4
+ref: verify-vault-secret
+title: "Verify the |vault-short| secret creation was successful."
+content: |
+
+  Invoke the following |vault-short| command to verify your secret, replacing
+  the variables with the values in the following table:
+
+   .. list-table::
+       :widths: 30 70
+       :header-rows: 1
+
+       * - Placeholder
+         - Description
+       
+       * - {Namespace}
+         - Label that identifies the namespace where you deployed |k8s-op-short|.
+
+       * - {SecretName}
+         - Human-readable label that identifies the secret you're creating in |vault-short|.
+
+   .. code-block:: sh
+
+      vault kv get secret/data/mongodbenterprise/operator/{Namespace}/{SecretName}
+
+   This command returns a secret description in the shell:
+
+   .. code-block:: sh
+
+      ====== Metadata ======
+      Key              Value
+      ---              -----
+      created_time     2021-12-15T17:20:22.985303Z
+      deletion_time    n/a
+      destroyed        false
+      version          1
+
+      ======= Data =======
+      Key          Value
+      ---          -----
+      publicKey    {PublicKey} 
+      privateKey   {PrivateKey}
+...

source/includes/steps-deploy-k8s-opsmgr-http.yaml

@@ -74,7 +74,7 @@ content: |
 
       * - :opsmgrkube:`spec.adminCredentials`
         - string
-        - Name of the |k8s-secret| you :ref:`created <om-rsrc-prereqs>`
+        - Name of the secret you :ref:`created <om-rsrc-prereqs>`
           for the |onprem| admin user.
 
           .. note::
@@ -213,7 +213,7 @@ content: |
         | ``.s3SecretRef``
         | ``.``:opsmgrkube:`~spec.backup.s3Stores.s3SecretRef.name`
       - string
-      - Name of the |k8s-secret| that contains the ``accessKey`` and
+      - Name of the secret that contains the ``accessKey`` and
         ``secretKey`` fields. The :ref:`backup-daemon` uses the
         values of these fields as credentials to access the |s3| or
         |s3|-compatible bucket.
@@ -439,8 +439,8 @@ ref: create-credentials
 content: |
 
   If you enabled Backup, you must create an |onprem| organization,
-  generate programmatic API keys, and create a |k8s-secret|. These
-  activities follow the prerequisites and procedure on the
+  generate programmatic API keys, and create a secret in your :ref:`secret-storage-tool <k8s-set-secret-storage-tool>`. 
+  These activities follow the prerequisites and procedure on the
   :ref:`create-k8s-credentials` page.
 
 ---

source/includes/steps-deploy-k8s-opsmgr-https.yaml

@@ -5,7 +5,7 @@ inherit:
   file: steps-configure-kubectl-namespace.yaml
   ref: configure-kubectl-namespace
 ---
-title: "Create a Kubernetes secret for your certificates."
+title: "Create a secret for your certificates."
 stepnum: 2
 ref: create-cert-secret
 content: |
@@ -18,6 +18,8 @@ content: |
       kubectl create secret tls <metadata.name>-cert \
        --cert=<om-tls-cert> \
        --key=<om-tls-key>
+
+   .. include:: /includes/facts/fact-if-use-vault.rst
 ---
 title: "If necessary, validate your TLS Certificate."
 stepnum: 3

source/includes/steps-deploy-k8s-sharded-cluster.yaml

@@ -113,7 +113,7 @@ content: |
 
       * - :setting:`spec.credentials`
         - string
-        - Name of the |k8s| |k8s-secret| you
+        - Name of the secret you
           :ref:`created <create-k8s-secret>` as |mms| |api|
           authentication credentials for the |k8s-op-short| to
           communicate with |onprem|.

source/includes/steps-deploy-k8s-standalone.yaml

@@ -84,7 +84,7 @@ content: |
 
       * - :setting:`spec.credentials`
         - string
-        - Name of the |k8s| |k8s-secret| you
+        - Name of the secret you
           :ref:`created <create-k8s-secret>` as |mms| |api|
           authentication credentials for the |k8s-op-short| to
           communicate with |onprem|.

source/includes/steps-source-deploy-k8s-resource.yaml

@@ -371,7 +371,7 @@ content: |
      Annotations:    <none>
 
 ---
-title: "Create the |k8s-secret| for your replica set's |tls| certificate."
+title: "Create the secret for your replica set's |tls| certificate."
 stepnum: 0
 level: 4
 ref: create-rs-tls-secret
@@ -386,6 +386,10 @@ content: |
        --cert=<replica-set-tls-cert> \
        --key=<replica-set-tls-key>
 
+  .. include:: /includes/facts/fact-if-use-vault.rst
+
+  .. include:: /includes/facts/fact-learn-more-secret-storage.rst
+
 ---
 title: "Create the |k8s-secret| for your agent's X.509 certificate."
 stepnum: 0
@@ -402,6 +406,8 @@ content: |
        --cert=<agent-tls-cert> \
        --key=<agent-tls-key>
 
+  .. include:: /includes/facts/fact-if-use-vault.rst
+
 ---
 title: "Renew the |k8s-secret| for your agents' X.509 certificates."
 stepnum: 0
@@ -495,7 +501,7 @@ content: |
      kubectl create configmap custom-ca --from-file=ca-pem
 
 ---
-title: "Create the |k8s-secret| for your Shards' TLS certificates."
+title: "Create the secret for your Shards' TLS certificates."
 stepnum: 0
 level: 4
 ref: create-sc-shards-tls-secret
@@ -513,6 +519,8 @@ content: |
      kubectl -n mongodb create secret tls <metadata.name>-1-cert \
        --cert=<shard-1-tls-cert> \
        --key=<shard-1-tls-key>
+
+  .. include:: /includes/facts/fact-if-use-vault.rst
 ---
 title: "Renew the |k8s-secret| for your Shards' TLS certificates."
 stepnum: 0
@@ -540,13 +548,13 @@ content: |
      kubectl apply -f -
 
 ---
-title: "Create the |k8s-secret| for your config servers' TLS certificate."
+title: "Create the secret for your config servers' TLS certificate."
 stepnum: 0
 level: 4
 ref: create-sc-config-tls-secret
 content: |
 
-  Run this ``kubectl`` command to create a new |k8s-secret| that stores
+  Run this ``kubectl`` command to create a new secret that stores
   the sharded cluster config servers' certificate:
 
   .. code-block:: sh
@@ -555,6 +563,8 @@ content: |
        --cert=<config-tls-cert> \
        --key=<config-tls-key>
 
+  .. include:: /includes/facts/fact-if-use-vault.rst
+
 ---
 title: "Renew the |k8s-secret| for your config server's TLS certificates."
 stepnum: 0
@@ -575,13 +585,13 @@ content: |
      kubectl apply -f -
 
 ---
-title: "Create the |k8s-secret| for your mongos servers' TLS certificate."
+title: "Create the secret for your mongos servers' TLS certificate."
 stepnum: 0
 level: 4
 ref: create-sc-mongos-tls-secret
 content: |
 
-  Run this ``kubectl`` command to create a new |k8s-secret| that stores
+  Run this ``kubectl`` command to create a new secret that stores
   the sharded cluster |mongos| certificate:
 
   .. code-block:: sh
@@ -590,6 +600,8 @@ content: |
        --cert=<mongos-tls-cert> \
        --key=<mongos-tls-key>
 
+  .. include:: /includes/facts/fact-if-use-vault.rst
+
 ---
 title: "Renew the |k8s-secret| for your mongos server's TLS certificates."
 stepnum: 0

source/includes/steps-source-deploy-om-resource.yaml

@@ -2,7 +2,7 @@
 stepnum: 0
 level: 4
 ref: create-om-appdb-secret
-title: "Create a Secret with your Application Database |tls| certificate."
+title: "Create a secret with your Application Database |tls| certificate."
 content: |
 
   Run this ``kubectl`` command to create a new |k8s-secret| that stores
@@ -14,6 +14,10 @@ content: |
        --cert=<appdb-tls-cert> \
        --key=<appdb-tls-key>
 
+  .. include:: /includes/facts/fact-if-use-vault.rst
+
+  .. include:: /includes/facts/fact-learn-more-secret-storage.rst
+
 ---
 stepnum: 0
 level: 4

source/includes/steps-use-vault.yaml

@@ -277,11 +277,11 @@ content: |
      |k8s-op-short| creates
    - TLS secrets
 
-   To manually migrate secrets, `add them to Vault <https://www.vaultproject.io/docs/secrets/kv/kv-v2#usage>`__.  
-   After you add them to |vault-short|, you can remove them from |k8s|. 
+   To manually migrate or create new secrets, :ref:`add them to Vault <create-vault-secret>`.  
+   After you add them to |vault-short|, you can remove them from |k8s|.
       
-   All other secrets migrate automatically, and |k8s-op-short| uses
-   |vault-short| for new secrets.
+   All other secrets that the |k8s-op-short| creates migrate automatically, and |k8s-op-short| uses
+   |vault-short| for new secrets. User-created secrets must be :ref:`added to Vault <create-vault-secret>`.
 
    .. note::
 

source/multi-cluster-arch.txt

@@ -71,6 +71,8 @@ The |k8s-op-full| performs these actions:
   each member cluster corresponding to the number of replica set members
   in the MongoDB cluster.
 
+  .. include:: /includes/facts/fact-can-change-secret-storage-tool.rst
+
 .. figure:: /images/multi-cluster-arch.svg
    :alt: Diagram showing the high-level architecture of the multi-cluster
          deployment across regions and availability zones using the

source/reference/k8s/example-opsmgr-minimal.yaml

@@ -7,7 +7,7 @@ spec:
   replicas: 1
   version: <opsmanagerversion>
   adminCredentials: <adminusercredentials> # Should match metadata.name
-                                           # in the Kubernetes secret
+                                           # in the secret
                                            # for the admin user
   externalConnectivity:
     type: LoadBalancer

source/tutorial/configure-om-queryable-backups.txt

@@ -35,13 +35,13 @@ In the following procedure you:
   </reference/configuration/#brs.queryable.pem>` file that holds the
   certificatesfor accessing the backup snapshots that you intend to query.
 
-- Create the Secret containing the :opsmgr:`queryable.pem
+- Create the secret containing the :opsmgr:`queryable.pem
   </reference/configuration/#brs.queryable.pem>` file.
 
 - Configure a persistent volume that is attached to the |onprem|
   |k8s| Pod in the |k8s-op-short|.
 
-- Specify the mount point for the Secret in  the persistent volume's
+- Specify the mount point for the secret in  the persistent volume's
   configuration.
 
 - Save the |onprem| custom resource configuration and apply it.