From f3f12ef1778f45b7d06178ea42f5f07fbb907c30 Mon Sep 17 00:00:00 2001 From: "tao.yang" Date: Mon, 18 Sep 2023 10:18:34 +0800 Subject: [PATCH] [docs]: add some usage and concepts for spiderpool Signed-off-by: tao.yang --- docs/concepts/allocation-zh_CN.md | 79 +++++ docs/concepts/allocation.md | 4 +- docs/mkdocs.yml | 1 + docs/usage/spider-affinity-zh_CN.md | 400 +++++++++++++++++++++++ docs/usage/spider-affinity.md | 5 + docs/usage/spider-multus-config-zh_CN.md | 194 +++++++++++ docs/usage/spider-multus-config.md | 2 + 7 files changed, 684 insertions(+), 1 deletion(-) create mode 100644 docs/concepts/allocation-zh_CN.md create mode 100644 docs/usage/spider-affinity-zh_CN.md create mode 100644 docs/usage/spider-affinity.md create mode 100644 docs/usage/spider-multus-config-zh_CN.md diff --git a/docs/concepts/allocation-zh_CN.md b/docs/concepts/allocation-zh_CN.md new file mode 100644 index 0000000000..5cfb5b4153 --- /dev/null +++ b/docs/concepts/allocation-zh_CN.md @@ -0,0 +1,79 @@ +# IP Allocation + +**简体中文** | [**English**](./allocation.md) + +当 Pod 创建时，它将按照以下步骤获取 IP 分配；IP 分配生命周期将经历 `获取候选池`、`过滤候选池`、`候选池排序` 三个大阶段。 + +- 获取候选池：Spiderpool 有多种池选择规则，会严格遵守 **高优先级到低优先级** 的池选择规则，获取**高优先级规则**命中的所有池，将它们标记为候选者身份，以有资格被进一步考虑。 + +- 过滤候选池：Spiderpool 通过亲和性等过滤机制，更精确地从所有候选池中选择合适的候选池，以满足特定的需求或复杂的使用场景。 + +- 候选池排序：对于多候选池，Spiderpool 根据 SpiderIPPool 对象中的优先级规则对这些候选者进行排序，然后按顺序从有空闲 IP 的 IP 池中开始选择 IP 地址进行分配。 + +## 获取候选池 + +Spiderpool 提供多种池选择规则，在为 Pod 分配 IP 地址时，会严格遵守 **高优先级到低优先级** 的池选择规则。以下规则按照从 **高优先级到低优先级** 的顺序列出，如果同时存在下面的多个规则，前一个规则将 **覆盖** 后一个规则。 + +- 优先级 1 ：SpiderSubnet 注解。 + + SpiderSubnet 资源代表 IP 地址的集合，当需要为应用分配固定的 IP 地址时，应用管理员需要平台管理员告知可用的 IP 地址和路由属性等，但双方分属两个不同的运营部门，这使得每一个应用创建的工作流程繁琐，借助于 Spiderpool 的 SpiderSubnet 功能，它能自动从中子网分配 IP 给 IPPool，并且还能为应用固定 IP 地址，极大的减少了运维的成本。创建应用时可以使用 `ipam.spidernet.io/subnets` 或 `ipam.spidernet.io/subnet` 注解指定 Subnet，从而实现从子网中随机选取 IP 地址自动创建 IP 池，并从池中分配固定 IP 地址给应用。有关详情，请参阅 [SpiderSubnet](../usage/spider-subnet-zh_CN.md)。 + +- 优先级 2 ：SpiderIPPool 注解。 + + 一个 Subnet 中的不同 IP 地址，可分别存储到不同的 IPPool 实例中（Spiderpool 会校验 IPPool 之间的地址集合不重叠）。依据需求，SpiderIPPool 中的 IP 集合可大可小。能很好的应对 Underlay 网络的 IP 地址资源有限情况，且这种设计特点，创建应用时，结合 SpiderIPPool 注解 `ipam.spidernet.io/ippools` 或 `ipam.spidernet.io/ippool` 能绑定不同的 IPPool，也能分享相同的 IPPool，既能够让所有应用共享使用同一个 Subnet，又能够实现 "微隔离"。有关详情，请参阅 [SpiderIPPool 注解](../reference/annotation.md)。 + +- 优先级 3 ：命名空间默认 IP 池。 + + 通过在命名空间中设置注解 `ipam.spidernet.io/default-ipv4-ippool` 或 `ipam.spidernet.io/default-ipv6-ippool` 指定默认的 IP 池。在该租户中创建应用时，如果没有其他高优先级的池规则，那么将从该租户可用的候选池中尝试分配 IP 地址。有关详情，请参阅 [命名空间注解](../reference/annotation.md)。 + +- 优先级 4 ：CNI 配置文件。 + + 通过在 CNI 配置文件中的 `default_ipv4_ippool` 和 `default_ipv6_ippool` 字段设置全局的 CNI 默认池，其可以设置多个 IP 池用作备选池，当应用使用该 CNI 配置网络时并调用 Spiderpool ，对于每个应用副本，Spiderpool 都会按照 "IP 池数组" 中元素的顺序依次尝试分配 IP 地址，在每个节点分属不同的地区或数据中心的场景，如果应用副本被调度到的节点，符合第一个 IP 池的节点亲和规则，Pod 会从该池中获得 IP 分配，如果不满足，Spiderpool 会尝试从备选池中选择 IP 池继续为 Pod 分配 IP ，直到所有备选池全部筛选失败。详细信息请参考[CNI 配置](../reference/plugin-ipam.md)。 + +- 优先级 5 ：集群默认 IPPool。 + + 在 SpiderIPPool CR 对象中，可以通过将 **spec.default** 字段设置为 `true`，将池设置为集群默认 IPPool，默认为 `false`。详细信息请参考[集群默认 IPPool](../reference/crd-spiderippool.md) + +## 过滤候选池 + +通过上述的池选择规则，获得 IPv4 和 IPv6 的 IPPool 候选后，Spiderpool 会根据以下规则进行过滤，了解哪个候选 IPPool 可用。 + +- IP 池处于候选者身份，但其处于 `terminating` 状态的，Spiderpool 将会过滤该池。 + +- IP 池的 `spec.disable` 字段用于设置 IPPool 是否可用，当该值为 `false` 时，意味着 IPPool 不可使用。 + +- 检查 `IPPool.Spec.NodeName` 和 `IPPool.Spec.NodeAffinity` 属性是否与 Pod 的调度节点匹配。 如果不匹配，则该 IPPool 将被过滤。 + +- 检查 `IPPool.Spec.NamespaceName` 和 `IPPool.Spec.NamespaceAffinity` 属性是否与 Pod 的命名空间匹配。如果不匹配，则该 IPPool 将被过滤。 + +- 检查 `IPPool.Spec.PodAffinity` 属性是否与 Pod 的 `matchLabels` 所匹配。如果不匹配，则该 IPPool 将被过滤。 + +- 检查 `IPPool.Spec.MultusName` 属性是否与 Pod 当前 NIC Multus 配置匹配。如果不匹配，则该 IPPool 将被过滤。 + +- 检查 IPPool 所有 IP 是不是都被 IPPool 实例的 `exclude_ips` 字段所包含，如果是，则该 IPPool 将被过滤。 + +- 检查 IPPool 所有 IP 是不是都被 ReservedIP 实例所保留了，如果是，则该 IPPool 将被过滤。 + +- IPPool 的可用 IP 资源被耗尽，则该 IPPool 也将被过滤。 + +## 候选池排序 + +过滤候选池后，可能仍存在多个候选池，Spiderpool 会进一步使用自定义优先级规则对这些候选者进行排序，然后按顺序从有空闲 IP 的 IP 池中开始选择 IP 地址进行分配。 + +- 具有 `IPPool.Spec.PodAffinity` 属性的 IPPool 资源具有最高优先级。 + +- 具有 `IPPool.Spec.NodeName` 或 `IPPool.Spec.NodeAffinity` 属性的 IPPool 资源具有第二高优先级。（`NodeName` 的优先级高于 `NodeAffinity`）。 + +- 具有 `IPPool.Spec.NamespaceName` 或 `IPPool.Spec.NamespaceAffinity` 属性的 IPPool 资源具有第三高优先级。（`NamespaceName` 的优先级高于 `NamespaceAffinity`）。 + +- 具有 `IPPool.Spec.MultusName` 属性的 IPPool 资源具有最低优先级。 + +> 注意：这里有一些简单的例子来描述这个规则。 +> +> 1. 具有属性 `IPPool.Spec.PodAffinity` 和 `IPPool.Spec.NodeName` 的 _IPPoolA_ 的优先级高于具有单一关联属性 `IPPool.Spec.PodAffinity` 的 _IPPoolB_。 +> 2. 具有单个属性 `IPPool.Spec.PodAffinity` 的 _IPPoolA_ 的优先级高于具有属性 `IPPool.Spec.NodeName` 和 `IPPool.Spec.NamespaceName` 的 _IPPoolB_。 +> 3. 具有属性 `IPPool.Spec.PodAffinity` 和 `IPPool.Spec.NodeName` 的 _IPPoolA_ 的优先级高于具有属性 `IPPool.Spec.PodAffinity`、`IPPool.Spec.NamespaceName` 和 `IPPool.Spec.MultusName` 的 _IPPoolB_ 。 + +NOTE： + +> 如果 Pod 属于 StatefulSet，则会优先分配符合上面规则的 IP 地址。 一旦 Pod 重新启动，它将尝试重用最后分配的 IP 地址。 diff --git a/docs/concepts/allocation.md b/docs/concepts/allocation.md index d511419d0e..ae2b0e4963 100644 --- a/docs/concepts/allocation.md +++ b/docs/concepts/allocation.md @@ -1,5 +1,7 @@ # IP Allocation +**English** | [**简体中文**](./allocation-zh_CN.md) + When a pod is creating, it will follow steps below to get IP allocations. 1. Get all IPPool candidates. @@ -32,7 +34,7 @@ When a pod is creating, it will follow steps below to get IP allocations. * The IPPool resource with `IPPool.Spec.NodeName` or `IPPool.Spec.NodeAffinity` property has the second-highest priority. * The IPPool resource with `IPPool.Spec.NamespaceName` or `IPPool.Spec.NamespaceAffinity` property has the second-highest priority. * The IPPool resource with `IPPool.Spec.MultusName` property has the lowest priority. - + > Notice: here are some simple instance to describe this rule. > > 1. *IPPoolA* with properties `IPPool.Spec.PodAffinity` and `IPPool.Spec.NodeName` has higher priority than *IPPoolB* with single affinity property `IPPool.Spec.PodAffinity`. diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index a6e7e22859..3ef5a62793 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -67,6 +67,7 @@ nav: - SpiderSubnet: usage/spider-subnet.md - SpiderMultusConfig: usage/spider-multus-config.md - Default IPPool at namespace: usage/ippool-namespace.md + - Spider Affinity of IPPool: usage/spider-affinity.md - Multiple interfaces: usage/multi-interfaces-annotation.md - Backup IPPool: usage/ippool-multi.md - Namespace affinity of IPPool: usage/ippool-affinity-namespace.md diff --git a/docs/usage/spider-affinity-zh_CN.md b/docs/usage/spider-affinity-zh_CN.md new file mode 100644 index 0000000000..495df8bfc9 --- /dev/null +++ b/docs/usage/spider-affinity-zh_CN.md @@ -0,0 +1,400 @@ +# SpiderIPPool Affinity + +**简体中文** | [**English**](./spider-affinity.md) + +## 介绍 + +SpiderIPPool 资源代表 IP 地址的集合，一个 Subnet 中的不同 IP 地址，可分别存储到不同的 IPPool 实例中（Spiderpool 会校验 IPPool 之间的地址集合不重叠）。因此，依据需求，SpiderIPPool 中的 IP 集合可大可小。能很好的应对 Underlay 网络的 IP 地址资源有限情况，且这种设计特点，能够通过各种亲和性规则让不同的应用、租户来绑定不同的 SpiderIPPool，也能分享相同的 SpiderIPPool，既能够让所有应用共享使用同一个 Subnet，又能够实现 "微隔离"。 + +## SpiderIPPool Affinity 功能 + +关于 SpiderIPPool Affinity 功能的一些优先级、匹配规则等信息，可以参考[概念文档](../concepts/allocation-zh_CN.md)。 + +## 步骤 + +### 安装 Spiderpool + +按照[安装指南](./install/underlay/get-started-kind.md)安装 Spiderpool。 + +### SpiderIPPool 节点亲和性 + +不同的 node 上，可用的 IP 范围也许并不相同，例如： + +- 同一数据中心内，集群接入的 node 分属不同 subnet 。 + +- 单个集群中，node 跨越了不同的数据中心。 + +在以上场景中，当同一个应用的不同副本被调度到了不同的 node 上，需要分配不同 subnet 下的 underlay IP 地址。在当前社区现有方案，它们并不能满足这样的需求。 + +对此，Spiderpool 提供一种节点亲和的方式，能很好的解决上述问题。Spiderpool 的 SpiderIPPool CR 中，提供了 `nodeAffinity` 与 `nodeName` 字段，用于设置 node label selector，从而实现 IPPool 和 node 之间亲和性，当 Pod 被调度到某个 node 上后，IPAM 插件能够从亲和的 IPPool 中进行 IP 地址分配。 + +### SpiderIPPool 租户亲和性 + +管理员往往会在集群划分多租户，能更好地隔离、管理和协作，同时也能提供更高的安全性、资源利用率和灵活性等。需要不同功能的应用部署在不同租户下，对此，期望实现一个 IPPool 能同一个或者多个 namespace 下的应用实现亲和，而拒绝不相干租户的应用创建，能帮助管理员减少运维负担。 + +当前社区中并没有解决上述场景的有效方案，Spiderpool 通过设置 SpiderIPPool CR 中的 `namespaceAffinity` 或 `namespaceName` 字段，实现同一个或者多个租户的亲和性，从而使得满足条件的应用才能够从 IPPool 中分配到 IP 地址。 + +### SpiderIPPool 应用亲和性 + +在集群中，防火墙通常用于管理南北向通信，即集群内部和外部网络之间的通信。为了实现安全管控，防火墙需要对通信流量进行检查和过滤，并对出口通信进行限制。由于防火墙安全管控，一组 Deployment 它的所有 Pod 期望能够在一个固定的 IP 地址范围内轮滚分配 IP 地址，以配合防火墙的放行策略，从而实现 Underlay 网络下的南北通信。 + +在社区现有方案中，是通过在 Deployment 上写关于 IP 地址的注解来实现。但这种方式存在一些缺点，如： + +- 随着应用的扩容，需要人为手动的修改应用的 annotaiton ，重新规划 IP 地址。 + +- annotaiton 方式的 IP 管理，脱钩于它们自身的 IPPool CR 机制，形成管理上的空白，无法获知哪些 IP 可用。 + +- 不同应用间极其容易分配了冲突的 IP 地址，从而导致应用创建失败。 + +对此，Spiderpool 借助于 IPPool 的 IP 集合可大可小的特点，并结合设置 IPPool 的 `podAffinity`，可实现同一组或者多组应用的亲和绑定，既保证了 IP 管理方式的统一，又解耦 "应用扩容" 和 "IP地址扩容"，也固定了应用的 IP 使用范围。 + +## 节点亲和性 + +### 创建节点亲和的 IPPool + +- SpiderIPPool 提供了 `nodeAffinity` 字段，当 Pod 在某个节点上启动，尝试从 SpiderIPPool 分配 IP 时，若 Pod 所在节点符合该 nodeAffinity 设置，则能从该 SpiderIPPool 中成功分配出 IP，否则无法从该 SpiderIPPool 中分配出IP。 + +依据如上所述，使用如下的 Yaml，创建如下具备节点亲和的 SpiderIPPool，它将为在运行该节点上的 Pod 提供 IP 地址。 + +```bash +~# cat < node2 +test-app-1-br5gw 0/1 ContainerCreating 0 115s master +test-app-1-dvhrx 1/1 Running 0 115s 10.6.168.108 node1 +``` + +## 租户亲和性 + +### 创建租户 + +```bash +~# kubectl create ns test-ns1 +namespace/test-ns1 created +~# kubectl create ns test-ns2 +namespace/test-ns2 created +``` + +#### 创建租户亲和的 IPPool + +使用如下的 Yaml，创建租户亲和的 IPPool。 + +- SpiderIPPool 提供了 `namespaceAffinity` 字段，当应用创建时，尝试从 SpiderIPPool 分配 IP 时，若 Pod 所在租户符合该 namespaceAffinity 设置，则能从该 SpiderIPPool 中成功分配出 IP，否则无法从该 SpiderIPPool 中分配出IP。 + +```bash +~# cat < +``` + +创建一个不在上述 `test-ns1` 租户内的应用，Spiderpool 将会拒绝为其分配 IP 地址，自动拒绝不相干租户的应用使用该 IPPool。 + +```bash +cat < node2 +``` + +## 应用亲和性 + +### 创建应用亲和性的 IPPool + +- SpiderIPPool 提供了 `podAffinity` 字段，当应用创建时，尝试从 SpiderIPPool 分配 IP 时，若 Pod 的 `selector.matchLabels` 符合该 podAffinity 设置，则能从该 SpiderIPPool 中成功分配出 IP，否则无法从该 SpiderIPPool 中分配出IP。 + +依据如上所述，使用如下的 Yaml，创建如下具备应用亲和的 SpiderIPPool，它将为 `selector.matchLabel` 为 `app: test-app-3` 的 Pod 提供 IP 地址。 + +```bash +~# cat < +``` + +创建另一个应用，并指定一个不符合 IPPool 应用亲和的 matchLabels ，Spiderpool 将会拒绝为其分配 IP 地址。 + +- `matchLabels`: 设置应用的 Label 为 `test-unmatch-labels`，不匹配 IPPool 亲和性。 + +```bash +cat < node1 +``` + +## 总结 + +SpiderIPPool 中的 IP 集合可大可小。能很好的应对 Underlay 网络的 IP 地址资源有限情况，且这种设计特点，能够通过各种亲和性规则让不同的应用、租户来绑定不同的 SpiderIPPool，也能分享相同的 SpiderIPPool，既能够让所有应用共享使用同一个 Subnet，又能够实现 "微隔离"。 diff --git a/docs/usage/spider-affinity.md b/docs/usage/spider-affinity.md new file mode 100644 index 0000000000..9e130ac1f5 --- /dev/null +++ b/docs/usage/spider-affinity.md @@ -0,0 +1,5 @@ +# SpiderIPPool Affinity + +**English** ｜ [**简体中文**](./spider-affinity-zh_CN.md) + +TODO diff --git a/docs/usage/spider-multus-config-zh_CN.md b/docs/usage/spider-multus-config-zh_CN.md new file mode 100644 index 0000000000..0d0148515e --- /dev/null +++ b/docs/usage/spider-multus-config-zh_CN.md @@ -0,0 +1,194 @@ +# SpiderMultusConfig + +**简体中文** | [**English**](./spider-multus-config.md) + +## 介绍 + +Spiderpool 提供了 Spidermultusconfig CR 来自动管理 Multus NetworkAttachmentDefinition CR ，实现了对开源项目 Multus CNI 配置管理的扩展。 + +## SpiderMultusConfig 功能 + +Multus 是一个 CNI 插件项目，它通过调度第三方 CNI 项目，能够实现为 Pod 接入多张网卡。并且，Multus 可以通过 CRD 方式管理 CNI 配置，避免在每个主机上手动编辑 CNI 配置文件。但创建 Multus CR 时，需要手动书写 JSON 格式的 CNI 配置字符串。将会导致如下问题。 + +- 人为书写容易出现 JSON 格式错误，增加 Pod 启动失败的排障成本。 + +- CNI 种类多，并且它们的各个配置项也很多，不容易记忆，经常需要进行资料查阅，用户体验不友好。 + +Spidermultusconfig CR 基于 `spec` 中的定义自动生成 Multus CR，改进了如上问题，并且具备如下的一些特点： + +- 误操作删除 Multus CR，Spidermultusconfig 将会自动重建；提升运维容错能力。 + +- 支持众多 CNI，如 Macvlan、IPvlan、Ovs、SRIOV。 + +- 支持通过注解 `multus.spidernet.io/cr-name` 自定义 Multus CR 的名字。 + +- 支持通过注解 `multus.spidernet.io/cni-version` 自定义设置 CNI 的版本。 + +- 完善的 Webhook 机制，提前规避一些人为错误，降低后续排障成本。 + +- 支持 Spiderpool 的 CNI plugin：[ifacer](./ifacer-zh_CN.md) 、[coordinator](coordinator-zh_CN.md) ，提高了 Spiderpool 的 CNI plugin 的配置体验。 + +NOTE: + +> 在已存在 Multus CR 实例时，创建与其同名 Spidermultusconfig CR ，Multus CR 实例将会被纳管，其配置内容将会被覆盖。如果不想发生被覆盖的情况，请避免创建与存量 Multus CR 实例同名的 Spidermultusconfig CR 实例或者在 Spidermultusconfig CR 中指定 `multus.spidernet.io/cr-name` 以更改自动生成的 Multus CR 的名字。 + +## 实施要求 + +1. 一套 Kubernetes 集群。 + +2. 已安装 [Helm](https://helm.sh/docs/intro/install/)。 + +## 步骤 + +### 安装 Spiderpool + +- 通过 helm 安装 Spiderpool。 + +```bash +helm repo add spiderpool https://spidernet-io.github.io/spiderpool +helm repo update spiderpool +helm install spiderpool spiderpool/spiderpool --namespace kube-system +``` + +> 如果您所在地区是中国大陆，可以指定参数 `--set global.imageRegistryOverride=ghcr.m.daocloud.io` ，以帮助您更快的拉取镜像。 + +- 检查安装完成 + +```bash +~# kubectl get po -n kube-system | grep spiderpool +NAME READY STATUS RESTARTS AGE +spiderpool-agent-7hhkz 1/1 Running 0 13m +spiderpool-agent-kxf27 1/1 Running 0 13m +spiderpool-controller-76798dbb68-xnktr 1/1 Running 0 13m +spiderpool-init 0/1 Completed 0 13m +spiderpool-multus-7vkm2 1/1 Running 0 13m +spiderpool-multus-rwzjn 1/1 Running 0 13m +``` + +### 创建 CNI 配置 + +SpiderMultusConfig CR 支持的 CNI 类型众多，跟随下面章节了解，进行创建。 + +#### 创建 Macvlan 配置 + +如下是创建 Macvlan SpiderMultusConfig 配置的示例： + +- master：在此示例用接口 `ens192` 作为 master 的参数。 + +```bash +MACVLAN_MASTER_INTERFACE="ens192" +MACVLAN_MULTUS_NAME="macvlan-$MACVLAN_MASTER_INTERFACE" + +cat <