Skip to content

Commit

Permalink
Merge pull request #2046 from ty-dc/pr/update_docs
Browse files Browse the repository at this point in the history 
update some outdated documentation
  • Loading branch information
@weizhoublue
weizhoublue authored Aug 7, 2023
2 parents f1d3fcd + 72efb3a commit 7948a5e
Show file tree
Hide file tree
Showing 38 changed files with 1,024 additions and 760 deletions.
2 changes: 1 addition & 1 deletion README-zh_CN.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -227,7 +227,7 @@ Spiderpool 提供了节点拓扑的 IP 池功能，与虚拟机的相同 IP 分
* 设置全局的预留 IP，让 IPAM 不分配出这些 IP 地址，这样能避免与集群外部的已用 IP 冲突。
可参考[例子](./docs/usage/reserved-ip.md)。

* 分配和释放 IP 地址的高效性能，可参考[报告](./docs/concepts/performance-zh_CH.md)。
* 分配和释放 IP 地址的高效性能，可参考[报告](./docs/concepts/performance-zh_CN.md)。

* 合理的 IP 回收机制设计，使得集群或应用在故障恢复过程中，能够及时分配到 IP 地址。可参考[例子](./docs/usage/gc.md)。

Expand Down
2 changes: 1 addition & 1 deletion docs/README-zh_CN.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -227,7 +227,7 @@ Spiderpool 提供了节点拓扑的 IP 池功能，与虚拟机的相同 IP 分
* 设置全局的预留 IP，让 IPAM 不分配出这些 IP 地址，这样能避免与集群外部的已用 IP 冲突。
可参考[例子](./usage/reserved-ip.md)。

* 分配和释放 IP 地址的高效性能，可参考[报告](./concepts/performance-zh_CH.md)。
* 分配和释放 IP 地址的高效性能，可参考[报告](./concepts/performance-zh_CN.md)。

* 合理的 IP 回收机制设计，使得集群或应用在故障恢复过程中，能够及时分配到 IP 地址。可参考[例子](./usage/gc.md)。

Expand Down
36 changes: 19 additions & 17 deletions docs/concepts/performance-zh_CH.md → docs/concepts/performance-zh_CN.md
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
# Spiderpool 性能测试

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

