Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs(module): update en\ru guides #420

Merged
merged 30 commits into from
Oct 14, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
30 commits
Select commit Hold shift + click to select a range
0e2da21
chore(module): update ru userguide
fl64 Oct 3, 2024
f9a67e4
chore(module): update ru adminguide
fl64 Oct 3, 2024
aafdb42
chore(module): add pics
fl64 Oct 3, 2024
7a97e43
chore(module): update faq install
fl64 Oct 3, 2024
422e625
chore(module): update
fl64 Oct 6, 2024
875282d
chore(module): update
fl64 Oct 7, 2024
03f028f
chore(module): update
fl64 Oct 7, 2024
8559b11
chore(module): update
fl64 Oct 7, 2024
1b60a4b
chore(module): update
fl64 Oct 7, 2024
e0b0b31
chore(module): update
fl64 Oct 7, 2024
eb5476d
chore(module): ubuntu-vm->linux-vm
fl64 Oct 8, 2024
8c82744
chore(module): ubuntu-root->linux-vm-root
fl64 Oct 8, 2024
8c858ce
chore(module): vd-blank->blank-disk
fl64 Oct 8, 2024
1773efa
chore(module): update images
fl64 Oct 8, 2024
75b951a
chore(module): update images
fl64 Oct 8, 2024
87d89b8
chore(module): add en guides
fl64 Oct 8, 2024
783e983
chore(module): update
fl64 Oct 8, 2024
8fab203
docs(module): add docs for vm snapshot and restore (#427)
Isteb4k Oct 8, 2024
cad9f8d
chore(module): update
fl64 Oct 8, 2024
3e03460
chore(module): update
fl64 Oct 8, 2024
9bf8aaa
chore(module): update
fl64 Oct 8, 2024
7921214
chore(module): update
fl64 Oct 8, 2024
7a5ae0e
chore(module): update
fl64 Oct 8, 2024
08ed9ad
chore(module): update
fl64 Oct 8, 2024
b0a56a9
chore(module): update
fl64 Oct 8, 2024
1dab683
chore(module): update
fl64 Oct 8, 2024
8fc7266
chore(module): update
fl64 Oct 8, 2024
c9e8055
chore(module): update
fl64 Oct 10, 2024
4c774d4
chore(module): update
fl64 Oct 10, 2024
409891c
chore(module): update
fl64 Oct 10, 2024
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
146 changes: 25 additions & 121 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,41 +16,44 @@ It offers the following features:
- Ability to run virtual machines and containerized applications in the same environment.
- Integration with the existing Deckhouse ecosystem to leverage its capabilities for virtual machines.

## Requirements
### Resource requirements:

The following conditions are required to run the module:
The following minimum resources are recommended for infrastructure nodes, depending on their role in the cluster:

- A processor with x86_64 architecture and support for Intel-VT or AMD-V instructions.
- Cluster resource requirements and configuration specifics are available for reading on [this](https://deckhouse.io/guides/production.html) page.
- Any [compatible](https://deckhouse.io/documentation/v1/supported_versions.html#linux) Linux-based OS is supported for installation.
- The Linux kernel on the cluster nodes must be version 5.7 or newer.
- The [CNI Cilium](/documentation/v1/modules/021-cni-cilium/) module to provide network connectivity for virtual machines.
- Modules [SDS-DRBD](https://deckhouse.io/modules/sds-drbd/stable/) or [CEPH-CSI](/documentation/v1/modules/031-ceph-csi/) for storing virtual machine data. It is also possible to use other storage options that support the creation of block devices with `RWX` (`ReadWriteMany`) access mode.
- Master node-4 CPUs, 8 GB of RAM, 60 GB of disk space on a fast disk (400+ IOPS);
- Worker node-the requirements are similar to those for the master node, but largely depend on the nature of the load running on the node (nodes).

> If you plan to use the virtualization module in a production environment, it is recommended to deploy it on physical servers. Deploying the module on virtual machines is also possible, but in this case you need to enable nested virtualization.

The command line utility [d8](https://github.com/deckhouse/deckhouse-cli) is used to create cluster resources and connect to virtual machines. For users of the EE-version the ability to manage resources via UI is available.
### Requirements for platform nodes:

- Linux-based OS:
- CentOS 7, 8, 9
- Debian 10, 11, 12
- Rocky Linux 8, 9
- Ubuntu 18.04, 20.04, 22.04, 24.04
- Linux kernel version >= 5.7
- CPU with x86_64 c architecture with support for Intel-VT (vmx) or AMD-V (svm) instructions

## What do I need to enable the module?

To enable the module, you need a Deckhouse Kubernetes Platform cluster deployed according to [requirements](#Requirements). To deploy Deckhouse Kubernetes Platform, follow [instructions](https://deckhouse.io/gs/#other-options).
1. Deploy the Deckhouse Kubernetes Platform cluster by [instruction](https://deckhouse.io/products/kubernetes-platform/gs/).

1. Enable the [CNI Cilium](/documentation/v1/modules/021-cni-cilium/) module to provide network connectivity for cluster resources.
2. To store virtual machine data, you must enable one of the following modules according to their installation instructions:
2. Enable the necessary modules.

- [SDS-Replicated-volume](https://deckhouse.io/modules/sds-replicated-volume/stable/)
- [CEPH-CSI](/documentation/v1/modules/031-ceph-csi/)
To store virtual machine data (virtual disks and images), you must enable one or more of the following modules according to the installation instructions:

It is also possible to use other storage options that support block device creation with `RWX` (`ReadWriteMany`) access mode.
- [SDS-Replicated-volume](https:/deckhouse.io/modules/sds-replicated-volume/stable/)
- [SDS-Local-volume](https://deckhouse.io/modules/sds-local-volume/stable/)
- [CSI-nfs](https://deckhouse.io/modules/csi-nfs/stable/)
- [CEPH-CSI](https://deckhouse.io/documentation/v1/modules/031-ceph-csi/)

4. Enable [module](./CONFIGURATION.md)
5. Install d8 command line utility:
3. [Set](https://kubernetes.io/docs/tasks/administer-cluster/change-default-storage-class/) default `StorageClass`.
4. Turn on the [console](https://deckhouse.ru/modules/console/stable/) module, which will allow you to manage virtualization components through via UI (This feature is available only to users of the EE edition).

```bash
curl -fsSL https://raw.githubusercontent.com/deckhouse/deckhouse-cli/main/d8-install.sh | sudo bash -s
```
5. Enable the `virtualization` module:

## How to enable module
Attention! Enabling the `virtualization` module involves restarting kubelet/containerd on all nodes where virtual machines are supposed to start. This is necessary to configure the connectivity of containerd and DVCR.

Example of `ModuleConfig` to enable the virtualization module

Expand All @@ -74,103 +77,4 @@ spec:
version: 1
```

## Architecture

The module includes the following components:

- The module core, based on the KubeVirt project and uses QEMU/KVM + libvirtd to run virtual machines.
- Deckhouse Virtualization Container Registry (DVCR) - repository for storing and caching virtual machine images.
- Virtualization-API - controller that implements a user API for creating and managing virtual machine resources.
- Routing Controller (ROUTER) - A controller that manages routes to provide network connectivity for virtual machines.

The API provides capabilities for creating and managing the following resources:

- Virtual Images
- Virtual Disks
- Virtuam machine Classes
- Virtual machines
- Virtual Machine Operations

## Description of functional features

### Virtual Images

Images are immutable resources that allow you to create new virtual machines based on preconfigured and configured images. Depending on the type, images can be in `raw`, `qcow2`, `vmdk` and other formats for virtual machine disk images, and in `iso` format for installation images that can be attached as `cdrom devices`.

You can use external sources such as `http server`, `container registry`, and locally via the command line (`cli`) to download images. It is also possible to create images from virtual machine disks, for example when you need to create a base image for replication (`golden-image`).

It is important to note that images can be attached to a virtual machine in read-only mode.

Images are of two types: clustered `ClusterVirtualImage`, which are available to all users of the platform, and namespaced `VirtualImage`, which are available only to users within a specific `namespace`.

For `ClusterVirtualImage`, images are stored only in `DVCR`, while for `VirtualImage` you can use both `DVCR` and platform-provided storage (`PVC`).

### Virtual Disks

Creating disks for virtual machines is provided by the `VirtualDisk` resource. Disks are used in the virtual machine as the primary storage medium. Disks can be created from external sources, previously created images (`VirtualImage` or `ClusterVirtualImage`) or can be created `empty`.

One of the key features of disks is the ability to resize them without having to stop the virtual machine. It is important to note that only the ability to increase disk size is supported, while decreasing is not available.

Furthermore, disks can be attached to virtual machines while they are running, providing flexibility in storage management. The `VirtualMachineBlockDeviceAttachment` resource is used for this task.

Platform-provided storage (`PVC`) is used to store disks.

### Virtual Machine Classes

A virtual machine class is designed for:

- configuring the type of virtual machine vCPU
- control the placement of virtual machines on the platform nodes
- configuring virtual machine resources (vCPU, memory) for more optimal planning and placement of virtual machines on the platform nodes.

The virtual machine class is configured using the `VirtualMachineClass` resource.

### Virtual Machines

The `VirtualMachine` resource is responsible for creating and managing the lifecycle of virtual machines. Through the `VirtualMachine` configuration you can define virtual machine parameters such as number of processors, amount of RAM, attached images and disks, as well as placement rules on platform nodes, similar to the way it is done for Pods.

A virtual machine's startup policy defines its state. It can be enabled, disabled, or the state can be managed manually. When a node on which a virtual machine is running is rebooted, it will be temporarily evicted from that node using a "live migration" mechanism to another free node that satisfies the placement rules.

The virtual machine runs inside the Pod, which allows you to manage virtual machines as normal Kubernetes resources and use all the features of the platform, including load balancers, network policies, automation tools, etc.

### Virtual Machine Operations

The `VirtualMachineOperations` resource is intended for declarative control of virtual machine state changes. The resource allows you to perform the following actions on virtual machines: Start, Stop, Restart.

## Role Model

The following user roles are provided for managing module resources:

- User
- PrivilegedUser
- Editor
- Admin
- ClusterEditor
- ClusterAdmin.

The following table shows the access matrix for these roles

| Abbreviation | Verb | Kubernetes verbs |
| ------------ | ------ | ------------------------ |
| C | create | create |
| R | read | get,list,watch |
| U | update | patch, update |
| D | delete | delete, deletecollection |

| Resource | User | PrivilegedUser | Editor | Admin | ClusterEditor | ClusterAdmin |
| ------------------------------------ | ---- | -------------- | ------ | ----- | ------------- | ------------ |
| virtualmachines | R | R | CRUD | CRUD | CRUD | CRUD |
| virtualdisks | R | R | CRUD | CRUD | CRUD | CRUD |
| virtualimages | R | R | R | CRUD | CRUD | CRUD |
| clustervirtualimages | R | R | R | R | CRUD | CRUD |
| virtualmachineblockdeviceattachments | R | R | CRUD | CRUD | CRUD | CRUD |
| virtualmachineoperations | R | CR | CRUD | CRUD | CRUD | CRUD |
| virtualmachineipaddresses | R | R | CRUD | CRUD | CRUD | CRUD |
| virtualmachineipaddressleases | - | - | - | R | R | CRUD |
| virtualmachineclasses | R | R | R | R | CRUD | CRUD |

| d8 cli | User | PrivilegedUser | Editor | Admin | ClusterEditor | ClusterAdmin |
| ----------------------------- | ---- | -------------- | ------ | ----- | ------------- | ------------ |
| d8 v console | N | Y | Y | Y | Y | Y |
| d8 v ssh / scp / port-forward | N | Y | Y | Y | Y | Y |
| d8 v vnc | N | Y | Y | Y | Y | Y |
[More information](https://deckhouse.io/modules/virtualization/stable/)
Loading