Installing AWS Load Balancer Operator on a Security Token Service cluster

You can install the AWS Load Balancer (ALB) Operator on a Security Token Service (STS) cluster.

The ALB Operator relies on a CredentialsRequest to bootstrap the Operator and for the AWSLoadBalancerController instance. The ALB Operator waits until the required secrets are created and available.

Creating an IAM role for the AWS Load Balancer Operator

An additional IAM role is required to successfully install the ALB Operator on a Security Token Service (STS) cluster. The IAM role is required to interact with subnets and Virtual Private Clouds (VPCs). The Operator generates a CredentialsRequest with this role to bootstrap itself.

There are two options for creating the IAM role:

  • Using ccoctl and a predefined CredentialsRequest.

  • Using the AWS CLI and predefined AWS manifests.

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

Using ccoctl to create an IAM role for the Operator

You can use the ccoctl binary to create an IAM role for the AWS Load Balancer (ALB) Operator. The created IAM role is used to interact with subnets and Virtual Private Clouds (VPCs).

Prerequisites

  • You must extract and prepare the ccoctl binary.

Procedure

  1. Download the CredentialsRequest custom resource (CR) of the ALB Operator and create a directory to store it in by running the following command:

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

  2. Use ccoctl to create an IAM role by running the following command:

    1. $ ccoctl aws create-iam-roles \
    2.     --name <name> \
    3.     --region=<aws_region> \
    4.     --credentials-requests-dir=<credrequests-dir> \
    5.     --identity-provider-arn <oidc-arn>

    Example output

    1. 2023/09/12 11:38:57 Role arn:aws:iam::777777777777:role/<name>-aws-load-balancer-operator-aws-load-balancer-operator created (1)
    2. 2023/09/12 11:38:57 Saved credentials configuration to: /home/user/<credrequests-dir>/manifests/aws-load-balancer-operator-aws-load-balancer-operator-credentials.yaml
    3. 2023/09/12 11:38:58 Updated Role policy for Role <name>-aws-load-balancer-operator-aws-load-balancer-operator created
    1Note the ARN of the created IAM role.

    The length of the role name must be less than or equal to 12 characters.

Using the AWS CLI to create an IAM role for the Operator

You can use the aws command line interface to create an IAM role for the AWS Load Balancer (ALB) Operator. The created IAM role is used to interact with subnets and Virtual Private Clouds (VPCs).

Prerequisites

  • You must have access to the aws command line interface.

Procedure

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

    1. $ cat <<EOF > albo-operator-trust-policy.json
    2. {
    3.     "Version": "2012-10-17",
    4.     "Statement": [
    5.         {
    6.             "Effect": "Allow",
    7.             "Principal": {
    8.                 "Federated": "arn:aws:iam::777777777777:oidc-provider/<oidc-provider-id>" (1)
    9.             },
    10.             "Action": "sts:AssumeRoleWithWebIdentity",
    11.             "Condition": {
    12.                 "StringEquals": {
    13.                     "<oidc-provider-id>:sub": "system:serviceaccount:aws-load-balancer-operator:aws-load-balancer-operator-controller-manager" (2)
    14.                 }
    15.             }
    16.         }
    17.     ]
    18. }
    19. EOF
    1Specifies the ARN of the identity provider.
    2Specifies the service account for the Operator.

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

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

    Example output

    1. ROLE    arn:aws:iam::777777777777:role/albo-operator    2023-08-02T12:13:22Z (1)
    2. ASSUMEROLEPOLICYDOCUMENT    2012-10-17
    3. STATEMENT    sts:AssumeRoleWithWebIdentity    Allow
    4. STRINGEQUALS    system:serviceaccount:aws-load-balancer-operator:aws-load-balancer-controller-manager
    5. PRINCIPAL    arn:aws:iam:777777777777:oidc-provider/<oidc-provider-id>
    1Note the ARN of the created IAM role.

  3. Download the permission policy for the ALB Operator by running the following command:

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

  4. Attach the permission policy for the AWSLoadBalancerController to the IAM role by running the following command:

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

Specifying the role ARN for the ALB Operator on an STS cluster

The role Amazon Resource Name (ARN) needs to be passed to the AWS Load Balancer (ALB) Operator as an environment variable. You can use the dedicated input box in the OperatorHub web UI or specify it in the Subscription resource when installing the Operator by using the OpenShift CLI.

Prerequisites

  • You have installed the OpenShift CLI (oc).

