PROD-615-proxy-enablement

_topic_map.yml

@@ -310,6 +310,8 @@ Topics:
     File: configuring-ingress-cluster-traffic-service-external-ip
   - Name: Configuring ingress cluster traffic using a NodePort
     File: configuring-ingress-cluster-traffic-nodeport
+- Name: Configuring the cluster-wide proxy
+  File: enable-cluster-wide-proxy
 ---
 Name: Storage
 Dir: storage

modules/nw-proxy-configure-object.adoc

@@ -0,0 +1,107 @@
+// Module included in the following assemblies:
+//
+// * networking/enable-cluster-wide-proxy.adoc
+
+[id="nw-proxy-configure-object_{context}"]
+= Enabling the cluster-wide proxy
+
+The Proxy object is used to manage the cluster-wide egress proxy. When a cluster is
+installed or upgraded without the proxy configured, a Proxy object is still
+generated but it will have a nil `spec`. For example:
+
+[source,yaml]
+----
+apiVersion: config.openshift.io/v1
+kind: Proxy
+metadata:
+  name: cluster
+spec:
+  trustedCA:
+    name: ""
+status:
+----
+
+A cluster administrator can configure the proxy for {product-title} by modifying
+this `cluster` Proxy object.
+
+NOTE: Only the Proxy object named `cluster` is supported, and no additional
+proxies can be created.
+
+.Prerequisites
+
+* Cluster administrator permissions
+* {product-title} `oc` CLI tool installed
+
+.Procedure
+
+. Create a ConfigMap that contains any additional CA certificates required for
+proxying HTTPS connections.
++
+NOTE: You can skip this step if the proxy’s identity certificate is signed by an
+authority from the RHCOS trust bundle.
+
+.. Create a file called `user-ca-bundle.yaml` with the following contents, and provide the values of your PEM-encoded certificates:
++
+[source,yaml]
+----
+apiVersion: v1
+data:
+  ca-bundle.crt: | <1>
+    <MY_PEM_ENCODED_CERTS> <2>
+kind: ConfigMap
+metadata:
+  name: user-ca-bundle <3>
+  namespace: openshift-config <4>
+----
+<1> This data key must be named `ca-bundle.crt`.
+<2> One or more PEM-encoded X.509 certificates used to sign the proxy's
+identity certificate.
+<3> The ConfigMap name that will be referenced from the Proxy object.
+<4> The ConfigMap must be in the `openshift-config` namespace.
+
+.. Create the ConfigMap from this file:
++
+----
+$ oc create -f user-ca-bundle.yaml
+----
+
+. Use the `oc edit` command to modify the Proxy object:
++
+----
+$ oc edit proxy/cluster
+----
+
+. Configure the necessary fields for the proxy:
++
+[source,yaml]
+----
+apiVersion: config.openshift.io/v1
+kind: Proxy
+metadata:
+  name: cluster
+spec:
+  httpProxy: http://<username>:<pswd>@<ip>:<port> <1>
+  httpsProxy: https://<username>:<pswd>@<ip>:<port> <2>
+  noProxy: example.com <3>
+  readinessEndpoints:
+  - http://www.google.com <4>
+  - https://www.google.com
+  trustedCA:
+    name: user-ca-bundle <5>
+----
+<1> A proxy URL to use for creating HTTP connections outside the cluster.
+<2> A proxy URL to use for creating HTTPS connections outside the cluster. If
+this is not specified, then `httpProxy` is used for both HTTP and HTTPS
+connections.
+<3> A comma-separated list of destination domain names, domains, IP addresses or
+other network CIDRs to exclude proxying. Preface a domain with `.` to include
+all subdomains of that domain. Use `*` to bypass proxy for all destinations.
+<4> One or more URLs external to the cluster to use to perform a readiness check
+before writing the `httpProxy` and `httpsProxy` values to status.
+<5> A reference to the ConfigMap in the `openshift-config` namespace that
+contains additional CA certificates required for proxying HTTPS connections.
+Note that the ConfigMap must already exist before referencing it here. This
+field is required unless the proxy's identity certificate is signed by an
+authority from the RHCOS trust bundle.
+
+. Save the file to apply the changes.

modules/nw-proxy-remove.adoc

@@ -0,0 +1,36 @@
+// Module included in the following assemblies:
+//
+// * networking/enable-cluster-wide-proxy.adoc
+
+[id="nw-proxy-remove_{context}"]
+= Removing the cluster-wide proxy
+
+The `cluster` Proxy object cannot be deleted. To remove the proxy from a cluster,
+remove all `spec` fields from the Proxy object.
+
+.Prerequisites
+
+* Cluster administrator permissions
+* {product-title} `oc` CLI tool installed
+
+.Procedure
+
+. Use the `oc edit` command to modify the proxy:
++
+----
+$ oc edit proxy/cluster
+----
+
+. Remove all `spec` fields from the Proxy object. For example:
++
+[source,yaml]
+----
+apiVersion: config.openshift.io/v1
+kind: Proxy
+metadata:
+  name: cluster
+spec: {}
+status: {}
+----
+
+. Save the file to apply the changes.

networking/enable-cluster-wide-proxy.adoc

@@ -0,0 +1,17 @@
+[id="enable-cluster-wide-proxy"]
+= Configuring the cluster-wide proxy
+include::modules/common-attributes.adoc[]
+:context: config-cluster-wide-proxy
+
+toc::[]
+
+Production environments can deny direct access to the Internet and instead have
+an HTTP or HTTPS proxy available. You can configure {product-title} to use a
+proxy by
+xref:../networking/enable-cluster-wide-proxy.adoc#nw-proxy-configure-object_config-cluster-wide-proxy[modifying the Proxy object for existing clusters]
+or by configuring the proxy settings in the `install-config.yaml` file for new
+clusters.
+
+include::modules/nw-proxy-configure-object.adoc[leveloffset=+1]
+
+include::modules/nw-proxy-remove.adoc[leveloffset=+1]