Configuring the cluster-wide proxy

Production environments can deny direct access to the internet and instead have an HTTP or HTTPS proxy available. You can configure OKD to use a proxy by modifying the Proxy object for existing clusters or by configuring the proxy settings in the install-config.yaml file for new clusters.

Prerequisites

  • Review the sites that your cluster requires access to and determine whether any of them must bypass the proxy. By default, all cluster system egress traffic is proxied, including calls to the cloud provider API for the cloud that hosts your cluster. System-wide proxy affects system components only, not user workloads. Add sites to the Proxy object’s spec.noProxy field to bypass the proxy if necessary.

    The Proxy object status.noProxy field is populated with the values of the networking.machineNetwork[].cidr, networking.clusterNetwork[].cidr, and networking.serviceNetwork[] fields from your installation configuration with most installation types.

    For installations on Amazon Web Services (AWS), Google Cloud Platform (GCP), Microsoft Azure, and OpenStack, the Proxy object status.noProxy field is also populated with the instance metadata endpoint (169.254.169.254).

    If your installation type does not include setting the networking.machineNetwork[].cidr field, you must include the machine IP addresses manually in the .status.noProxy field to make sure that the traffic between nodes can bypass the proxy.

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:

  1. apiVersion: config.openshift.io/v1
  2. kind: Proxy
  3. metadata:
  4.   name: cluster
  5. spec:
  6.   trustedCA:
  7.     name: ""
  8. status:

A cluster administrator can configure the proxy for OKD by modifying this cluster Proxy object.

Only the Proxy object named cluster is supported, and no additional proxies can be created.

Prerequisites

  • Cluster administrator permissions

  • OKD oc CLI tool installed

Procedure

  1. Create a config map that contains any additional CA certificates required for proxying HTTPS connections.

    You can skip this step if the proxy’s identity certificate is signed by an authority from the RHCOS trust bundle.

    1. Create a file called user-ca-bundle.yaml with the following contents, and provide the values of your PEM-encoded certificates:

      1. apiVersion: v1
      2. data:
      3.   ca-bundle.crt: | (1)
      4.     <MY_PEM_ENCODED_CERTS> (2)
      5. kind: ConfigMap
      6. metadata:
      7.   name: user-ca-bundle (3)
      8.   namespace: openshift-config (4)
      1This data key must be named ca-bundle.crt.
      2One or more PEM-encoded X.509 certificates used to sign the proxy’s identity certificate.
      3The config map name that will be referenced from the Proxy object.
      4The config map must be in the openshift-config namespace.

    2. Create the config map from this file:

      1. $ oc create -f user-ca-bundle.yaml

  2. Use the oc edit command to modify the Proxy object:

    1. $ oc edit proxy/cluster

  3. Configure the necessary fields for the proxy:

    1. apiVersion: config.openshift.io/v1
    2. kind: Proxy
    3. metadata:
    4.   name: cluster
    5. spec:
    6.   httpProxy: http://<username>:<pswd>@<ip>:<port> (1)
    7.   httpsProxy: https://<username>:<pswd>@<ip>:<port> (2)
    8.   noProxy: example.com (3)
    9.   readinessEndpoints:
    10.   - http://www.google.com (4)
    11.   - https://www.google.com
    12.   trustedCA:
    13.     name: user-ca-bundle (5)
    1A proxy URL to use for creating HTTP connections outside the cluster. The URL scheme must be http.
    2A proxy URL to use for creating HTTPS connections outside the cluster. The URL scheme must be either http or https. Specify a URL for the proxy that supports the URL scheme. For example, most proxies will report an error if they are configured to use https but they only support http. This failure message may not propagate to the logs and can appear to be a network connection failure instead. If using a proxy that listens for https connections from the cluster, you may need to configure the cluster to accept the CAs and certificates that the proxy uses.
    3A comma-separated list of destination domain names, domains, IP addresses or other network CIDRs to exclude proxying.

    Preface a domain with . to match subdomains only. For example, .y.com matches x.y.com, but not y.com. Use * to bypass proxy for all destinations. If you scale up workers that are not included in the network defined by the networking.machineNetwork[].cidr field from the installation configuration, you must add them to this list to prevent connection issues.

    This field is ignored if neither the httpProxy or httpsProxy fields are set.

    4One or more URLs external to the cluster to use to perform a readiness check before writing the httpProxy and httpsProxy values to status.
    5A reference to the config map in the openshift-config namespace that contains additional CA certificates required for proxying HTTPS connections. Note that the config map 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.

  4. Save the file to apply the changes.

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

  • OKD oc CLI tool installed

Procedure

  1. Use the oc edit command to modify the proxy:

    1. $ oc edit proxy/cluster

  2. Remove all spec fields from the Proxy object. For example:

    1. apiVersion: config.openshift.io/v1
    2. kind: Proxy
    3. metadata:
    4.   name: cluster
    5. spec: {}

  3. Save the file to apply the changes.

Additional resources