Skip to content

Commit 87062ea

Browse files
moadqassemmohamed-rafraf
moadqassem
and
mohamed-rafraf
authored
KubeV docs (#1945)
* KubeV docs Signed-off-by: moadqassem <[email protected]> Signed-off-by: moadqassem <[email protected]> * add installation doc * Revert "add installation doc" This reverts commit bb3e060. --------- Signed-off-by: moadqassem <[email protected]> Co-authored-by: Mohamed Rafraf <[email protected]>
1 parent f0375e1 commit 87062ea

File tree

19 files changed

+951
-0
lines changed

19 files changed

+951
-0
lines changed

‎content/kubermatic-virtualization/_index.md

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
+++
2+
title = "Kubermatic Virtualization Docs"
3+
description = "Seamlessly modernize your infrastructure by building your private cloud entirely with Kubernetes"
4+
sitemapexclude = true
5+
+++
6+
7+
Seamlessly modernize your infrastructure by building your private cloud entirely with Kubernetes

‎content/kubermatic-virtualization/main/_index.en.md

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
+++
2+
title = ""
3+
date = 2025-07-18T16:06:34+02:00
4+
+++
5+
6+
## What is Kubermatic Virtualization (Kube-V)?
7+
Kubermatic Virtualization (Kube-V) provides a unified platform that enables organizations to seamlessly orchestrate and manage both traditional virtual machines (VMs) and modern containerized applications.
8+
9+
It extends the powerful automation and operational benefits of Kubernetes to your VM-based workloads, allowing for a more consistent and efficient approach to infrastructure management.
10+
11+
Kubermatic Virtualization leverages Kubernetes-native management by unifying VM and container orchestration as it integrates virtual machines (VMs) directly into Kubernetes as native, first-class objects by managing, scaling, and deploying VMs using the same familiar Kubernetes tools, APIs, and workflows you already use for your containerized applications.
12+
## Features
13+
Kubermatic Virtualization offers a comprehensive set of features designed to modernize infrastructure and streamline operations by converging virtual machine and container management.
14+
15+
### Streamlined Transition and Unified Control
16+
17+
* Effortless Migration: Tools are provided to simplify the migration of existing VMs from diverse environments to the unified platform, making infrastructure modernization more accessible.
18+
* Centralized Operations: Gain single-pane-of-glass management for the entire lifecycle of both VMs and containers. This includes everything from creation, networking, and storage to scaling and monitoring, all accessible from a centralized interface or command-line tools.
19+
20+
### Infrastructure Modernization and Efficiency
21+
22+
* Gradual Modernization Path: Integrate VMs into a cloud-native environment, offering a practical pathway to modernize legacy applications without the immediate need for extensive refactoring into containers. You can run new containerized applications alongside existing virtualized ones.
23+
* Optimized Resource Use: By running VMs and containers on the same underlying physical infrastructure, organizations can achieve better hardware resource utilization and significantly reduce operational overhead.
24+
25+
### Enhanced Development and Reliability
26+
27+
* Improved Developer Experience: Developers can leverage familiar, native Kubernetes tools and workflows for managing both VMs and containers, which minimizes learning curves and speeds up development cycles.
28+
* Automated Workflows (CI/CD): Integrate VMs seamlessly into Kubernetes-native CI/CD pipelines, enabling automated testing and deployment processes.
29+
* Built-in Resilience: Benefit from the platform's inherent high availability and fault tolerance features, including automated restarts and live migration of VMs between nodes, ensuring continuous application uptime.
30+
* Integrated Networking and Storage: VMs natively use the platform's software-defined networking (SDN) and storage capabilities, providing consistent network policies, enhanced security, and streamlined storage management.
31+
32+
See [kubermatic.com](https://www.kubermatic.com/).

‎content/kubermatic-virtualization/main/architecture/_index.en.md

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
+++
2+
title = "Architecture"
3+
date = 2025-07-18T16:06:34+02:00
4+
weight = 5
5+
6+
+++
7+
8+
## Architecture Overview
9+
Kubermatic-Virtualization (Kube-V) is an advanced platform engineered to construct private cloud infrastructures founded
10+
entirely on Kubernetes. Its core design principle is the seamless integration of Kubernetes-native workloads (containers)
11+
and traditional virtualized workloads (Virtual Machines - VMs) under a unified management umbrella. Kube-V achieves this
12+
by building upon Kubernetes as its foundational layer and incorporating KubeVirt to orchestrate and manage VMs alongside
13+
containerized applications.
14+
15+
Here's a breakdown of the architecture and how these components interact:
16+
### Host Nodes
17+
Host nodes can operate on any popular Linux-based operating system such as Ubuntu and RockyLinux where nested virtualization
18+
is enabled to run KVM based virtual machines.
19+
20+
### Kubernetes
21+
The foundation, providing the orchestration, scheduling, and management plane for all workloads. In addition to introduce
22+
declarative API and custom resources (CRDs).
23+
24+
### KubeVirt
25+
An extension to Kubernetes that enables running and managing VMs as native Kubernetes objects. It utilizes Kubernetes pods
26+
as the execution unit each running VM is encapsulated within a standard Kubernetes pod, specifically a virt-launcher pod.
27+
28+
### OVN (Open Virtual Network)
29+
The network fabric, providing advanced SDN (Software-Defined Networking) capabilities for VMs and Pods, replacing or
30+
augmenting the default CNI (Container Network Interface). The network fabric introduces VPCs(Virtual Private Cloud) as
31+
an operational and isolated ecosystem, through subnets and network policies.
32+
33+
### CSI Drivers
34+
A standardized interface that allows Kubernetes to connect to various storage systems, providing persistent storage for
35+
VMs and containers. Kube-V is agnostic about the storage of the underlying infrastructure where any CSI driver can be
36+
used to enabling dynamic provisioning, attachment, and management of persistent volumes for VMs and Pods.
37+
38+
![Kubermatic-Virtualization](kube-v-architecture.png)

‎content/kubermatic-virtualization/main/architecture/compatibility/_index.en.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
+++
2+
title = "Compatibility"
3+
date = 2025-07-18T16:06:34+02:00
4+
weight = 5
5+
+++

‎content/kubermatic-virtualization/main/architecture/compatibility/kubev-components-versioning/_index.en.md

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
+++
2+
title = "Kubermatic Virtualization Components"
3+
date = 2025-07-18T16:06:34+02:00
4+
weight = 5
5+
+++
6+
7+
The following list is only applicable for the Kube-V version that is currently available. Kubermatic has a strong emphasis
8+
on security and reliability of provided software and therefore releases updates regularly that also include component updates.
9+
10+
11+
| Kube-V Component | Version |
12+
|:---------------------------------:|:-------:|
13+
| Kubernetes | v1.33.0 |
14+
| KubeVirt | v1.5.2 |
15+
| Containerized Data Importer (CDI) | v1.62.0 |
16+
| KubeOVN | v1.14.4 |
17+
| KubeOne | v1.11.1 |
18+
| Kyverno | v1.14.4 |
19+
| Cert Manager | v1.18.2 |
20+
| MetalLB | v0.15.2 |
21+

‎content/kubermatic-virtualization/main/architecture/compatibility/operating-system/_index.en.md

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
+++
2+
title = "Operating Systems"
3+
date = 2025-07-18T16:06:34+02:00
4+
weight = 3
5+
+++
6+
7+
## Supported Operating Systems
8+
9+
The following operating systems are supported:
10+
11+
* Ubuntu 20.04 (Focal)
12+
* Ubuntu 22.04 (Jammy Jellyfish)
13+
* Ubuntu 24.04 (Noble Numbat)
14+
* Rocky Linux 8
15+
* RHEL 8.0, 8.1, 8.2, 8.3, 8.4
16+
* Flatcar
17+
18+
{{% notice warning %}}
19+
The minimum kernel version for Kubernetes 1.32 clusters is 4.19. Some operating system versions, such as RHEL 8,
20+
do not meet this requirement and therefore do not support Kubernetes 1.32 or newer.
21+
{{% /notice %}}

‎content/kubermatic-virtualization/main/architecture/concepts/_index.en.md

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
+++
2+
title = "Concepts"
3+
date = 2025-07-18T16:06:34+02:00
4+
weight = 1
5+
+++
6+
7+
Get to know the concepts behind Kubermatic Virtualization (KubeV).

‎content/kubermatic-virtualization/main/architecture/concepts/compute/_index.en.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
+++
2+
title = "Compute"
3+
date = 2025-07-18T16:06:34+02:00
4+
weight = 15
5+
+++

‎content/kubermatic-virtualization/main/architecture/concepts/compute/virtual-machines/_index.en.md

Lines changed: 241 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,241 @@
1+
+++
2+
title = "VirtualMachines Resources"
3+
date = 2025-07-18T16:06:34+02:00
4+
weight = 15
5+
+++
6+
7+
## VirtualMachines
8+
As the name suggests, a VirtualMachine(VM) represents a long-running, stateful virtual machine. It's similar to a
9+
Kubernetes Deployment for Pods, meaning you define the desired state (e.g., "this VM should be running," "it should
10+
have 2 CPUs and 4GB RAM") and Kubermatic-Virtualization ensures that state is maintained. It allows you to start, stop, and configure VMs.
11+
12+
Here is an example of how users can create a VM:
13+
```yaml
14+
apiVersion: kubevirt.io/v1
15+
kind: VirtualMachine
16+
metadata:
17+
name: my-vm-with-http-data-volume
18+
spec:
19+
runStrategy: RerunOnFailure
20+
template:
21+
metadata:
22+
labels:
23+
app: my-vm-with-http-data-volume
24+
annotations:
25+
kubevirt.io/allow-pod-bridge-network-live-migration: "true"
26+
spec:
27+
domain:
28+
cpu:
29+
cores: 1
30+
memory:
31+
guest: 2Gi
32+
devices:
33+
disks:
34+
- name: rootdisk
35+
disk:
36+
bus: virtio
37+
interfaces:
38+
- name: default
39+
masquerade: {}
40+
volumes:
41+
- name: rootdisk
42+
dataVolume:
43+
name: my-http-data-volume
44+
networks:
45+
- name: default
46+
pod: {}
47+
dataVolumeTemplates:
48+
- metadata:
49+
name: my-http-data-volume
50+
spec:
51+
sourceRef:
52+
kind: DataSource
53+
name: my-http-datasource
54+
apiGroup: cdi.kubevirt.io
55+
pvc:
56+
accessModes:
57+
- ReadWriteOnce
58+
resources:
59+
requests:
60+
storage: 10Gi # <--- IMPORTANT: Adjust to your desired disk size
61+
# storageClassName: my-storage-class # <--- OPTIONAL: Uncomment and replace with your StorageClass name if needed
62+
---
63+
apiVersion: cdi.kubevirt.io/v1beta1
64+
kind: DataSource
65+
metadata:
66+
name: my-http-datasource
67+
spec:
68+
source:
69+
http:
70+
url: "http://example.com/path/to/your/image.qcow2" # <--- IMPORTANT: Replace with the actual URL of your disk image
71+
# certConfig: # <--- OPTIONAL: Uncomment and configure if your HTTP server uses a custom CA
72+
# caBundle: "base64encodedCABundle"
73+
# secretRef:
74+
# name: "my-http-cert-secret"
75+
# cert:
76+
# secretRef:
77+
# name: "my-http-cert-secret"
78+
# key:
79+
# secretRef:
80+
# name: "my-http-key-secret"
81+
```
82+
### 1. `VirtualMachine` (apiVersion: `kubevirt.io/v1`)
83+
84+
This is the main KubeVirt resource that defines your virtual machine.
85+
86+
- **`spec.template.spec.domain.devices.disks`**:
87+
Defines the disk attached to the VM. We reference `rootdisk` here, which is backed by our DataVolume.
88+
89+
- **`spec.template.spec.volumes`**:
90+
Links the `rootdisk` to a `dataVolume` named `my-http-data-volume`.
91+
92+
- **`spec.dataVolumeTemplates`**:
93+
This is the crucial part. It defines a template for a DataVolume that will be created automatically when the VM is started.
94+
95+
---
96+
97+
### 2. `DataVolumeTemplate` (within `VirtualMachine.spec.dataVolumeTemplates`)
98+
99+
- **`metadata.name`**:
100+
The name of the DataVolume that will be created (referenced in `spec.template.spec.volumes`).
101+
102+
- **`spec.sourceRef`**:
103+
Points to a `DataSource` resource that defines the actual source of the disk image. A `DataSource` is used here to encapsulate HTTP details.
104+
105+
- **`spec.pvc`**:
106+
Defines the characteristics of the PersistentVolumeClaim (PVC) that will be created for this DataVolume:
107+
108+
- **`accessModes`**: Typically `ReadWriteOnce` for VM disks.
109+
- **`resources.requests.storage`**:
110+
⚠️ **Crucially, set this to the desired size of your VM's disk.** It should be at least as large as your source image.
111+
- **`storageClassName`**: *(Optional)* Specify a StorageClass if needed; otherwise, the default will be used.
112+
113+
---
114+
115+
### 3. `DataSource` (apiVersion: `cdi.kubevirt.io/v1beta1`)
116+
117+
This is a CDI (Containerized Data Importer) resource that encapsulates the details of where your disk image comes from.
118+
119+
- **`metadata.name`**:
120+
The name of the `DataSource` (referenced in `dataVolumeTemplate.spec.sourceRef`).
121+
122+
- **`spec.source.http.url`**:
123+
🔗 This is where you put the direct URL to your disk image (e.g., a `.qcow2`, `.raw`, etc. file).
124+
125+
- **`spec.source.http.certConfig`**: *(Optional)*
126+
If your HTTP server uses a custom CA or requires client certificates, configure them here.
127+
128+
---
129+
130+
### VirtualMachinePools
131+
KubeVirt's VirtualMachinePool is a powerful resource that allows you to manage a group of identical Virtual Machines (VMs)
132+
as a single unit, similar to how a Kubernetes Deployment manages a set of Pods. It's designed for scenarios where you need
133+
multiple, consistent, and often ephemeral VMs that can scale up or down based on demand.
134+
135+
Here's a breakdown of the key aspects of KubeVirt VirtualMachinePools:
136+
137+
138+
```yaml
139+
apiVersion: kubevirt.io/v1alpha1
140+
kind: VirtualMachinePool
141+
metadata:
142+
name: my-vm-http-pool
143+
spec:
144+
replicas: 3 # <--- IMPORTANT: Number of VMs in the pool
145+
selector:
146+
matchLabels:
147+
app: my-vm-http-pool-member
148+
virtualMachineTemplate:
149+
metadata:
150+
labels:
151+
app: my-vm-http-pool-member
152+
annotations:
153+
kubevirt.io/allow-pod-bridge-network-live-migration: "true"
154+
spec:
155+
runStrategy: RerunOnFailure # Or Always, Halted, Manual
156+
domain:
157+
cpu:
158+
cores: 1
159+
memory:
160+
guest: 2Gi
161+
devices:
162+
disks:
163+
- name: rootdisk
164+
disk:
165+
bus: virtio
166+
interfaces:
167+
- name: default
168+
masquerade: {}
169+
volumes:
170+
- name: rootdisk
171+
dataVolume:
172+
name: my-pool-vm-data-volume # This name will have a unique suffix appended by KubeVirt
173+
networks:
174+
- name: default
175+
pod: {}
176+
dataVolumeTemplates:
177+
- metadata:
178+
name: my-pool-vm-data-volume # This name will be the base for the unique DataVolume names
179+
spec:
180+
sourceRef:
181+
kind: DataSource
182+
name: my-http-datasource
183+
apiGroup: cdi.kubevirt.io
184+
pvc:
185+
accessModes:
186+
- ReadWriteOnce
187+
resources:
188+
requests:
189+
storage: 10Gi # <--- IMPORTANT: Adjust to your desired disk size for each VM
190+
# storageClassName: my-storage-class # <--- OPTIONAL: Uncomment and replace with your StorageClass name if needed
191+
---
192+
apiVersion: cdi.kubevirt.io/v1beta1
193+
kind: DataSource
194+
metadata:
195+
name: my-http-datasource
196+
spec:
197+
source:
198+
http:
199+
url: "http://example.com/path/to/your/image.qcow2" # <--- IMPORTANT: Replace with the actual URL of your disk image
200+
# certConfig: # <--- OPTIONAL: Uncomment and configure if your HTTP server uses a custom CA
201+
# caBundle: "base64encodedCABundle"
202+
# secretRef:
203+
# name: "my-http-cert-secret"
204+
# cert:
205+
# secretRef:
206+
# name: "my-http-cert-secret"
207+
# key:
208+
# secretRef:
209+
# name: "my-http-key-secret"
210+
211+
```
212+
### VirtualMachinePool (apiVersion: `kubevirt.io/v1alpha1`)
213+
214+
1. **`API Version`**
215+
- Use `apiVersion: kubevirt.io/v1alpha1` for `VirtualMachinePool`.
216+
- This is a slightly different API version than `VirtualMachine`.
217+
218+
2. **`spec.replicas`**
219+
- Specifies how many `VirtualMachine` instances the pool should maintain.
220+
221+
3. **`spec.selector`**
222+
- Essential for the `VirtualMachinePool` controller to manage its VMs.
223+
- `matchLabels` must correspond to the `metadata.labels` within `virtualMachineTemplate`.
224+
225+
4. **spec.virtualMachineTemplate**
226+
- This section contains the full `VirtualMachine` spec that serves as the template for each VM in the pool.
227+
228+
5. **`dataVolumeTemplates` Naming in a Pool**
229+
- `VirtualMachinePool` creates `DataVolumes` from `dataVolumeTemplates`.
230+
- A unique suffix is appended to the `metadata.name` of each `DataVolume` (e.g., `my-pool-vm-data-volume-abcde`), ensuring each VM gets a distinct PVC.
231+
232+
---
233+
234+
### How It Works (Similar to Deployment for Pods)
235+
236+
1. Apply the `VirtualMachinePool` manifest. KubeVirt ensures the `my-http-datasource` `DataSource` exists.
237+
2. The `VirtualMachinePool` controller creates the defined number of `VirtualMachine` replicas.
238+
3. Each `VirtualMachine` triggers the creation of a `DataVolume` using the specified `dataVolumeTemplate` and `my-http-datasource`.
239+
4. CDI (Containerized Data Importer) downloads the image into a new unique `PersistentVolumeClaim` (PVC) for each VM.
240+
5. Each `VirtualMachine` then starts using its dedicated PVC.
241+

‎content/kubermatic-virtualization/main/architecture/concepts/networks/_index.en.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
+++
2+
title = "Networking"
3+
date = 2025-07-18T16:06:34+02:00
4+
weight = 15
5+
+++

0 commit comments

Comments
 (0)