Procedure

  1. Create the aws-load-balancer-operator project by running the following command:

    1. $ oc new-project aws-load-balancer-operator

  2. Create an OperatorGroup for the ALB Operator by running the following command:

    1. $ cat <<EOF | oc apply -f -
    2. apiVersion: operators.coreos.com/v1
    3. kind: OperatorGroup
    4. metadata:
    5.   name: aws-load-balancer-operator
    6.   namespace: aws-load-balancer-operator
    7. spec:
    8.   targetNamespaces: []
    9. EOF

  3. Create a Subscription object for the ALB Operator with the role ARN by running the following command:

    1. $ cat <<EOF | oc apply -f -
    2. apiVersion: operators.coreos.com/v1alpha1
    3. kind: Subscription
    4. metadata:
    5.   name: aws-load-balancer-operator
    6.   namespace: aws-load-balancer-operator
    7. spec:
    8.   channel: stable-v1
    9.   name: aws-load-balancer-operator
    10.   source: redhat-operators
    11.   sourceNamespace: openshift-marketplace
    12.   config:
    13.     env:
    14.     - name: ROLEARN
    15.       value: "<role-arn>" (1)
    16. EOF
    1Specifies the role ARN to be used in the CredentialsRequest to provision the AWS credentials for the Operator.

    The ALB Operator waits until the creation of the required secret before moving to the available state.

Creating an IAM role for the AWS Load Balancer Controller

The CredentialsRequest for the AWS Load Balancer Controller must be set with a manually provisioned IAM role.

There are two options for creating the IAM role:

  • Using ccoctl and a predefined CredentialsRequest.

  • Using the AWS CLI and predefined AWS manifests.

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

Using ccoctl to create an IAM role for the Controller

You can use the ccoctl binary to create an IAM role for the AWSLoadBalancerController. The created IAM role is used to interact with subnets and Virtual Private Clouds (VPCs).

Prerequisites

  • You must extract and prepare the ccoctl binary.

Procedure

  1. Download the CredentialsRequest custom resource (CR) of the AWS Load Balancer Operator and create a directory to store it in by running the following command:

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

  2. Use ccoctl to create an IAM role by running the following command:

    1. $ ccoctl aws create-iam-roles \
    2.     --name <name> \
    3.     --region=<aws_region> \
    4.     --credentials-requests-dir=<credrequests-dir> \
    5.     --identity-provider-arn <oidc-arn>

    Example output

    1. 2023/09/12 11:38:57 Role arn:aws:iam::777777777777:role/<name>-aws-load-balancer-operator-aws-load-balancer-controller created (1)
    2. 2023/09/12 11:38:57 Saved credentials configuration to: /home/user/<credrequests-dir>/manifests/aws-load-balancer-operator-aws-load-balancer-controller-credentials.yaml
    3. 2023/09/12 11:38:58 Updated Role policy for Role <name>-aws-load-balancer-operator-aws-load-balancer-controller created
    1Note the ARN of the created IAM role.

    The length of the role name must be less than or equal to 12 characters.

Using the AWS CLI to create an IAM role for the Controller

You can use the aws command line interface to create an IAM role for the AWSLoadBalancerController. The created IAM role is used to interact with subnets and Virtual Private Clouds (VPCs).

Prerequisites

  • You must have access to the aws command line interface.

Procedure

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

    1. $ cat <<EOF > albo-controller-trust-policy.json
    2. {
    3.     "Version": "2012-10-17",
    4.     "Statement": [
    5.         {
    6.             "Effect": "Allow",
    7.             "Principal": {
    8.                 "Federated": "arn:aws:iam::777777777777:oidc-provider/<oidc-provider-id>" (1)
    9.             },
    10.             "Action": "sts:AssumeRoleWithWebIdentity",
    11.             "Condition": {
    12.                 "StringEquals": {
    13.                     "<oidc-provider-id>:sub": "system:serviceaccount:aws-load-balancer-operator:aws-load-balancer-controller-cluster" (2)
    14.                 }
    15.             }
    16.         }
    17.     ]
    18. }
    19. EOF
    1Specifies the ARN of the identity provider.
    2Specifies the service account for the AWSLoadBalancerController.

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

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

    Example output

    1. ROLE    arn:aws:iam::777777777777:role/albo-controller    2023-08-02T12:13:22Z (1)
    2. ASSUMEROLEPOLICYDOCUMENT    2012-10-17
    3. STATEMENT    sts:AssumeRoleWithWebIdentity    Allow
    4. STRINGEQUALS    system:serviceaccount:aws-load-balancer-operator:aws-load-balancer-controller-cluster
    5. PRINCIPAL    arn:aws:iam:777777777777:oidc-provider/<oidc-provider-id>
    1Note the ARN of the created IAM role.

  3. Download the permission policy for the AWSLoadBalancerController by running the following command:

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

  4. Attach the permission policy for the AWSLoadBalancerController to the IAM role by running the following command:

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

  5. Create an AWSLoadBalancerController resource file named example-sts-iam-role.yaml with contents such as the following example:

    1. apiVersion: networking.olm.openshift.io/v1
    2. kind: AWSLoadBalancerController (1)
    3. metadata:
    4.   name: cluster (2)
    5. spec:
    6.   credentialsRequestConfig:
    7.     stsIAMRoleARN: <role-arn> (3)
    1Defines the AWSLoadBalancerController resource.
    2Defines the instance name for the AWSLoadBalancerController. All related resources use this instance name as a suffix.
    3Specifies the role ARN to be used in a CredentialsRequest to provision the AWS credentials for the controller.

Additional resources