Skip to content

Commit 1ff78d8

Browse files
EricPonvelleEricPonvelle
authored
Merge pull request #42320 from EricPonvelle/OSDOCS-3001_Day2-Proxy
OSDOCS-3001: Added Day 2 information for proxies
2 parents 5e81fb2 + 04e3add commit 1ff78d8

File tree

3 files changed

+140
-5
lines changed

3 files changed

+140
-5
lines changed

‎modules/cluster-wide-proxy-updates.adoc‎

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * networking/configuring-cluster-wide-proxy.adoc
4+
5+
//OSDOCS-3001 Configuration for cluster-wide-proxy Day 2
6+
:_content-type: PROCEDURE
7+
[id="cluster-wide-proxy-updates_{context}"]
8+
= Configuring or updating your cluster-wide proxy after installation
9+
10+
ifdef::openshift-rosa[]
11+
As the cluster owner, you may wish to add a proxy to your created cluster after installation, or you may wish to make changes to your proxy that you configured during cluster installation. The `rosa` CLI provides some options for adding a proxy to your cluster or modifying an existing proxy on your cluster.
12+
endif::[]
13+
ifdef::openshift-dedicated[]
14+
As the cluster owner, you may wish to add a proxy to your created cluster after installation, or you may wish to make changes to your proxy that you configured during cluster installation. The `ocm` CLI provides some options for adding a proxy to your cluster or modifying an existing proxy on your cluster.
15+
endif::[]
16+
17+
You may need to perform these actions if:
18+
19+
* the cluster-wide proxy is configured after installation,
20+
* the proxy's network address needs to be updated, and/or
21+
* any of the proxy's certificate authorities have expired and the additional trust bundle needs to be replaced.
22+
23+
[NOTE]
24+
====
25+
The cluster applies the configuration to the cluster’s control plane and worker nodes. This process results in each node in the cluster temporarily being placed into an unschedulable state and drained of its workloads while applying the configuration. Each node will be restarted as part of this process.
26+
====
27+
28+
.Prerequsites
29+
ifdef::openshift-rosa[]
30+
* You have the `rosa` CLI installed and configured.
31+
endif::[]
32+
ifdef::openshift-dedicated[]
33+
* You have the `ocm` CLI installed and configured.
34+
endif::[]
35+
36+
.Procedure
37+
* To edit a cluster, run the following command:
38+
+
39+
ifdef::openshift-rosa[]
40+
[source,terminal]
41+
----
42+
$ rosa edit cluster \
43+
--cluster $CLUSTER_NAME \
44+
--additional-trust-bundle-file $CA_BUNDLE_FILE \
45+
--http-proxy $HTTP_PROXY \
46+
--https-proxy $HTTPS_PROXY
47+
----
48+
endif::[]
49+
ifdef::openshift-dedicated[]
50+
[source,terminal]
51+
----
52+
$ ocm edit cluster \
53+
--cluster $CLUSTER_NAME \
54+
--additional-trust-bundle-file $CA_BUNDLE_FILE \
55+
--http-proxy $HTTP_PROXY \
56+
--https-proxy $HTTPS_PROXY
57+
----
58+
endif::[]
59+
+
60+
While the `additional-trust-bundle-file`, `http-proxy`, and `https-proxy` arguments are optional, if you set a `additional-trust-bundle-file` without either an `http-proxy` or `https-proxy` argument, then the additional trust bundle will still be used for verifying cluster system egress traffic.
61+
* You can verify that the proxy and certificate authority configuration updates have been successfully applied to your cluster by:
62+
** All of the MachineConfigPools are updated. Run the following command to see their status:
63+
+
64+
[source,terminal]
65+
----
66+
$ oc get machineconfigpools
67+
----
68+
+
69+
.Sample Output
70+
[source,terminal]
71+
----
72+
NAME CONFIG UPDATED UPDATING DEGRADED MACHINECOUNT READYMACHINECOUNT UPDATEDMACHINECOUNT DEGRADEDMACHINECOUNT AGE
73+
master rendered-master-d9a03f612a432095dcde6dcf44597d90 True False False 3 3 3 0 31h
74+
worker rendered-worker-f6827a4efe21e155c25c21b43c46f65e True False False 6 6 6 0 31h
75+
----
76+
+
77+
** As the cluster owner, the following command displays the proxy status:
78+
+
79+
[source,terminal]
80+
----
81+
$ oc get proxy cluster -o yaml
82+
----
83+
+
84+
.Sample Output
85+
[source,terminal]
86+
----
87+
apiVersion: config.openshift.io/v1
88+
kind: Proxy
89+
spec:
90+
httpProxy: http://proxy.host.domain:<port>
91+
httpsProxy: https://proxy.host.domain:<port>
92+
<...more...>
93+
status:
94+
httpProxy: http://proxy.host.domain:<port>
95+
httpsProxy: https://proxy.host.domain:<port>
96+
<...more...>
97+
----

