docs: link prerequisistes, install and tutorial docs without overlapping

openshift · Oct 23, 2023 · 6f8f180 · 6f8f180
1 parent 7d6ff40
commit 6f8f180
Show file tree

Hide file tree

Showing 4 changed files with 73 additions and 119 deletions.
diff --git a/README.md b/README.md
@@ -79,7 +79,7 @@ make test-e2e
 
 **Prerequisistes**:
 - The operator has to be deployed with [the prerequisites for the STS cluster](./docs/prerequisites.md#iam-role-for-sts-clusters).
-- The controller's IAM role needs to be created as described in [the installation instructions for the STS cluster](./docs/install.md#post-operator-installation).
+- The controller's IAM role needs to be created as described in [the installation instructions for the STS cluster](./docs/install.md#post-operator-installation-on-sts-cluster).
 - The test WAFv2 and WAF regional WebACLs need to be created. You can use the following commands:
 ```bash
 aws wafv2 create-web-acl --name "echoserver-acl" --scope REGIONAL --default-action '{"Block":{}}'  --visibility-config '{"MetricName":"echoserver","CloudWatchMetricsEnabled": false,"SampledRequestsEnabled":false}'

diff --git a/docs/install.md b/docs/install.md
@@ -3,15 +3,56 @@
 This document provides the necessary installation and post-installation steps to ensure the operator can function correctly.
 
 - [STS Clusters](#sts-clusters)
-    - [Post operator installation](#post-operator-installation)
+    - [Operator installation on STS cluster](#operator-installation-on-sts-cluster)
+    - [Post operator installation on STS cluster](#post-operator-installation-on-sts-cluster)
         - [Option 1. Using ccoctl](#option-1-using-ccoctl)
         - [Option 2. Using the AWS CLI](#option-2-using-the-aws-cli)
 
-## STS Clusters
-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.
+## STS clusters
 
-### Post operator installation
+The **aws-load-balancer-operator** relies on the **cloud-credential-operator** to provision the secrets for itself and for the operated controller. For this `CredentialsRequest` instances are created by **aws-load-balancer-operator**.
+
+### Operator installation on STS cluster
+
+In an STS cluster, the `CredentialsRequest` needs to be set with the IAM role which needs to be [provisioned manually](prerequsites.md#iam-role-for-sts-clusters).
+
+The operator can be installed using [the OperatorHub web UI](https://docs.openshift.com/container-platform/latest/operators/understanding/olm-understanding-operatorhub.html) or by running the following commands:
+
+    ```bash
+    $ oc new-project aws-load-balancer-operator
+
+    $ 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
+
+    $ 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: "${ROLEARN}"
+    EOF
+    ```
+
+The **aws-load-balancer-operator** will wait until the required secret is created before moving to the available state.
+
+### Post operator installation on STS cluster
+In an STS cluster, the `CredentialsRequest` needs to be set with the IAM role which needs to be provisioned manually.
 
 There are two options for creating the controller's IAM role:
 1. Using [`ccoctl`](https://docs.openshift.com/container-platform/latest/authentication/managing_cloud_provider_credentials/cco-mode-sts.html#cco-ccoctl-configuring_cco-mode-sts) and a pre-defined `CredentialsRequest`.
@@ -51,28 +92,7 @@ Its contents are identical to the ones requested by **aws-load-balancer-operator
     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 the [credentialsRequestConfig.stsIAMRoleARN](./tutorial.md#credentialsrequestconfigstsiamrolearn) field:
-
-    ```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:
-
-    ```bash
-    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
-    ```
+4. Create a controller instance with the role IAM set in the [credentialsRequestConfig.stsIAMRoleARN](./tutorial.md#credentialsrequestconfigstsiamrolearn) field.
 
 #### Option 2. Using the AWS CLI
 
@@ -117,25 +137,4 @@ Its contents are identical to the ones requested by **aws-load-balancer-operator
     aws iam put-role-policy --role-name albo-controller --policy-name perms-policy-albo-controller --policy-document file://albo-controller-permission-policy.json
     ```
 
-4. Create a controller instance with the role IAM set in the [credentialsRequestConfig.stsIAMRoleARN](./tutorial.md#credentialsrequestconfigstsiamrolearn) field:
-
-    ```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:
-
-    ```bash
-    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
-    ```
+4. Create a controller instance with the role IAM set in the [credentialsRequestConfig.stsIAMRoleARN](./tutorial.md#credentialsrequestconfigstsiamrolearn) field.
diff --git a/docs/prerequisites.md b/docs/prerequisites.md
@@ -12,7 +12,7 @@ In certain scenarios, the operator requires extra steps to be executed before it
         - [Private subnets](#private-subnets)
 
 ## IAM Role for STS clusters
-An additional IAM Role is needed for the operator to be successfully installed in STS clusters. It is needed to interact with subnets and VPCs.
+An additional IAM Role is needed for the operator to be [successfully installed in STS clusters](install.md#operator-installation-on-sts-cluster). It is needed to interact with subnets and VPCs.
 The operator will generate a `CredentialsRequest` with this role to self bootstrap with AWS credentials.
 
 There are two options for creating the operator's IAM role:
@@ -52,39 +52,6 @@ The operator's `CredentialsRequest` is maintained in [hack/](../hack/) directory
     arn:aws:iam::777777777777:role/<name>-aws-load-balancer-operator-aws-load-balancer-operator
     ```
 
-4. Install the operator using the OpenShift OperatorHub web UI or by running the following commands:
-
-    ```bash
-    $ oc create namespace aws-load-balancer-operator
-
-    $ 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
-
-    $ 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: "${ROLEARN}"
-    EOF
-    ```
-
 ### Option 2. Using the AWS CLI
 
 1. Generate a trusted policy file using your identity provider (e.g. OpenID Connect):
@@ -128,39 +95,6 @@ The operator's `CredentialsRequest` is maintained in [hack/](../hack/) directory
     aws iam put-role-policy --role-name albo-operator --policy-name perms-policy-albo-operator --policy-document file://albo-operator-permission-policy.json
     ```
 
-4. Install the operator using the OpenShift OperatorHub web UI or by running the following commands:
-
-    ```bash
-    $ oc create namespace aws-load-balancer-operator
-
-    $ 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
-
-    $ 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: "${ROLEARN}"
-    EOF
-    ```
-
 ## VPC and Subnets
 
 The **aws-load-balancer-operator** requires specific tags on some AWS

diff --git a/docs/tutorial.md b/docs/tutorial.md
@@ -105,11 +105,32 @@ 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.
 
+```yaml
+apiVersion: networking.olm.openshift.io/v1
+kind: AWSLoadBalancerController
+metadata:
+  name: cluster
+spec:
+  credentials:
+    name: controller-aws-creds
+```
+
 ### 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.
+This field can be used to specify the IAM role be set in `CredentialsRequest` created for the controller. While this field can be specified on both STS and non-STS clusters, its effect is relevant only for STS clusters.
+The operator will wait until the secret is provisioned by the Cloud Credentials Operator before spawning the controller pod.
+The secret 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.
 
+```yaml
+apiVersion: networking.olm.openshift.io/v1
+kind: AWSLoadBalancerController
+metadata:
+  name: cluster
+spec:
+  credentialsRequestConfig:
+    stsIAMRoleARN: "arn:aws:iam::777777777777:role/albo-controller"
+```
+
 ## Creating an Ingress
 
 Once the controller is running an ALB backed Ingress can be created. The