Merge pull request #4886 from muraee/rosa-docs

📖 ROSA: Update docs

Author: k8s-ci-robot

docs/book/src/SUMMARY_PREFIX.md

@@ -24,6 +24,8 @@
   - [ROSA Support](./topics/rosa/index.md)
     - [Enabling ROSA Support](./topics/rosa/enabling.md)
     - [Creating a cluster](./topics/rosa/creating-a-cluster.md)
+    - [Creating MachinePools](./topics/rosa/creating-rosa-machinepools.md)
+    - [Upgrades](./topics/rosa/upgrades.md)
   - [Bring Your Own AWS Infrastructure](./topics/bring-your-own-aws-infrastructure.md)
   - [Specifying the IAM Role to use for Management Components](./topics/specify-management-iam-role.md)
   - [Using external cloud provider with EBS CSI driver](./topics/external-cloud-provider-with-ebs-csi-driver.md)

docs/book/src/topics/rosa/creating-a-cluster.md

@@ -37,7 +37,6 @@ Once Step 3 is done, you will be ready to proceed with creating a ROSA cluster u
 1. Prepare the environment:
     ```bash
     export OPENSHIFT_VERSION="4.14.5"
-    export CLUSTER_NAME="capi-rosa-quickstart"
     export AWS_REGION="us-west-2"
     export AWS_AVAILABILITY_ZONE="us-west-2a"
     export AWS_ACCOUNT_ID="<account_id"
@@ -54,11 +53,10 @@ Once Step 3 is done, you will be ready to proceed with creating a ROSA cluster u
 
 1. Render the cluster manifest using the ROSA cluster template:
     ```shell
-    cat templates/cluster-template-rosa.yaml | envsubst > rosa-capi-cluster.yaml
+    clusterctl generate cluster <cluster-name> --from templates/cluster-template-rosa.yaml > rosa-capi-cluster.yaml
     ```
 
 1. If a credentials secret was created earlier, edit `ROSAControlPlane` to refernce it:
-
     ```yaml
     apiVersion: controlplane.cluster.x-k8s.io/v1beta2
     kind: ROSAControlPlane
@@ -70,7 +68,34 @@ Once Step 3 is done, you will be ready to proceed with creating a ROSA cluster u
     ...
     ```
 
+1. Provide an AWS identity reference  
+    ```yaml
+    apiVersion: controlplane.cluster.x-k8s.io/v1beta2
+    kind: ROSAControlPlane
+    metadata:
+      name: "capi-rosa-quickstart-control-plane"
+    spec:
+      identityRef:
+        kind: <IdentityType>
+        name: <IdentityName>
+    ...
+    ```
+
+    Otherwise, make sure the following `AWSClusterControllerIdentity` singleton exists in your managment cluster:
+    ```yaml
+    apiVersion: infrastructure.cluster.x-k8s.io/v1beta2
+    kind: AWSClusterControllerIdentity
+    metadata:
+      name: "default"
+    spec:
+      allowedNamespaces: {}  # matches all namespaces
+    ```
+
+    see [Multi-tenancy](../multitenancy.md) for more details
+
 1. Finally apply the manifest to create your Rosa cluster:
     ```shell
     kubectl apply -f rosa-capi-cluster.yaml
     ```
+
+see [ROSAControlPlane CRD Reference](https://cluster-api-aws.sigs.k8s.io/crd/#controlplane.cluster.x-k8s.io/v1beta2.ROSAControlPlane) for all possible configurations.

docs/book/src/topics/rosa/creating-rosa-machinepools.md

@@ -0,0 +1,49 @@
+# Creating MachinePools
+
+Cluster API Provider AWS (CAPA) has experimental support for managed ROSA MachinePools through the infrastructure type `ROSAMachinePool`. A `ROSAMachinePool` is responsible for orchestrating and bootstraping a group of EC2 machines into kubernetes nodes.
+
+### Using `clusterctl` to deploy
+
+To deploy a MachinePool / ROSAMachinePool via `clusterctl generate` use the template located [here](https://github.com/kubernetes-sigs/cluster-api-provider-aws/blob/main/templates/cluster-template-rosa-machinepool.yaml).
+
+Make sure to set up your environment as described [here](./creating-a-cluster.md#creating-the-cluster).
+
+```shell
+clusterctl generate cluster my-cluster --from templates/cluster-template-rosa-machinepool > my-cluster.yaml
+```
+
+## Example
+
+Below is an example of the resources needed to create a ROSA MachinePool.
+
+```yaml
+---
+apiVersion: cluster.x-k8s.io/v1beta1
+kind: MachinePool
+metadata:
+  name: "${CLUSTER_NAME}-pool-0"
+spec:
+  clusterName: "${CLUSTER_NAME}"
+  replicas: 1
+  template:
+    spec:
+      clusterName: "${CLUSTER_NAME}"
+      bootstrap:
+        dataSecretName: ""
+      infrastructureRef:
+        name: "${CLUSTER_NAME}-pool-0"
+        apiVersion: infrastructure.cluster.x-k8s.io/v1beta2
+        kind: ROSAMachinePool
+---
+apiVersion: infrastructure.cluster.x-k8s.io/v1beta2
+kind: ROSAMachinePool
+metadata:
+  name: "${CLUSTER_NAME}-pool-0"
+spec:
+  nodePoolName: "nodepool-0"
+  instanceType: "m5.xlarge"
+  subnet: "${PRIVATE_SUBNET_ID}"
+  version: "${OPENSHIFT_VERSION}"
+```
+
+see [ROSAMachinePool CRD Reference](https://cluster-api-aws.sigs.k8s.io/crd/#infrastructure.cluster.x-k8s.io/v1beta2.ROSAMachinePool) for all possible configurations.

docs/book/src/topics/rosa/enabling.md

@@ -1,7 +1,8 @@
 # Enabling ROSA Support
 
-To enable support for ROSA clusters, the ROSA feature flag must be set to true. This can be done using the **EXP_ROSA** environment variable:
+To enable support for ROSA clusters, the ROSA feature flag must be set to true. This can be done using the **EXP_ROSA** environment variable.
 
+Make sure to set up your AWS environment first as described [here](https://cluster-api.sigs.k8s.io/user/quick-start.html).
 ```shell
 export EXP_ROSA="true"
 export EXP_MACHINE_POOL="true"

