From 58c04e16c00ecc30a3417b9dc40c35eaa50468a9 Mon Sep 17 00:00:00 2001 From: Danil-Grigorev Date: Fri, 25 Oct 2024 10:56:19 +0200 Subject: [PATCH 1/3] Simplify CAPIProvider setup guide Signed-off-by: Danil-Grigorev --- .../getting-started/cluster-class/provision.md | 18 ++++-------------- 1 file changed, 4 insertions(+), 14 deletions(-) diff --git a/docs/getting-started/cluster-class/provision.md b/docs/getting-started/cluster-class/provision.md index 89b74218..816b31a7 100644 --- a/docs/getting-started/cluster-class/provision.md +++ b/docs/getting-started/cluster-class/provision.md @@ -34,16 +34,6 @@ This guide uses the [examples repository](https://github.com/rancher-sandbox/ran namespace: capz-system spec: type: infrastructure - name: azure - credentials: - rancherCloudCredential: # 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 @@ -51,7 +41,7 @@ This guide uses the [examples repository](https://github.com/rancher-sandbox/ran 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" @@ -62,10 +52,10 @@ This guide uses the [examples repository](https://github.com/rancher-sandbox/ran export AZURE_CLIENT_SECRET= ``` - 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. @@ -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. From 50d2caf7142a5c2161b24f1c7d1a2a1d1e12b833 Mon Sep 17 00:00:00 2001 From: Danil-Grigorev Date: Fri, 25 Oct 2024 10:58:32 +0200 Subject: [PATCH 2/3] Remove clusterctl in favor of envsubst + curl clusterctl generate works in presence of core CAPI provider, which is provisioned with `clusterctl init`. This functionality overlaps with turtles core CAPIProvider, and may cause issues. Signed-off-by: Danil-Grigorev --- .../create-first-cluster/using_fleet.md | 10 ++++------ .../create-first-cluster/using_kubectl.md | 5 ++--- docs/reference-guides/providers/howto.md | 17 +++++++---------- 3 files changed, 13 insertions(+), 19 deletions(-) diff --git a/docs/getting-started/create-first-cluster/using_fleet.md b/docs/getting-started/create-first-cluster/using_fleet.md index 0fd00327..8936cf00 100644 --- a/docs/getting-started/create-first-cluster/using_fleet.md +++ b/docs/getting-started/create-first-cluster/using_fleet.md @@ -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. @@ -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. diff --git a/docs/getting-started/create-first-cluster/using_kubectl.md b/docs/getting-started/create-first-cluster/using_kubectl.md index bb8cf504..c925f716 100644 --- a/docs/getting-started/create-first-cluster/using_kubectl.md +++ b/docs/getting-started/create-first-cluster/using_kubectl.md @@ -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. diff --git a/docs/reference-guides/providers/howto.md b/docs/reference-guides/providers/howto.md index 4e462775..6ce0ef2d 100644 --- a/docs/reference-guides/providers/howto.md +++ b/docs/reference-guides/providers/howto.md @@ -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 @@ -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. @@ -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. @@ -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. @@ -131,7 +128,7 @@ kubectl create -f cluster1.yaml :::tip After your cluster is provisioned, you can check functionality of the workload cluster using `clusterctl`: ```bash -clusterctl describe cluster cluster1 +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. From 7c8c922063a4b6c56cdf0024d69eb439e3dc0ee4 Mon Sep 17 00:00:00 2001 From: Danil Grigorev Date: Fri, 25 Oct 2024 14:41:05 +0200 Subject: [PATCH 3/3] Update docs/reference-guides/providers/howto.md Co-authored-by: Furkat Gofurov --- docs/reference-guides/providers/howto.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference-guides/providers/howto.md b/docs/reference-guides/providers/howto.md index 6ce0ef2d..a2307b03 100644 --- a/docs/reference-guides/providers/howto.md +++ b/docs/reference-guides/providers/howto.md @@ -126,7 +126,7 @@ kubectl create -f cluster1.yaml :::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 kubectl describe cluster cluster1 ```