Skip to content

extend docs on clusterclass #163

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Oct 17, 2024
Merged

extend docs on clusterclass #163

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 21 additions & 21 deletions docs/getting-started/cluster-class/intro.md
View file
Open in desktop
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)**.
:::

:::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).
:::

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

```yaml
apiVersion: v1
kind: Secret
metadata:
name: capd-variables
namespace: default
type: Opaque
stringData:
CLUSTER_TOPOLOGY: "true"
```

Which can then be referenced from a provider declaration. 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: operator.cluster.x-k8s.io/v1alpha1
kind: InfrastructureProvider
apiVersion: turtles-capi.cattle.io/v1alpha1
kind: CAPIProvider
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`.
109 changes: 109 additions & 0 deletions docs/getting-started/cluster-class/provision.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,109 @@
---
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"
```
## 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) 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.
28 changes: 28 additions & 0 deletions docs/reference-guides/providers/certified.md
View file
Open in desktop
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>
Loading