4.2 private

_topic_map.yml

@@ -196,6 +196,9 @@ Topics:
     Distros: openshift-enterprise,openshift-origin
   - Name: Configuring your firewall
     File: configuring-firewall
+  - Name: Configuring a private cluster
+    Distros: openshift-enterprise,openshift-origin
+    File: configuring-private-cluster
 ---
 Name: Updating clusters
 Dir: updating

installing/install_config/configuring-private-cluster.adoc

@@ -0,0 +1,21 @@
+[id="configuring-private-cluster"]
+= Configuring a private cluster
+include::modules/common-attributes.adoc[]
+:context: configuring-private-cluster
+
+toc::[]
+
+After you install {product-title} version 4.2 cluster, you can set some of its core components to be private.
+
+[IMPORTANT]
+====
+You can configure this change for only clusters that use infrastructure that you provision to a cloud provider.
+====
+
+include::modules/private-clusters-about.adoc[leveloffset=+1]
+
+include::modules/private-clusters-setting-dns-private.adoc[leveloffset=+1]
+
+include::modules/private-clusters-setting-ingress-private.adoc[leveloffset=+1]
+
+include::modules/private-clusters-setting-api-private.adoc[leveloffset=+1]

modules/private-clusters-about.adoc

@@ -0,0 +1,33 @@
+// Module included in the following assemblies:
+//
+// * installing/install_config/configuring-private-cluster.adoc
+
+[id="private-clusters-about_{context}"]
+= About private clusters
+
+By default, {product-title} is provisioned using publicly-accessible DNS and endpoints. You can set the DNS, Ingress Controller, and API server to private after you deploy your cluster.
+
+[discrete]
+[id="private-clusters-about-dns_{context}"]
+== DNS
+
+If you install {product-title} on installer-provisioned infrastructure, the installation program creates records in a pre-existing public zone and, where possible, creates a private zone for the cluster’s own DNS resolution. In both the public zone and the private zone, the installation program or cluster creates DNS entries for `*.apps`, for Ingress, and `api`, for the API server.
+
+The `*.apps` records in the public and private zone are identical, so when you delete the public zone, the private zone seamlessly provides all DNS resolution for the cluster.
+
+[discrete]
+[id="private-clusters-about-ingress-controller_{context}"]
+== Ingress Controller
+Because the default Ingress object is created as public, the load balancer is internet-facing and in the public subnets. You can replace the default Ingress Controller with an internal one.
+
+[discrete]
+[id="private-clusters-about-api-server_{context}"]
+== API server
+
+By default, the installation program creates appropriate network load balancers for the API server to use for both internal and external traffic.
+
+On Amazon Web Services (AWS), separate public and private load balancers are created. The load balancers are identical except that an additional port is available on the internal one for use within the cluster. Although the installation program automatically creates or destroys the load balancer based on API server requirements, the cluster does not manage or maintain them. As long as you preserve the cluster's access to the API server, you can manually modify or move the load balancers. For the public load balancer, port 6443 is open and the health check is configured for HTTPS against the `/readyz` path.
+
+On Google Cloud Platform, a single load balancer is created to manage both internal and external API traffic, so you do not need to modify the load balancer.
+
+On Microsoft Azure, both public and private load balancers are created. However, because of limitations in current implementation, you just retain both load balancers in a private cluster.

modules/private-clusters-setting-api-private.adoc

@@ -0,0 +1,65 @@
+// Module included in the following assemblies:
+//
+// * installing/install_config/configuring-private-cluster.adoc
+
+[id="private-clusters-setting-api-private_{context}"]
+= Restricting the API server to private
+
+After you deploy a cluster to Amazon Web Services (AWS) or Microsoft Azure, you can reconfigure the API server to use only the private zone.
+
+.Prerequisites
+
+* Install the OpenShift Command-line Interface (CLI), commonly known as `oc`.
+* Have access to the web console as a user with `admin` privileges.
+
+.Procedure
+
+. In the web portal or console for AWS or Azure, take the following actions:
+
+.. Locate and delete appropriate load balancer component.
+*** For AWS, delete the the external load balancer. The API DNS entry in the private zone already points to the internal load balancer, which uses an identical configuration, so you do not need to modify the internal load balancer.
+*** For Azure, delete the `api-internal` rule for the load balancer.
+
+.. Delete the `api.$clustername.$yourdomain` DNS entry in the public zone.
+
+. From your terminal, list the cluster machines:
++
+----
+$ oc get machine -n openshift-machine-api
+NAME                            STATE     TYPE        REGION      ZONE         AGE
+lk4pj-master-0                  running   m4.xlarge   us-east-1   us-east-1a   17m
+lk4pj-master-1                  running   m4.xlarge   us-east-1   us-east-1b   17m
+lk4pj-master-2                  running   m4.xlarge   us-east-1   us-east-1a   17m
+lk4pj-worker-us-east-1a-5fzfj   running   m4.xlarge   us-east-1   us-east-1a   15m
+lk4pj-worker-us-east-1a-vbghs   running   m4.xlarge   us-east-1   us-east-1a   15m
+lk4pj-worker-us-east-1b-zgpzg   running   m4.xlarge   us-east-1   us-east-1b   15m
+----
++
+You modify the control plane machines, which contain `master` in the name, in the following step.
+
+. Remove the external load balancer from each control plane machine.
+.. Edit a `master` Machine object to remove the reference to the external load balancer.
++
+----
+$ oc edit machines -n openshift-machine-api <master_name> <1>
+----
+<1> Specify the name of the control plane, or master, Machine to modify.
+
+.. Remove the lines that describe the external load balancer, which are marked in the following example, and save and exit the object specification:
++
+[source,yaml]
+----
+...
+spec:
+  providerSpec:
+    value:
+    ...
+      loadBalancers:
+      - name: lk4pj-ext <1>
+        type: network <1>
+      - name: lk4pj-int
+        type: network
+----
+<1> Delete this line.
+
+.. Repeat this process for each of the machines that contains `master` in the name.