*[Spiderpool](https://github.com/spidernet-io/spiderpool) 是一个适用于 underlay 网络的高性能 IPAM CNI 插件，此文将对比其与市面上主流的 underlay IPAM CNI 插件（如 [Whereabouts](https://github.com/k8snetworkplumbingwg/whereabouts)，[Kube-OVN](https://github.com/kubeovn/kube-ovn)）以及被广泛使用的 overlay IPAM CNI 插件 [calico-ipam](https://github.com/projectcalico/calico) 在 ”1000 Pod“ 场景下的性能表现。*

## 背景
Expand All @@ -17,29 +19,29 @@
- OS: `CentOS Linux 8`
- kernel: `4.18.0-348.7.1.el8_5.x86_64`

| Node | Role | CPU | Memory |
| -------- | ------------- | ---- | ------ |
| master1 | control-plane | 4C | 8Gi |
| master2 | control-plane | 4C | 8Gi |
| master3 | control-plane | 4C | 8Gi |
| worker4 | | 3C | 8Gi |
| worker5 | | 3C | 8Gi |
| worker6 | | 3C | 8Gi |
| worker7 | | 3C | 8Gi |
| worker8 | | 3C | 8Gi |
| worker9 | | 3C | 8Gi |
| worker10 | | 3C | 8Gi |
| Node | Role | CPU | Memory |
| -------- | ------------- | --- | ------ |
| master1 | control-plane | 4C | 8Gi |
| master2 | control-plane | 4C | 8Gi |
| master3 | control-plane | 4C | 8Gi |
| worker4 | | 3C | 8Gi |
| worker5 | | 3C | 8Gi |
| worker6 | | 3C | 8Gi |
| worker7 | | 3C | 8Gi |
| worker8 | | 3C | 8Gi |
| worker9 | | 3C | 8Gi |
| worker10 | | 3C | 8Gi |

## 测试对象

本次测试基于 `0.3.1` 版本的 [CNI Specification](https://www.cni.dev/docs/spec/)，以 [macvlan](https://www.cni.dev/plugins/current/main/macvlan/) 搭配 Spiderpool 作为测试方案，并选择了开源社区中其它几种对接 underlay 网络的方案作为对比：

| Main CNI | Main CNI 版本 | IPAM CNI | IPAM CNI 版本 | 特点 |
| ------------------- | ------------- | ------------------------- | ------------- | ------------------------------------------------------------ |
| Main CNI | Main CNI 版本 | IPAM CNI | IPAM CNI 版本 | 特点 |
| ------------------- | ------------- | ------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| macvlan | `v1.1.1` | Spiderpool | `v0.4.1` | 集群中存在多个 IP 池，每个池中的 IP 地址都可以被集群中的任意一个节点上的 Pod 所使用，当集群中的多个 Pod 并发的从同一个池中分配 IP 地址时，存在竞争。支持托管 IP 池的全生命流程，使其同步的与工作负载创建、扩缩容、删除，弱化了过大的共享池所带来的并发或存储问题。 |
| macvlan | `v1.1.1` | Whereabouts (CRD backend) | `v0.6.1` | 各节点可以定义各自可用的 IP 池范围，若节点间存在重复定义的 IP 地址，那么这些 IP 地址上升为一种共享资源。 |
| Kube-OVN (underlay) | `v1.11.3` | Kube-OVN | `v1.11.3` | 以子网来组织 IP 地址，每个 Namespace 可以归属于特定的子网， Namespace 下的 Pod 会自动从所属的子网中获取 IP 地址。子网也是一种集群资源，同一个子网的 IP 地址可以分布在任意一个节点上。 |
| Calico | `v3.23.3` | calico-ipam (CRD backend) | `v3.23.3` | 每个节点独享一个或多个 IP block，各节点上的 Pod 仅使用本地 IP block 中的 IP 地址，节点间无任何竞争与冲突，分配的效率非常高。 |
| macvlan | `v1.1.1` | Whereabouts (CRD backend) | `v0.6.1` | 各节点可以定义各自可用的 IP 池范围，若节点间存在重复定义的 IP 地址，那么这些 IP 地址上升为一种共享资源。 |
| Kube-OVN (underlay) | `v1.11.3` | Kube-OVN | `v1.11.3` | 以子网来组织 IP 地址，每个 Namespace 可以归属于特定的子网， Namespace 下的 Pod 会自动从所属的子网中获取 IP 地址。子网也是一种集群资源，同一个子网的 IP 地址可以分布在任意一个节点上。 |
| Calico | `v3.23.3` | calico-ipam (CRD backend) | `v3.23.3` | 每个节点独享一个或多个 IP block，各节点上的 Pod 仅使用本地 IP block 中的 IP 地址，节点间无任何竞争与冲突，分配的效率非常高。 |

## 方案

Expand Down
36 changes: 19 additions & 17 deletions docs/concepts/performance.md
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
# Spiderpool Performance Testing

**English** | [**简体中文**](./performance-zh_CN.md)

*[Spiderpool](https://github.com/spidernet-io/spiderpool) is a high-performance IPAM CNI plugin for underlay networks. This report will compare its performance with the mainstream underlay IPAM CNI plugins (such as [Whereabouts](https://github.com/k8snetworkplumbingwg/whereabouts), [Kube-OVN](https://github.com/kubeovn/kube-ovn)) and the widely used overlay IPAM CNI plugin [calico-ipam](https://github.com/projectcalico/calico) under the "1000 Pod" scenario.*

## Background
Expand All @@ -17,29 +19,29 @@ Why do we need to do performance testing on the underlay IPAM CNI plugin?
- OS: `CentOS Linux 8`
- kernel: `4.18.0-348.7.1.el8_5.x86_64`

| Node | Role | CPU | Memory |
| -------- | ------------- | ---- | ------ |
| master1 | control-plane | 4C | 8Gi |
| master2 | control-plane | 4C | 8Gi |
| master3 | control-plane | 4C | 8Gi |
| worker4 | | 3C | 8Gi |
| worker5 | | 3C | 8Gi |
| worker6 | | 3C | 8Gi |
| worker7 | | 3C | 8Gi |
| worker8 | | 3C | 8Gi |
| worker9 | | 3C | 8Gi |
| worker10 | | 3C | 8Gi |
| Node | Role | CPU | Memory |
| -------- | ------------- | --- | ------ |
| master1 | control-plane | 4C | 8Gi |
| master2 | control-plane | 4C | 8Gi |
| master3 | control-plane | 4C | 8Gi |
| worker4 | | 3C | 8Gi |
| worker5 | | 3C | 8Gi |
| worker6 | | 3C | 8Gi |
| worker7 | | 3C | 8Gi |
| worker8 | | 3C | 8Gi |
| worker9 | | 3C | 8Gi |
| worker10 | | 3C | 8Gi |

## Objects

This test is based on the [CNI Specification](https://www.cni.dev/docs/spec/) `0.3.1`, using [macvlan](https://www.cni.dev/plugins/current/main/macvlan/)with Spiderpool, and selecting several other underlay network solutions in the open source community for comparison:

| Main CNI | Main CNI Version | IPAM CNI | IPAM CNI Version | Features |
| ------------------- | ---------------- | ------------------------- | ---------------- | ------------------------------------------------------------ |
| Main CNI | Main CNI Version | IPAM CNI | IPAM CNI Version | Features |
| ------------------- | ---------------- | ------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| macvlan | `v1.1.1` | Spiderpool | `v0.4.1` | There are multiple IP pools in a cluster, and the IP addresses in each pool can be used by Pods on any Node in the cluster. Competition occurs when multiple Pods in a cluster allocate IP addresses from the same pool. Support hosting the entire lifecycle of an IP pool, synchronizing it with workload creation, scaling, deletion, and reducing concurrency or storage issues caused by overly large shared pools. |
| macvlan | `v1.1.1` | Whereabouts (CRD backend) | `v0.6.1` | Each Node can define its own available IP pool ranges. If there are duplicate IP addresses defined between Nodes, these IP addresses are promoted as a shared resource. |
| Kube-OVN (underlay) | `v1.11.3` | Kube-OVN | `v1.11.3` | IP addresses are organized by Subnet. Each Namespace can belong to a specific Subnet. Pods under the Namespace will automatically obtain IP addresses from the Subnet they belong to. Subnets are also a cluster resource, and the IP addresses of the same Subnet can be distributed on any Node. |
| Calico | `v3.23.3` | calico-ipam (CRD backend) | `v3.23.3` | Each Node has one or more IP blocks exclusively, and the Pods on each Node only use the IP addresses in the local IP block. There is no competition or conflict between Nodes, and the allocation efficiency is very high. |
| macvlan | `v1.1.1` | Whereabouts (CRD backend) | `v0.6.1` | Each Node can define its own available IP pool ranges. If there are duplicate IP addresses defined between Nodes, these IP addresses are promoted as a shared resource. |
| Kube-OVN (underlay) | `v1.11.3` | Kube-OVN | `v1.11.3` | IP addresses are organized by Subnet. Each Namespace can belong to a specific Subnet. Pods under the Namespace will automatically obtain IP addresses from the Subnet they belong to. Subnets are also a cluster resource, and the IP addresses of the same Subnet can be distributed on any Node. |
| Calico | `v3.23.3` | calico-ipam (CRD backend) | `v3.23.3` | Each Node has one or more IP blocks exclusively, and the Pods on each Node only use the IP addresses in the local IP block. There is no competition or conflict between Nodes, and the allocation efficiency is very high. |

## Plan

Expand Down
Binary file added docs/images/ip-allocation-across-networks-1.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/images/ip-allocation-across-networks-2.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
2 changes: 1 addition & 1 deletion docs/usage/_feature_example_zh.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@

## 实施要求

安装要求，如 内核限制、K8S版本、第三方项目版本等，本项目安装时哪些选型要打开或关闭
安装要求，如内核限制、K8s 版本、第三方项目版本等，本项目安装时哪些选型要打开或关闭

## 步骤

Expand Down
2 changes: 1 addition & 1 deletion docs/usage/_install_example_zh.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@

## 实施要求

安装要求，如 内核限制、K8S版本、第三方项目版本等
安装要求，如内核限制、K8s 版本、第三方项目版本等

## 步骤

Expand Down
51 changes: 8 additions & 43 deletions docs/usage/gc-zh_CN.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,53 +2,18 @@

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

Spiderpool 有一个 IP 垃圾回收机制，它可以帮助清理 CNI `cmdDel` 失败后泄漏的 IP。
## 介绍

## 启用 IP 回收支持
在 Kubernetes 中，垃圾回收（Garbage Collection，简称GC）对于 IP 地址的回收非常重要。IP 地址的可用性关系到 Pod 是否能够启动成功。GC 机制可以自动回收这些不再使用的 IP 地址，避免资源浪费和 IP 地址的耗尽。本文将介绍 Spiderpool 优秀的 GC 能力。

检查 `spiderpool-controller` Kubernetes 部署的 `SPIDERPOOL_GC_IP_ENABLED` 环境属性是否已设置为 `true`（默认已启用）。
## 项目功能

```shell
kubectl edit deploy spiderpool-controller -n kube-system
```
在 IPAM 中记录了分配给 Pod 使用的 IP 地址，但是这些 Pod 在 Kubernetes 集群中已经不复存在，这些 IP 可称为 `僵尸 IP` ，Spiderpool 可针对 `僵尸 IP` 进行回收，它的实现原理如下：

## 设计
在集群中 `delete Pod` 时，但由于`网络异常`或 `cni 二进制 crash` 等问题，导致调用 `cni delete` 失败，从而导致 IP 地址无法被 cni 回收。

spiderpool-controller 使用 `Pod informer` 和定期间隔扫描所有 SpiderIPPool 实例来清理泄漏的 IP 及其相应的
SpiderEndpoint 对象。使用内存缓存来追踪应该清理的具有相应 IP 和 SpiderEndpoint 对象的 Pod。
- 在 `cni delete 失败` 等故障场景，如果一个曾经分配了 IP 的 Pod 被销毁后，但在 IPAM 中还记录分配着IP 地址，形成了僵尸 IP 的现象。Spiderpool 针对这种问题，会基于周期和事件扫描机制，自动回收这些僵尸 IP 地址。

以下是释放 IP 的几种情况：
节点意外宕机后，集群中的 Pod 永久处于 `deleting` 状态，Pod 占用的 IP 地址无法被释放。

* Pod 被 `deleted`，不包括 StatefulSet 重启其 Pod 的情况。

* Pod 正在 `Terminating`，我们将在 `spec.terminationGracePeriodSecond` 后释放其 IP，
您可以设置 `AdditionalGraceDelay`（默认为 0 秒）环境变量以添加延迟时间。
您还可以使用环境变量 `SPIDERPOOL_GC_TERMINATING_POD_IP_ENABLED`（默认已启用）确定是否回收
`Terminating` 状态的 Pod。此环境变量可能在以下两种情况中有所帮助：

1. 如果集群中的某个节点挂了，您必须依靠 IP GC 来释放这些 IP。
2. 在某些基础模式下，如果不释放正在终止 Pod 的 IP，新 Pod 将因为缺少 IP 资源无法获取可用的 IP 去运行。

然而，有一种特殊情况需要注意：如果节点由于接口或网络问题与 Master API 服务器失去连接，
则 Pod 网络仍然可以正常工作。在这种情况下，如果我们释放其 IP 并将其分配给其他 Pod，会导致 IP 冲突。

* Pod 处于 `Succeeded` 或 `Failed` 阶段，我们将在 `pod.DeletionGracePeriodSeconds` 后清理 Pod 的 IP，
您可以设置 `AdditionalGraceDelay`（默认为 0 秒）环境变量以添加延迟时间。

* SpiderIPPool 分配的 IP 所对应的 Pod 在 Kubernetes 中不存在，不包括 StatefulSet 重启其 Pod 的情况。

* Pod UID 不同于 SpiderIPPool IP 分配的 Pod UID。

## 注意事项

* `spiderpool-controller` 有多个副本并使用领导者选举。IP 垃圾回收 `pod informer` 仅为 `Master` 服务。
但是，每个备份都会使用 `scan all SpiderIPPool` 以立即释放应清理的泄漏 IP。
在上述 Pod 状态下，它不会追踪内存缓存中的 Pod。

* 我们可以使用环境变量 `SPIDERPOOL_GC_ADDITIONAL_GRACE_DELAY`（默认为 5 秒）更改追踪 Pod `AdditionalGraceDelay`。

* 如果集群中有一个节点损坏，且启用了 `SPIDERPOOL_GC_TERMINATING_POD_IP_ENABLED` 环境变量，
IP GC 将强制释放不可达的 Pod 对应的 IP。还有一种罕见情况，即在 Pod 的 `DeletionGracePeriod` 时间之后，
您的 Pod 仍然存活。IP GC 仍将强制释放无法访问的 Pod 对应的 IP。对于这两种情况，我们建议 Main CNI 具有检查
IP 冲突的功能。[Veth](https://github.com/spidernet-io/plugins) 插件已经实现了此功能，
您可以协调使用 `Macvlan` 或 `SR-IOV` CNI。
- 对处于 `Terminating` 状态的 Pod，Spiderpool 将在 Pod 的 `spec.terminationGracePeriodSecond` 后，自动释放其 IP 地址。该功能可通过环境变量 `SPIDERPOOL_GC_TERMINATING_POD_IP_ENABLED` 来控制。该能力能够用以解决 `节点意外宕机` 的故障场景。
Loading

0 comments on commit 7948a5e

Please sign in to comment.