Merge pull request #27 from sunilarjun/main

Porting Community PR 163

versions/next/modules/en/pages/getting-started/cluster-class/intro.adoc

@@ -5,38 +5,37 @@ In this section we cover using *ClusterClass* with {product_name}.
 
 [CAUTION]
 ====
-ClusterClass is an experiment feature of Cluster API. As with any experimental feature it should be used with caution as it may be unreliable. All experimental features are not subject to any compatibility or deprecation promise.
+ClusterClass is an experimental feature of Cluster API. As with any experimental features it should be used with caution as it may be unreliable. All experimental features are not subject to any compatibility or deprecation promise. **It is planned to be graduated with https://github.com/kubernetes-sigs/cluster-api/milestone/38[CAPI v1.9]**.
 ====
 
+[TIP]
+====
+Before using ClusterClass, study the provider docs and confirm that the feature is supported. This documentation includes a matrix in the xref:../../reference-guides/providers/certified.adoc[Certified providers] section with xref:../../reference-guides/providers/certified.adoc#_clusterclass_support_for_certified_providers[cluster topology support status].
+====
 
 == Pre-requisities
 
 To use ClusterClass it needs to be enabled for core Cluster API and any provider that supports it. This is done by setting the `CLUSTER_TOPOLOGY` variable to `true`.
 
-The {product_name} Helm chart will set this variable by default when its installed. However, when enabling additional providers you will have to ensure `CLUSTER_TOPOLGY` is set in the providers secret. For example:
+The {product_name} Helm chart will automatically enable the feature when installing CAPI. However, when enabling additional providers, ensure `CLUSTER_TOPOLOGY` is set in the provider configuration. Turtles' xref:../tasks/capi-operator/capiprovider_resource.adoc[CAPIProvider] resource supports passing installation parameters to the provider via `variables` as follows:
 
 [source,yaml]
 ----
-apiVersion: v1
-kind: Secret
+apiVersion: turtles-capi.cattle.io/v1alpha1
+kind: CAPIProvider
 metadata:
-  name: capd-variables
-  namespace: default
-type: Opaque
-stringData:
-  CLUSTER_TOPOLOGY: "true"
-----
-
-Which can then be referenced from a provider declaration. For example:
-
-[source,yaml]
-----
-apiVersion: operator.cluster.x-k8s.io/v1alpha1
-kind: InfrastructureProvider
-metadata:
-  name: docker
-  namespace: capd-system
+  name: azure
+  namespace: capz-system
 spec:
-  secretName: capd-variables
-  secretNamespace: default
+  type: infrastructure
+  name: azure
+  configSecret:
+    name: azure-variables
+  variables:
+    CLUSTER_TOPOLOGY: "true"
+    EXP_CLUSTER_RESOURCE_SET: "true"
+    EXP_MACHINE_POOL: "true"
+    EXP_AKS_RESOURCE_HEALTH: "true"
 ----
+
+The resource defined in this yaml file will install CAPZ with support for a number of features, including `CLUSTER_TOPOLOGY`.

versions/next/modules/en/pages/getting-started/cluster-class/provision.adoc

