docs: kubevirt: add documentation

Added how to on downloading the KubeVirt OEM image and how to create a KubeVirt VM with userdata in both supported formats: * cloud-Init * Ignition Signed-off-by: Adrian Vladu <[email protected]>
flatcar · May 29, 2024 · adaeba9 · adaeba9
1 parent b1488d2
commit adaeba9
Show file tree

Hide file tree

Showing 2 changed files with 193 additions and 0 deletions.
diff --git a/content/docs/latest/_index.md b/content/docs/latest/_index.md
@@ -40,6 +40,7 @@ purposes. You can use any of the following options.
  * [VirtualBox][virtualbox] (not officially supported)
  * [Vagrant][vagrant] (not officially supported)
  * [Hyper-V][hyper-v] (not officially supported)
+ * [KubeVirt][kubevirt] (not officially supported)
 
 #### Bare Metal
 You can install Flatcar on bare metal machines in different ways: using ISO
@@ -195,6 +196,7 @@ Flatcar tutorial to deep dive into some Flatcar fundamental concepts.
 [virtualbox]: installing/vms/virtualbox
 [vagrant]: installing/vms/vagrant
 [hyper-v]: installing/vms/hyper-v
+[kubevirt]: installing/vms/kubevirt
 [vmware]: installing/cloud/vmware
 [cluster-architectures]: setup/clusters/architectures
 [update-strategies]: setup/releases/update-strategies

