DOCSP-7918: externalConnectivity for OM in k8s (#152)

* (DOCSP-7918): initial om external connectivity commit

* (DOCSP-7918): internal and external access to om in k8s

* (DOCSP-7918): typo

* (DOCSP-7918): copy review edits

* (DOCSP-7918): tech review feedback

* (DOCSP-7918): typo

* (DOCSP-7918): tech review feedback pt 2

* (DOCSP-7918): fix merge conflicts

Author: jwilliams-mongo

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

@@ -214,10 +214,48 @@ content: |
           .. include:: /includes/k8s/k8s-persistent-volumes-om.rst
 
         - ``true``
+---
+title: "Allow external traffic to reach the |onprem| application."
+stepnum: 4
+level: 4
+ref: om-external-connectivity
+content: |
+  
+  By default, the |k8s-op-short| does not create a |k8s| service to 
+  route traffic originating from outside of the |k8s| cluster to the 
+  |onprem| application.
+
+  To access the |onprem| application, you can:
+  
+  - Configure the |k8s-op-short| to create a |k8s| service.
+  - Create a |k8s| service manually. MongoDB recommends using a 
+    ``LoadBalancer`` |k8s| service if your cloud provider supports it.
+  - If you're using OpenShift, use 
+    `Routes <https://docs.openshift.com/enterprise/3.0/architecture/core_concepts/routes.html>`__.
+  - Use a third-party service, such as Istio.
+
+  The simplest method is to configure the |k8s-op-short| to create a 
+  |k8s| service to route external traffic to the |onprem| application:
+
+  a. Add the ``spec.``:opsmgrkube:`~spec.externalConnectivity` setting 
+     to the |k8s-obj| specification.
+
+  #. Add the following settings to the |k8s-obj| specification 
+     to configure the |k8s| service that routes external traffic to the 
+     |onprem| application:
+
+     - ``spec.externalConnectivity.``:opsmgrkube:`~spec.externalConnectivity.type`
+     - (optional) ``spec.externalConnectivity.``:opsmgrkube:`~spec.externalConnectivity.port`
+
+  To learn how to create a |k8s| :k8sdocs:`service </concepts/services-networking/service/>`
+  manually, see the |k8s| documentation.
+
+  To learn how to route external traffic to the |onprem| application 
+  using a different method, refer to the documentation for your solution.
 
 ---
 title: "(Optional) Configure any additional settings for an |onprem| deployment."
-stepnum: 4
+stepnum: 5
 level: 4
 ref: add-k8s-values
 content: |
@@ -251,13 +289,13 @@ content: |
 
 ---
 title: "Save this file with a ``.yaml`` file extension."
-stepnum: 5
+stepnum: 6
 level: 4
 ref: save-object-spec
 
 ---
 title: "Create your |onprem| instance."
-stepnum: 6
+stepnum: 7
 level: 4
 ref: start-k8s-instance
 content: |
@@ -271,7 +309,7 @@ content: |
 
 ---
 title: "Track the status of your |onprem| instance."
-stepnum: 7
+stepnum: 8
 level: 4
 ref: track-k8s-instance
 content: |
@@ -333,45 +371,60 @@ content: |
      ConfigMap <create-k8s-project>`.
 
 ---
-title: "Access your |onprem| instance from a browser."
-stepnum: 8
+title: "Access the |onprem| application."
+stepnum: 9
 level: 4
 ref: access-opsmgr-instance
 content: |
-  
-  a. After the resource deploys successfully, find the external port to 
-     your |onprem| instance.
-     
-     Invoke the following ``kubectl`` command on 
-     ``<metadata.name>-svc-external : <metadata.name>`` :
 
-     .. code-block:: sh
+  The steps you take differ based on how you are routing traffic to the 
+  |onprem| application in |k8s|. If you configured the |k8s-op-short| to 
+  create a |k8s| service for you, or you created a |k8s| service 
+  manually, use one of the following methods to access the |onprem| 
+  application:
 
-        kubectl get svc <metadata.name>-svc-external -n <namespace>
+  .. tabs::
 
-     The command returns the external port in the ``PORT(S)`` column. In
-     the following example output, the external port is ``30036``:
+     .. tab:: External Traffic Routes Using LoadBalancer Service
+        :tabid: om-loadbalancer-svc-access
 
-     .. code-block:: sh
-        :copyable: false
+        a. Query your cloud provider to get the |fqdn| of the load
+           balancer service. See your cloud provider's documentation
+           for details.
 
-        NAME                            TYPE       CLUSTER-IP       EXTERNAL-IP   PORT(S)           AGE
-        <metadata.name>-svc-external    NodePort   100.66.92.110    <none>        8080:30036/TCP    1d
+        #. Open a browser window and navigate to the |onprem| 
+           application using the |fqdn| and port number of your load 
+           balancer service.
+     
+           .. code-block:: sh
+              :copyable: false
+        
+              http://ops.example.com:8080
   
-  #. Set your firewall rules to allow access from the Internet to the
-     external port on the host.
+        #. Log in to |onprem| using the :ref:`admin user credentials 
+           <om-rsrc-prereqs>`. 
+
+     .. tab:: External Traffic Routed Using NodePort Service
+        :tabid: om-nodeport-svc-access
 
-  #. Open a browser window and navigate to the |onprem| application
-     using the |fqdn| and port number.
+        a. Set your firewall rules to allow access from the Internet to 
+           the ``spec.externalConnectivity.``:opsmgrkube:`~spec.externalConnectivity.port` 
+           on the host on which your |k8s| cluster is running.
+    
+        #. Open a browser window and navigate to the |onprem| 
+           application using the |fqdn| and the 
+           ``spec.externalConnectivity.``:opsmgrkube:`~spec.externalConnectivity.port`.
 
-     .. code-block:: sh
-        :copyable: false
+           .. code-block:: sh
+              :copyable: false
 
-        http://ops.example.com:30036
-  
-  #. Log in to |onprem| using the :ref:`admin user credentials 
-     <om-rsrc-prereqs>`.
+              http://ops.example.com:30036
+        
+        #. Log in to |onprem| using the :ref:`admin user credentials <om-rsrc-prereqs>`.
 
+    To learn how to access the |onprem| application using a different 
+    traffic routing method, refer to the documentation for your solution.
+  
 ---
 title: "Create credentials for the Kubernetes Operator."
 stepnum: 9

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

@@ -371,6 +371,103 @@ Optional |onprem| Resource Settings
    </reference/configuration/>` for property names and descriptions.
    Each property takes a value of type ``string``.
 
+.. opsmgrkube:: spec.externalConnectivity
+
+   *Type*: collection
+
+   Configuration object that enables external connectivity to |onprem|. 
+   If provided, the |k8s-op-short| creates a |k8s| :k8sdocs:`service 
+   </concepts/services-networking/service/>` that allows traffic 
+   originating from outside of the |k8s| cluster to reach the |onprem| 
+   application.
+
+   If not provided, the |k8s-op-short| does not create a |k8s| service. 
+   You must create one manually or use a third-party solution that 
+   enables you to route external traffic to the |onprem| application in 
+   your |k8s| cluster.
+
+.. opsmgrkube:: spec.externalConnectivity.type
+
+   *Type*: string
+
+   The |k8s| service :k8sdocs:`ServiceType 
+   </concepts/services-networking/service/#publishing-services-service-types>` 
+   that exposes |onprem| outside of |k8s|.
+
+   *Required* if :opsmgrkube:`spec.externalConnectivity.type` is 
+   present.
+
+   Accepted values are: ``LoadBalancer`` and ``NodePort``. 
+   ``LoadBalancer`` is recommended if your cloud provider supports it.
+   Use ``NodePort`` for local deployments.
+
+.. opsmgrkube:: spec.externalConnectivity.port
+
+   *Type*: integer
+
+   If :opsmgrkube:`spec.externalConnectivity.type` is ``NodePort``, the
+   port on the |k8s| service from which external traffic is routed to 
+   the |onprem| application.
+
+   .. note::
+   
+      You must configure your network's firewall to allow traffic over 
+      this port.
+
+   If :opsmgrkube:`spec.externalConnectivity.type` is ``LoadBalancer``,
+   the load balancer resource that your cloud provider creates routes 
+   traffic to this port on the |k8s| service. You don't need to provide
+   this value. |k8s| uses an open port within the default range and 
+   handles internal traffic routing appropriately.
+
+   In both cases, if this value is not provided, the |k8s| service 
+   routes traffic from an available port within the following default 
+   range to the |onprem| application: ``30000``-``32767``. 
+
+.. opsmgrkube:: spec.externalConnectivity.loadBalancerIP
+
+   *Type*: string
+
+   The IP address the ``LoadBalancer`` |k8s| service uses when the 
+   |k8s-op-short| creates it.
+
+   This setting can only be used if your cloud provider supports it and
+   :opsmgrkube:`spec.externalConnectivity.type` is ``LoadBalancer``. To
+   learn more about the 
+   :k8sdocs:`Type LoadBalancer 
+   </concepts/services-networking/service/#loadbalancer>`, see the 
+   |k8s| documentation.
+
+.. opsmgrkube:: spec.externalConnectivity.externalTrafficPolicy
+
+   *Type*: string
+
+   Routing policy for external traffic to the |onprem| |k8s| service.
+   The service routes external traffic to node-local or cluster-wide 
+   endpoints depending the value of this setting. 
+   
+   Accepted values are: ``Cluster`` and ``Local``. To learn which of
+   values meet your requirements, see :k8sdocs:`Source IPs in Kubernetes
+   </tutorials/services/source-ip/>` in the |k8s| documentation.
+   
+   .. note:: 
+      If you select ``Cluster``, the ``Source-IP`` of your clients are 
+      lost during the network hops that happen at the |k8s| 
+      network boundary.
+
+.. opsmgrkube:: spec.externalConnectivity.annotations
+
+   *Type*: collection
+
+   Key-value pairs that allow you to provide cloud provider-specific 
+   configuration settings. 
+
+   To learn more about :k8sdocs:`Annotations 
+   </concepts/overview/working-with-objects/annotations/>` and
+   :k8sdocs:`TLS support on AWS
+   </concepts/services-networking/service/#ssl-support-on-aws>`, see the
+   |k8s| documentation.
+
 .. opsmgrkube:: spec.applicationDatabase.passwordSecretKeyRef.name
 
    *Type*: string
@@ -380,7 +477,6 @@ Optional |onprem| Resource Settings
    |onprem| uses this password to :ref:`authenticate to the Application
    Database <app-db-auth>`.
 
-
 .. opsmgrkube:: spec.applicationDatabase.passwordSecretKeyRef.key
 
    *Type*: string