From dc639a5a7be87d192f2ddcbe2dcedbb8f500e30a Mon Sep 17 00:00:00 2001 From: Evan Johnson Date: Mon, 26 Feb 2024 16:48:50 -0500 Subject: [PATCH] add docs for k3s and other flavors --- docs/src/flavors/clusterclass-kubeadm.md | 59 ++++++++++++++++++++ docs/src/flavors/default.md | 16 ++++++ docs/src/flavors/flavors.md | 20 +++++++ docs/src/flavors/k3s.md | 34 +++++++++++ docs/src/topics/getting-started.md | 20 +++++-- templates/flavors/README.md | 12 +--- templates/flavors/k3s/k3sConfigTemplate.yaml | 2 +- templates/flavors/k3s/k3sControlPlane.yaml | 2 +- templates/flavors/k3s/kustomization.yaml | 2 +- templates/flavors/k3s/secret.yaml | 6 +- 10 files changed, 151 insertions(+), 22 deletions(-) create mode 100644 docs/src/flavors/clusterclass-kubeadm.md create mode 100644 docs/src/flavors/default.md create mode 100644 docs/src/flavors/flavors.md create mode 100644 docs/src/flavors/k3s.md diff --git a/docs/src/flavors/clusterclass-kubeadm.md b/docs/src/flavors/clusterclass-kubeadm.md new file mode 100644 index 000000000..c361694a3 --- /dev/null +++ b/docs/src/flavors/clusterclass-kubeadm.md @@ -0,0 +1,59 @@ +# Kubeadm ClusterClass +## Specification +| Control Plane | CNI | OS | Installs ClusterClass | +|---------------|--------|--------|-----------------------| +| Kubeadm | Cilium | Ubuntu | Yes | +## Prerequisites +[Quickstart](../topics/getting-started.md) completed +## Usage +### Create clusterClass and first cluster +1. Generate clusterClass & cluster manifests + ```bash + clusterctl generate cluster test-cluster --flavor clusterclass-kubeadm > test-cluster.yaml + ``` +2. Apply cluster manifests + ```bash + kubectl apply -f test-cluster.yaml + ``` +### Create second cluster +1. Generate cluster manifests + ```bash + clusterctl generate cluster test-cluster-2 --flavor clusterclass-kubeadm > test-cluster-2.yaml + ``` + ```yaml + apiVersion: cluster.x-k8s.io/v1beta1 + kind: Cluster + metadata: + labels: + ccm: linode + cni: cilium + crs: test-cluster-2-crs + name: test-cluster-2 + namespace: default + spec: + clusterNetwork: + pods: + cidrBlocks: + - 192.168.128.0/17 + topology: + class: kubeadm + controlPlane: + replicas: 1 + variables: + - name: region + value: us-ord + - name: controlPlaneMachineType + value: g6-standard-2 + - name: workerMachineType + value: g6-standard-2 + version: v1.29.1 + workers: + machineDeployments: + - class: default-worker + name: md-0 + replicas: 1 + ``` +2. Apply cluster manifests + ```bash + kubectl apply -f test-cluster-2.yaml + ``` diff --git a/docs/src/flavors/default.md b/docs/src/flavors/default.md new file mode 100644 index 000000000..ed6ce50f6 --- /dev/null +++ b/docs/src/flavors/default.md @@ -0,0 +1,16 @@ +# Default +## Specification +| Control Plane | CNI | OS | Installs ClusterClass | +|---------------|--------|--------|-----------------------| +| Kubeadm | Cilium | Ubuntu | No | +## Prerequisites +[Quickstart](../topics/getting-started.md) completed +## Usage +1. Generate cluster yaml + ```bash + clusterctl generate cluster test-cluster --flavor clusterclass > test-cluster.yaml + ``` +2. Apply cluster yaml + ```bash + kubectl apply -f test-cluster.yaml + ``` diff --git a/docs/src/flavors/flavors.md b/docs/src/flavors/flavors.md new file mode 100644 index 000000000..5d70bb859 --- /dev/null +++ b/docs/src/flavors/flavors.md @@ -0,0 +1,20 @@ +# Flavors + +In `clusterctl` the infrastructure provider authors can provide different types +of cluster templates referred to as "flavors". You can use the `--flavor` flag +to specify which flavor to use for a cluster, e.g: + +```bash +clusterctl generate cluster test-cluster --flavor clusterclass +``` + +To use the default flavor, omit the `--flavor` flag. + +See the [`clusterctl` flavors docs](https://cluster-api.sigs.k8s.io/clusterctl/commands/generate-cluster.html#flavors) for more information. + + +## supported flavors + +- [Default](default.md) +- [Cluster Class Kubeadm](clusterclass-kubeadm.md) +- [k3s](k3s.md) diff --git a/docs/src/flavors/k3s.md b/docs/src/flavors/k3s.md new file mode 100644 index 000000000..1bd153f1a --- /dev/null +++ b/docs/src/flavors/k3s.md @@ -0,0 +1,34 @@ +# K3s +## Specification +| Control Plane | CNI | OS | Installs ClusterClass | +|-----------------------------|--------|--------|-----------------------| +| [k3s](https://docs.k3s.io/) | Cilium | Ubuntu | No | +## Prerequisites +* [Quickstart](../topics/getting-started.md) completed +* Select a [k3s kubernetes version](https://github.com/k3s-io/k3s/releases) to set for the kubernetes version + ```bash + export KUBERNETES_VERSION=v1.29.1+k3s2 + ``` +* Installed [k3s bootstrap provider](https://github.com/k3s-io/cluster-api-k3s) into your management cluster + * Add `k3s-clusterctl.yaml` config for the k3s bootstrap/control plane providers + ```yaml + providers: + - name: "k3s" + url: https://github.com/k3s-io/cluster-api-k3s/releases/latest/bootstrap-components.yaml + type: "BootstrapProvider" + - name: "k3s" + url: https://github.com/k3s-io/cluster-api-k3s/releases/latest/control-plane-components.yaml + ``` + * Install the k3s provider into your management cluster + ```shell + clusterctl init --bootstrap k3s --control-plane k3s --config k3s-clusterctl.yaml + ``` +## Usage +1. Generate cluster yaml + ```bash + clusterctl generate cluster test-cluster --kubernetes-version ${K3S_KUBERNETES_VERSION} --flavor k3s > test-k3s-cluster.yaml + ``` +2. Apply cluster yaml + ```bash + kubectl apply -f test-k3s-cluster.yaml + ``` diff --git a/docs/src/topics/getting-started.md b/docs/src/topics/getting-started.md index bb6327681..ca2969742 100644 --- a/docs/src/topics/getting-started.md +++ b/docs/src/topics/getting-started.md @@ -17,14 +17,22 @@ For more information please see the [Linode Guide](https://www.linode.com/docs/products/tools/api/guides/manage-api-tokens/#create-an-api-token). ``` -## Setting up your Linode environment +## Setting up your cluster environment variable -Once you have provisioned your PAT, save it in an environment variable: +Once you have provisioned your PAT, save it in an environment variable along with other required settings: ```bash -export LINODE_TOKEN="" +# Cluster settings +export CLUSTER_NAME=capl-cluster +export KUBERNETES_VERSION=v1.29.1 + +# Linode settings +export LINODE_REGION=us-ord +export LINODE_TOKEN= +export LINODE_CONTROL_PLANE_MACHINE_TYPE=g6-standard-2 +export LINODE_MACHINE_TYPE=g6-standard-2 ``` -## Building your first cluster -Please continue from the [setting up the environment](../developers/development.md#setting-up-the-environment) -section for creating your first Kubernetes cluster on Linode using Cluster API. +## Deploying your first cluster + +please refer to the [default flavor](../flavors/default.md) section for creating your first Kubernetes cluster on Linode using Cluster API. diff --git a/templates/flavors/README.md b/templates/flavors/README.md index c297af5a1..fe61bd1cf 100644 --- a/templates/flavors/README.md +++ b/templates/flavors/README.md @@ -1,16 +1,8 @@ # Flavors -In `clusterctl` the infrastructure provider authors can provide different types -of cluster templates referred to as "flavors". You can use the `--flavor` flag -to specify which flavor to use for a cluster, e.g: +## [Flavor usage documentation](https://linode.github.io/cluster-api-provider-linode/flavors/flavors.html) -```shell -clusterctl generate cluster test-cluster --flavor clusterclass -``` - -To use the default flavor, omit the `--flavor` flag. - -See the [`clusterctl` flavors docs](https://cluster-api.sigs.k8s.io/clusterctl/commands/generate-cluster.html#flavors) for more information. +## Development This directory contains each of the flavors for CAPL. Each directory besides `base` will be used to create a flavor by running `kustomize build` on the directory. The name of the directory will be diff --git a/templates/flavors/k3s/k3sConfigTemplate.yaml b/templates/flavors/k3s/k3sConfigTemplate.yaml index b3d77b30a..9127f4eab 100644 --- a/templates/flavors/k3s/k3sConfigTemplate.yaml +++ b/templates/flavors/k3s/k3sConfigTemplate.yaml @@ -15,4 +15,4 @@ spec: mkdir -p /etc/rancher/k3s/config.yaml.d/ echo "node-ip: $(hostname -I | grep -oE 192\.168\.[0-9]+\.[0-9]+)" >> /etc/rancher/k3s/config.yaml.d/capi-config.yaml - sed -i '/swap/d' /etc/fstab - - swapoff -a \ No newline at end of file + - swapoff -a diff --git a/templates/flavors/k3s/k3sControlPlane.yaml b/templates/flavors/k3s/k3sControlPlane.yaml index 5916b65e7..ec81c48f4 100644 --- a/templates/flavors/k3s/k3sControlPlane.yaml +++ b/templates/flavors/k3s/k3sControlPlane.yaml @@ -47,4 +47,4 @@ spec: - sed -i '/swap/d' /etc/fstab - swapoff -a replicas: ${CONTROL_PLANE_MACHINE_COUNT} - version: ${KUBERNETES_VERSION} \ No newline at end of file + version: ${KUBERNETES_VERSION} diff --git a/templates/flavors/k3s/kustomization.yaml b/templates/flavors/k3s/kustomization.yaml index 181a4be61..3b8dc7923 100644 --- a/templates/flavors/k3s/kustomization.yaml +++ b/templates/flavors/k3s/kustomization.yaml @@ -19,4 +19,4 @@ patches: patch: |- - op: replace path: /spec/template/spec/bootstrap/configRef/kind - value: KThreesConfigTemplate \ No newline at end of file + value: KThreesConfigTemplate diff --git a/templates/flavors/k3s/secret.yaml b/templates/flavors/k3s/secret.yaml index 07522ec53..d6f8f02b4 100644 --- a/templates/flavors/k3s/secret.yaml +++ b/templates/flavors/k3s/secret.yaml @@ -21,7 +21,7 @@ stringData: name: cilium spec: targetNamespace: kube-system - version: v1.15.0 + version: ${CILIUM_VERSION:=1.15.0} chart: cilium repo: https://helm.cilium.io/ bootstrap: true @@ -39,7 +39,7 @@ stringData: name: ccm-linode spec: targetNamespace: kube-system - version: v0.3.24 + version: ${LINODE_CCM_VERSION:=v0.3.24} chart: ccm-linode repo: https://linode.github.io/linode-cloud-controller-manager/ bootstrap: true @@ -47,4 +47,4 @@ stringData: secretRef: name: "linode-token-region" nodeSelector: - node-role.kubernetes.io/control-plane: "true" \ No newline at end of file + node-role.kubernetes.io/control-plane: "true"