Skip to content

Commit

Permalink
Merge pull request #2554 from spidernet-io/doc/kubevirt
Browse files Browse the repository at this point in the history 
doc: add en kubevirt
  • Loading branch information
@weizhoublue
weizhoublue authored Nov 7, 2023
2 parents f577fad + 0f1fceb commit 2b72050
Show file tree
Hide file tree
Showing 2 changed files with 187 additions and 19 deletions.
36 changes: 18 additions & 18 deletions docs/usage/kubevirt-zh_CN.md
View file
Original file line number Diff line number Diff line change
@@ -1,36 +1,36 @@
# Kubevirt
# KubeVirt

**简体中文** | [**English**](./kubevirt.md)

## 介绍

*Spiderpool 能保证 kubevirt vm 的 Pod 在重启、重建场景下，持续获取到相同的 IP 地址。*
*Spiderpool 能保证 kubevirt VM 的 Pod 在重启、重建场景下，持续获取到相同的 IP 地址。*

## Kubevirt 网络搭配
## KubeVirt 网络搭配

Spiderpool underlay 网络解决方案可给 Kubevirt 赋予介入 underlay 的能力:
Spiderpool underlay 网络解决方案可给 KubeVirt 赋予介入 underlay 的能力:

1. 对于 Kubevirt 的 Passt 网络模式，可搭配 Spiderpool macvlan 集成方案使用。在该网络模式下，**支持** Service Mesh 的所有功能，不过只能使用**单网卡**，且不支持热迁移。
1. 对于 KubeVirt 的 passt 网络模式，可搭配 Spiderpool macvlan 集成方案使用。在该网络模式下，**支持** Service Mesh 的所有功能，不过只能使用**单网卡**，且不支持热迁移。

2. 对于 Kubevirt 的 Bridge 网络模式，可搭配 OVS CNI 使用。在该网络模式下，**不支持** Service Mesh 功能，可使用**多网卡**，不支持热迁移。
2. 对于 KubeVirt 的 bridge 网络模式，可搭配 OVS CNI 使用。在该网络模式下，**不支持** Service Mesh 功能，可使用**多网卡**，不支持热迁移。

## Kubevirt VM 固定地址
## KubeVirt VM 固定地址

Kubevirt VM 会在以下一些场景中会出现固定地址的使用：
KubeVirt VM 会在以下一些场景中会出现固定地址的使用：

1. VM 的热迁移，期望迁移过后的 VM 仍能继承之前的 IP 地址。

2. VM 资源对应的 Pod 出现了重启的情况。

3. VM 资源对应的 VMI(VirtualMachineInstance) 资源被删除的情景。

此外，Kubevirt VM 固定 IP 地址与 StatefulSet 的表现形式是不一样的：
此外，KubeVirt VM 固定 IP 地址与 StatefulSet 的表现形式是不一样的：

1. 对于 VM ，Pod 重启前后，其 Pod 的名字是会发生变化的，但是其对应的 VMI 不论重启与否，其名字都不会发生变化。因此，我们将会以 VM 为单位来记录其固定的 IP 地址(我们的 SpiderEndpoint 资源将会继承使用 VM 资源的命名空间以及名字)。

2. 对于 StatefulSet，Pod 副本重启前后，其 Pod 名保持不变，我们 Spiderpool 会因此以 Pod 为单位来记录其固定的 IP 地址。

> Notice: 该功能默认开启。若开启，无任何限制， VM 可通过有限 IP 地址集合的 IP 池来固化 IP 的范围，但是，无论 VM 是否使用固定的 IP 池，它的 Pod 都可以持续分到相同 IP。 若关闭，VM 对应的 Pod 将被当作无状态对待，使用 Helm 安装 Spiderpool 时，可通过`--set ipam.enableKubevirtStaticIP=false` 关闭。
> 该功能默认开启。若开启，无任何限制，VM 可通过有限 IP 地址集合的 IP 池来固化 IP 的范围，但是，无论 VM 是否使用固定的 IP 池，它的 Pod 都可以持续分到相同 IP。 若关闭，VM 对应的 Pod 将被当作无状态对待，使用 Helm 安装 Spiderpool 时，可通过 `--set ipam.enableKubevirtStaticIP=false` 关闭。
## 实施要求

