From e107f483a7ea14f89588d38caca7e536651fc52d Mon Sep 17 00:00:00 2001 From: Nick Chase Date: Wed, 29 Apr 2026 11:34:16 -0400 Subject: [PATCH 1/3] Reorganize to add prerequisits to SSH Quickstart --- docs/quickstarts/quickstart-2-remote.md | 51 ++++++++++++++++++++++++- 1 file changed, 50 insertions(+), 1 deletion(-) diff --git a/docs/quickstarts/quickstart-2-remote.md b/docs/quickstarts/quickstart-2-remote.md index 03fd859e4..09005d7f4 100644 --- a/docs/quickstarts/quickstart-2-remote.md +++ b/docs/quickstarts/quickstart-2-remote.md @@ -15,7 +15,56 @@ Note that if you have already done one of the other quickstarts, such as our AWS Before proceeding, make sure your management cluster meets the following requirements: -1. A [default storage class](https://kubernetes.io/docs/tasks/administer-cluster/change-default-storage-class/) is configured on the management cluster to support Persistent Volumes. +1. Increase filesystem limits by adding the following to `/etc/sysctl.conf`: + + ```bash + fs.inotify.max_user_instances=8192 + fs.inotify.max_user_watches=524288 + ``` + + Then set `systemd` limits: + + ```bash + sudo tee -a /etc/systemd/system.conf < Date: Thu, 30 Apr 2026 21:14:51 -0400 Subject: [PATCH 2/3] Add workaround to remote quickstart --- docs/quickstarts/quickstart-2-remote.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/quickstarts/quickstart-2-remote.md b/docs/quickstarts/quickstart-2-remote.md index 09005d7f4..904362dc1 100644 --- a/docs/quickstarts/quickstart-2-remote.md +++ b/docs/quickstarts/quickstart-2-remote.md @@ -65,6 +65,8 @@ Before proceeding, make sure your management cluster meets the following require -p '{"metadata": {"annotations":{"storageclass.kubernetes.io/is-default-class":"true"}}}' ``` +1. Make sure the key you will use to log in as root exists on the child machines. + 2. If the API server will be exposed as a `LoadBalancer`, ensure the appropriate cloud provider is installed on the management cluster. ## Create a Secret object containing the private SSH key to access remote machines From 8226f19a6f171e18c043975cbf19d2c8bcdca195 Mon Sep 17 00:00:00 2001 From: Nick Chase Date: Wed, 20 May 2026 14:27:37 -0400 Subject: [PATCH 3/3] Add additional instructions --- docs/appendix/index.md | 1 + docs/appendix/storageclass.md | 97 +++++++++++++++++++++++++ docs/quickstarts/quickstart-2-remote.md | 24 ++---- mkdocs.yml | 1 + 4 files changed, 106 insertions(+), 17 deletions(-) create mode 100644 docs/appendix/storageclass.md diff --git a/docs/appendix/index.md b/docs/appendix/index.md index 71df05093..837584fa6 100644 --- a/docs/appendix/index.md +++ b/docs/appendix/index.md @@ -6,4 +6,5 @@ - [Cloud provider credentials management in CAPI](appendix-providers.md) - [Running k0rdent on ARM64](arm64.md) - [KubeVirt Infrastructure Cluster Preparation](kubevirt-infra.md) +- [Confirming default storage class](storageclass.md) - [Glossary](glossary.md) diff --git a/docs/appendix/storageclass.md b/docs/appendix/storageclass.md new file mode 100644 index 000000000..8dd3f977e --- /dev/null +++ b/docs/appendix/storageclass.md @@ -0,0 +1,97 @@ +# Verifying a default StorageClass + +Some operations, such as deploying a remote (SSH-based) cluster, require the management cluster to have a default `StorageClass`. Follow these steps: + +1. If not already installed, install and configure a `StorageClass` provider. For example: + + ```bash + helm repo add openebs https://openebs.github.io/openebs + helm repo update + + helm install openebs openebs/openebs \ + --namespace openebs \ + --create-namespace + + kubectl patch storageclass openebs-hostpath \ + -p '{"metadata": {"annotations":{"storageclass.kubernetes.io/is-default-class":"true"}}}' + ``` + +2. Make sure you see the default setting: + + ```bash + kubectl get storageclass + ``` + + You should see a result such as: + + ```console { .no-copy } + NAME PROVISIONER RECLAIMPOLICY VOLUMEBINDINGMODE ALLOWVOLUMEEXPANSION AGE + mayastor-etcd-localpv openebs.io/local Delete WaitForFirstConsumer false 2m2s + openebs-hostpath (default) openebs.io/local Delete WaitForFirstConsumer false 2m2s + openebs-loki-localpv openebs.io/local Delete WaitForFirstConsumer false 2m2s + openebs-minio-localpv openebs.io/local Delete WaitForFirstConsumer false 2m2s + openebs-single-replica io.openebs.csi-mayastor Delete Immediate true 2m2s + ``` + +3. Create a test PVC: + + ```bash + cat <<'EOF' | kubectl apply -f - + apiVersion: v1 + kind: PersistentVolumeClaim + metadata: + name: test-pvc + spec: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 1Gi + EOF + ``` + +4. Create a test pod: + + ```bash + cat <<'EOF' | kubectl apply -f - + apiVersion: v1 + kind: Pod + metadata: + name: test-pvc-pod + spec: + containers: + - name: test + image: busybox + command: ["sh", "-c", "echo hello > /data/test.txt && sleep 3600"] + volumeMounts: + - name: data + mountPath: /data + volumes: + - name: data + persistentVolumeClaim: + claimName: test-pvc + EOF + ``` + +5. Check the results: + + ```bash + kubectl get pod test-pvc-pod + kubectl get pvc test-pvc + ``` + ```console { .no-copy } + NAME READY STATUS RESTARTS AGE + test-pvc-pod 1/1 Running 0 20s + + NAME STATUS VOLUME CAPACITY ACCESS MODES STORAGECLASS VOLUMEATTRIBUTESCLASS AGE + test-pvc Bound pvc-61b4dd8b-9bcc-48e3-9055-9f0f80ea9abd 1Gi RWO openebs-hostpath 36s + ``` + + You should see the PVC become `Bound`. + +6. Finally, clean up the test: + + ```bash + kubectl delete pod test-pvc-pod + kubectl delete pvc test-pvc + ``` \ No newline at end of file diff --git a/docs/quickstarts/quickstart-2-remote.md b/docs/quickstarts/quickstart-2-remote.md index 904362dc1..5259a5792 100644 --- a/docs/quickstarts/quickstart-2-remote.md +++ b/docs/quickstarts/quickstart-2-remote.md @@ -4,7 +4,7 @@ In many cases, you will want {{{ docsVersionInfo.k0rdentName }}} (running on you The remote machines that will be part of the cluster must meet the following prerequisites: -1. Linux-based operating system; the remote hosts should meet the [k0s system requirements](https://docs.k0sproject.io/stable/system-requirements/) +1. Linux-based operating system; the remote hosts should meet the [k0s system requirements](https://docs.k0sproject.io/stable/system-requirements/). Note that Ubuntu 26.04 is not yet supported by Ubuntu 26.04. 2. SSH access enabled for the root user 3. Internet access 4. Connectivity between the management cluster and the remote hosts' networks @@ -51,21 +51,9 @@ Before proceeding, make sure your management cluster meets the following require sudo reboot ``` -1. A [default storage class](https://kubernetes.io/docs/tasks/administer-cluster/change-default-storage-class/) is configured on the management cluster to support Persistent Volumes. For example: +1. A [default storage class](https://kubernetes.io/docs/tasks/administer-cluster/change-default-storage-class/) is configured on the management cluster to support Persistent Volumes. Make sure the storage class is [configured and working properly](../appendix/storageclass.md). - ```bash - helm repo add openebs https://openebs.github.io/openebs - helm repo update - - helm install openebs openebs/openebs \ - --namespace openebs \ - --create-namespace - - kubectl patch storageclass openebs-hostpath \ - -p '{"metadata": {"annotations":{"storageclass.kubernetes.io/is-default-class":"true"}}}' - ``` - -1. Make sure the key you will use to log in as root exists on the child machines. +1. Make sure the key you will use to log in as root exists and has been configured on the child machines. 2. If the API server will be exposed as a `LoadBalancer`, ensure the appropriate cloud provider is installed on the management cluster. @@ -201,7 +189,7 @@ kcm-system vsphere-standalone-cp-{{{ extra.docsVersionInfo.providerVersions.da ## Create your ClusterDeployment -To deploy a cluster, create a YAML file called `my-remote-clusterdeployment1.yaml`. We'll use this to create a `ClusterDeployment` object representing the deployed cluster. The `ClusterDeployment` identifies for {{{ docsVersionInfo.k0rdentName }}} the `ClusterTemplate` you want to use for cluster creation, the identity credential object you want to create it under, plus the machines' IP addresses (represented by the placeholder `MACHINE_0_ADDRESS` and `MACHINE_1_ADDRESS` below), the SSH port of the remote machines and the user to use when connecting to remote machines (`root`): +To deploy a cluster, create a YAML file called `my-remote-clusterdeployment1.yaml`. We'll use this to create a `ClusterDeployment` object representing the deployed cluster. The `ClusterDeployment` identifies for {{{ docsVersionInfo.k0rdentName }}} the `ClusterTemplate` you want to use for cluster creation, the identity credential object you want to create it under, plus the machines' IP addresses (represented by the placeholder `MACHINE_0_ADDRESS` and `MACHINE_1_ADDRESS` below), the SSH port of the remote machines and the user to use when connecting to remote machines (`root`). Also, if necessary, specify the k0s version; at the time of this writing, v1.35.4 is required: > NOTE: > The user must have root permissions. @@ -220,9 +208,11 @@ spec: credential: remote-cred propagateCredentials: false config: + k0s: + version: v1.35.4+k0s.0 k0smotron: service: - type: LoadBalancer + type: NodePort machines: - address: $MACHINE_0_ADDRESS user: root # The user must have root permissions diff --git a/mkdocs.yml b/mkdocs.yml index 5358dc286..3dbcd9b13 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -301,6 +301,7 @@ nav: - Configuration: appendix/telemetry/configuration.md - Proxy configuration: appendix/proxy.md - KubeVirt Infrastructure Cluster Preparation: appendix/kubevirt-infra.md + - Verifying a default `StorageClass`: appendix/storageclass.md - Release Notes: - Overview: release-notes/index.md - v1.8.0: release-notes/release-notes-v1.8.0.md