@@ -0,0 +1,109 @@
+= Create a workload cluster
+
+This section will guide you through creating a `ClusterClass` which you will then use to provision a workload `Cluster`. The Cluster API book includes a https://cluster-api.sigs.k8s.io/tasks/experimental-features/cluster-class/[ClusterClass section] with detailed information on what is supported and how you can use the powerful abstraction this feature provides, including operations such as https://cluster-api.sigs.k8s.io/tasks/experimental-features/cluster-class/write-clusterclass#clusterclass-with-patches[patching class values] and https://cluster-api.sigs.k8s.io/tasks/experimental-features/cluster-class/operate-cluster[operating a managed cluster]. We recommend you familiarize with the feature to get the most out of it.
+
+[NOTE]
+====
+This guide uses the https://github.com/rancher-sandbox/rancher-turtles-fleet-example/tree/templates[examples repository].
+====
+
+== Providers Guide
+
+=== Prerequisites
+
+- Rancher Manager cluster with Rancher Turtles installed
+- Configure cloud credentials for Azure in Rancher: `Cluster Management` > `Cloud Credentials`.
+    - Keep the name you assign to the new set of credentials.
+- Install the https://github.com/kubernetes-sigs/cluster-api-provider-azure/[CAPI Infrastructure Provider for Azure] using the xref:../tasks/capi-operator/basic_cluster_api_provider_installation.adoc[`CAPIProvider` resource].
+
+[source,yaml]
+----
+apiVersion: v1
+kind: Namespace
+metadata:
+  name: capz-system
+---
+apiVersion: turtles-capi.cattle.io/v1alpha1
+kind: CAPIProvider
+metadata:
+  name: azure
+  namespace: capz-system
+spec:
+  type: infrastructure
+  name: azure
+  credentials:
+      rancherCloudCredential: <rancher-credential-name> # Rancher credentials secret for Azure
+  configSecret:
+      name: azure-variables
+  variables:
+      CLUSTER_TOPOLOGY: "true"
+      EXP_CLUSTER_RESOURCE_SET: "true"
+      EXP_MACHINE_POOL: "true"
+      EXP_AKS_RESOURCE_HEALTH: "true"
+----
+
+=== Create ClusterClass object
+
+The `ClusterClass` object represents a template that defines the shape of the control plane and infrastructure of a cluster. This is the base definition of the `Cluster` object/s that will be created from it. If the template is created optimizing flexibility, we could use it to provision workload clusters supporting variants of the same cluster shape, simplifying the configuration applied to each cluster, as the class removes most of the complexity.
+
+The template we're using in this example will use CAPZ to provision a managed Azure (AKS) cluster. Before applying the yaml file, you will need to export the following environment variables. Remember to adapt the values to your specific scenario as these are just placeholders:
+
+[source,bash]
+----
+export CLUSTER_CLASS_NAME="azure-sample"                      
+export CLUSTER_NAME="azure-aks-cluster"
+export AZURE_LOCATION="northeurope"
+export AZURE_SUBSCRIPTION_ID=<subs-id> # you can use: az account show --query 'id' --output tsv
+export KUBERNETES_VERSION="v1.30.4"
+export AZURE_CLIENT_ID=<app-id>
+export AZURE_TENANT_ID=<tenant-id>
+export AZURE_CLIENT_SECRET=<password>
+----
+
+Using `envsubst` to substitute the exported variables in the original file. 
+
+[source,bash]
+----
+curl -s https://raw.githubusercontent.com/rancher-sandbox/rancher-turtles-fleet-example/templates/capz/cluster-template-aks-clusterclass.yaml | envsubst >> clusterclass1.yaml
+----
+
+This will create a new yaml file `clusterclass1.yaml` that contains the class definition formatted with the exported values. You can study the resulting file before applying it to the cluster.
+
+[source,bash]
+----
+kubectl apply -f clusterclass1.yaml
+----
+
+You can validate that the class has been created successfully and inspect its content via `kubectl`:
+
+[source,bash]
+----
+kubectl get clusterclasses.cluster.x-k8s.io
+kubectl describe clusterclasses.cluster.x-k8s.io <class-name>
+----
+
+=== Provision workload cluster
+
+Now that the class resource is available in the cluster, we can go ahead and create a cluster from this topology. Let's first substitute the variables in the template, as we did before:
+
+[source,bash]
+----
+curl -s https://raw.githubusercontent.com/rancher-sandbox/rancher-turtles-fleet-example/templates/capz/cluster-template-aks-topology.yaml | envsubst >> cluster1.yaml
+----
+
+This will create a new yaml file `cluster1.yaml` that contains the cluster definition formatted with the exported values. You can study the resulting file before applying it to the cluster, which will effectively trigger workload cluster creation.
+
+[source,bash]
+----
+kubectl apply -f cluster1.yaml
+----
+
+Be patient, cluster provisioning will take some time (up to 10min). While you wait for it to become ready, you can go through the `capz-controller-manager` logs, which is responsible for reconciling the cluster resources you just created.
+
+== Enable auto-import into Rancher
+
+As with any other CAPI clusters, you will have to enable auto-import for Turtles to manage importing it into Rancher Manager. Please, refer to xref:../../getting-started/create-first-cluster/using_fleet.adoc#_mark_namespace_for_auto_import[Mark namespace for auto-import] notes to enable auto-import.
+
+== Post provisioning actions
+
+The functionality provided by cluster classes makes it possible for you to deploy as many clusters as desired from the topology you created. This template can be written in a way that makes it flexible enough to be used in as many Clusters as possible by supporting variants of the same base Cluster shape.

versions/next/modules/en/pages/reference-guides/providers/certified.adoc

@@ -60,3 +60,36 @@ This is a list of providers that are in an advanced state of development and wil
 |===
 | Platform | Code Name | Provider Type | Docs
 |===
+
+== ClusterClass Support for Certified Providers
+
+The following is a support matrix for each certified provider and their support of the cluster topology feature:
+
+[tabs]
+======
+CAPZ::
++
+- **Full support** of `ClusterClass`: both managed (AKS) and unmanaged (virtual machines) clusters can be provisioned via topology.
+
+CAPA::
++
+- **Supports** `ClusterClass` when provisioning unmanaged (EC2-based) clusters.
+- **Does not support** `ClusterClass` when provisioning managed (EKS) clusters: this is a work-in-progress.
+
+CAPRKE2::
++
+- **Full support** of `ClusterClass`.
+
+CABPK::
++
+- **Full support** of `ClusterClass`.
+
+CAPV::
++
+- **Full support** of `ClusterClass`.
+
+CAPD::
++
+- **Full support** of `ClusterClass`.
+
+======