diff --git a/content/docs/latest/installing/vms/kubevirt.md b/content/docs/latest/installing/vms/kubevirt.md
@@ -0,0 +1,191 @@
+---
+title: Running Flatcar Container Linux on KubeVirt
+linktitle: Running on KubeVirt
+weight: 30
+---
+
+_While we always welcome community contributions and fixes, please note that KubeVirt is not an officially supported platform at this time because the release tests don't run for it. (See the [platform overview](/#installing-flatcar).)_
+
+These instructions will walk you through running Flatcar Container Linux on KubeVirt.
+
+## Choose a channel
+
+Flatcar Container Linux is designed to be updated automatically with different schedules per channel. You can [disable this feature][update-strategies], although we don't recommend it. Read the [release notes][release-notes] for specific features and bug fixes.
+
+KubeVirt OEM images are created for both amd64 and arm64 and come in qcow2 compressed format.
+
+How to download a KubeVirt qcow2 image file:
+
+```bash
+# KubeVirt image is available for download from the alpha version 3975.0.0
+wget https://alpha.release.flatcar-linux.net/amd64-usr/3975.0.0/flatcar_production_kubevirt_image.qcow2
+```
+
+## Preparing the Kubernetes cluster
+
+Firstly, KubeVirt needs to be installed on your Kubernetes cluster - see [kubevirt-docs](https://kubevirt.io/user-guide).
+Secondly, CDI needs to be installed and `virtctl` needs to be present on your upload machine, to be able to create the PVC (Persistent Volume Claim) using the qcow2 image - see [KubeVirt CDI](https://kubevirt.io/user-guide/operations/containerized_data_importer/).
+
+Let's create the PVC from the downloaded image using `virtctl`:
+
+```bash
+virtctl image-upload pvc flatcar-production-kubevirt-image --size=10Gi --image-path=flatcar_production_kubevirt_image.qcow2 \
+    --uploadproxy-url https://cdi-uploadproxy:31001 --insecure
+```
+
+Alternatively, we can use a PVC CRD entity (note the cdi.kubevirt.io/storage.import.endpoint annotation):
+
+```yaml
+apiVersion: v1
+kind: PersistentVolumeClaim
+metadata:
+  name: "flatcar-amd64-3975"
+  labels:
+    app: containerized-data-importer
+  annotations:
+    cdi.kubevirt.io/storage.import.endpoint: "https://alpha.release.flatcar-linux.net/amd64-usr/3975.0.0/flatcar_production_kubevirt_image.qcow2"
+spec:
+  accessModes:
+  - ReadWriteOnce
+  resources:
+    requests:
+      storage: 10Gi
+  storageClassName: ceph-block
+```
+
+For provisioning, the Flatcar KubeVirt image supports both [cloud-init](https://cloudinit.readthedocs.io/en/latest/explanation/format.html) and [Ignition](https://coreos.github.io/ignition/getting-started/#providing-a-config) userdata formats.
+
+## Deploying a new virtual machine on KubeVirt using OpenStack userdata config drive
+
+KubeVirt VM definition yaml - vm-flatcar-cfgdrive.yaml:
+
+```yaml
+apiVersion: kubevirt.io/v1
+kind: VirtualMachine
+metadata:
+  generation: 1
+  labels:
+    kubevirt.io/os: linux
+  name: vm-flatcar-cfgdrive
+spec:
+  running: true
+  template:
+    metadata:
+      creationTimestamp: null
+      labels:
+        kubevirt.io/domain: vm-flatcar-cfgdrive
+    spec:
+      domain:
+        cpu:
+          cores: 1
+        devices:
+          disks:
+          - disk:
+              bus: virtio
+            name: disk0
+          - disk:
+              bus: sata
+            name: cloudinitdisk
+        resources:
+          requests:
+            memory: 1024M
+      volumes:
+      - name: disk0
+        persistentVolumeClaim:
+          claimName: flatcar-amd64-3975
+      - cloudInitConfigDrive:
+          userData: |
+            #!/bin/bash
+            echo "core:foo" | chpasswd
+        name: cloudinitdisk
+```
+
+Then, we can apply the VM definition and we should be able to connect to it with username/password - core/foo.
+
+```bash
+kubectl apply -f vm-flatcar-cfgdrive.yaml
+```
+
+## Deploying a new virtual machine on KubeVirt using Ignition userdata config drive
+
+The [Butane](https://coreos.github.io/butane/) configuration used to generate the Ignition configuration:
+
+```yaml
+variant: flatcar
+version: 1.0.0
+kernel_arguments:
+  should_exist:
+    - flatcar.autologin
+passwd:
+  users:
+    - name: core
+      password_hash: $6$sn3ZSJJJln5JkAZb$VDTKzLpCyjlEe7Kh0DKjOnEawkkOoi0tOKVbcCv0FIWSf3u9Y1p1I5YdJJ5L8uDmmMvO2CBlmJZNdxFuekjjE1
+```
+
+The `password_hash` was obtained by running `mkpasswd`.
+
+To obtain the `userData` content, `butane` is required to convert it:
+
+```bash
+butane < userdata.yaml > userdata.json
+cat userdata.json
+# {"ignition":{"version":"3.3.0"},"kernelArguments":{"shouldExist":["flatcar.autologin"]},"passwd":{"users":[{"name":"core","passwordHash":"$6$sn3ZSJJJln5JkAZb$VDTKzLpCyjlEe7Kh0DKjOnEawkkOoi0tOKVbcCv0FIWSf3u9Y1p1I5YdJJ5L8uDmmMvO2CBlmJZNdxFuekjjE1"}]}}
+```
+
+KubeVirt VM definition yaml - vm-flatcar-ignition.yaml:
+
+```yaml
+apiVersion: kubevirt.io/v1
+kind: VirtualMachine
+metadata:
+  generation: 1
+  labels:
+    kubevirt.io/os: linux
+  name: vm-flatcar-ignition
+spec:
+  running: true
+  template:
+    metadata:
+      labels:
+        kubevirt.io/domain: vm-flatcar-ignition
+    spec:
+      domain:
+        cpu:
+          cores: 1
+        devices:
+          disks:
+          - disk:
+              bus: virtio
+            name: disk0
+          - cdrom:
+              bus: sata
+              readonly: true
+            name: cloudinitdisk
+        resources:
+          requests:
+            memory: 1024M
+      volumes:
+      - name: disk0
+        persistentVolumeClaim:
+          claimName: flatcar-amd64-3975
+      - cloudInitConfigDrive:
+          userData: |
+            {"ignition":{"version":"3.3.0"},"kernelArguments":{"shouldExist":["flatcar.autologin"]},"passwd":{"users":[{"name":"core","passwordHash":"$6$sn3ZSJJJln5JkAZb$VDTKzLpCyjlEe7Kh0DKjOnEawkkOoi0tOKVbcCv0FIWSf3u9Y1p1I5YdJJ5L8uDmmMvO2CBlmJZNdxFuekjjE1"}]}}
+        name: cloudinitdisk
+```
+
+Then, we can apply the VM definition and we should be able to connect to it with username/password - core/foo.
+The VM is set via Ignition to autologin the core user at boot.
+
+```bash
+kubectl apply -f vm-flatcar-ignition.yaml
+```
+
+## Using Flatcar Container Linux
+
+Now that you have a KubeVirt machine booted it is time to play around. Check out the [Flatcar Container Linux Quickstart][quickstart] guide or dig into [more specific topics][doc-index].
+
+[update-strategies]: ../../setup/releases/update-strategies
+[release-notes]: https://flatcar-linux.org/releases
+[quickstart]: ../
+[doc-index]: ../../