docs/book/src/topics/rosa/index.md

@@ -19,4 +19,6 @@ A new template is available in the templates folder for creating a managed ROSA
 ## SEE ALSO
 
 * [Enabling ROSA Support](enabling.md)
-* [Creating a cluster](creating-a-cluster.md)
+* [Creating a cluster](creating-a-cluster.md)
+* [Creating MachinePools](creating-rosa-machinepools.md)
+* [Upgrades](upgrades.md)

docs/book/src/topics/rosa/upgrades.md

@@ -0,0 +1,15 @@
+# Upgrades
+
+## Control Plane Upgrade
+
+Upgrading the OpenShift version of the control plane is supported by the provider. To perform an upgrade you need to update the `version` in the spec of the `ROSAControlPlane`. Once the version has changed the provider will handle the upgrade for you.
+
+The Upgrade state can be checked in the conditions under `ROSAControlPlane.status`.
+
+## MachinePool Upgrade
+
+Upgrading the OpenShift version of the MachinePools is supported by the provider and can be performed independetly from the Control Plane upgrades. To perform an upgrade you need to update the `version` in the spec of the `ROSAMachinePool`. Once the version has changed the provider will handle the upgrade for you.
+
+The Upgrade state can be checked in the conditions under `ROSAMachinePool.status`.
+
+The version of the MachinePool can't be greater than Control Plane version.

templates/cluster-template-rosa-machinepool.yaml

@@ -27,7 +27,7 @@ kind: ROSAControlPlane
 metadata:
   name: "${CLUSTER_NAME}-control-plane"
 spec:
-  rosaClusterName: ${CLUSTER_NAME:0:15}
+  rosaClusterName: ${CLUSTER_NAME:0:54}
   version: "${OPENSHIFT_VERSION}"
   region: "${AWS_REGION}"
   network:
@@ -43,7 +43,7 @@ spec:
     kmsProviderARN: "arn:aws:iam::${AWS_ACCOUNT_ID}:role/${OPERATOR_ROLES_PREFIX}-kube-system-kms-provider"
   oidcID: "${OIDC_CONFIG_ID}"
   subnets:
-    - "${PUBLIC_SUBNET_ID}"
+    - "${PUBLIC_SUBNET_ID}" # remove if creating a private cluster
     - "${PRIVATE_SUBNET_ID}"
   availabilityZones:
     - "${AWS_AVAILABILITY_ZONE}"
@@ -77,5 +77,3 @@ spec:
   instanceType: "m5.xlarge"
   subnet: "${PRIVATE_SUBNET_ID}"
   version: "${OPENSHIFT_VERSION}"
-
-

templates/cluster-template-rosa.yaml

@@ -27,7 +27,7 @@ kind: ROSAControlPlane
 metadata:
   name: "${CLUSTER_NAME}-control-plane"
 spec:
-  rosaClusterName: ${CLUSTER_NAME:0:15}
+  rosaClusterName: ${CLUSTER_NAME:0:54}
   version: "${OPENSHIFT_VERSION}"
   region: "${AWS_REGION}"
   network:
@@ -43,7 +43,7 @@ spec:
     kmsProviderARN: "arn:aws:iam::${AWS_ACCOUNT_ID}:role/${OPERATOR_ROLES_PREFIX}-kube-system-kms-provider"
   oidcID: "${OIDC_CONFIG_ID}"
   subnets:
-    - "${PUBLIC_SUBNET_ID}"
+    - "${PUBLIC_SUBNET_ID}" # remove if creating a private cluster
     - "${PRIVATE_SUBNET_ID}"
   availabilityZones:
     - "${AWS_AVAILABILITY_ZONE}"