add docs for k3s and other flavors

linode · Feb 26, 2024 · dc639a5 · dc639a5
1 parent 1f86d01
commit dc639a5
Show file tree

Hide file tree

Showing 10 changed files with 151 additions and 22 deletions.
diff --git a/docs/src/flavors/clusterclass-kubeadm.md 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
@@ -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
@@ -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
@@ -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
@@ -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="<LinodePAT>"
+# Cluster settings
+export CLUSTER_NAME=capl-cluster
+export KUBERNETES_VERSION=v1.29.1
+
+# Linode settings
+export LINODE_REGION=us-ord
+export LINODE_TOKEN=<your linode PAT>
+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
@@ -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
@@ -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
+        - swapoff -a
diff --git 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}
+  version: ${KUBERNETES_VERSION}
diff --git 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
+        value: KThreesConfigTemplate
diff --git 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,12 +39,12 @@ 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
      valuesContent: |-
        secretRef:
          name: "linode-token-region"
        nodeSelector:
-         node-role.kubernetes.io/control-plane: "true"
+         node-role.kubernetes.io/control-plane: "true"