‎modules/cluster-wide-proxy.adoc‎

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44

55
:_content-type: PROCEDURE
66
[id="cluster-wide-proxy-config_{context}"]
7-
= Configuring a cluster-wide proxy
7+
= Configuring a cluster-wide proxy during installation
88

99
You can add a proxy during cluster installation. Prior to installation, however, you should verify that the proxy is accessible from the intended cluster virtual private cloud (VPC) and its private subnets.
1010

@@ -16,7 +16,6 @@ ifdef::openshift-dedicated[]
1616
* You have the `ocm` CLI installed and configured.
1717
endif::[]
1818

19-
//CANARY
2019
[WARNING]
2120
====
2221
Only cluster system egress traffic is proxied, including calls to the AWS API. A system-wide proxy does not affect user workloads. It only affects system components.
@@ -48,5 +47,5 @@ endif::[]
4847
+
4948
<1> The `http-proxy`, `https-proxy`, and `additional-trust-bundle-file` arguments are all optional.
5049
<2> If you use the `additional-trust-bundle-file` option without an `http(s)-proxy` argument, the passed additional trust bundle is set on the cluster, but it is not configured to be used with the proxy.
51-
<3> The `additional-trust-bundle-file` argument is a file path pointing to a bundle of PEM-encoded X.509 certificates, which are all concatenated together. The `additionalTrustBundle` field is required unless the proxy's identity certificate is signed by an authority from the {op-system} trust bundle. If you use an MITM transparent proxy network that does not require additional proxy configuration but requires additional CAs, you must provide the MITM CA certificate.
50+
<3> The `additional-trust-bundle-file` argument is a file path pointing to a bundle of PEM-encoded X.509 certificates, which are all concatenated together. The `additionalTrustBundle` parameter is required unless the proxy's identity certificate is signed by an authority from the {op-system} trust bundle. If you use an MITM transparent proxy network that does not require additional proxy configuration but requires additional CAs, you must provide the MITM CA certificate.
5251
<4> The `http-proxy` and `https-proxy` arguments must point to a valid URL.

‎networking/configuring-cluster-wide-proxy.adoc‎

Lines changed: 41 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,12 @@ toc::[]
1111

1212
You can configure a cluster-wide proxy during cluster installation.
1313

