diff --git a/_topic_map.yml b/_topic_map.yml index 1637dcd47e06..491ccf4b96c8 100644 --- a/_topic_map.yml +++ b/_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 diff --git a/modules/nw-proxy-configure-object.adoc b/modules/nw-proxy-configure-object.adoc new file mode 100644 index 000000000000..387f6db5bcc5 --- /dev/null +++ b/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> + <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://:@: <1> + httpsProxy: https://:@: <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. diff --git a/modules/nw-proxy-remove.adoc b/modules/nw-proxy-remove.adoc new file mode 100644 index 000000000000..e273876e8938 --- /dev/null +++ b/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. diff --git a/networking/enable-cluster-wide-proxy.adoc b/networking/enable-cluster-wide-proxy.adoc new file mode 100644 index 000000000000..188356c042ea --- /dev/null +++ b/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]