feat: Configuring proxy article

modules/administration-guide/nav.adoc

@@ -76,6 +76,7 @@
 *** xref:importing-untrusted-tls-certificates.adoc[]
 *** xref:adding-labels-and-annotations.adoc[]
 *** xref:configuring-workspaces-endpoints-base-domain.adoc[]
+*** xref:configuring-proxy.adoc[]
 ** xref:configuring-storage.adoc[]
 *** xref:configuring-storage-classes.adoc[]
 *** xref:configuring-the-storage-strategy.adoc[]

modules/administration-guide/pages/configuring-networking.adoc

@@ -12,4 +12,5 @@
 include::example$snip_{project-context}-xref-configuring-che-with-self-signed-certificate.adoc[]
 * xref:importing-untrusted-tls-certificates.adoc[]
 * xref:adding-labels-and-annotations.adoc[]
-* xref:configuring-workspaces-endpoints-base-domain.adoc[]
+* xref:configuring-workspaces-endpoints-base-domain.adoc[]
+* xref:configuring-proxy.adoc[]

modules/administration-guide/pages/configuring-proxy.adoc

@@ -0,0 +1,74 @@
+:_content-type: PROCEDURE
+:description: Configuring proxy
+:keywords: administration guide, proxy, networking
+:navtitle: Configuring proxy
+:page-aliases:
+
+[id="configuring-proxy"]
+= Configuring proxy
+
+Learn how to configure a proxy for {prod}. The steps include creating a {kubernetes} Secret for proxy credentials and configuring the necessary proxy settings in the CheCluster custom resource. The proxy settings are propagated to the operands and workspaces through environment variables.
+
+On OpenShift cluster, you do not need to configure proxy settings. {prod-short} Operator automatically uses OpenShift cluster-wide proxy configuration. However, you can override the proxy settings by specifying them  in the CheCluster custom resource.
+
+.Procedure
+
+. (OPTIONAL) Create a Secret in the {prod-namespace} {namespace} that contains a user and password for a proxy server. The secret must have the `app.kubernetes.io/part-of=che.eclipse.org` label. Skip this step if the proxy server does not require authentication.
++
+[source,subs="+quotes,+attributes,+macros"]
+----
+{orch-cli} apply -f - <<EOF
+kind: Secret
+apiVersion: v1
+metadata:
+  name: {prod-id-short}-proxy-credentials
+  namespace: {prod-namespace}
+  labels:
+    app.kubernetes.io/part-of: che.eclipse.org
+type: Opaque
+stringData:
+  user: __<user>__          <1>
+  password: __<password>__  <2>
+EOF
+----
+<1> The username for the proxy server.
+<2> The password for the proxy server.
+
+. Configure the proxy or override the cluster-wide proxy configuration for an OpenShift cluster by setting the following properties in the CheCluster custom resource:
++
+[source,subs="+quotes,attributes,macros"]
+----
+{orch-cli} patch checluster/{prod-checluster} \
+    --namespace {prod-namespace} \
+    --type='merge' -p \
+'{"spec":
+    {"components":
+        {"cheServer":
+            {"proxy":
+                {"credentialsSecretName" : "__<secretName>__",                      <1>
+                 "nonProxyHosts"         : ["__<host_1>__"],                        <2>
+                 "port"                  : "__<port>__",                            <3>
+                 "url"                   : "__<protocol>__://__<domain>__"}}}}}'    <4>
+----
+<1> The credentials secret name created in the previous step.
+<2> The list of hosts that can be reached directly, without using the proxy. Use the following form `.<DOMAIN>` to specify a wildcard domain. {prod-short} Operator automatically adds .svc and Kubernetes service host to the list of non-proxy hosts. In OpenShift, {prod-short} Operator combines the non-proxy host list from the cluster-wide proxy configuration with the custom resource.
++
+[IMPORTANT]
+====
+In some proxy configurations, `localhost` may not translate to `127.0.0.1`. Both `localhost` and `127.0.0.1` should be specified in this situation.
+====
+<3> The port of the proxy server.
+<4> Protocol and domain of the proxy server.
+
+
+.Verification steps
+
+. Start a workspace
+
+. Verify that the workspace pod contains `HTTP_PROXY`, `HTTPS_PROXY`, `http_proxy` and `https_proxy` environment variables, each set to `__<protocol>__://<user>:<password@<domain>:<port>`.
+
+. Verify that the workspace pod contains `NO_PROXY` and `no_proxy` environment variables, each set to comma-separated list of non-proxy hosts.
+
+.Additional resources
+
+* link:https://docs.openshift.com/container-platform/latest/networking/enable-cluster-wide-proxy.html[Configuring the cluster-wide proxy on OpenShift]