diff --git a/modules/aws-installing-an-aws-load-balancer-operator.adoc b/modules/aws-installing-an-aws-load-balancer-operator.adoc index a6714db933..d5d5763dd4 100644 --- a/modules/aws-installing-an-aws-load-balancer-operator.adoc +++ b/modules/aws-installing-an-aws-load-balancer-operator.adoc @@ -5,113 +5,88 @@ :_mod-docs-content-type: PROCEDURE [id="aws-installing-an-aws-load-balancer-operator_{context}"] = Installing an AWS Load Balancer Operator -You can install an AWS Load Balancer Operator (ALBO) if you meet certain requirements. +You can install an AWS Load Balancer Operator and an AWS Load Balancer Controller 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} (ROSA) cluster with bring-your-own-VPC (BYO-VPC) configuration across multiple Availability Zones (AZs) installed in Hosted Control Plane (HCP) 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} -endif::openshift-rosa[] -ifdef::openshift-rosa[] -ROSA -endif::openshift-rosa[] -CLI (`rosa`). +* 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 Amazon Web Services (AWS) CLI. -* You have installed the OpenShift CLI (oc). -* You are using OpenShift Container Platform (OCP) 4.13 or later. +* You are using OpenShift Container Platform 4.13 or later. [IMPORTANT] ==== -When installing an ALBO for use with -ifndef::openshift-rosa[] -a {product-title} -endif::openshift-rosa[] -ifdef::openshift-rosa[] -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. +When installing an AWS Load Balancer Operator for use with a ROSA cluster in an AWS Local Zone (LZ), you must enable the AWS Local Zone for the account. Additionally, you must ensure that AWS Elastic Load Balancing v2 (ELBv2) services exist in the AWS Local Zone. ==== + .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} -endif::openshift-rosa[] -ifdef::openshift-rosa[] -ROSA -endif::openshift-rosa[] -cluster INFRA ID: + -[source,terminal] +.. Identify the ROSA cluster ID: ++ +[source,terminal,subs="quotes,verbatim"] ---- $ rosa describe cluster --cluster= | grep -i 'Infra ID' ---- + or + -[source,terminal] +[source,terminal,subs="quotes,verbatim"] ---- $ oc get infrastructure cluster -o json | jq -r '.status.infrastructureName' ---- -.. Identify the -ifndef::openshift-rosa[] -{product-title} -endif::openshift-rosa[] -ifdef::openshift-rosa[] -ROSA -endif::openshift-rosa[] -cluster OIDC DNS: + --- -[source, terminal] ----- -$ rosa describe cluster --cluster= | grep -i 'OIDC' ----- -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: +.. Identify the ROSA cluster OIDC DNS by using the following `rosa` CLI command: + -.. Log in to the -ifndef::openshift-rosa[] -{product-title} -endif::openshift-rosa[] -ifdef::openshift-rosa[] -ROSA -endif::openshift-rosa[] -cluster as a user with the `dedicated-admin` role and create a new project using the following command: +[source,terminal,subs="quotes,verbatim"] +---- +$ rosa describe cluster --cluster= | grep -i OIDC <1> +---- +<1> An OIDC DNS example is `oidc.op1.openshiftapps.com/28q7fsn54m2jjts3kd556aij4mu9omah`. + -[source, terminal] +or ++ +[source,terminal,subs="quotes,verbatim"] ---- -$ oc new-project aws-load-balancer-operator +$ oc get authentication.config cluster -o=jsonpath="{.spec.serviceAccountIssuer}" ---- ++ +.. Locate the OIDC Amazon Resource Name (ARN) information on the AWS Web Console by navigating to *IAM* *Access management* *Identity providers*. An OIDC ARN example is `arn:aws:iam::777777777777: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 AWS Load Balancer Operator by using the AWS CLI. + -.. Assign the following trust policy to the newly-created AWS IAM role: +.. Log in to the ROSA cluster as a user with the `dedicated-admin` role and create a new project using the following command: + [source,terminal] ---- +$ oc new-project aws-load-balancer-operator +---- ++ +.. Assign the following trust policy to the newly-created AWS IAM role: ++ +[source,terminal,subs="quotes,verbatim"] +---- $ IDP='{Cluster_OIDC_Endpoint}' +---- ++ +[source,terminal,subs="quotes,verbatim"] +---- $ IDP_ARN="arn:aws:iam::{AWS_AccountNo}:oidc-provider/${IDP}" <1> -$ cat < albo-operator-trusted-policy.json +---- +<1> Replace `{AWS_AccountNo}` with your AWS account number and `{Cluster_OIDC_Endpoint}` with the OIDC DNS identified earlier in this procedure. ++ +.. Verify that the trsut policy was assigned to the AWS IAM role. ++ +.Example output +[source,terminal,subs="quotes,verbatim"] +---- +$ cat EOF albo-operator-trusted-policy.json { "Version": "2012-10-17", "Statement": [ @@ -131,56 +106,53 @@ $ cat < albo-operator-trusted-policy.json } EOF ---- -<1> Replace '{AWS_AccountNo}' with your AWS account number and '{Cluster_OIDC_Endpoint}' with the OIDC DNS identified earlier in this procedure. + [IMPORTANT] ==== 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. ==== + -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: + -[source, terminal] +[source,terminal] ---- $ aws iam create-role --role-name albo-operator --assume-role-policy-document file://albo-operator-trusted-policy.json +---- ++ +[source,terminal] +---- $ OPERATOR_ROLE_ARN=$(aws iam get-role --role-name albo-operator --output json | jq -r '.Role.Arn') +---- ++ +[source,terminal] +---- $ echo $OPERATOR_ROLE_ARN ---- + -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]. +.Example output +[source,terminal] +---- +ROLE arn:aws:iam:::role/albo-operator 2023-08-02T12:13:22Z +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/ +---- ++ +[NOTE] +==== +Where `arn` of the AWS IAM role was created for the AWS Load Balancer Operator, such as `arn:aws:iam::777777777777:role/albo-operator`. +==== + .. Attach the operator's permission policy to the role: + -[source, terminal] +[source,terminal] ---- $ curl -o albo-operator-permission-policy.json https://raw.githubusercontent.com/openshift/aws-load-balancer-operator/release-1.1/hack/operator-permission-policy.json $ aws iam put-role-policy --role-name albo-operator --policy-name perms-policy-albo-operator --policy-document file://albo-operator-permission-policy.json ---- -+ -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]. -+ -.. Generate the operator's AWS credentials: -+ -[source,terminal] ----- -$ cat < albo-operator-aws-credentials.cfg -[default] -sts_regional_endpoints = regional -role_arn = ${OPERATOR_ROLE_ARN} -web_identity_token_file = /var/run/secrets/openshift/serviceaccount/token -EOF ----- -+ -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]. -+ -.. Create the operator's credentials secret with the generated AWS credentials: -+ -[source, terminal] ----- -$ 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 by using the AWS CLI: + .. Generate a trust policy file for your identity provider. The following example uses OpenID Connect: + @@ -188,7 +160,7 @@ $ oc -n aws-load-balancer-operator create secret generic aws-load-balancer-opera ---- $ IDP='{Cluster_OIDC_Endpoint}' $ IDP_ARN="arn:aws:iam::{AWS_AccountNo}:oidc-provider/${IDP}" -$ cat < albo-controller-trusted-policy.json +$ cat albo-controller-trusted-policy.json { "Version": "2012-10-17", "Statement": [ @@ -211,13 +183,28 @@ EOF + .. Create and verify the role by using the generated trust policy: + -[source, terminal] +[source,terminal] ---- $ aws iam create-role --role-name albo-controller --assume-role-policy-document file://albo-controller-trusted-policy.json $ CONTROLLER_ROLE_ARN=$(aws iam get-role --role-name albo-controller --output json | jq -r '.Role.Arn') $ echo $CONTROLLER_ROLE_ARN ---- + +.Example output +[source,terminal] +---- +ROLE arn:aws:iam:::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::oidc-provider/ +---- ++ +[NOTE] +==== +Where `arn` of the AWS IAM role that was created for the AWS Load Balancer Controller, such as `arn:aws:iam::777777777777:role/albo-controller`. +==== ++ .. Attach the controller's permission policy to the role: + [source,terminal] @@ -225,92 +212,72 @@ $ echo $CONTROLLER_ROLE_ARN $ 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 $ aws iam put-role-policy --role-name albo-controller --policy-name perms-policy-albo-controller --policy-document file://albo-controller-permission-policy.json ---- + +. For a ROSA with HCP cluster, add the tags necessary for subnet discovery: + -.. Generate the controller's AWS credentials: +.. Add the following `{Key: Value}` tag to the VPC hosting the ROSA cluster and to all its subnets. Replace `{Cluster Infra ID}` with the Infra ID specified previously: + -[source,terminal] +[source,terminal,subs="quotes,verbatim"] ---- -$ cat < albo-controller-aws-credentials.cfg -[default] -sts_regional_endpoints = regional -role_arn = ${CONTROLLER_ROLE_ARN} -web_identity_token_file = /var/run/secrets/openshift/serviceaccount/token -EOF ----- -+ -.. Create the controller's credentials secret by using the generated AWS credentials: -+ -[source,terminal] ----- -$ 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 following `{Key: Value}` tag to the VPC hosting the -ifndef::openshift-rosa[] -{product-title} -endif::openshift-rosa[] -ifdef::openshift-rosa[] -ROSA -endif::openshift-rosa[] -cluster and to all its subnets. Replace `{Cluster Infra ID}` with the Infra ID specified previously: -+ -[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: - ++ * Private subnets: `kubernetes.io/role/internal-elb:1` * Public subnets: `kubernetes.io/role/elb:1` + [NOTE] ==== -Internet-facing and internal load balancers will be created within the AZ to which these subnets belong. +Internet-facing and internal load balancers will be created within the AWS Availability Zone to which these subnets belong. ==== + -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]. -+ [IMPORTANT] ==== -ELBv2 resources (such as ALBs and NLBs) created by ALBO do not inherit custom tags set for -ifndef::openshift-rosa[] -{product-title} -endif::openshift-rosa[] -ifdef::openshift-rosa[] -ROSA -endif::openshift-rosa[] -clusters. You must set tags separately for these resources. +ELBv2 resources (such as ALBs and NLBs) created by AWS Load Balancer Operator do not inherit custom tags set for ROSA clusters. You must set tags separately for these resources. ==== + +. Create the AWS Load Balancer Operator by completing the following steps: + -. Create ALBO: +.. Create an `OperatorGroup` object by running the following command: + -[source,yaml] +[source,terminal] ---- +$ cat EOF | oc apply -f - apiVersion: operators.coreos.com/v1 kind: OperatorGroup metadata: name: aws-load-balancer-operator namespace: aws-load-balancer-operator spec: - upgradeStrategy: Default ---- + targetNamespaces: [] +EOF +---- ++ +.. Create a `Subscription` object by running the following command: ++ +[source,terminal] +---- +$ cat EOF | oc apply -f - 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> +EOF ---- -+ -. Create an AWS ALBC: +<1> Specifies the ARN role for the {aws-short} Load Balancer Operator. The `CredentialsRequest` object uses this ARN role to provision the {aws-short} credentials. An example of `` is `arn:aws:iam:::role/albo-operator`. + +. Create the AWS Load Balancer Controller: + [source,yaml] ---- @@ -320,48 +287,29 @@ metadata: name: cluster spec: subnetTagging: Manual - credentials: - name: aws-load-balancer-controller-cluster + credentialsRequestConfig: + stsIAMRoleARN: ---- + [IMPORTANT] ==== -Because AWS ALBCs do not support creating ALBs associated with both AZs and AWS LZs, -ifndef::openshift-rosa[] -{product-title} -endif::openshift-rosa[] -ifdef::openshift-rosa[] -ROSA -endif::openshift-rosa[] -clusters can have ALBs associated exclusively with either AWS LZs or AZs but not both simultaneously. +Because AWS Load Balancer Controllers do not support creating AWS Load Balancers (ALBs) associated with both AWS Availability Zones and AWS Local Zones, ROSA clusters can have ALBs associated exclusively with either AWS Local Zones or AWS Availability Zones but not both simultaneously. ==== -+ -For more information regarding AWS ALBC configurations, see the following topics: - -* 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] -* 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] .Verification -* Confirm successful installation by running the following commands: - -. Gather information about pods within the project: +. Confirm a successful installation by running the following commands: + -[source, terminal] +.. Gather information about pods within the project: ++ +[source,terminal] ---- $ oc get pods -n aws-load-balancer-operator ---- -. View the logs within the project: + -[source, terminal] +.. View the logs within the project: ++ +[source,terminal] ---- $ oc logs -n aws-load-balancer-operator deployment/aws-load-balancer-operator-controller-manager -c manager ---- -For detailed instructions on verifying that the ELBv2 was created for the application running in the -ifndef::openshift-rosa[] -{product-title} -endif::openshift-rosa[] -ifdef::openshift-rosa[] -ROSA -endif::openshift-rosa[] -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]. diff --git a/modules/aws-uninstalling-an-aws-load-balancer-operator.adoc b/modules/aws-uninstalling-an-aws-load-balancer-operator.adoc index 0cd9f20bb3..116cb04e29 100644 --- a/modules/aws-uninstalling-an-aws-load-balancer-operator.adoc +++ b/modules/aws-uninstalling-an-aws-load-balancer-operator.adoc @@ -5,10 +5,12 @@ :_mod-docs-content-type: PROCEDURE [id="aws-uninstalling-an-aws-load-balancer-operator_{context}"] = Uninstalling an AWS Load Balancer Operator -To uninstall an AWS Load Balancer Operator (ALBO) and perform an overall cleanup of the associated resources, perform the following procedure. +To uninstall an AWS Load Balancer Operator and perform an overall cleanup of the associated resources, perform the following procedure. .Procedure . 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]. + . 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]. -. Clean up ALBO components by deleting both the ALBO and the Application Load Balancer Controller (ALBC). + +. Clean up AWS Load Balancer Operator components by deleting both the AWS Load Balancer Operator and the Application Load Balancer Controller. 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]. diff --git a/networking/aws-load-balancer-operator.adoc b/networking/aws-load-balancer-operator.adoc index 05cc9e1c1c..c408d888b5 100644 --- a/networking/aws-load-balancer-operator.adoc +++ b/networking/aws-load-balancer-operator.adoc @@ -6,22 +6,33 @@ include::_attributes/common-attributes.adoc[] toc::[] +The AWS Load Balancer Operator is an Operator supported by Red{nbsp}Hat that users can optionally install on SRE-managed {product-title} (ROSA) clusters. The AWS Load Balancer Operator manages the lifecycle of the AWS Load Balancer Controller that provisions AWS Elastic Load Balancing v2 (ELBv2) services for applications running in ROSA clusters. -The AWS Load Balancer Operator (ALBO) is an Operator supported by Red{nbsp}Hat that users can optionally install on SRE-managed -ifndef::openshift-rosa[] -{product-title} -endif::openshift-rosa[] -ifdef::openshift-rosa[] -{product-title} (ROSA) -endif::openshift-rosa[] -clusters. The ALBO manages the lifecycle of the AWS-managed AWS Load Balancer Controller (ALBC) that provisions AWS Elastic Load Balancing v2 (ELBv2) services for applications running in -ifndef::openshift-rosa[] -{product-title} -endif::openshift-rosa[] -ifdef::openshift-rosa[] -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] + +[role="_additional-resources"] +.Additional resources + +* For more information about 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]. + +* For more information about creating AWS IAM roles, see link:https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create.html[Creating IAM roles]. + +* 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]. + +* For more information about formatting credentials files, see link:https://access.redhat.com/documentation/en-us/openshift_container_platform/{ocp-version}/html/authentication_and_authorization/managing-cloud-provider-credentials#cco-mode-sts[Using manual mode with Amazon Web Services Security Token Service]. + +* For more information regarding AWS Load Balancer Controllers configurations, link:https://access.redhat.com/documentation/en-us/openshift_container_platform/{ocp-version}/html/networking/aws-load-balancer-operator-1#nw-multiple-ingress-through-single-alb[Creating multiple ingresses] and link:https://access.redhat.com/documentation/en-us/openshift_container_platform/{ocp-version}/html/networking/aws-load-balancer-operator-1#nw-adding-tls-termination_adding-tls-termination[Adding TLS termination] + +* 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]. + +* For detailed instructions on verifying that the ELBv2 was created for the application running in the ROSA 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]. + +// Uninstalling an AWS Load Balancer Operator include::modules/aws-uninstalling-an-aws-load-balancer-operator.adoc[leveloffset=+1] \ No newline at end of file