From db0fab6e222b28780c0e3025ea49a69e4521273a Mon Sep 17 00:00:00 2001 From: dfitzmau Date: Mon, 2 Sep 2024 17:20:49 +0100 Subject: [PATCH] OCPBUGS-38771: Improved the ROSA AWS Load Balancer Operator document --- ...talling-an-aws-load-balancer-operator.adoc | 198 +++++++++++++----- networking/aws-load-balancer-operator.adoc | 9 + 2 files changed, 153 insertions(+), 54 deletions(-) diff --git a/modules/aws-installing-an-aws-load-balancer-operator.adoc b/modules/aws-installing-an-aws-load-balancer-operator.adoc index a6714db93379..688b05719d2e 100644 --- a/modules/aws-installing-an-aws-load-balancer-operator.adoc +++ b/modules/aws-installing-an-aws-load-balancer-operator.adoc @@ -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] ==== @@ -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} @@ -63,8 +56,16 @@ cluster INFRA ID: + [source,terminal] ---- -$ rosa describe cluster --cluster= | grep -i 'Infra ID' +$ rosa describe cluster --cluster= | 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= | grep -i '^ID' <1> +---- +<1> Use this command on an {hcp-title-first} cluster. + or + @@ -72,23 +73,30 @@ or ---- $ 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}" + <1> +---- +<1> An example of `` 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= | 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:::oidc-provider/`. ++ 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[] @@ -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] ---- @@ -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:::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::oidc-provider/ +---- +<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:::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::oidc-provider/ <2> +---- +<1> Where `` 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 `` 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: @@ -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: + @@ -209,15 +252,49 @@ $ cat < 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/ +---- ++ +.. 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:::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::oidc-provider/ <2> +---- +<1> Where `` 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 `` 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] @@ -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} @@ -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: @@ -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] ---- @@ -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: "" <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 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: <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] ==== diff --git a/networking/aws-load-balancer-operator.adoc b/networking/aws-load-balancer-operator.adoc index 05cc9e1c1c40..cfd731c4a01e 100644 --- a/networking/aws-load-balancer-operator.adoc +++ b/networking/aws-load-balancer-operator.adoc @@ -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] \ No newline at end of file