Skip to content

Commit 7f004b3

Browse files
jldohmannjldohmann
authored
Merge pull request #62273 from mletalie/OSDOCS-4880
[OSDOCS-4880]: [feature] ALB on OSD/ROSA
2 parents c1183f8 + aa745af commit 7f004b3

File tree

4 files changed

+410
-0
lines changed

4 files changed

+410
-0
lines changed

‎_topic_maps/_topic_map_rosa.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -431,6 +431,8 @@ Topics:
431431
File: dns-operator
432432
- Name: Understanding the Ingress Operator
433433
File: ingress-operator
434+
- Name: AWS Load Balancer Operator
435+
File: aws-load-balancer-operator
434436
- Name: OpenShift SDN default CNI network provider
435437
Dir: openshift_sdn
436438
Topics:

‎modules/aws-installing-an-aws-load-balancer-operator.adoc

Lines changed: 367 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,367 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * networking/aws-load-balancer-operator.adoc
4+
5+
:_content-type: PROCEDURE
6+
[id="aws-installing-an-aws-load-balancer-operator_{context}"]
7+
= Installing an AWS Load Balancer Operator
8+
You can install an AWS Load Balancer Operator (ALBO) if you meet certain requirements.
9+
10+
.Prerequisites
11+
12+
* You have an existing
13+
ifndef::openshift-rosa[]
14+
{product-title}
15+
endif::openshift-rosa[]
16+
ifdef::openshift-rosa[]
17+
{product-title} (ROSA)
18+
endif::openshift-rosa[]
19+
cluster with bring-your-own-VPC (BYO-VPC) configuration across multiple availability zones (AZ) installed in STS mode.
20+
* You have access to the cluster as a user with the `dedicated-admin` role.
21+
* You have access to modify the VPC and subnets of the created
22+
ifndef::openshift-rosa[]
23+
{product-title}
24+
endif::openshift-rosa[]
25+
ifdef::openshift-rosa[]
26+
ROSA
27+
endif::openshift-rosa[]
28+
cluster.
29+
* You have installed the
30+
ifndef::openshift-rosa[]
31+
{product-title}
32+
endif::openshift-rosa[]
33+
ifdef::openshift-rosa[]
34+
ROSA
35+
endif::openshift-rosa[]
36+
CLI (`rosa`).
37+
* You have installed the Amazon Web Services (AWS) CLI.
38+
* You have installed the OpenShift CLI (oc).
39+
* You are using OpenShift Container Platform (OCP) 4.13 or later.
40+
41+
[IMPORTANT]
42+
====
43+
When installing an ALBO for use with
44+
ifndef::openshift-rosa[]
45+
a {product-title}
46+
endif::openshift-rosa[]
47+
ifdef::openshift-rosa[]
48+
a ROSA
49+
endif::openshift-rosa[]
50+
cluster in an AWS Local Zone (LZ), you must enable the AWS LZ for the account, and AWS Elastic Load Balancing v2 (ELBv2) services must be available in the AWS LZ.
51+
====
52+
.Procedure
53+
54+
. Identify the cluster infrastructure ID and the cluster OpenID Connect (OIDC) DNS by running the following commands:
55+
.. Identify the
56+
ifndef::openshift-rosa[]
57+
{product-title}
58+
endif::openshift-rosa[]
59+
ifdef::openshift-rosa[]
60+
ROSA
61+
endif::openshift-rosa[]
62+
cluster INFRA ID:
63+
+
64+
[source,terminal]
65+
----
66+
$ rosa describe cluster --cluster=<cluster_name> | grep -i 'Infra ID'
67+
----
68+
+
69+
or
70+
+
71+
[source,terminal]
72+
----
73+
$ oc get infrastructure cluster -o json | jq -r '.status.infrastructureName'
74+
----
75+
.. Identify the
76+
ifndef::openshift-rosa[]
77+
{product-title}
78+
endif::openshift-rosa[]
79+
ifdef::openshift-rosa[]
80+
ROSA
81+
endif::openshift-rosa[]
82+
cluster OIDC DNS:
83+
+
84+
--
85+
[source, terminal]
86+
----
87+
$ rosa describe cluster --cluster=<cluster_name> | grep -i 'OIDC'
88+
----
89+
Save the output from the commands. You will use this information in future steps within this procedure.
90+
--
91+
. Create the AWS IAM policy required for the ALBO:
92+
+
93+
.. Log in to the
94+
ifndef::openshift-rosa[]
95+
{product-title}
96+
endif::openshift-rosa[]
97+
ifdef::openshift-rosa[]
98+
ROSA
99+
endif::openshift-rosa[]
100+
cluster as a user with the `dedicated-admin` role and create a new project using the following command:
101+
+
102+
[source, terminal]
103+
----
104+
$ oc new-project aws-load-balancer-operator
105+
----
106+
107+
+
108+
.. Assign the following trust policy to the newly-created AWS IAM role:
109+
+
110+
[source,terminal]
111+
----
112+
$ IDP='{Cluster_OIDC_Endpoint}'
113+
$ IDP_ARN="arn:aws:iam::{AWS_AccountNo}:oidc-provider/${IDP}" <1>
114+
$ cat <<EOF > albo-operator-trusted-policy.json
115+
{
116+
"Version": "2012-10-17",
117+
"Statement": [
118+
{
119+
"Effect": "Allow",
120+
"Principal": {
121+
"Federated": "${IDP_ARN}"
122+
},
123+
"Action": "sts:AssumeRoleWithWebIdentity",
124+
"Condition": {
125+
"StringEquals": {
126+
"${IDP}:sub": "system:serviceaccount:aws-load-balancer-operator:aws-load-balancer-operator-controller-manager"
127+
}
128+
}
129+
}
130+
]
131+
}
132+
EOF
133+
----
134+
<1> Replace '{AWS_AccountNo}' with your AWS account number and '{Cluster_OIDC_Endpoint}' with the OIDC DNS identified earlier in this procedure.
135+
+
136+
[IMPORTANT]
137+
====
138+
Do not include the `https` portion of the OIDC DNS URL when replacing `{Cluster_OIDC_Endpoint}` with the OIDC DNS you identified earlier. Only the alphanumeric information that follows the `/` within the URL is needed.
139+
====
140+
+
141+
For more information on assigning trust policies to AWS IAM roles, see link:https://aws.amazon.com/blogs/security/how-to-use-trust-policies-with-iam-roles/[How to use trust policies with IAM roles].
142+
.. Create and verify the role by using the generated trusted policy:
143+
+
144+
[source, terminal]
145+
----
146+
$ aws iam create-role --role-name albo-operator --assume-role-policy-document file://albo-operator-trusted-policy.json
147+
$ OPERATOR_ROLE_ARN=$(aws iam get-role --role-name albo-operator --output json | jq -r '.Role.Arn')
148+
$ echo $OPERATOR_ROLE_ARN
149+
----
150+
+
151+
For more information on creating AWS IAM roles, see link:https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create.html[Creating IAM roles].
152+
+
153+
.. Attach the operator's permission policy to the role:
154+
+
155+
[source, terminal]
156+
----
157+
$ curl -o albo-operator-permission-policy.json https://raw.githubusercontent.com/alebedev87/aws-load-balancer-operator/aws-cli-commands-for-sts/hack/operator-permission-policy.json
158+
aws iam put-role-policy --role-name albo-operator --policy-name perms-policy-albo-operator --policy-document file://albo-operator-permission-policy.json
159+
----
160+
+
161+
For more information on adding AWS IAM permissions to AWS IAM roles, see link:https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_manage-attach-detach.html[Adding and removing IAM identity permissions].
162+
+
163+
.. Generate the operator's AWS credentials:
164+
+
165+
[source,terminal]
166+
----
167+
$ cat <<EOF> albo-operator-aws-credentials.cfg
168+
[default]
169+
sts_regional_endpoints = regional
170+
role_arn = ${OPERATOR_ROLE_ARN}
171+
web_identity_token_file = /var/run/secrets/openshift/serviceaccount/token
172+
EOF
173+
----
174+
+
175+
For more information about formatting credentials files, see link:https://access.redhat.com/documentation/en-us/openshift_container_platform/4.13/html/authentication_and_authorization/managing-cloud-provider-credentials#cco-mode-sts[Using manual mode with Amazon Web Services Security Token Service].
176+
+
177+
.. Create the operator's credentials secret with the generated AWS credentials:
178+
+
179+
[source, terminal]
180+
----
181+
$ oc -n aws-load-balancer-operator create secret generic aws-load-balancer-operator --from-file=credentials=albo-operator-aws-credentials.cfg
182+
----
183+
. Create the AWS IAM policy required for the AWS Load Balancer Controller (ALBC):
184+
+
185+
.. Generate a trusted policy file for your identity provider. The following example uses OpenID Connect:
186+
+
187+
[source,terminal]
188+
----
189+
$ IDP='{Cluster_OIDC_Endpoint}'
190+
$ IDP_ARN="arn:aws:iam::{AWS_AccountNo}:oidc-provider/${IDP}"
191+
$ cat <<EOF > albo-controller-trusted-policy.json
192+
{
193+
"Version": "2012-10-17",
194+
"Statement": [
195+
{
196+
"Effect": "Allow",
197+
"Principal": {
198+
"Federated": "${IDP_ARN}"
199+
},
200+
"Action": "sts:AssumeRoleWithWebIdentity",
201+
"Condition": {
202+
"StringEquals": {
203+
"${IDP}:sub": "system:serviceaccount:aws-load-balancer-operator:aws-load-balancer-controller-cluster"
204+
}
205+
}
206+
}
207+
]
208+
}
209+
EOF
210+
----
211+
+
212+
.. Create and verify the role by using the generated trusted policy:
213+
+
214+
[source, terminal]
215+
----
216+
$ aws iam create-role --role-name albo-controller --assume-role-policy-document file://albo-controller-trusted-policy.json
217+
$ CONTROLLER_ROLE_ARN=$(aws iam get-role --role-name albo-controller --output json | jq -r '.Role.Arn')
218+
$ echo $CONTROLLER_ROLE_ARN
219+
----
220+
+
221+
.. Attach the controller's permission policy to the role:
222+
+
223+
[source,terminal]
224+
----
225+
$ curl -o albo-controller-permission-policy.json https://raw.githubusercontent.com/kubernetes-sigs/aws-load-balancer-controller/v2.4.7/docs/install/iam_policy.json
226+
aws iam put-role-policy --role-name albo-controller --policy-name perms-policy-albo-controller --policy-document file://albo-controller-permission-policy.json
227+
----
228+
+
229+
.. Generate the controller's AWS credentials:
230+
+
231+
[source,terminal]
232+
----
233+
$ cat <<EOF > albo-controller-aws-credentials.cfg
234+
[default]
235+
sts_regional_endpoints = regional
236+
role_arn = ${CONTROLLER_ROLE_ARN}
237+
web_identity_token_file = /var/run/secrets/openshift/serviceaccount/token
238+
EOF
239+
----
240+
+
241+
.. Create the controller's credentials secret by using the generated AWS credentials:
242+
+
243+
[source,terminal]
244+
----
245+
$ oc -n aws-load-balancer-operator create secret generic aws-load-balancer-controller-cluster --from-file=credentials=albo-controller-aws-credentials.cfg
246+
----
247+
+
248+
. Add the tags necessary for subnet discovery:
249+
.. Add the following `{Key: Value}` tag to the VPC hosting the
250+
ifndef::openshift-rosa[]
251+
{product-title}
252+
endif::openshift-rosa[]
253+
ifdef::openshift-rosa[]
254+
ROSA
255+
endif::openshift-rosa[]
256+
cluster. Replace `{Cluster Infra ID}` with the Infra ID specified previously:
257+
+
258+
[source, terminal]
259+
----
260+
* kubernetes.io/cluster/${Cluster Infra ID}:owned
261+
----
262+
+
263+
.. Add the following ELBv2 `{Key: Value}` tags to the private subnets and, optionally, to the public subnets:
264+
265+
* Private subnets: `kubernetes.io/role/internal-elb:1`
266+
* Public subnets: `kubernetes.io/role/elb:1`
267+
+
268+
[NOTE]
269+
====
270+
Internet-facing and internal load balancers will be created within the AZ to which these subnets belong.
271+
====
272+
+
273+
For more information on adding tags to AWS resources, including VPCs and subnets, see link:https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/Using_Tags.html[Tag your Amazon EC2 resources].
274+
+
275+
[IMPORTANT]
276+
====
277+
ELBv2 resources (such as ALBs and NLBs) created by ALBO do not inherit custom tags set for
278+
ifndef::openshift-rosa[]
279+
{product-title}
280+
endif::openshift-rosa[]
281+
ifdef::openshift-rosa[]
282+
ROSA
283+
endif::openshift-rosa[]
284+
clusters. You must set tags separately for these resources.
285+
====
286+
+
287+
. Create ALBO:
288+
+
289+
[source,yaml]
290+
----
291+
apiVersion: operators.coreos.com/v1
292+
kind: OperatorGroup
293+
metadata:
294+
name: aws-load-balancer-operator
295+
namespace: aws-load-balancer-operator
296+
spec:
297+
upgradeStrategy: Default
298+
---
299+
apiVersion: operators.coreos.com/v1alpha1
300+
kind: Subscription
301+
metadata:
302+
name: aws-load-balancer-operator
303+
namespace: aws-load-balancer-operator
304+
spec:
305+
channel: stable-v1.0
306+
installPlanApproval: Automatic
307+
name: aws-load-balancer-operator
308+
source: redhat-operators
309+
sourceNamespace: openshift-marketplace
310+
startingCSV: aws-load-balancer-operator.v1.0.0
311+
----
312+
+
313+
. Create an AWS ALBC:
314+
+
315+
[source,yaml]
316+
----
317+
apiVersion: networking.olm.openshift.io/v1
318+
kind: AWSLoadBalancerController
319+
metadata:
320+
name: cluster
321+
spec:
322+
subnetTagging: Manual
323+
credentials:
324+
name: aws-load-balancer-controller-cluster
325+
----
326+
+
327+
[IMPORTANT]
328+
====
329+
Because AWS ALBCs do not support creating ALBs associated with both AZs and AWS LZs,
330+
ifndef::openshift-rosa[]
331+
{product-title}
332+
endif::openshift-rosa[]
333+
ifdef::openshift-rosa[]
334+
ROSA
335+
endif::openshift-rosa[]
336+
clusters can have ALBs associated exclusively with either AWS LZs or AZs but not both simultaneously.
337+
====
338+
+
339+
For more information regarding AWS ALBC configurations, see the following topics:
340+
341+
* link:https://access.redhat.com/documentation/en-us/openshift_container_platform/4.13/html/networking/aws-load-balancer-operator-1#nw-multiple-ingress-through-single-alb[Creating multiple ingresses]
342+
* link:https://access.redhat.com/documentation/en-us/openshift_container_platform/4.13/html/networking/aws-load-balancer-operator-1#nw-adding-tls-termination_adding-tls-termination[Adding TLS termination]
343+
344+
.Verification
345+
346+
* Confirm successful installation by running the following commands:
347+
348+
. Gather information about pods within the project:
349+
+
350+
[source, terminal]
351+
----
352+
$ oc get pods -n aws-load-balancer-operator
353+
----
354+
. View the logs within the project:
355+
+
356+
[source, terminal]
357+
----
358+
$ oc logs -n aws-load-balancer-operator deployment/aws-load-balancer-operator-controller-manager -c manager
359+
----
360+
For detailed instructions on verifying that the ELBv2 was created for the application running in the
361+
ifndef::openshift-rosa[]
362+
{product-title}
363+
endif::openshift-rosa[]
364+
ifdef::openshift-rosa[]
365+
ROSA
366+
endif::openshift-rosa[]
367+
cluster, see link:https://docs.openshift.com/container-platform/4.13/networking/aws_load_balancer_operator/create-instance-aws-load-balancer-controller.html[Creating an instance of AWS Load Balancer Controller].

