From 66eb63c9bf8aa68e60b37a198244e3abdff8c591 Mon Sep 17 00:00:00 2001 From: "tao.yang" Date: Fri, 11 Aug 2023 10:11:39 +0800 Subject: [PATCH] [docs]: add spidersubnet usage for spiderpool Signed-off-by: tao.yang --- docs/usage/network-topology-zh_CN.md | 2 +- docs/usage/spider-subnet-zh_CN.md | 477 +++++++++++++++++++++++++++ 2 files changed, 478 insertions(+), 1 deletion(-) create mode 100644 docs/usage/spider-subnet-zh_CN.md diff --git a/docs/usage/network-topology-zh_CN.md b/docs/usage/network-topology-zh_CN.md index f78967c085..0fbc46b356 100644 --- a/docs/usage/network-topology-zh_CN.md +++ b/docs/usage/network-topology-zh_CN.md @@ -98,7 +98,7 @@ spec: - ${MACVLAN_MASTER_INTERFACE} ``` -在本文示例中，使用如上配置，创建如下的两个 Macvlan SpiderMultusConfig，将基于它自动生成的 Multus NetworkAttachmentDefinition CR，它对应了宿主机的 `eth0` 网卡。 +在本文示例中，使用如上配置，创建如下的 Macvlan SpiderMultusConfig，将基于它自动生成的 Multus NetworkAttachmentDefinition CR，它对应了宿主机的 `eth0` 网卡。 ```bash ~# ~# kubectl get spidermultusconfigs.spiderpool.spidernet.io -n kube-system diff --git a/docs/usage/spider-subnet-zh_CN.md b/docs/usage/spider-subnet-zh_CN.md new file mode 100644 index 0000000000..512d4f8608 --- /dev/null +++ b/docs/usage/spider-subnet-zh_CN.md @@ -0,0 +1,477 @@ +# SpiderSubnet + +**简体中文** | [**English**](./spider-subnet.md) + +## 介绍 + +SpiderSubnet 资源代表 IP 地址的集合，当需要为应用分配固定的 IP 地址时，应用管理员需要平台管理员告知可用的 IP 地址和路由属性等，但双方分属两个不同的运营部门，这使得每一个应用创建的工作流程繁琐，借助于 Spiderpool 的 SpiderSubnet 功能，它能自动从中子网分配 IP 给 SpiderIPPool，并且还能为应用固定 IP 地址，极大的减少了运维的成本。 + +## SpiderSubnet 功能 + +启用 Subnet 功能时，每一个 IPPool 实例都归属于子网号相同的 Subnet 实例，IPPool 实例中的 IP 地址必须是 Subnet 实例中 IP 地址的子集，IPPool 实例之间不出现重叠 IP 地址，创建 IPPool 实例时的各种路由属性，默认继承 Subnet 实例中的设置。 + +在为应用分配固定的 IP 地址时，带来了如下两种实践手段，从而完成应用管理员和网络管理员的职责解耦： + +- 手动创建 IPPool : 应用管理员手动创建 IPPool 实例时，可基于对应的 Subnet 实例中的 IP 地址约束，来获知可使用哪些 IP 地址。 + +- 自动创建 IPPool : 应用管理员可在 Pod annotation 中注明使用的 Subnet 实例名，在应用创建时，Spiderpool 会自动根据 Subnet 实例中的可用 IP 地址来创建固定 IP 的 IPPool 实例，从中分配 IP 地址给 Pod。并且 Spiderpool 能够自动监控应用的扩缩容和删除事件，自动完成 IPPool 中的 IP 地址扩缩容和删除。 + +SpiderSubnet 功能还支持众多的控制器，如：ReplicaSet、Deployment、Statefulset、Daemonset、Job、Cronjob，第三方控制器等。对于第三方控制器，您可以参考[示例](./third-party-controller.md) + +## 实施要求 + +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 ipam.enableSpiderSubnet=true --set multus.multusCNI.defaultCniCRName="macvlan-ens192" +``` + +> 如果您所在地区是中国大陆，可以指定参数 `--set global.imageRegistryOverride=ghcr.m.daocloud.io` ，以帮助您更快的拉取镜像。 +> +> 通过 `multus.multusCNI.defaultCniCRName` 指定集群的 Multus clusterNetwork，clusterNetwork 是 Multus 插件的一个特定字段，用于指定 Pod 的默认网络接口。 + +- 检查安装完成 + +```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 配置 + +Spiderpool 为简化书写 JSON 格式的 Multus CNI 配置，它提供了 SpiderMultusConfig CR 来自动管理 Multus NetworkAttachmentDefinition CR。如下是创建 Macvlan SpiderMultusConfig 配置的示例： + +- master：在此示例用接口 `ens192` 和 `ens224` 作为 master 的参数。 + +```bash +MACVLAN_MASTER_INTERFACE0="ens192" +MACVLAN_MULTUS_NAME0="macvlan-$MACVLAN_MASTER_INTERFACE0" +MACVLAN_MASTER_INTERFACE1="ens224" +MACVLAN_MULTUS_NAME1="macvlan-$MACVLAN_MASTER_INTERFACE1" + +cat < +test-app-1-74cbbf654-4f2w2 1/1 Running 0 46s 10.6.168.103 worker-node-1 + +~# kubectl get spiderippool auto4-test-app-1-eth0-a5bd3 -ojsonpath={.spec} | jq +{ + "default": false, + "disable": false, + "gateway": "10.6.0.1", + "ipVersion": 4, + "ips": [ + "10.6.168.101-10.6.168.103" + ], +... + "routes": [ + { + "dst": "10.7.0.0/16", + "gw": "10.6.0.1" + } + ], + "subnet": "10.6.0.0/16", + "vlan": 0 +} +``` + +经过多次测试，不断重启 Pod，其 Pod IP 都被固定在 IP 池范围内: + +```bash +~# kubectl delete po -l app=test-app-1 + +~# kubectl get po -l app=test-app-1 -o wide +NAME READY STATUS RESTARTS AGE IP NODE NOMINATED NODE READINESS GATES +test-app-1-74cbbf654-7v54p 1/1 Running 0 7s 10.6.168.101 worker-node-1 +test-app-1-74cbbf654-qzxp7 1/1 Running 0 7s 10.6.168.102 controller-node-1 +``` + +### 固定 IP 池 IP 数量的动态扩缩容 + +创建应用时指定了注解 `ipam.spidernet.io/ippool-ip-number`: '+1'，其表示应用分配到的固定 IP 数量比应用的副本数多 1 个，在应用滚动更新时，能够避免旧 Pod 未删除，新 Pod 没有可用 IP 的问题。 + +以下演示了扩容场景，将应用的副本数从 2 扩容到 3，应用对应的两个固定 IP 池会自动从 3 个 IP 扩容到 4 个 IP，一直保持一个冗余 IP，符合预期。 + +```bash +~# kubectl scale deploy test-app-1 --replicas 3 +deployment.apps/test-app-1 scaled + +~# kubectl get po -l app=test-app-1 -o wide +NAME READY STATUS RESTARTS AGE IP NODE NOMINATED NODE READINESS GATES +test-app-1-74cbbf654-7v54p 1/1 Running 0 54s 10.6.168.101 worker-node-1 +test-app-1-74cbbf654-9w8gd 1/1 Running 0 19s 10.6.168.103 worker-node-1 +test-app-1-74cbbf654-qzxp7 1/1 Running 0 54s 10.6.168.102 controller-node-1 + +~# kubectl get spiderippool +NAME VERSION SUBNET ALLOCATED-IP-COUNT TOTAL-IP-COUNT DEFAULT +auto4-test-app-1-eth0-a5bd3 4 10.6.0.0/16 3 4 false +``` + +通过上述，Spiderpool 对于应用扩缩容的场景，只需要修改应用的副本数即可。 + +### 自动回收 IP 池 + +创建应用时指定了注解 `ipam.spidernet.io/ippool-reclaim`，该注解默认值为 `true`，为 true 时，随着应用的删除，将自动删除对应的自动池。在本文中设置为 `false`，其表示删除应用时，自动创建的固定 IP 池不会被回收，并且当使用相同配置再次创建同名应用时，会自动继承该 IP 池。 + +```bash +~# kubectl delete deploy test-app-1 +deployment.apps "test-app-1" deleted + +~# kubectl get spiderippool +NAME VERSION SUBNET ALLOCATED-IP-COUNT TOTAL-IP-COUNT DEFAULT +auto4-test-app-1-eth0-a5bd3 4 10.6.0.0/16 0 4 false +``` + +使用上述所示的应用 Yaml，再次创建同名应用，可以观察到不会再次创建新的 IP 池，将自动复用旧 IP 池，并且其副本数和 IP 池的 IP 分配情况与实际相同。 + +```bash +~# kubectl get spiderippool +NAME VERSION SUBNET ALLOCATED-IP-COUNT TOTAL-IP-COUNT DEFAULT +auto4-test-app-1-eth0-a5bd3 4 10.6.0.0/16 2 3 false +``` + +### 自动固定多网卡 IP + +如果您希望为 Pod 实现多网卡 IP 的固定，参考本章节。在以下的示例 Yaml 中， 会创建 2 个副本的 Deployment，每个副本拥有多张网卡，其中： + +- `ipam.spidernet.io/subnets`：用于指定 Spiderpool 的子网，Spiderpool 会自动在该子网中随机选择一些 IP 来创建固定 IP 池，与本应用绑定，实现 IP 固定的效果。在本示例中该注解会为 Pod 创建 2 个属于不同 Underlay 子网的固定 IP 池。 + +- `v1.multus-cni.io/default-network`：为应用创建一张默认网卡。 + +- `k8s.v1.cni.cncf.io/networks`：为应用创建另一张网卡。 + +```bash +cat < +test-app-2-f5d6b8d6c-rvx55 1/1 Running 0 6m22s 10.6.168.105 worker-node-1 + +~# kubectl get spiderippool auto4-test-app-2-eth0-44037 -ojsonpath={.spec} | jq +{ + "default": false, + "disable": false, + "gateway": "10.6.0.1", + "ipVersion": 4, + "ips": [ + "10.6.168.101", + "10.6.168.105-10.6.168.106" + ], +... + "routes": [ + { + "dst": "10.7.0.0/16", + "gw": "10.6.0.1" + } + ], + "subnet": "10.6.0.0/16", + "vlan": 0 +} + +~# kubectl get spiderippool auto4-test-app-2-net1-44037 -ojsonpath={.spec} | jq +{ + "default": false, + "disable": false, + "gateway": "10.7.0.1", + "ipVersion": 4, + "ips": [ + "10.7.168.101-10.7.168.103" + ], +... + "routes": [ + { + "dst": "10.6.0.0/16", + "gw": "10.7.0.1" + } + ], + "subnet": "10.7.0.0/16", + "vlan": 0 +} +``` + +SpiderSubnet 也支持多网卡的动态 IP 扩缩容、自动回收 IP 池等功能。 + +## 总结 + +SpiderSubnet 功能可以帮助将基础设施管理员和应用程序管理员的责任分开，支持自动创建和动态扩展固定 IPPool 到每个需要静态 IP 的应用程序。