Preparing an AWS STS cluster for the AWS Load Balancer Operator

To install the Amazon Web Services (AWS) Load Balancer Operator on a cluster that uses the Security Token Service (STS), prepare the cluster by configuring the CredentialsRequest object. This ensures the Operator can bootstrap the AWS Load Balancer Controller and access the required secrets.

The AWS Load Balancer Operator waits until the required secrets are created and available.

Before you start any Security Token Service (STS) procedures, ensure that you meet the following prerequisites:

You installed the OpenShift CLI (oc).
You know the infrastructure ID of your cluster. To show this ID, run the following command in your CLI:
```
$ oc get infrastructure cluster -o=jsonpath="{.status.infrastructureName}"
```
You know the OpenID Connect (OIDC) DNS information for your cluster. To show this information, enter the following command in your CLI:
```
$ oc get authentication.config cluster -o=jsonpath="{.spec.serviceAccountIssuer}"
```
where:

{.spec.serviceAccountIssuer}

Specifies an OIDC DNS URL. An example URL is https://rh-oidc.s3.us-east-1.amazonaws.com/28292va7ad7mr9r4he1fb09b14t59t4f.
You logged into the AWS management console, navigated to IAM → Access management → Identity providers, and located the OIDC Amazon Resource Name (ARN) information. An OIDC ARN example is arn:aws:iam::777777777777:oidc-provider/<oidc_dns_url>.

Additional resources

the Cloud Credential Operator utility (ccoctl)

The IAM role for the AWS Load Balancer Operator

To install the Amazon Web Services (AWS) Load Balancer Operator on a cluster by using STS, configure an additional Identity and Access Management (IAM) role. This role enables the Operator to interact with subnets and Virtual Private Clouds (VPCs), allowing the Operator to generate the CredentialsRequest object required for bootstrapping.

You can create the IAM role by using the following options:

Using the Cloud Credential Operator utility (ccoctl) and a predefined CredentialsRequest object.
Using the AWS CLI and predefined AWS manifests.

Use the AWS CLI if your environment does not support the ccoctl command.

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

To enable the AWS Load Balancer Operator to interact with subnets and VPCs, create an AWS IAM role by using the Cloud Credential Operator utility (ccoctl). By doing this task, you can generate the necessary credentials for the operator to function correctly within the cluster environment.

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
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

where:

<name>: Specifies the Amazon Resource Name (ARN) for 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.

Note

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

Creating an AWS IAM role by using the AWS CLI

To enable the AWS Load Balancer Operator to interact with subnets and VPCs, create an AWS IAM role by using the AWS CLI. This enables the Operator to access and manage the necessary network resources within the cluster.

Prerequisites

You must have access to the AWS Command Line Interface (aws).

Procedure

Generate a trust policy file by using your identity provider by running the following command:

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

where:

<oidc_arn>: Specifies the Amazon Resource Name (ARN) of the OIDC identity provider, such as arn:aws:iam::777777777777:oidc-provider/rh-oidc.s3.us-east-1.amazonaws.com/28292va7ad7mr9r4he1fb09b14t59t4f.
serviceaccount: Specifies the service account for the AWS Load Balancer Controller. An example of <cluster_oidc_endpoint> is rh-oidc.s3.us-east-1.amazonaws.com/28292va7ad7mr9r4he1fb09b14t59t4f.

Create the IAM role with the generated trust policy by running the following command:

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

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/<cluster_oidc_endpoint>

where:

<aws_account_number>: Specifies the ARN of the created AWS IAM role for the AWS Load Balancer Operator, such as arn:aws:iam::777777777777:role/albo-operator.

Download the permission policy for the AWS Load Balancer Operator by running the following command:

$ curl -o albo-operator-permission-policy.json https://raw.githubusercontent.com/openshift/aws-load-balancer-operator/main/hack/operator-permission-policy.json

Attach the permission policy for the AWS Load Balancer Controller to the IAM role by running the following command:

$ aws iam put-role-policy --role-name albo-operator --policy-name perms-policy-albo-operator --policy-document file://albo-operator-permission-policy.json

Configuring the ARN role for the AWS Load Balancer Operator