‎modules/aws-uninstalling-an-aws-load-balancer-operator.adoc

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * networking/aws-load-balancer-operator.adoc
4+
5+
:_content-type: PROCEDURE
6+
[id="aws-uninstalling-an-aws-load-balancer-operator_{context}"]
7+
= Uninstalling an AWS Load Balancer Operator
8+
To uninstall an AWS Load Balancer Operator (ALBO) and perform an overall cleanup of the associated resources, perform the following procedure.
9+
10+
.Procedure
11+
. Clean up the sample application by deleting the Load Balancers created and managed by the ALBO. For more information about deleting Load Balancers, see link:https://docs.aws.amazon.com/elasticloadbalancing/latest/application/load-balancer-delete.html[Delete an Application Load Balancer].
12+
. Clean up the AWS VPC tags by removing the VPC tags that were added to the subnets for discovering subnets and for creating Application Load Balancers (ALBs). For more information, see link:https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/Using_Tags.html#tag-basics[Tag basics].
13+
. Clean up ALBO components by deleting both the ALBO and the Application Load Balancer Controller (ALBC).
14+
For more information, see link:https://access.redhat.com/documentation/en-us/openshift_container_platform/4.13/html/operators/administrator-tasks#olm-deleting-operators-from-a-cluster[Deleting Operators from a cluster].

0 commit comments

Comments
 (0)