Skip to content
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

Simplify CAPIProvider example and replace clusterctl mentions #168

Merged
merged 3 commits into from
Oct 25, 2024
Merged

Simplify CAPIProvider example and replace clusterctl mentions #168

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
58c04e1
Simplify CAPIProvider setup guide
Danil-Grigorev Oct 25, 2024
50d2caf
Remove clusterctl in favor of envsubst + curl
Danil-Grigorev Oct 25, 2024
7c8c922
Update docs/reference-guides/providers/howto.md
Danil-Grigorev Oct 25, 2024
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
18 changes: 4 additions & 14 deletions docs/getting-started/cluster-class/provision.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,24 +34,14 @@ This guide uses the [examples repository](https://github.com/rancher-sandbox/ran
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_CLASS_NAME="azure-sample"
export CLUSTER_NAME="azure-aks-cluster"
export AZURE_LOCATION="northeurope"
export AZURE_NODE_MACHINE_TYPE="Standard_D2s_v3"
Expand All @@ -62,10 +52,10 @@ This guide uses the [examples repository](https://github.com/rancher-sandbox/ran
export AZURE_CLIENT_SECRET=<password>
```

Using `envsubst` to substitute the exported variables in the original file.
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
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.
Expand All @@ -86,7 +76,7 @@ This guide uses the [examples repository](https://github.com/rancher-sandbox/ran
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
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.
Expand Down
10 changes: 4 additions & 6 deletions docs/getting-started/create-first-cluster/using_fleet.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,13 +10,12 @@ This section will guide you through creating your first cluster and importing it

- Rancher Manager cluster with Rancher Turtles installed
- Cluster API providers installed for your scenario - we'll be using the [Docker infrastructure](https://github.com/kubernetes-sigs/cluster-api/tree/main/test/infrastructure/docker) and [RKE2 bootstrap/control plane](https://github.com/rancher-sandbox/cluster-api-provider-rke2) providers in these instructions - see [Initialization for common providers using Turtles' `CAPIProvider`](../../tasks/capi-operator/capiprovider_resource.md)
- **clusterctl** CLI - see the [releases](https://github.com/kubernetes-sigs/cluster-api/releases)

## Create your cluster definition

The **clusterctl** CLI can be used to generate the YAML for a cluster. When you run `clusterctl generate cluster`, it will connect to the management cluster to see what infrastructure providers have been installed. Also, it will take care of replacing any tokens in the chosen template (a.k.a flavour) with values from environment variables.
The **envsubst** can be used to generate the YAML for a cluster from a template, and substitute environment variables.

Alternatively, you can craft the YAML for your cluster manually. If you decide to do this then you can use the **templates** that infrastructure providers publish as part of their releases. For example, the AWS provider [publishes files](https://github.com/kubernetes-sigs/cluster-api-provider-aws/releases/tag/v2.2.1) prefixed with **cluster-template** that can be used as a base. You will need to replace any tokens yourself or by using clusterctl (e.g. `clusterctl generate cluster test1 --from https://github.com/kubernetes-sigs/cluster-api-provider-aws/releases/download/v2.2.1/cluster-template-eks.yaml > cluster.yaml`).
You can craft the YAML for your cluster manually. If you decide to do this then you can use the **templates** that infrastructure providers publish as part of their releases. For example, the AWS provider [publishes files](https://github.com/kubernetes-sigs/cluster-api-provider-aws/releases/tag/v2.2.1) prefixed with **cluster-template** that can be used as a base. You will need to replace any tokens yourself or by using clusterctl (e.g. `curl -s https://github.com/kubernetes-sigs/cluster-api-provider-aws/releases/download/v2.2.1/cluster-template-eks.yaml | envsubst > cluster.yaml`).

:::tip
To maintain proper resource management and avoid accidental deletion of custom resources managed outside of Helm during Helm operations, include the `helm.sh/resource-policy": keep` annotation in the top-level CAPI kinds within your cluster manifests.
Expand All @@ -31,13 +30,12 @@ To generate the YAML for the cluster do the following (assuming the Docker infra
1. Open a terminal and run the following:

```bash
export CLUSTER_NAME=cluster1
export CONTROL_PLANE_MACHINE_COUNT=1
export WORKER_MACHINE_COUNT=1
export KUBERNETES_VERSION=v1.30.0

clusterctl generate cluster cluster1 \
--from https://raw.githubusercontent.com/rancher-sandbox/rancher-turtles-fleet-example/templates/docker-rke2.yaml \
> cluster1.yaml
curl -s https://raw.githubusercontent.com/rancher-sandbox/rancher-turtles-fleet-example/templates/docker-rke2.yaml | envsubst > cluster1.yaml
```

2. View **cluster1.yaml** to ensure there are no tokens. You can make any changes you want as well.
Expand Down
5 changes: 2 additions & 3 deletions docs/getting-started/create-first-cluster/using_kubectl.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,13 +19,12 @@ To generate the YAML for the cluster, do the following (assuming the Docker infr
1. Open a terminal and run the following:

```bash
export CLUSTER_NAME=cluster1
export CONTROL_PLANE_MACHINE_COUNT=1
export WORKER_MACHINE_COUNT=1
export KUBERNETES_VERSION=v1.30.0

clusterctl generate cluster cluster1 \
--from https://raw.githubusercontent.com/rancher-sandbox/rancher-turtles-fleet-example/templates/docker-rke2.yaml \
> cluster1.yaml
curl -s https://raw.githubusercontent.com/rancher-sandbox/rancher-turtles-fleet-example/templates/docker-rke2.yaml | envsubst > cluster1.yaml
```

2. View **cluster1.yaml** to ensure there are no tokens. You can make any changes you want as well.
Expand Down
19 changes: 8 additions & 11 deletions docs/reference-guides/providers/howto.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,6 +54,7 @@ To generate the YAML for the cluster, do the following:
1. Open a terminal and run the following:

```bash
export CLUSTER_NAME="cluster1"
export CONTROL_PLANE_MACHINE_COUNT=3
export WORKER_MACHINE_COUNT=3
export RKE2_VERSION=v1.30.3+rke2r1
Expand All @@ -63,9 +64,7 @@ export AWS_SSH_KEY_NAME="aws-ssh-key"
export AWS_REGION="aws-region"
export AWS_AMI_ID="ami-id"

clusterctl generate cluster cluster1 \
--from https://github.com/rancher/cluster-api-provider-rke2/blob/main/samples/aws/internal/cluster-template.yaml \
> cluster1.yaml
curl -s https://raw.githubusercontent.com/rancher/cluster-api-provider-rke2/refs/heads/main/examples/aws/cluster-template.yaml | envsubst > cluster1.yaml
```
2. View **cluster1.yaml** and examine the resulting yaml file. You can make any changes you want as well.

Expand All @@ -83,13 +82,12 @@ To generate the YAML for the cluster, do the following:
1. Open a terminal and run the following:

```bash
export CLUSTER_NAME=cluster1
export KUBERNETES_VERSION=v1.30
export AWS_REGION=eu-west-2
export AWS_INSTANCE_TYPE=t3.medium

clusterctl generate cluster cluster1 \
--from https://raw.githubusercontent.com/rancher-sandbox/rancher-turtles-fleet-example/templates/capa.yaml \
> cluster1.yaml
curl -s https://raw.githubusercontent.com/rancher-sandbox/rancher-turtles-fleet-example/templates/capa.yaml | envsubst > cluster1.yaml
```
2. View **cluster1.yaml** to ensure there are no tokens (i.e. SSH keys or cloud credentials). You can make any changes you want as well.

Expand All @@ -107,13 +105,12 @@ To generate the YAML for the cluster, do the following:
1. Open a terminal and run the following:

```bash
export CLUSTER_NAME=cluster1
export CONTROL_PLANE_MACHINE_COUNT=1
export WORKER_MACHINE_COUNT=1
export KUBERNETES_VERSION=v1.30.0

clusterctl generate cluster cluster1 \
--from https://raw.githubusercontent.com/rancher-sandbox/rancher-turtles-fleet-example/templates/docker-kubeadm.yaml \
> cluster1.yaml
curl -s https://raw.githubusercontent.com/rancher-sandbox/rancher-turtles-fleet-example/templates/docker-kubeadm.yaml | envsubst > cluster1.yaml
```

2. View **cluster1.yaml** to ensure there are no tokens. You can make any changes you want as well.
Expand All @@ -129,9 +126,9 @@ kubectl create -f cluster1.yaml
</Tabs>

:::tip
After your cluster is provisioned, you can check functionality of the workload cluster using `clusterctl`:
After your cluster is provisioned, you can check functionality of the workload cluster using `kubectl`:
```bash
clusterctl describe cluster cluster1
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Wow, this was an ugly one. Good catch!

kubectl describe cluster cluster1
```

Remember that clusters are namespaced resources. These examples provision clusters in the `default` namespace, but you will need to provide yours if using a different one.
Expand Down
Loading