To authorize the AWS Load Balancer Operator, configure the Amazon Resource Name (ARN) role as an environment variable by using the CLI. This ensures the Operator has the necessary permissions to manage resources within the cluster.

Prerequisites

You have installed the OpenShift CLI (oc).

Procedure

Create the aws-load-balancer-operator project by running the following command:
```
$ oc new-project aws-load-balancer-operator
```

Create the 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 the 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: "<albo_role_arn>"
EOF
```
where:

<albo_role_arn>

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::<aws_account_number>:role/albo-operator.

Note

The AWS Load Balancer Operator waits until the secret is created before moving to the Available status.

The IAM role for the AWS Load Balancer Controller

To authorize the AWS Load Balancer Controller, configure the CredentialsRequest object with a manually provisioned IAM role. This ensures the controller functions correctly by using the specific permissions defined in your manual provisioning process.

You can create the IAM role by using the following options:

Using the Cloud Credential Operator utility (ccoctl) and a predefined CredentialsRequest object.
Using the AWS CLI and predefined AWS manifests.

If your environment does not support the ccoctl command.ws-short CLI, use the AWS CLI.

Additional resources

the Cloud Credential Operator utility (ccoctl)

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

To enable the AWS Load Balancer Controller to interact with subnets and VPCs, create an IAM role by using the Cloud Credential Operator utility (ccoctl). This utility ensures the controller has the specific permissions required to manage network resources within the cluster.

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
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

where:

<name>: Specifies the Amazon Resource Name (ARN) for 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.

Note

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

Creating an AWS IAM role for the controller by using the AWS CLI

To enable the AWS Load Balancer Controller to interact with subnets and Virtual Private Clouds (VPCs), create an IAM role by using the AWS CLI. This ensures the controller has the specific permissions required to manage network resources within the cluster.

Prerequisites

You must have access to the AWS command-line interface (aws).

Procedure

Generate a trust policy file using your identity provider by running the following command:

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

where:

<oidc_arn>: Specifies the Amazon Resource Name (ARN) of the OIDC identity provider, such as arn:aws:iam::777777777777:oidc-provider/rh-oidc.s3.us-east-1.amazonaws.com/28292va7ad7mr9r4he1fb09b14t59t4f.
serviceaccount: Specifies the service account for the AWS Load Balancer Controller. An example of <cluster_oidc_endpoint> is rh-oidc.s3.us-east-1.amazonaws.com/28292va7ad7mr9r4he1fb09b14t59t4f.

Create an AWS IAM role with the generated trust policy by running the following command:

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

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-operator-controller-manager
PRINCIPAL	arn:aws:iam:<aws_account_number>:oidc-provider/<cluster_oidc_endpoint>

where:

<aws_account_number>: Specifies the ARN for an AWS IAM role for the AWS Load Balancer Controller, such as arn:aws:iam::777777777777:role/albo-controller.

Download the permission policy for the AWS Load Balancer Controller by running the following command:

$ curl -o albo-controller-permission-policy.json https://raw.githubusercontent.com/openshift/aws-load-balancer-operator/main/assets/iam-policy.json

Attach the permission policy for the AWS Load Balancer Controller to an AWS IAM role by running the following command:

$ aws iam put-role-policy --role-name albo-controller --policy-name perms-policy-albo-controller --policy-document file://albo-controller-permission-policy.json

Create a YAML file that defines the AWSLoadBalancerController object:
Example sample-aws-lb-manual-creds.yaml file
```
apiVersion: networking.olm.openshift.io/v1
kind: AWSLoadBalancerController
metadata:
  name: cluster
spec:
  credentialsRequestConfig:
    stsIAMRoleARN: <albc_role_arn>
```
where:

kind

Specifies the AWSLoadBalancerController object.

metatdata.name

Specifies the AWS Load Balancer Controller name. All related resources use this instance name as a suffix.

stsIAMRoleARN

Specifies the ARN role for the AWS Load Balancer Controller. The CredentialsRequest object uses this ARN role to provision the AWS credentials. An example of <albc_role_arn> is arn:aws:iam::777777777777:role/albo-controller.

Additional resources

Configuring the Cloud Credential Operator utility