AWS Load Balancer Operator - Networking Operators | Networking

Creating an AWS IAM role by using the Cloud Credential Operator utility
Creating an AWS IAM role for the controller by using the Cloud Credential Operator utility
Installing an AWS Load Balancer Operator
Uninstalling an AWS Load Balancer Operator

The AWS Load Balancer Operator is an Operator supported by Red Hat that users can optionally install on SRE-managed Red Hat OpenShift Service on AWS (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.

edit

Creating an AWS IAM role by using the Cloud Credential Operator utility

You can use the Cloud Credential Operator utility (ccoctl) to create an AWS IAM role for the AWS Load Balancer Operator. An AWS IAM role interacts with subnets and Virtual Private Clouds (VPCs).

Prerequisites

You must extract and prepare the ccoctl binary.

Procedure

Download the CredentialsRequest custom resource (CR) and store it in a directory by running the following command:

$ curl --create-dirs -o <credentials_requests_dir>/operator.yaml https://raw.githubusercontent.com/openshift/aws-load-balancer-operator/main/hack/operator-credentials-request.yaml

Use the ccoctl utility to create an AWS IAM role by running the following command:

$ ccoctl aws create-iam-roles \
    --name <name> \
    --region=<aws_region> \
    --credentials-requests-dir=<credentials_requests_dir> \
    --identity-provider-arn <oidc_arn>

Example output

2023/09/12 11:38:57 Role arn:aws:iam::777777777777:role/<name>-aws-load-balancer-operator-aws-load-balancer-operator created (1)
2023/09/12 11:38:57 Saved credentials configuration to: /home/user/<credentials_requests_dir>/manifests/aws-load-balancer-operator-aws-load-balancer-operator-credentials.yaml
2023/09/12 11:38:58 Updated Role policy for Role <name>-aws-load-balancer-operator-aws-load-balancer-operator created

1	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/<name>-aws-load-balancer-operator-aws-load-balancer-operator`.

The length of an AWS IAM role name must be less than or equal to 12 characters.

edit

Creating an AWS IAM role for the controller by using the Cloud Credential Operator utility

You can use the Cloud Credential Operator utility (ccoctl) to create an AWS IAM role for the AWS Load Balancer Controller. An AWS IAM role is used to interact with subnets and Virtual Private Clouds (VPCs).

Prerequisites

You must extract and prepare the ccoctl binary.

Procedure

Download the CredentialsRequest custom resource (CR) and store it in a directory by running the following command:

$ curl --create-dirs -o <credentials_requests_dir>/controller.yaml https://raw.githubusercontent.com/openshift/aws-load-balancer-operator/main/hack/controller/controller-credentials-request.yaml

Use the ccoctl utility to create an AWS IAM role by running the following command:

$ ccoctl aws create-iam-roles \
    --name <name> \
    --region=<aws_region> \
    --credentials-requests-dir=<credentials_requests_dir> \
    --identity-provider-arn <oidc_arn>

Example output

2023/09/12 11:38:57 Role arn:aws:iam::777777777777:role/<name>-aws-load-balancer-operator-aws-load-balancer-controller created (1)
2023/09/12 11:38:57 Saved credentials configuration to: /home/user/<credentials_requests_dir>/manifests/aws-load-balancer-operator-aws-load-balancer-controller-credentials.yaml
2023/09/12 11:38:58 Updated Role policy for Role <name>-aws-load-balancer-operator-aws-load-balancer-controller created

1	Note the Amazon Resource Name (ARN) of an AWS IAM role that was created for the AWS Load Balancer Controller, such as `arn:aws:iam::777777777777:role/<name>-aws-load-balancer-operator-aws-load-balancer-controller`.

The length of an AWS IAM role name must be less than or equal to 12 characters.

edit

Installing an AWS Load Balancer Operator

You can install an AWS Load Balancer Operator and an AWS Load Balancer Controller if you meet certain requirements.

Prerequisites

You have an existing Red Hat OpenShift Service on AWS (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 ROSA cluster.
You have installed the ROSA CLI (rosa).
You have installed the Amazon Web Services (AWS) CLI.
You are using OpenShift Container Platform 4.13 or later.

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:
1. Identify the ROSA cluster ID:
  $ rosa describe cluster --cluster=<cluster_name> | grep -i 'Infra ID'
  or
  $ oc get infrastructure cluster -o json | jq -r '.status.infrastructureName'
2. Identify the ROSA cluster OIDC DNS by using the following rosa CLI command:
  $ rosa describe cluster --cluster=<cluster_name> | grep -i OIDC (1)
  1 An OIDC DNS example is oidc.op1.openshiftapps.com/28q7fsn54m2jjts3kd556aij4mu9omah.
  
  or
  $ oc get authentication.config cluster -o=jsonpath="{.spec.serviceAccountIssuer}"
3. 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/<oidc_dns_url>.
4. 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.

Log in to the ROSA cluster as a user with the dedicated-admin role and create a new project using the following command:
```
$ oc new-project aws-load-balancer-operator
```
Assign the following trust policy to the newly-created AWS IAM role:
```
$ IDP='{Cluster_OIDC_Endpoint}'
```
```
$ IDP_ARN="arn:aws:iam::{AWS_AccountNo}:oidc-provider/${IDP}" (1)
```
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

$ cat EOF albo-operator-trusted-policy.json
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Federated": "${IDP_ARN}"
            },
            "Action": "sts:AssumeRoleWithWebIdentity",
            "Condition": {
                "StringEquals": {
                    "${IDP}:sub": "system:serviceaccount:aws-load-balancer-operator:aws-load-balancer-operator-controller-manager"
                }
            }
        }
    ]
}
EOF

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.

Create and verify the role by using the generated trust policy:

$ aws iam create-role --role-name albo-operator --assume-role-policy-document file://albo-operator-trusted-policy.json

$ OPERATOR_ROLE_ARN=$(aws iam get-role --role-name albo-operator --output json | jq -r '.Role.Arn')

$ echo $OPERATOR_ROLE_ARN

Example output

ROLE arn:aws:iam::<aws_account_number>: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:<aws_account_number>:oidc-provider/<oidc_provider_id>

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:

$ 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

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:

$ IDP='{Cluster_OIDC_Endpoint}'
$ IDP_ARN="arn:aws:iam::{AWS_AccountNo}:oidc-provider/${IDP}"
$ cat <EOF> albo-controller-trusted-policy.json
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Federated": "${IDP_ARN}"
            },
            "Action": "sts:AssumeRoleWithWebIdentity",
            "Condition": {
                "StringEquals": {
                    "${IDP}:sub": "system:serviceaccount:aws-load-balancer-operator:aws-load-balancer-controller-cluster"
                }
            }
        }
    ]
}
EOF

Create and verify the role by using the generated trust policy:

$ 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

ROLE	arn:aws:iam::<aws_account_number>: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:<aws_account_number>:oidc-provider/<oidc_provider_id>

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:

$ 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:
1. 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:
  kubernetes.io/cluster/${Cluster Infra ID}:owned
2. 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
    
    Internet-facing and internal load balancers will be created within the AWS Availability Zone to which these subnets belong.
    
    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 an OperatorGroup object by running the following command:

$ cat EOF | oc apply -f -
apiVersion: operators.coreos.com/v1
kind: OperatorGroup
metadata:
  name: aws-load-balancer-operator
  namespace: aws-load-balancer-operator
spec:
  targetNamespaces: []
EOF

Create a Subscription object by running the following command:

$ 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
  name: aws-load-balancer-operator
  source: redhat-operators
  sourceNamespace: openshift-marketplace
  config:
    env:
    - name: ROLEARN
      value: "<operator_role_arn>" (1)
EOF

1	Specifies the ARN role for the AWS Load Balancer Operator. The `CredentialsRequest` object uses this ARN role to provision the AWS credentials. An example of `<operator_role_arn>` is `arn:aws:iam::<aws_account_number>:role/albo-operator`.

Create the AWS Load Balancer Controller:

apiVersion: networking.olm.openshift.io/v1
kind: AWSLoadBalancerController
metadata:
  name: cluster
spec:
  subnetTagging: Manual
  credentialsRequestConfig:
    stsIAMRoleARN: <controller_role_arn>

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.

Verification

Confirm a successful installation by running the following commands:

Gather information about pods within the project:
```
$ oc get pods -n aws-load-balancer-operator
```

View the logs within the project:

$ oc logs -n aws-load-balancer-operator deployment/aws-load-balancer-operator-controller-manager -c manager

Additional resources

For more information about assigning trust policies to AWS IAM roles, see How to use trust policies with IAM roles.
For more information about creating AWS IAM roles, see Creating IAM roles.
For more information on adding AWS IAM permissions to AWS IAM roles, see Adding and removing IAM identity permissions.
For more information about formatting credentials files, see Using manual mode with Amazon Web Services Security Token Service.
For more information regarding AWS Load Balancer Controllers configurations, Creating multiple ingresses and Adding TLS termination
For more information on adding tags to AWS resources, including VPCs and subnets, see Tag your Amazon EC2 resources.
For detailed instructions on verifying that the ELBv2 was created for the application running in the ROSA cluster, see Creating an instance of AWS Load Balancer Controller.

edit

Uninstalling an AWS Load Balancer Operator

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 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 Tag basics.
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 Deleting Operators from a cluster.