Skip to content

Commit

Permalink
extend docs on clusterclass
Browse files Browse the repository at this point in the history 
Signed-off-by: Carlos Salas <[email protected]>
  • Loading branch information
@salasberryfin
salasberryfin committed Oct 11, 2024
1 parent 254ce7f commit cb5fd10
Show file tree
Hide file tree
Showing 3 changed files with 188 additions and 20 deletions.
40 changes: 20 additions & 20 deletions docs/getting-started/cluster-class/intro.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,35 +7,35 @@ sidebar_position: 1
In this section we cover using **ClusterClass** with Rancher Turtles.

:::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 [CAPI v1.9](https://github.com/kubernetes-sigs/cluster-api/milestone/38)**.
:::

## 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 Rancher Turtles 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 Turtles 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' [CAPIProvider](../../tasks/capi-operator/capiprovider_resource.md) resource supports passing installation parameters to the provider via `variables` as follows:

```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"
name: azure
namespace: capz-system
spec:
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"
```
Which can then be referenced from a provider declaration. For example:
The resource defined in this yaml file will install CAPZ with support for a number of features, including `CLUSTER_TOPOLOGY`.

```yaml
apiVersion: operator.cluster.x-k8s.io/v1alpha1
kind: InfrastructureProvider
metadata:
name: docker
namespace: capd-system
spec:
secretName: capd-variables
secretNamespace: default
```
:::tip
Before using ClusterClass, study the provider docs and confirm that the feature is supported. This documentation includes a matrix in the [Certified providers](../../reference-guides/providers/certified.md) section with [cluster topology support status](../../reference-guides/providers/certified.md#clusterclass-support-for-certified-providers).
:::
140 changes: 140 additions & 0 deletions docs/getting-started/cluster-class/provision.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,140 @@
---
sidebar_position: 1
---
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# 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 [ClusterClass section](https://cluster-api.sigs.k8s.io/tasks/experimental-features/cluster-class/) with detailed information on what is supported and how you can use the powerful abstraction this feature provides, including operations such as [patching class values](https://cluster-api.sigs.k8s.io/tasks/experimental-features/cluster-class/write-clusterclass#clusterclass-with-patches) and [operating a managed cluster](https://cluster-api.sigs.k8s.io/tasks/experimental-features/cluster-class/operate-cluster). We recommend you familiarize with the feature to get the most out of it.

:::note
This guide uses the [examples repository](https://github.com/rancher-sandbox/rancher-turtles-fleet-example/tree/templates).
:::

## Providers guide

<Tabs>
<TabItem value="azure-aks" label="CAPZ AKS" default>
## 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 [CAPI Infrastructure Provider for Azure](https://github.com/kubernetes-sigs/cluster-api-provider-azure/) using the [`CAPIProvider` resource](../../tasks/capi-operator/basic_cluster_api_provider_installation.md).
```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"
```
- Install the [Kubeadm bootstrap provider](https://cluster-api.sigs.k8s.io/tasks/bootstrap/kubeadm-bootstrap/) using the [`CAPIProvider` resource](../../tasks/capi-operator/basic_cluster_api_provider_installation.md).
```yaml
---
apiVersion: v1
kind: Namespace
metadata:
name: capi-kubeadm-bootstrap-system
---
apiVersion: turtles-capi.cattle.io/v1alpha1
kind: CAPIProvider
metadata:
name: kubeadm-bootstrap
namespace: capi-kubeadm-bootstrap-system
spec:
name: kubeadm
type: bootstrap
configSecret:
name: variables
---
apiVersion: v1
kind: Namespace
metadata:
name: capi-kubeadm-control-plane-system
---
apiVersion: turtles-capi.cattle.io/v1alpha1
kind: CAPIProvider
metadata:
name: kubeadm-control-plane
namespace: capi-kubeadm-control-plane-system
spec:
name: kubeadm
type: controlPlane
configSecret:
name: variables
```
## 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:
```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.

```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.

```bash
kubectl apply -f clusterclass1.yaml
```

You can validate that the class has been created successfully and inspect its content via `kubectl`:

```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:

```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.

```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.

</TabItem>

</Tabs>

## 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 [Mark namespace for auto-import](../../getting-started/create-first-cluster/using_fleet#mark-namespace-for-auto-import).

## Post provisioning actions
The functionality provided by cluster classes make 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.
28 changes: 28 additions & 0 deletions docs/reference-guides/providers/certified.md
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,8 @@
---
sidebar_position: 1
---
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Certified CAPI Providers

Expand Down Expand Up @@ -33,3 +35,29 @@ This is a list of providers that are in an advanced state of development and wil
| Platform | Code Name | Provider Type | Docs |
|-----------------|--------------------------------|--------------------------|--------------------------|
| **Elemental** | elemental | Infrastructure | https://github.com/rancher-sandbox/cluster-api-provider-elemental |

## ClusterClass support for certified providers

The following is a support matrix for each certified provider and their support of the cluster topology feature:

<Tabs>
<TabItem value="azure" label="CAPZ">
- **Full support** of `ClusterClass`: both managed (AKS) and unmanaged (virtual machines) clusters can be provisioned via topology.
</TabItem>
<TabItem value="aws" label="CAPA" default>
- **Supports** `ClusterClass` when provisioning unmanaged (EC2-based) clusters.
- **Does not support** `ClusterClass` when provisioning managed (EKS) clusters: this is a work-in-progress.
</TabItem>
<TabItem value="rke2" label="CAPRKE2" default>
- **Full support** of `ClusterClass`.
</TabItem>
<TabItem value="kubeadm" label="CABPK" default>
- **Full support** of `ClusterClass`.
</TabItem>
<TabItem value="vsphere" label="CAPV" default>
- **Full support** of `ClusterClass`.
</TabItem>
<TabItem value="docker" label="CAPD" default>
- **Full support** of `ClusterClass`.
</TabItem>
</Tabs>

0 comments on commit cb5fd10

Please sign in to comment.