Skip to content

OCPBUGS#38771: Improved the ROSA AWS Load Balancer Operator document #81213

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 1 commit into from
Closed

OCPBUGS#38771: Improved the ROSA AWS Load Balancer Operator document #81213

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
198 changes: 144 additions & 54 deletions modules/aws-installing-an-aws-load-balancer-operator.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,35 +8,26 @@
You can install an AWS Load Balancer Operator (ALBO) if you meet certain requirements.

.Prerequisites

* You have an existing
ifndef::openshift-rosa[]
{product-title}
endif::openshift-rosa[]
ifdef::openshift-rosa[]
{product-title} (ROSA)
endif::openshift-rosa[]
cluster with bring-your-own-VPC (BYO-VPC) configuration across multiple availability zones (AZ) installed in STS mode.
* You have an existing {product-title} cluster with bring-your-own-VPC (BYO-VPC) configuration across multiple availability zones (AZ) installed in {hcp-title-first} mode.
* You have access to the cluster as a user with the `dedicated-admin` role.
* You have access to modify the VPC and subnets of the created
ifndef::openshift-rosa[]
{product-title}
endif::openshift-rosa[]
ifdef::openshift-rosa[]
ROSA
endif::openshift-rosa[]
cluster.
* You have installed the
ifndef::openshift-rosa[]
{product-title}
* You have access to modify the VPC and subnets of the created {product-title} cluster.
* You have installed the {product-title} * You have installed the ROSA CLI (`rosa`).
* You have installed the {AWS} CLI.
* You have installed the OpenShift CLI (oc).
* You are using {product-title} 4.13 or later.
endif::openshift-rosa[]

ifdef::openshift-rosa[]
ROSA
endif::openshift-rosa[]
CLI (`rosa`).
* You have installed the Amazon Web Services (AWS) CLI.
You have an existing {product-title} (ROSA) cluster with bring-your-own-VPC (BYO-VPC) configuration across multiple availability zones (AZ) installed in {hcp-title-first} mode.

* You have access to the cluster as a user with the `dedicated-admin` role.
* You have access to modify the VPC and subnets of the created ROSA cluster.
* You have installed the ROSA CLI (`rosa`).
* You have installed the {AWS} CLI.
* You have installed the OpenShift CLI (oc).
* You are using OpenShift Container Platform (OCP) 4.13 or later.
* You are using {product-title} 4.13 or later.
endif::openshift-rosa[]

[IMPORTANT]
====
Expand All @@ -49,9 +40,11 @@ a ROSA
endif::openshift-rosa[]
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.
====

.Procedure

. Identify the cluster infrastructure ID and the cluster OpenID Connect (OIDC) DNS by running the following commands:
+
.. Identify the
ifndef::openshift-rosa[]
{product-title}
Expand All @@ -63,32 +56,47 @@ cluster INFRA ID:
+
[source,terminal]
----
$ rosa describe cluster --cluster=<cluster_name> | grep -i 'Infra ID'
$ rosa describe cluster --cluster=<cluster_name> | grep -i 'Infra ID' <1>
----
<1> Use this command on an ROSA {sts-first} cluster.
//ifdef needed for "ROSA"?
+
[source,terminal]
----
$ rosa describe cluster --cluster=<cluster_name> | grep -i '^ID' <1>
----
<1> Use this command on an {hcp-title-first} cluster.
+
or
+
[source,terminal]
----
$ oc get infrastructure cluster -o json | jq -r '.status.infrastructureName'
----
.. Identify the
+
ifndef::openshift-rosa[]
{product-title}
.. Identify the{product-title} cluster OIDC DNS by entering the following CLI command:
+
[source, terminal]
----
$ oc get authentication.config cluster -o=jsonpath="{.spec.serviceAccountIssuer}"
<url_oidc_dns> <1>
----
<1> An example of `<url_oidc_dns>` is `https://oidc.op1.openshiftapps.com/28q7fsn54m2jjts3kd556aij4mu9omah`.
endif::openshift-rosa[]
ifdef::openshift-rosa[]
ROSA
endif::openshift-rosa[]
cluster OIDC DNS:
.. Identify the{product-title} cluster OIDC DNS by entering the following CLI command:
+
--
[source, terminal]
----
$ rosa describe cluster --cluster=<cluster_name> | grep -i 'OIDC'
----
endif::openshift-rosa[]
.. Locate the OIDC Amazon Resource Name (ARN) information for yoru cluster by Logging in to the {aws-short} Web Console and then navigate to *IAM* -> *Access management* -> *Identity providers*. An OIDC ARN example is `arn:aws:iam::<aws_account_number>:oidc-provider/<oidc_dns_url>`.
+
Save the output from the commands. You will use this information in future steps within this procedure.
--
. Create the AWS IAM policy required for the ALBO:

. Create the AWS IAM policy required for the AWS Load Balancer Operator (ALBO) by using the AWS CLI:
+
.. Log in to the
ifndef::openshift-rosa[]
Expand All @@ -103,9 +111,8 @@ cluster as a user with the `dedicated-admin` role and create a new project using
----
$ oc new-project aws-load-balancer-operator
----

+
.. Assign the following trust policy to the newly-created AWS IAM role:
.. Assign the following trust policy to the created AWS IAM role:
+
[source,terminal]
----
Expand Down Expand Up @@ -139,15 +146,50 @@ Do not include the `https` portion of the OIDC DNS URL when replacing `{Cluster_
====
+
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].
.. Create and verify the role by using the generated trust policy:
+
.. Create a role by using the trust policy:
+
[source, terminal]
----
$ aws iam create-role --role-name albo-operator --assume-role-policy-document file://albo-operator-trusted-policy.json
----
+
.Example output
[source, terminal]
----
ROLE arn:aws:iam::<aws_account_number>:role/albo-operator 2023-08-02T12:13:22Z <1>
ASSUMEROLEPOLICYDOCUMENT 2012-10-17
STATEMENT sts:AssumeRoleWithWebIdentity Allow
STRINGEQUALS system:serviceaccount:aws-load-balancer-operator:aws-load-balancer-controller-manager
PRINCIPAL arn:aws:iam:<aws_account_number>:oidc-provider/<oidc_provider_id>
----
<1> Note the ARN of the AWS IAM role that was created for the AWS Load Balancer Operator, such as `arn:aws:iam::777777777777:role/albo-operator`.
+
.. Verify that the role was created by the trust policy:
+
[source, terminal]
----
$ OPERATOR_ROLE_ARN=$(aws iam get-role --role-name albo-operator --output json | jq -r '.Role.Arn')
----
+
.. Output information for the role:
[source, terminal]
----
$ echo $OPERATOR_ROLE_ARN
----
+
.Output example
[source, terminal]
----
ROLE arn:aws:iam::<aws_account_number>:role/aws-load-balancer-operator 2023-08-02T12:13:22Z <1>
ASSUMEROLEPOLICYDOCUMENT 2012-10-17
STATEMENT sts:AssumeRoleWithWebIdentity Allow
STRINGEQUALS system:serviceaccount:aws-load-balancer-operator:aws-load-balancer-controller-manager
PRINCIPAL arn:aws:iam:<aws_account_number>:oidc-provider/<oidc_provider_id> <2>
----
<1> Where `<aws_account_number>` is the AWS account ID. Note the Amazon Resource Name (ARN) of an AWS IAM role that was created for the AWS Load Balancer Operator, such as `arn:aws:iam::777777777777:role/albo-operator`.
<2> Where `<oidc_provider_id>` is your OIDC identity provider’s publicly available URL. TAKEN FROM https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc.html
+
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].
+
.. Attach the operator's permission policy to the role:
Expand Down Expand Up @@ -180,7 +222,8 @@ For more information about formatting credentials files, see link:https://access
----
$ oc -n aws-load-balancer-operator create secret generic aws-load-balancer-operator --from-file=credentials=albo-operator-aws-credentials.cfg
----
. Create the AWS IAM policy required for the AWS Load Balancer Controller:

. Create the AWS IAM policy required for the AWS Load Balancer Controller (ALBC) by using the AWS CLI:
+
.. Generate a trust policy file for your identity provider. The following example uses OpenID Connect:
+
Expand Down Expand Up @@ -209,15 +252,49 @@ $ cat <<EOF > albo-controller-trusted-policy.json
EOF
----
+
.. Create and verify the role by using the generated trust policy:
.. Create a role by using the trust policy:
+
[source, terminal]
----
$ aws iam create-role --role-name albo-controller --assume-role-policy-document file://albo-controller-trusted-policy.json
----
+
.Example output
+
[source,terminal]
----
ROLE arn:aws:iam::777777777777:role/albo-controller 2023-08-02T12:13:22Z
ASSUMEROLEPOLICYDOCUMENT 2012-10-17
STATEMENT sts:AssumeRoleWithWebIdentity Allow
STRINGEQUALS system:serviceaccount:aws-load-balancer-operator:aws-load-balancer-controller-cluster
PRINCIPAL arn:aws:iam:777777777777:oidc-provider/<oidc-provider-id>
----
+
.. Verify that the role was created by the trust policy:
+
[source, terminal]
----
$ CONTROLLER_ROLE_ARN=$(aws iam get-role --role-name albo-controller --output json | jq -r '.Role.Arn')
----
+
.. Output information for the role:
[source, terminal]
----
$ echo $CONTROLLER_ROLE_ARN
----
+
Output example
[source, terminal]
----
ROLE arn:aws:iam::<aws_account_number>:role/albo-controller 2023-08-02T12:13:22Z <1>
ASSUMEROLEPOLICYDOCUMENT 2012-10-17
STATEMENT sts:AssumeRoleWithWebIdentity Allow
STRINGEQUALS system:serviceaccount:aws-load-balancer-operator:aws-load-balancer-controller-cluster
PRINCIPAL arn:aws:iam:<aws_account_number>:oidc-provider/<oidc_provider_id> <2>
----
<1> Where `<aws_account_number>` is the AWS account ID. Note the Amazon Resource Name (ARN) of an AWS IAM role that was created for the AWS Load Balancer Operator, such as `arn:aws:iam::777777777777:role/albo-controller`.
<2> Where `<oidc_provider_id>` is your OIDC identity provider’s publicly available URL. TAKEN FROM https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc.html
+
.. Attach the controller's permission policy to the role:
+
[source,terminal]
Expand Down Expand Up @@ -245,7 +322,7 @@ EOF
$ oc -n aws-load-balancer-operator create secret generic aws-load-balancer-controller-cluster --from-file=credentials=albo-controller-aws-credentials.cfg
----
+
. Add the tags necessary for subnet discovery:
. Add the tags necessary for subnet discovery to the ROSA HCP cluster (ifdef needed for ROSA)?:
.. Add the following `{Key: Value}` tag to the VPC hosting the
ifndef::openshift-rosa[]
{product-title}
Expand All @@ -257,7 +334,7 @@ cluster and to all its subnets. Replace `{Cluster Infra ID}` with the Infra ID s
+
[source, terminal]
----
* kubernetes.io/cluster/${Cluster Infra ID}:owned
kubernetes.io/cluster/${Cluster Infra ID}:owned
----
+
.. Add the following ELBv2 `{Key: Value}` tags to the private subnets and, optionally, to the public subnets:
Expand All @@ -283,8 +360,8 @@ ROSA
endif::openshift-rosa[]
clusters. You must set tags separately for these resources.
====
+
. Create ALBO:

. Create an `OperatorGroup` resource for the AWS Load Balancer Operator:
+
[source,yaml]
----
Expand All @@ -294,35 +371,48 @@ metadata:
name: aws-load-balancer-operator
namespace: aws-load-balancer-operator
spec:
upgradeStrategy: Default
---
targetNamespaces: []
# ...
----

. Create a `Subscription` resource for the AWS Load Balancer Operator:
+
[source,yaml]
----
apiVersion: operators.coreos.com/v1alpha1
kind: Subscription
metadata:
name: aws-load-balancer-operator
namespace: aws-load-balancer-operator
spec:
channel: stable-v1.0
installPlanApproval: Automatic
channel: stable-v1
name: aws-load-balancer-operator
source: redhat-operators
sourceNamespace: openshift-marketplace
startingCSV: aws-load-balancer-operator.v1.0.0
config:
env:
- name: ROLEARN
value: "<role_arn>" <1>
# ...
----
+
. Create an AWS ALBC:
<1> Specifies the ARN role to be used in the CredentialsRequest to provision the AWS credentials for the AWS Load Balancer Operator. An example for <albo_role_arn> is arn:aws:iam::777777777777:role/albo-operator.

. Create an `AWSLoadBalancerController` resource for the AWS Load Balancer Controller:
+
[source,yaml]
----
apiVersion: networking.olm.openshift.io/v1
kind: AWSLoadBalancerController
kind: AWSLoadBalancerController <1>
metadata:
name: cluster
name: cluster <2>
spec:
subnetTagging: Manual
credentials:
name: aws-load-balancer-controller-cluster
credentialsRequestConfig:
stsIAMRoleARN: <role_arn> <3>
# ...
----
<1> Defines the `AWSLoadBalancerController` object.
<2> Defines the AWS Load Balancer Controller name. All related resources use this instance name as a suffix.
<3> Specifies the ARN role of ALBC. The CredentialsRequest object uses this ARN role to provision the AWS credentials. for example, it could be: "arn:aws:iam::777777777777:role/albo-controller".
+
[IMPORTANT]
====
Expand Down
9 changes: 9 additions & 0 deletions networking/aws-load-balancer-operator.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,5 +23,14 @@ ROSA
endif::openshift-rosa[]
clusters.

// Creating an AWS IAM role by using the Cloud Credential Operator utility
include::modules/using-ccoctl-create-iam-role-alb-operator.adoc[leveloffset=+1]

// Creating an AWS IAM role for the controller by using the Cloud Credential Operator utility
include::modules/using-ccoctl-create-iam-role-alb-controller.adoc[leveloffset=+1]

// Installing an AWS Load Balancer Operator
include::modules/aws-installing-an-aws-load-balancer-operator.adoc[leveloffset=+1]

// Uninstalling an AWS Load Balancer Operator
include::modules/aws-uninstalling-an-aws-load-balancer-operator.adoc[leveloffset=+1]