modules/private-clusters-setting-dns-private.adoc

@@ -0,0 +1,72 @@
+// Module included in the following assemblies:
+//
+// * installing/install_config/configuring-private-cluster.adoc
+
+[id="private-clusters-setting-dns-private_{context}"]
+= Setting DNS to private
+
+After you deploy a cluster, you can modify its DNS to use only a private zone.
+
+.Procedure
+
+. Review the DNS custom resource for your cluster:
++
+----
+$ oc get dnses.config.openshift.io/cluster -o yaml
+apiVersion: config.openshift.io/v1
+kind: DNS
+metadata:
+  creationTimestamp: "2019-10-25T18:27:09Z"
+  generation: 2
+  name: cluster
+  resourceVersion: "37966"
+  selfLink: /apis/config.openshift.io/v1/dnses/cluster
+  uid: 0e714746-f755-11f9-9cb1-02ff55d8f976
+spec:
+  baseDomain: <base_domain>
+  privateZone:
+    tags:
+      Name: <infrastructureID>-int
+      kubernetes.io/cluster/<infrastructureID>: owned
+  publicZone:
+    id: Z2XXXXXXXXXXA4
+status: {}
+----
++
+Note that the `spec` section contains both a private and a public zone.
+
+. Patch the DNS custom resource to remove the public zone:
++
+----
+$ oc patch dnses.config.openshift.io/cluster --type=merge --patch='{"spec": {"publicZone": null}}'
+dns.config.openshift.io/cluster patched
+----
++
+Because the Ingress Controller consults the DNS definition when it creates Ingress objects, When you create or modify Ingress objects, only private records are created.
++
+[IMPORTANT]
+====
+DNS records for the existing Ingress objects are not modified when you remove the public zone.
+====
+
+. Optional: Review the DNS custom resource for your cluster and confirm that the public zone was removed:
++
+----
+$ oc get dnses.config.openshift.io/cluster -o yaml
+apiVersion: config.openshift.io/v1
+kind: DNS
+metadata:
+  creationTimestamp: "2019-10-25T18:27:09Z"
+  generation: 2
+  name: cluster
+  resourceVersion: "37966"
+  selfLink: /apis/config.openshift.io/v1/dnses/cluster
+  uid: 0e714746-f755-11f9-9cb1-02ff55d8f976
+spec:
+  baseDomain: <base_domain>
+  privateZone:
+    tags:
+      Name: <infrastructureID>-int
+      kubernetes.io/cluster/<infrastructureID>-wfpg4: owned
+status: {}
+----

modules/private-clusters-setting-ingress-private.adoc

@@ -0,0 +1,31 @@
+// Module included in the following assemblies:
+//
+// * installing/install_config/configuring-private-cluster.adoc
+
+[id="private-clusters-setting-ingress-private_{context}"]
+= Setting the Ingress Controller to private
+
+After you deploy a cluster, you can modify its Ingress Controller to use only a private zone.
+
+.Procedure
+
+. Modify the default Ingress Controller to use only an internal endpoint:
++
+----
+$ oc replace --force --wait --filename - <<EOF
+apiVersion: operator.openshift.io/v1
+kind: IngressController
+metadata:
+  namespace: openshift-ingress-operator
+  name: default
+spec:
+  endpointPublishingStrategy:
+    type: LoadBalancerService
+    loadBalancer:
+      scope: Internal
+EOF
+ingresscontroller.operator.openshift.io "default" deleted
+ingresscontroller.operator.openshift.io/default replaced
+----
++
+The public DNS entry is removed, and the private zone entry is updated.