Add externalAccess spec, guidance for acme certs (#1263)

Add externalAccess spec, guidance for acme certs

reconcile changes against multi-cluster spec

reconcile changes against multi-cluster spec

copy and tech review feedback 1

tech review feedback 2

copy review 2

add includes for externalAccess

copy review 2 (cont.)

copy and tech review 3

final copy review

final tech review

final updates

Author: davidhou17

conf.py

@@ -84,6 +84,7 @@
     '.. |copy| unicode:: U+000A9',
     '.. |year| replace:: {0}'.format(datetime.date.today().year),
     '.. |a-application| replace:: an Ops Manager Application',
+    '.. |acme| replace:: :abbr:`ACME (Automatic Certificate Management Environment)`',
     '.. |a-mms| replace:: an Ops Manager',
     '.. |A-mms| replace:: An Ops Manager',
     '.. |application-s| replace:: Ops Manager Applications',

source/includes/facts/fact-acme-provider-certs.rst

@@ -0,0 +1,4 @@
+If you're using an |acme| based service provider such as `Let's Encrypt 
+<https://letsencrypt.org>`_ to issue |tls| certificates, the provider 
+might prohibit you from adding the Pod's default |fqdn|\s (``*.svc.cluster.local``)
+to |san-dns|\s in the certificate.

source/includes/facts/fact-external-access-spec.rst

@@ -0,0 +1,36 @@
+If you add ``spec.externalAccess``, the |k8s-op-short| creates an external service 
+for each Pod in a replica set. External services provide an external entry point 
+for each MongoDB database Pod in a cluster. Each external service has selectors 
+that match the external service to a specific Pod.
+
+If you add this setting without any values, the |k8s-op-short| creates 
+an external service with the following default values:
+
+.. list-table::
+  :header-rows: 1
+  :widths: 30 25 45
+
+  * - Field
+    - Value
+    - Description
+
+  * - ``Name``
+    - ``<pod-name>-svc-external``
+    - Name of the external service. You can't change this value.
+
+  * - ``Type``
+    - ``LoadBalancer``
+    - Creates an external :k8sdocs:`LoadBalancer 
+      </concepts/services-networking/service/#loadbalancer>` service.
+
+  * - ``Port``
+    - ``<Port Number>``
+    - A port for |mongod|. If you set |external-domain|,
+      the external service adds another port (``Port Number + 1``) for backups.
+  
+  * - ``publishNotReadyAddress``
+    - ``true``
+    -  Specifies that :k8sdocs:`DNS records </concepts/services-networking/dns-pod-service/>`
+       are created even if the Pod isn't ready. 
+       Do not set to ``false`` for any database Pod.
+        

source/includes/facts/fact-external-domain-spec.rst

@@ -0,0 +1,34 @@
+An external domain used to externally expose your replica set deployment.
+
+By default, each replica set member uses the |k8s| Pod's |fqdn| 
+(``*.svc.cluster.local``) as the default hostname. However, if you add a
+external domain to this setting, the replica set uses a hostname that is a 
+subdomain of the specified domain instead. This hostname uses the following 
+format:
+
+|hostname-format|
+
+For example:
+
+|hostname-example|
+
+After you deploy the replica set with this setting, the
+|k8s-op-short| uses the hostname with the external domain to override 
+the ``processes[n].hostname`` field in the |onprem| :opsmgr:`automation configuration 
+</reference/cluster-configuration>`. Then, the {+mdbagent+} uses this hostname to 
+connect to |mongod|.
+
+To specify other hostnames for connecting to the replica set, you can use the 
+:setting:`spec.connectivity.replicaSetHorizons` setting. However, the following 
+connections still use the hostname with the external domain:
+
+- The {+mdbagent+} to connect to |mongod|.
+- |mongod| to connect to other |mongod| instances.
+
+.. warning::
+
+    Specifying this field changes how |onprem| registers |mongod| processes.
+    You can specify this field only for new replica set deployments starting in |k8s-op-short| 
+    version 1.19. You can't change the value of this field or any ``processes[n].hostname`` fields 
+    in the |onprem| :opsmgr:`automation configuration </reference/cluster-configuration>` for a running
+    replica set deployment.

source/includes/facts/fact-external-service-annotation-spec.rst

@@ -0,0 +1,6 @@
+Key-value pairs that let you add cloud provider-specific
+configuration settings to all clusters in your deployment. 
+
+To learn more about annotations, see the 
+:k8sdocs:`Kubernetes documentation </concepts/overview/working-with-objects/annotations/>`
+and the documentation for your |k8s| cloud provider.

source/includes/facts/fact-external-service-spec.rst

@@ -0,0 +1,21 @@
+When you set the :setting:`spec.externalAccess` setting, the |k8s-op-short| 
+automatically creates an external load balancer service with preset values. 
+You can override certain values or add new values depending on your needs. 
+For example, if you intend to create :k8sdocs:`NodePort services
+</concepts/services-networking/service/#type-nodeport>`
+and don't need a load balancer, you must configure overrides in your
+|k8s| specification:
+
+.. code-block:: yaml
+
+   externalAccess:
+     externalService: 
+       annotations:
+         # cloud-specific annotations for the service
+       spec:
+         type: NodePort # default is LoadBalancer
+         # you can specify other spec overrides if necessary
+
+For more information about the |k8s| specification, see :k8sdocs:`ServiceSpec 
+</reference/kubernetes-api/service-resources/service-v1/#ServiceSpec>` 
+in the |k8s| documentation.

source/includes/list-tables/configure-acme-based-certs.rst

@@ -0,0 +1,28 @@
+.. list-table::
+   :widths: 25 10 10 55
+   :header-rows: 1
+
+   * - Key
+     - Type
+     - Necessity
+     - Description
+
+   * - | ``spec.externalAccess``
+       | :setting:`.externalDomain<spec.externalAccess.externalDomain>`
+     - string
+     - Required
+     - .. include:: /includes/facts/fact-external-domain-spec.rst
+
+   * - | ``spec.externalAccess``
+       | :setting:`.externalService.spec<spec.externalAccess.externalService.spec>`
+     - collection
+     - Optional
+     - Configuration for the :k8sdocs:`ServiceSpec </reference/kubernetes-api/service-resources/service-v1/#ServiceSpec>`.
+     
+       .. include:: /includes/facts/fact-external-service-spec.rst
+
+   * - | ``spec.externalAccess``
+       | :setting:`.externalService.annotations<spec.externalAccess.externalService.annotations>`
+     - collection
+     - Optional
+     -  .. include:: /includes/facts/fact-external-service-annotation-spec.rst

source/includes/options-k8s-shared.yaml

@@ -630,8 +630,8 @@ description: |
 
   .. important::
 
-     :setting:`spec.security.tls.enabled` is deprecated and will be
-     removed in a future release. To enable |tls|, provide a value for 
+     :setting:`spec.security.tls.enabled` is deprecated starting in |k8s-op-short| version 1.19. 
+     To enable |tls|, provide a value for 
      the :setting:`spec.security.certsSecretPrefix` setting.
 
   Encrypts communications using TLS certificates between:
@@ -1341,9 +1341,16 @@ optional: true
 default: "false"
 description: |
 
-  Determines whether the MongoDB deployment is exposed outside of the
-  Kubernetes cluster. This results in |k8s| creating a
-  :k8sdocs:`NodePort service </concepts/services-networking/service/#nodeport>`.
+  .. important::
+
+     ``spec.exposedExternally`` is deprecated starting in |k8s-op-short| version 1.19 
+     and will be removed in a future |k8s-op-short| release. To configure how your deployment 
+     should be exposed externally, use the :setting:`spec.externalAccess` settings.
+
+  Determines whether a |multi-cluster| is exposed outside the |k8s| clusters. 
+  Setting ``spec.exposedExternally: true`` is equivalent to setting ``spec.externalAccess: {}``. 
+  See :setting:`spec.externalAccess` for details.
+
 ---
 program: _shared
 name: spec.podSpec.podTemplate
@@ -1353,7 +1360,7 @@ optional: true
 description: |
 
   :k8sdocs:`Template </concepts/workloads/pods/pod-overview/#pod-templates>`
-  for the |k8s| pods that the |k8s-op| creates for {{component}}.
+  for the |k8s| Pods that the |k8s-op| creates for {{component}}.
 
   Template values take precedence over values specified in {{podSpec}}.
 
@@ -1370,7 +1377,7 @@ directive: setting
 optional: true
 description: |
 
-  Metadata for the |k8s| pods that the |k8s-op| creates for
+  Metadata for the |k8s| Pods that the |k8s-op| creates for
   {{component}}.
 
   To review which fields you can add to {{podTemplate_metadata}}, see
@@ -1384,7 +1391,7 @@ directive: setting
 optional: true
 description: |
 
-  Specifications of the |k8s| pods that the |k8s-op| creates for
+  Specifications of the |k8s| Pods that the |k8s-op| creates for
   {{component}}.
 
   To review which fields you can add to {{podTemplate_spec}}, see the
@@ -1497,5 +1504,4 @@ description: |
     deployed with the |k8s-op-short|. 
 
   {{example}}
-
 ...

source/includes/prereqs/custom-ca-prereqs-rs-tls-only.rst

@@ -8,6 +8,15 @@
 
     .. include:: /includes/prereqs/san-format.rst
 
+    .. important:: 
+      
+       .. include:: /includes/facts/fact-acme-provider-certs.rst
+       
+       To use an |acme| based certificate, you must configure 
+       the certificate for your replica set resource. 
+       To learn more, see the step about |acme| based |tls| 
+       certificates in the :ref:`procedure <tls-for-replica-set>`.
+
   .. include:: /includes/prereqs/mdbagent-reqs.rst
 
 - You must possess the |certauth| certificate and the key that you used to 

source/includes/steps-deploy-k8s-replica-set-with-tls.yaml

@@ -72,22 +72,30 @@ replacement:
   k8sResource: :term:`replica set`
 ---
 stepnum: 9
+ref: k8s-add-external-access
+source:
+  file: steps-source-deploy-k8s-resource.yaml
+  ref: add-k8s-external-access
+replacement:
+  k8sResource: :term:`replica set`
+---
+stepnum: 10
 ref: add-other-spec-rs
 source:
   file: steps-source-deploy-k8s-resource.yaml
   ref: add-k8s-rs-values
 replacement:
   k8sResource: :term:`replica set`
 ---
-stepnum: 10
+stepnum: 11
 ref: save-object-spec-rs
 source:
   file: steps-source-deploy-k8s-resource.yaml
   ref: save-object-spec
 replacement:
   k8sResource: :term:`replica set`
 ---
-stepnum: 11
+stepnum: 12
 ref: start-k8s-deployment-rs
 source:
   file: steps-source-deploy-k8s-resource.yaml
@@ -96,7 +104,7 @@ replacement:
   k8sResource: :term:`replica set`
   k8sResourceType: replica-set
 ---
-stepnum: 12
+stepnum: 13
 ref: track-k8s-deployment-rs
 source:
   file: steps-source-deploy-k8s-resource.yaml

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

@@ -227,6 +227,38 @@ content: |
 
   .. include:: /includes/list-tables/resource-keys-internal-x509.rst
 
+---
+title: "Configure |acme| based |tls| certificates for your {{k8sResource}} resource."
+stepnum: 0
+level: 4
+optional: true
+ref: add-k8s-external-access
+content: |
+
+  .. include:: /includes/facts/fact-acme-provider-certs.rst
+  
+  To configure a certificate that doesn't contain the pod's |fqdn|\s:
+  
+  a. Issue the certificate for an external domain. For more information, see the 
+     `Let's Encrypt documentation <https://letsencrypt.org/how-it-works/>`_ or 
+     the documentation for your provider.
+
+  #. Ensure that your certificate contains all hostnames that you plan to deploy in the 
+     replica set. Alternatively, you can issue a wildcard certificate for ``*.<externalDomain>``.
+     
+  #. To use a certificate containing only external domains for your replica set deployment, 
+     you must change the default hostname used by the replica set: 
+
+     - If you prefer to configure the hostname while creating your |k8s| cluster, change the 
+       :k8sdocs:`default domain </concepts/services-networking/dns-pod-service#what-things-get-dns-names>` 
+       from ``cluster.local`` to the external domain when creating or recreating your |k8s| cluster. 
+       Then, set this domain in your MongoDB resource by using the :setting:`spec.clusterDomain` setting.
+    
+     - Otherwise, create your MongoDB deployment with the following settings configured in your |k8s| 
+       object:
+      
+  .. include:: /includes/list-tables/configure-acme-based-certs.rst
+
 ---
 title: "Add any additional accepted settings for a {{k8sResource}} deployment."
 stepnum: 0

source/reference/k8s-op-exclusive-settings.txt

@@ -25,7 +25,7 @@ The following list of settings are exclusive to |k8s|. This list may
 change at a later date.
 
 These settings can be found on the
-:opsmgr:`Automation Configuration </reference/cluster-configuration>`
+:opsmgr:`automation configuration </reference/cluster-configuration>`
 page:
 
 - ``auth.autoAuthMechanisms``