Expand All @@ -40,18 +40,18 @@ Kubevirt VM 会在以下一些场景中会出现固定地址的使用：

## 步骤

以下流程将会演示 Kubevirt 的 Passt 网络模式搭配 macvlan CNI 以使得 VM 获得 underlay 接入能力，并通过 spiderpool 实现分配固定 IP 的功能。
以下流程将会演示 KubeVirt 的 passt 网络模式搭配 macvlan CNI 以使得 VM 获得 underlay 接入能力，并通过 Spiderpool 实现分配固定 IP 的功能。

> Notice：当前 macvlan 和 ipvlan 并不适用于 Kubevirt 的 bridge 网络模式，因为对于 bridge 网络模式会将 pod 网卡的 MAC 地址移动到VM，使得 Pod 使用另一个不同的地址。而 macvlan 和 ipvlan CNI 要求 Pod 的网卡接口具有原始 MAC 地址。
> Notice：当前 macvlan 和 ipvlan 并不适用于 KubeVirt 的 bridge 网络模式，因为对于 bridge 网络模式会将 Pod 网卡的 MAC 地址移动到 VM，使得 Pod 使用另一个不同的地址。而 macvlan 和 ipvlan CNI 要求 Pod 的网卡接口具有原始 MAC 地址。
### 安装 Spiderpool

请参考 [Macvlan Quick Start](./install/underlay/get-started-macvlan-zh_CN.md) 安装 Spiderpool. 其中，可确保 helm 安装选项 `ipam.enableKubevirtStaticIP=true`


### 创建 Kubevirt VM 应用
### 创建 KubeVirt VM 应用

以下的示例 Yaml 中， 会创建 1 个 Kubevirt VM 应用 ，其中：
以下的示例 Yaml 中， 会创建 1 个 KubeVirt VM 应用 ，其中：

- `v1.multus-cni.io/default-network`：为应用选择一张默认网卡的 CNI 配置。

Expand Down Expand Up @@ -100,7 +100,7 @@ spec:
echo 'printed from cloud-init userdata'
```

最终，在 Kubevirt VM 应用被创建时，Spiderpool 会从指定 IPPool 中随机选择一个 IP 来与应用形成绑定关系。
最终，在 KubeVirt VM 应用被创建时，Spiderpool 会从指定 IPPool 中随机选择一个 IP 来与应用形成绑定关系。

```bash
~# kubectl get spiderippool
Expand All @@ -112,7 +112,7 @@ NAME READY STATUS RESTARTS AGE IP
virt-launcher-vm-cirros-rg6fs 2/2 Running 0 3m43s 10.6.168.105 node2 <none> 1/1
```

重启 Kubevirt VM Pod, 观察到新的 Pod 的 IP 不会变化，符合预期。
重启 KubeVirt VM Pod, 观察到新的 Pod 的 IP 不会变化，符合预期。

```bash
~# kubectl delete pod virt-launcher-vm-cirros-rg6fs
Expand All @@ -123,7 +123,7 @@ NAME READY STATUS RESTARTS AGE IP
virt-launcher-vm-cirros-d68l2 2/2 Running 0 1m21s 10.6.168.105 node2 <none> 1/1
```

重启 Kubevirt VMI，观察到后续新的 Pod 的IP 也不会变化，符合预期。
重启 KubeVirt VMI，观察到后续新的 Pod 的IP 也不会变化，符合预期。

```bash
~# kubectl delete vmi vm-cirros
Expand Down Expand Up @@ -172,4 +172,4 @@ Accept-Ranges: bytes

## 总结

