DOCSP-32152 Document S3 Backup APIs to support an array of CA (#1426)

* DOCSP-32152 Document S3 Backup APIs to support an array of CA

* DOCSP-32152 updates for Nam's feedback

* DOCSP-32152 updates for Nam's proposed rewording

* Update source/reference/k8s-operator-om-specification.txt

Co-authored-by: John Williams <[email protected]>

* DOCSP-32152 updates for JW's feedback

* DOCSP-32152 updates for Nam's feedback

---------

Co-authored-by: John Williams <[email protected]>

Author: kanchana-mongodb

source/reference/k8s-operator-om-specification.txt

@@ -1247,10 +1247,59 @@ You can use |tls| for both |s3| and your application database, or for
 
    *Type*: boolean
 
-   Flag that indicates whether you use custom |tls| certificates for 
-   your |s3| oplog store specified by 
-   :opsmgrkube:`spec.applicationDatabase.security.tls.ca`.
-   The default is ``False``.
+   *Deprecated*. Use
+   :opsmgrkube:`spec.backup.s3OpLogStores.customCertificateSecretRefs`
+   instead. 
+   
+   Flag that indicates whether you use AppDB certificates
+   (``appdb-ca``) as the custom |tls| certificate for your |s3| oplog
+   store. The default is ``False``. 
+
+.. opsmgrkube:: spec.backup.s3OpLogStores.customCertificateSecretRefs 
+
+   *Type*: array of objects
+
+   List of custom certificates for your |s3| oplog store using |k8s|
+   |k8s-secrets|. The base64-encoded x.509 certificate must already be
+   present in a |k8s| |k8s-secret| with a key and must be parsable by
+   the `Java CertifcateFactory <https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/security/cert/CertificateFactory.html>`__.
+   You can't specify multiple certificates in a chain in one secret. If
+   you specify multiple certificates in a chain in one secret,
+   |k8s-op-short| uses only the first certificate in the chain. If you
+   also provide the
+   :opsmgrkube:`~spec.backup.s3OpLogStores.customCertificate` setting,  
+   |k8s-op-short| uses the
+   :opsmgrkube:`spec.applicationDatabase.security.tls.ca` as the custom
+   certificate for backups.   
+   
+   Each entry in the list specifies the
+   :opsmgrkube:`~spec.backup.s3OpLogStores.customCertificateSecretRefs.name`
+   and the
+   :opsmgrkube:`~spec.backup.s3OpLogStores.customCertificateSecretRefs.key`.
+   If you specify multiple secrets, |k8s-op-short| uses all the
+   certificates in the specified secrets. 
+
+   If you don't provide this setting, |onprem| uses the :abbr:`JVM (Java
+   Virtual Machine)` Default Trust Store used by |onprem|.
+
+.. opsmgrkube:: spec.backup.s3OpLogStores.customCertificateSecretRefs.name 
+
+   *Type*: string
+
+   *Required to use custom certificates for your S3 oplog store.*
+
+   |k8s| |k8s-secret| that contains the custom certificate.
+
+.. opsmgrkube:: spec.backup.s3OpLogStores.customCertificateSecretRefs.key 
+
+   *Type*: string
+
+   *Required to use custom certificates for your S3 oplog store.*
+
+   File that represents the key in the |k8s-secret| that contains the
+   base64-encoded x.509 certificate. If you don't specify this setting,
+   |k8s-op-short| can't utilize the custom certificate for |s3| oplog
+   store backups. 
 
 .. opsmgrkube:: spec.backup.s3OpLogStores.irsaEnabled
 
@@ -1411,10 +1460,60 @@ You can use |tls| for both |s3| and your application database, or for
 
    *Type*: boolean
 
-   Flag that indicates whether you use custom |tls| certificates for 
-   your |s3| snapshot store specified by 
-   :opsmgrkube:`spec.applicationDatabase.security.tls.ca`.
-   The default is ``False``.
+   *Deprecated*. Use
+   :opsmgrkube:`spec.backup.s3Stores.customCertificateSecretRefs`
+   instead. 
+   
+   Flag that indicates whether you use AppDB certificates
+   (``appdb-ca``) as the custom |tls| certificate for your |s3| backups.
+   The default is ``False``. 
+
+.. opsmgrkube:: spec.backup.s3Stores.customCertificateSecretRefs 
+
+   *Type*: array of objects
+
+   List of custom certificates for your |s3| snapshot store using |k8s|
+   |k8s-secrets|. The base64-encoded x.509 certificate must already be
+   present in a |k8s| |k8s-secret| with a key and must be parsable by
+   the `Java CertifcateFactory <https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/security/cert/CertificateFactory.html>`__.
+   You can't specify multiple  certificates in a chain in one secret. If
+   you specify multiple certificates in a chain in one secret,
+   |k8s-op-short| uses only the first certificate in the chain. If you
+   also provide the :opsmgrkube:`spec.backup.s3Stores.customCertificate`
+   setting, |k8s-op-short| uses the
+   :opsmgrkube:`spec.applicationDatabase.security.tls.ca` as the
+   custom certificate for backups.    
+   
+   Each entry in the list specifies the
+   :opsmgrkube:`~spec.backup.s3Stores.customCertificateSecretRefs.name`
+   and the
+   :opsmgrkube:`~spec.backup.s3Stores.customCertificateSecretRefs.key`.
+   If you specify multiple secrets, |k8s-op-short| uses all the
+   specified secrets. 
+
+   If you don't provide this setting, the |k8s-op-short| uses the
+   :abbr:`JVM (Java Virtual Machine)` Default Trust Store used by
+   |onprem| for backups. 
+
+.. opsmgrkube:: spec.backup.s3Stores.customCertificateSecretRefs.name 
+
+   *Type*: string
+
+   *Required to use custom certificates for your S3 oplog store.*
+
+   |k8s| |k8s-secret| that contains the custom certificate.
+
+.. opsmgrkube:: spec.backup.s3Stores.customCertificateSecretRefs.key 
+
+   *Type*: string
+
+   *Required to use custom certificates for your S3 oplog store.*
+
+   File that represents the key in the |k8s-secret| that contains the
+   base64-encoded x.509 certificate. If you don't specify this setting,
+   |k8s-op-short| can't utilize the custom certificate for |s3| snapshot
+   store and defaults to the default :abbr:`JVM {Java Virtual Machine)`
+   trust store used by |onprem|. 
 
 .. opsmgrkube:: spec.backup.s3Stores.irsaEnabled