14+
//OSDOCS-2830 Customer Responsibilities
15+
If you use a cluster-wide proxy, you are responsible for the following:
16+
17+
* Maintaining the availability of the proxy to the cluster.
18+
* Understanding that if the proxy becomes unavailable, then it may impact the health and supportability of the cluster.
19+
1420
[IMPORTANT]
1521
====
1622
Cluster-wide proxy is a functionally-complete feature and suitable for production workloads. There are additional considerations that need to be added to documentation, and until then, this feature is considered a Technology Preview.
@@ -22,13 +28,46 @@ Cluster-wide proxy is a functionally-complete feature and suitable for productio
2228
* You are the cluster owner.
2329
* Your account has sufficient privileges.
2430
* You have added the `ec2.<region>.amazonaws.com`, `elasticloadbalancing.<region>.amazonaws.com`, and `s3.<region>.amazonaws.com` endpoints to your VPC endpoint. These endpoints are required to complete requests from the nodes to the AWS EC2 API. Because the proxy works on the container level, not the node level, you must route these requests to the AWS EC2 API through the AWS private network. Adding the public IP address of the EC2 API to your allowlist in your proxy server is not sufficient.
31+
ifdef::openshift-rosa[]
32+
For information about standard installation prerequisites, see xref:../rosa_getting_started/rosa-aws-prereqs.adoc#prerequisites[AWS prerequisites for ROSA]. For information about the prerequisites for installation using AWS Security Token Service (STS), see xref:../rosa_getting_started_sts/rosa-sts-aws-prereqs.adoc#rosa-sts-aws-prerequisites[AWS prerequisites for ROSA with STS].
33+
endif::[]
2534
ifdef::openshift-dedicated[]
2635
* You must have a Customer Cloud Subscription (CCS) cluster with a VPC that the proxy can access.
2736

2837
For more information, see xref:../osd_quickstart/osd-quickstart.adoc#osd-getting-started[Getting started with {product-title}] for a basic cluster installation workflow.
2938
endif::[]
39+
40+
//OSDOCS-3290 Transparent Proxy Update
41+
[IMPORTANT]
42+
====
43+
The use of a proxy server to perform TLS re-encryption is currently not supported if the server is acting as a transparent forward proxy where it is not configured on-cluster via the `--http-proxy` or `--https-proxy` arguments.
44+
45+
A transparent forward proxy intercepts the cluster’s traffic, but it is not actually configured on the cluster itself.
46+
====
47+
48+
include::modules/cluster-wide-proxy.adoc[leveloffset=+1]
49+
include::modules/cluster-wide-proxy-updates.adoc[leveloffset=+1]
50+
51+
//OSDOCS-2630 Proxy Configuration Expectations
3052
ifdef::openshift-rosa[]
31-
For information about standard installation prerequisites, see xref:../rosa_getting_started/rosa-aws-prereqs.adoc#prerequisites[AWS prerequisites for ROSA]. For information about the prerequisites for installation using AWS Security Token Service (STS), see xref:../rosa_getting_started_sts/rosa-sts-aws-prereqs.adoc#rosa-sts-aws-prerequisites[AWS prerequisites for ROSA with STS].
53+
[NOTE]
54+
====
55+
You should not attempt to change the proxy or additional trust bundle configuration on the cluster itself. These changes should always be done via the `rosa` command-line tools. Any changes that are made directly to the cluster will be reverted automatically.
56+
====
57+
endif::[]
58+
ifdef::openshift-dedicated[]
59+
[NOTE]
60+
====
61+
You should not attempt to change the proxy or additional trust bundle configuration on the cluster itself. These changes should always be done via the `ocm` command-line tools. Any changes that are made directly to the cluster will be reverted automatically.
62+
====
3263
endif::[]
3364

34-
include::modules/cluster-wide-proxy.adoc[leveloffset=+1]
65+
//OSDOCS-2830 Customer Responsibilities
66+
[id="trust_bundle_responsibilities_cluster-wide-proxy-configuration"]
67+
=== Responsibilites for additional trust bundles
68+
69+
If you supplied an additional trust bundle file, you are responsible for the following:
70+
71+
* Ensuring that the contents of the additional trust bundle are valid,
72+
* Ensuring that the certificates, including intermediary certificates, contained in the additional trust bundle have not expired, and
73+
* Tracking the expiry and performing any necessary renewals for certificates contained in the additional trust bundle, and subsequently updating the cluster’s configuration with the updated additional trust bundle.

0 commit comments

Comments
 (0)