Spiderpool 能保证 Kubevirt VM Pod 在重启、重建场景下，持续获取到相同的 IP 地址，能很好的满足 Kubevirt 虚拟机的固定 IP 需求。并可配合 macvlan 或 OVS CNI 与 Kubevirt 的多种网络模式实现 VM underlay 接入能力。
Spiderpool 能保证 KubeVirt VM Pod 在重启、重建场景下，持续获取到相同的 IP 地址，能很好的满足 KubeVirt 虚拟机的固定 IP 需求。并可配合 macvlan 或 OVS CNI 与 KubeVirt 的多种网络模式实现 VM underlay 接入能力。
170 changes: 169 additions & 1 deletion docs/usage/kubevirt.md
View file
Original file line number Diff line number Diff line change
@@ -1,3 +1,171 @@
# Kubevirt
# KubeVirt

**English** ｜ [**简体中文**](./kubevirt-zh_CN.md)

## Introduction

*Spiderpool ensures that KubeVirt VM Pods consistently obtain the same IP addresses during restart and rebuild processes.*

## Integrate with KubeVirt Networking

The Spiderpool underlay networking solution provides the ability to integrate with KubeVirt:

1. For KubeVirt's passt network mode, it can be used in conjunction with the Spiderpool macvlan integrated solution. In this network mode, all Service Mesh functionalities are **supported**. However, only **single NIC** is supported, and live migration is not available.

2. For KubeVirt's bridge network mode, it can be used in conjunction with OVS CNI. In this network mode, Service Mesh functionalities are **not supported**, but **multiple NICs** can be used, and live migration is not available.

## Fix IP Address for KubeVirt VMs

KubeVirt VMs may require fixed IP addresses in the following scenarios:

1. During VM live migration, it is expected that the VM retains its previous IP address after migration.
2. When the Pod associated with the VM resource undergoes a restart.
3. When the VMI (VirtualMachineInstance) resource corresponding to the VM resource is deleted.

It is important to note that the pattern of fixed IP addresses for KubeVirt VMs differs from that of StatefulSets:

1. For VMs, the Pod name changes between restarts, but the VMI name remains unchanged regardless of restarts. Therefore, the fixed IPs will be recorded based on VMs. Specifically, SpiderEndpoint resource will be associated with the VM resource's namespace and name to record its fixed IP address.
2. For StatefulSets, the Pod name remains the same between restarts, so Spiderpool records the fixed IP addresses based on Pods.

> This feature is enabled by default. When enabled, there are no restrictions. VMs can use a limited set of IP addresses from an IP pool to assign fixed IPs. However, regardless of whether a VM uses a fixed IP pool, its Pod can consistently obtain the same IP address. If disabled, Pods associated with VMs will be treated as stateless. During installation of Spiderpool using Helm, you can disable it by using `--set ipam.enableKubevirtStaticIP=false`.
## Prerequisites

1. A ready Kubernetes cluster.

