NE-1381: docs updated

openshift · Oct 19, 2023 · 7548094 · 7548094
1 parent f1a1b7c
commit 7548094
Show file tree

Hide file tree

Showing 4 changed files with 74 additions and 97 deletions.
diff --git a/config/samples/sts-iam-role-v1.yaml b/config/samples/sts-iam-role-v1.yaml
@@ -0,0 +1,7 @@
+apiVersion: networking.olm.openshift.io/v1
+kind: AWSLoadBalancerController
+metadata:
+  name: cluster
+spec:
+  credentialsRequestConfig:
+    stsIAMRoleARN: "arn:aws:iam::999999999999:role/myuser-controller"
diff --git a/docs/install.md b/docs/install.md
@@ -5,64 +5,66 @@ post installation to ensure the operator can function correctly.
 
 - [STS Clusters](#sts-clusters)
     - [Post operator installation](#post-operator-installation)
-        - [Use CredentialsRequest created by the operator](#use-credentialsrequest-created-by-the-operator)
-        - [Use predefined secret](#use-predefined-secret)
-            - [Option 1. Using ccoctl](#option-1-using-ccoctl)
-            - [Option 2. Using the AWS CLI](#option-2-using-the-aws-cli)
+        - [Option 1. Using ccoctl](#option-1-using-ccoctl)
+        - [Option 2. Using the AWS CLI](#option-2-using-the-aws-cli)
 
 ## STS Clusters
-In an STS cluster,  the **cloud-credential-operator** does not automatically provision secrets for `CredentialsRequest`s, 
-so the cluster-admin must provision them manually.
-IAM role and policies must also be provisioned manually.
-
-Normally, the **aws-load-balancer-operator** relies on the **cloud-credential-operator**
-to provision the secret for the operated controller using `CredentialsRequest`. However, in an STS cluster this
-secret needs to be provisioned manually. The **aws-load-balancer-operator** will wait until the required
-secret is created and available before spawning the **aws-load-balancer-controller** pod.
+The **aws-load-balancer-operator** relies on the **cloud-credential-operator**
+to provision the secret for the operated controller using `CredentialsRequest`. In an STS cluster, the `CredentialsRequest` needs to be set with the IAM role which in turn needs to be provisioned manually. The **aws-load-balancer-operator** will wait until the required secret is created and available before spawning the **aws-load-balancer-controller** pod.
 
 ### Post operator installation
 
-There are three ways to manually create the required IAM resources:
-- Using a `CredentialsRequest` generated by the operator for an existing `AWSLoadBalancerController`.
-- Using a pre-defined `CredentialsRequest` before `AWSLoadBalancerController` creation.
-- Using pre-defined AWS manifests before `AWSLoadBalancerController` creation.
+There are two ways to manually create the required IAM role:
+- Using a pre-defined `CredentialsRequest`.
+- Using pre-defined AWS manifests.
 
 For handling `CredentialsRequests`, the cloud credential operator utility, [ccoctl](https://docs.openshift.com/container-platform/latest/authentication/managing_cloud_provider_credentials/cco-mode-sts.html#cco-ccoctl-configuring_cco-mode-sts), can be utilized.
 If you prefer not to use `ccoctl`, or your system doesn't support it, the AWS CLI can be an alternative.
 
-The controller pod will wait for the generated credentials secret if `AWSLoadBalancerController` already exists or it can be configured in the `credentials` field of `AWSLoadBalancerController` before its creation.
-
-#### Use `CredentialsRequest` created by the operator
-
-1. Extract and prepare the `ccoctl` binary as described in [Configuring the Cloud Credential Operator utility](https://docs.openshift.com/container-platform/4.13/authentication/managing_cloud_provider_credentials/cco-mode-sts.html#cco-ccoctl-configuring_cco-mode-sts).
-
-2. For `AWSLoadBalancerController` CR the **aws-load-balancer-operator** creates a `CredentialsRequest` named `aws-load-balancer-controller-cluster` in the `openshift-cloud-credential-operator` namespace. Extract and save the created `CredentialsRequest` in a directory:
+#### Option 1. Using `ccoctl`
+The dedicated controller's `CredentialsRequest` is maintained in [hack/controller](../hack/controller/) directory of this repository.
+Its contents are identical to the ones requested by **aws-load-balancer-operator** from the **cloud-credential-operator**.
 
-    ```bash
-    oc get credentialsrequest -n openshift-cloud-credential-operator  \
-        aws-load-balancer-controller-cluster -o yaml > <path-to-credrequests-dir>/cr.yaml
-    ```
-    Note: currently `AWSLoadBalancerController` CR can only be named `cluster`
+1. [Extract and prepare the `ccoctl` binary](https://docs.openshift.com/container-platform/4.13/authentication/managing_cloud_provider_credentials/cco-mode-sts.html#cco-ccoctl-configuring_cco-mode-sts)
 
-3. Use the `ccoctl` tool to process all `CredentialsRequest` objects from the credrequests directory:
+2. Use the `ccoctl` tool to create a IAM role from the pre-defined controller's `CredentialsRequest`:
 
     ```bash
-    ccoctl aws create-iam-roles \
-        --name <name> --region=<aws_region> \
-        --credentials-requests-dir=<path-to-credrequests-dir> \
-        --identity-provider-arn <oidc-arn>
+   $ curl --create-dirs -o <credrequests-dir>/controller.yaml https://raw.githubusercontent.com/openshift/aws-load-balancer-operator/main/hack/controller/controller-credentials-request.yaml
+   $ CCOCTL_OUTPUT=$(mktemp)
+   $ ROLENAME=<name>
+   $ ccoctl aws create-iam-roles --name ${ROLENAME:0:12} --region=<aws_region> --credentials-requests-dir=<credrequests-dir> --identity-provider-arn <oidc-arn> 2>&1 | tee "${CCOCTL_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/<credrequests-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
     ```
 
     For each `CredentialsRequest` object, `ccoctl` creates an IAM role with a trust
     policy that is tied to the specified OIDC identity provider, and permissions
     policy as defined in each `CredentialsRequest` object. This also generates a set
-    of secrets in a **manifests** directory that is required
-    by the **aws-load-balancer-controller**.
+    of secrets in a `manifests` directory, which are not needed by the controller.
 
-4. Apply the secrets to your cluster:
+3. Extract and verify the controller's role ARN from the output of `ccoctl` command:
 
     ```bash
-    ls manifests/*-credentials.yaml | xargs -I{} oc apply -f {}
+    $ CONTROLLER_ROLEARN=$(grep -Po 'arn:aws:iam[0-9a-z/:\-_]+' "${CCOCTL_OUTPUT}")
+    $ echo "${CONTROLLER_ROLEARN}"
+    arn:aws:iam::777777777777:role/<name>-aws-load-balancer-operator-aws-load-balancer-controller
+    ```
+
+4. Create a controller instance with the role IAM set in [credentialsRequestConfig.stsIAMRoleARN field](./tutorial.md#credentialsrequestconfigstsiamrolearn):
+
+    ```bash
+    $ cat <<EOF | oc apply -f -
+    apiVersion: networking.olm.openshift.io/v1
+    kind: AWSLoadBalancerController
+    metadata:
+      name: cluster
+    spec:
+      credentialsRequestConfig:
+        stsIAMRoleARN: ${CONTROLLER_ROLEARN}
+    EOF
     ```
 
 5. Verify that the corresponding **aws-load-balancer-controller** pod was created:
@@ -74,52 +76,10 @@ The controller pod will wait for the generated credentials secret if `AWSLoadBal
     aws-load-balancer-operator-controller-manager-b55ff68cc-85jzg   2/2     Running   0          3h26m
     ```
 
-#### Use a Predefined Secret
-In some cases, the provisioning of the credentials secret cannot be done by the **cloud-credential-operator**, e.g. ROSA user clusters are forbidden to create `CredentialsRequest`.
-Instead, the secret can be explicitly referenced in the `AWSLoadBalancerController` CR, see [credentials.name field description](./tutorial.md#credentialsname).
-The credentials secret needs to reference a role with all the policies needed by the controller.
-There are two options for creating the credentials secret.  Use Option 1 with `ccoctl`, or Option 2 with the AWS CLI.
-
-##### Option 1. Using `ccoctl`
-The dedicated controller's `CredentialsRequest` is maintained in [hack/controller](../hack/controller/) directory of this repository.
-Its contents are identical to the ones requested by **aws-load-balancer-operator** from the **cloud-credential-operator**.
-
-1. [Extract and prepare the `ccoctl` binary](https://docs.openshift.com/container-platform/4.13/authentication/managing_cloud_provider_credentials/cco-mode-sts.html#cco-ccoctl-configuring_cco-mode-sts)
-
-2. Use the `ccoctl` tool to process the controller's `CredentialsRequest` object:
-
-    ```bash
-    ccoctl aws create-iam-roles \
-        --name <name> --region=<aws_region> \
-        --credentials-requests-dir=hack/controller \
-        --identity-provider-arn <oidc-arn>
-    ```
-
-    For each `CredentialsRequest` object, `ccoctl` creates an IAM role with a trust
-    policy that is tied to the specified OIDC identity provider, and permissions
-    policy as defined in each `CredentialsRequest` object. This also generates a set
-    of secrets in a **manifests** directory that is required
-    by the **aws-load-balancer-controller**.
-
-3. Apply the secrets to your cluster:
-
-    ```bash
-    ls manifests/*-credentials.yaml | xargs -I{} oc apply -f {}
-    ```
-
-4. Verify that the controller's credentials secret is created:
-
-    ```bash
-    oc -n aws-load-balancer-operator get secret aws-load-balancer-controller-cluster -o json | jq -r '.data.credentials' | base64 -d
-    [default]
-    sts_regional_endpoints = regional
-    role_arn = arn:aws:iam::999999999999:role/aws-load-balancer-operator-aws-load-balancer-controller
-    web_identity_token_file = /var/run/secrets/openshift/serviceaccount/token
-    ```
-
-##### Option 2. Using the AWS CLI
+#### Option 2. Using the AWS CLI
 
 1. Generate a trusted policy file using your identity provider (e.g. OpenID Connect):
+
     ```bash
     IDP="<my-oidc-provider-name>"
     IDP_ARN="arn:aws:iam::<my-aws-account>:oidc-provider/${IDP}"
@@ -145,30 +105,39 @@ Its contents are identical to the ones requested by **aws-load-balancer-operator
     ```
 
 2. Create and verify the role with the generated trusted policy:
+
     ```bash
     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 | \grep '^ROLE' | \grep -Po 'arn:aws:iam[0-9a-z/:\-_]+')
-    echo $CONTROLLER_ROLE_ARN
+    CONTROLLER_ROLEARN=$(aws iam get-role --role-name albo-controller | grep '^ROLE' | grep -Po 'arn:aws:iam[0-9a-z/:\-_]+')
+    echo $CONTROLLER_ROLEARN
     ```
 
 3. Attach the controller's permission policy to the role:
+
     ```bash
     curl -o albo-controller-permission-policy.json https://raw.githubusercontent.com/openshift/aws-load-balancer-operator/main/assets/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
     ```
 
-4. Generate the controller's aws credentials:
+4. Create a controller instance with the role IAM set in [credentialsRequestConfig.stsIAMRoleARN field](./tutorial.md#credentialsrequestconfigstsiamrolearn):
+
     ```bash
-    cat <<EOF > 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
+    $ cat <<EOF | oc apply -f -
+    apiVersion: networking.olm.openshift.io/v1
+    kind: AWSLoadBalancerController
+    metadata:
+      name: cluster
+    spec:
+      credentialsRequestConfig:
+        stsIAMRoleARN: ${CONTROLLER_ROLEARN}
     EOF
     ```
-    **Note**: verify the format of the credentials file. Examples can be found in [OCP documentation](https://docs.openshift.com/container-platform/4.13/authentication/managing_cloud_provider_credentials/cco-mode-sts.html#sts-mode-about_cco-mode-sts).
 
-5. Create the controller's credentials secret with the generated aws credentials:
+5. Verify that the corresponding **aws-load-balancer-controller** pod was created:
+
     ```bash
-    oc -n aws-load-balancer-operator create secret generic aws-load-balancer-controller-cluster --from-file=credentials=albo-controller-aws-credentials.cfg
+    oc -n aws-load-balancer-operator get pods
+    NAME                                                            READY   STATUS    RESTARTS   AGE
+    aws-load-balancer-controller-cluster-9b766d6-gg82c              1/1     Running   0          137m
+    aws-load-balancer-operator-controller-manager-b55ff68cc-85jzg   2/2     Running   0          3h26m
     ```
diff --git a/docs/prerequisites.md b/docs/prerequisites.md
@@ -29,12 +29,10 @@ If you prefer not to use `ccoctl`, or your system doesn't support it, the AWS CL
 2. Use the `ccoctl` tool to create a IAM role from the operator's `CredentialsRequest`:
 
     ```bash
-   $ curl --create-dirs -o <path-to-credrequests-dir>/cr.yaml https://raw.githubusercontent.com/openshift/aws-load-balancer-operator/main/hack/operator-credentials-request.yaml
+   $ curl --create-dirs -o <credrequests-dir>/operator.yaml https://raw.githubusercontent.com/openshift/aws-load-balancer-operator/main/hack/operator-credentials-request.yaml
    $ CCOCTL_OUTPUT=$(mktemp)
-   $ ccoctl aws create-iam-roles \
-        --name <name> --region=<aws_region> \
-        --credentials-requests-dir=<path-to-credrequests-dir> \
-        --identity-provider-arn <oidc-arn> 2>&1 | tee "${CCOCTL_OUTPUT}"
+   $ ROLENAME=<name>
+   $ ccoctl aws create-iam-roles --name ${ROLENAME:0:12} --region=<aws_region> --credentials-requests-dir=<credrequests-dir> --identity-provider-arn <oidc-arn> 2>&1 | tee "${CCOCTL_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/<credrequests-dir>/manifests/aws-load-balancer-operator-aws-load-balancer-operator-credentials.yaml

diff --git a/docs/tutorial.md b/docs/tutorial.md
@@ -105,6 +105,9 @@ The secret specified must be created in the namespace where the operator was ins
 see [Cloud Credentials Operator](https://docs.openshift.com/container-platform/4.11/authentication/managing_cloud_provider_credentials/about-cloud-credential-operator.html).   
 The IAM policy required for the controller can be found in [`assets/iam-policy.json`](../assets/iam-policy.json) in this repository.
 
+### credentialsRequestConfig.stsIAMRoleARN
+This field can be used to specify the IAM role to be used in `CredentialsRequest` created for the controller. While it can be specified on both STS and non-STS clusters, its effect is relevant only for STS clusters. The secret provisioned by the Cloud Credentials Operator will be in the STS format, containing the ARN set in this field. Note that the user must create the role, it's not created by the Cloud Credentials Operator. The IAM policy required for the controller can be found in [`assets/iam-policy.json`](../assets/iam-policy.json) in this repository.
+
 ## Creating an Ingress
 
 Once the controller is running an ALB backed Ingress can be created. The