2. [Helm](https://helm.sh/docs/intro/install/) has been installed.

## Steps

The following steps demonstrate how to use the passt network mode of KubeVirt with macvlan CNI to enable VMs to access the underlay network and assign fixed IPs using Spiderpool.

> Currently, macvlan and ipvlan are not suitable for KubeVirt's bridge network mode because in bridge network mode, the MAC address of the Pod interface is moved to the VM, causing the Pod to use a different address. However, macvlan and ipvlan CNI require the Pod's network interface to have the original MAC address.
### Install Spiderpool

Please refer to [Macvlan Quick Start](./install/underlay/get-started-macvlan.md) for installing Spiderpool. Make sure to set the Helm installation option `ipam.enableKubevirtStaticIP=true`.

### Create KubeVirt VM Applications

In the example YAML below, we create 1 KubeVirt VM application:

- `v1.multus-cni.io/default-network`: select the default network CNI configuration for the application.

```bash
apiVersion: kubevirt.io/v1
kind: VirtualMachine
metadata:
name: vm-cirros
labels:
kubevirt.io/vm: vm-cirros
spec:
runStrategy: Always
template:
metadata:
annotations:
v1.multus-cni.io/default-network: kube-system/macvlan-ens192
labels:
kubevirt.io/vm: vm-cirros
spec:
domain:
devices:
disks:
- name: containerdisk
disk:
bus: virtio
- name: cloudinitdisk
disk:
bus: virtio
interfaces:
- name: default
passt: {}
resources:
requests:
memory: 64M
networks:
- name: default
pod: {}
volumes:
- name: containerdisk
containerDisk:
image: quay.io/kubevirt/cirros-container-disk-demo
- name: cloudinitdisk
cloudInitNoCloud:
userData: |
#!/bin/sh
echo 'printed from cloud-init userdata'
```

When creating a KubeVirt VM application, Spiderpool randomly selects an IP from the specified IP pool to establish a binding with the application.

```bash
~# kubectl get spiderippool
NAME VERSION SUBNET ALLOCATED-IP-COUNT TOTAL-IP-COUNT DEFAULT
test-ippool 4 10.6.0.0/16 1 10 false

~# kubectl get po -l vm.kubevirt.io/name=vm-cirros -o wide
NAME READY STATUS RESTARTS AGE IP NODE NOMINATED NODE READINESS GATES
virt-launcher-vm-cirros-rg6fs 2/2 Running 0 3m43s 10.6.168.105 node2 <none> 1/1
```

Upon restarting a Kubevirt VM Pod, the new Pod retains its original IP address as expected.

```bash
~# kubectl delete pod virt-launcher-vm-cirros-rg6fs
pod "virt-launcher-vm-cirros-rg6fs" deleted

~# kubectl get po -l vm.kubevirt.io/name=vm-cirros -o wide
NAME READY STATUS RESTARTS AGE IP NODE NOMINATED NODE READINESS GATES
virt-launcher-vm-cirros-d68l2 2/2 Running 0 1m21s 10.6.168.105 node2 <none> 1/1
```

When restarting a Kubevirt VMI, new Pods also maintain their assigned IP addresses as expected.

```bash
~# kubectl delete vmi vm-cirros
virtualmachineinstance.kubevirt.io "vm-cirros" deleted

~# kubectl get po -l vm.kubevirt.io/name=vm-cirros -o wide
NAME READY STATUS RESTARTS AGE IP NODE NOMINATED NODE READINESS GATES
virt-launcher-vm-cirros-jjgrl 2/2 Running 0 104s 10.6.168.105 node2 <none> 1/1
```

The VM can communicate with other underlay Pods

```bash
~# kubectl get po -o wide
NAME READY STATUS RESTARTS AGE IP NODE NOMINATED NODE READINESS GATES
daocloud-2048-5855b45f44-bvmdr 1/1 Running 0 5m55s 10.6.168.108 spider-worker <none> <none>

~# kubectl virtctl console vm-cirros
$ ping -c 1 10.6.168.108
PING 10.6.168.108 (10.6.168.108): 56 data bytes
64 bytes from 10.6.168.108: seq=0 ttl=255 time=70.554 ms

--- 10.6.168.108 ping statistics ---
1 packets transmitted, 1 packets received, 0% packet loss
round-trip min/avg/max = 70.554/70.554/70.554 ms
```

The VM can access cluster IP addresses.

```bash
~# kubectl get svc -o wide
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE SELECTOR
daocloud-2048-svc ClusterIP 10.233.36.38 <none> 80/TCP 3m50s app=daocloud-2048

~# curl -I 10.233.36.38:80
HTTP/1.1 200 OK
Server: nginx/1.10.1
Date: Tue, 17 Oct 2023 06:50:04 GMT
Content-Type: text/html
Content-Length: 4090
Last-Modified: Tue, 17 Oct 2023 06:40:53 GMT
Connection: keep-alive
ETag: "652e2c75-ffa"
Accept-Ranges: bytes
```

## Summary

Spiderpool guarantees that KubeVirt VM Pods consistently acquire the same IP addresses during restart and rebuild processes, meeting the fixed IP address requirements for Kubevirt VMs. It seamlessly integrates with macvlan or OVS CNI to enable VMs to access underlay networks.

0 comments on commit 2b72050

Please sign in to comment.