From 8d9f2d30e34c1af966d326d8abdd8a011e5b5ed8 Mon Sep 17 00:00:00 2001 From: Icarus9913 Date: Tue, 31 Oct 2023 16:06:40 +0800 Subject: [PATCH] integrade IPPool docs Signed-off-by: Icarus9913 --- docs/mkdocs.yml | 4 +- docs/reference/crd-spiderippool.md | 4 + docs/usage/ippool-multi.md | 89 ------------ docs/usage/ippool-namespace.md | 70 --------- docs/usage/ipv6.md | 211 ---------------------------- docs/usage/readme-zh_CN.md | 4 +- docs/usage/readme.md | 4 +- docs/usage/route-zh_CN.md | 65 +++++++++ docs/usage/spider-affinity-zh_CN.md | 33 +++++ docs/usage/spider-ippool-zh_CN.md | 174 +++++++++++++++++++++++ docs/usage/spider-ippool.md | 3 + 11 files changed, 284 insertions(+), 377 deletions(-) delete mode 100644 docs/usage/ippool-multi.md delete mode 100644 docs/usage/ippool-namespace.md delete mode 100644 docs/usage/ipv6.md create mode 100644 docs/usage/spider-ippool-zh_CN.md create mode 100644 docs/usage/spider-ippool.md diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 3ada4a805e..472319085d 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -64,16 +64,14 @@ nav: - Upgrading: usage/install/upgrade.md - Usage: - SpiderMultusConfig: usage/spider-multus-config.md - - IPAM of IPPool Namespace: usage/ippool-namespace.md + - IPAM of SpiderIPPool: usage/spider-ippool.md - IPAM of IPPool Affinity: usage/spider-affinity.md - - IPAM of Backup IPPool: usage/ippool-multi.md - IPAM of SpiderSubnet: usage/spider-subnet.md - IPAM for custom controllers: usage/third-party-controller.md - IPAM for StatefulSet: usage/statefulset.md - IPAM of Reserved IP: usage/reserved-ip.md - MultipleInterfaces: usage/multi-interfaces-annotation.md - Egress Policy: usage/egress.md - - IPv6 Support: usage/ipv6.md - Route Support: usage/route.md - Service Support: usage/service.md - Plugin coordinator: usage/coordinator.md diff --git a/docs/reference/crd-spiderippool.md b/docs/reference/crd-spiderippool.md index f1d88d5512..576f7be06e 100644 --- a/docs/reference/crd-spiderippool.md +++ b/docs/reference/crd-spiderippool.md @@ -83,3 +83,7 @@ For details on configuring SpiderIPPool namespaceAffinity or namespaceName, plea For details on configuring SpiderIPPool nodeAffinity or nodeName, please read the [Node Affinity of IPPool](../usage/spider-affinity.md) and [Network topology allocation](./../usage/network-topology.md). > Notice: `nodeName` has higher priority than `nodeAffinity`. + +### Multus Affinity + +For details on configuring SpiderIPPool multusName, please read the [multus Affinity of IPPool](../usage/spider-affinity.md). diff --git a/docs/usage/ippool-multi.md b/docs/usage/ippool-multi.md deleted file mode 100644 index 204356afc8..0000000000 --- a/docs/usage/ippool-multi.md +++ /dev/null @@ -1,89 +0,0 @@ -# Backup IPPool - -Multiple IP pools can be set for a Pod for the usage of backup IP resources. - -## Get Started - -### Set up Spiderpool - -Follow the guide [installation](./install/underlay/get-started-kind.md) to install Spiderpool. - -### Backup IPPool effect - -Create two IPPools each containing 2 IP addresses. - -```bash -kubectl apply -f https://raw.githubusercontent.com/spidernet-io/spiderpool/main/docs/example/ippool-multi/test-ipv4-ippools.yaml -``` - -Create a Pod and allocate an IP address to it from these IPPools. - -```bash -kubectl apply -f https://raw.githubusercontent.com/spidernet-io/spiderpool/main/docs/example/ippool-multi/dummy-pod.yaml -``` - -You will find that you still have 3 available IP addresses, one in IPPool `default-ipv4-ippool` and two in IPPool `backup-ipv4-ippool`. - -```bash -kubectl get sp -l case=backup -NAME VERSION SUBNET ALLOCATED-IP-COUNT TOTAL-IP-COUNT DISABLE -backup-ipv4-ippool 4 172.18.42.0/24 0 2 false -default-ipv4-ippool 4 172.18.41.0/24 1 2 false -``` - -Then, create a Deployment with 2 replicas and allocate IP addresses to its Pods from the two IPPools above. - -```bash -kubectl apply -f https://raw.githubusercontent.com/spidernet-io/spiderpool/main/docs/example/ippool-multi/multi-ippool-deploy.yaml -``` - -```yaml -apiVersion: apps/v1 -kind: Deployment -metadata: - name: multi-ippool-deploy -spec: - replicas: 2 - selector: - matchLabels: - app: multi-ippool-deploy - template: - metadata: - annotations: - ipam.spidernet.io/ippool: |- - { - "ipv4": ["default-ipv4-ippool", "backup-ipv4-ippool"] - } - labels: - app: multi-ippool-deploy - spec: - containers: - - name: multi-ippool-deploy - image: busybox - imagePullPolicy: IfNotPresent - command: ["/bin/sh", "-c", "trap : TERM INT; sleep infinity & wait"] -``` - -Spiderpool will successively try to allocate IP addresses **in the order of** the elements in the "IP pool array" until the first allocation succeeds or all fail. Of course, you can specify the [pool selection rules](TODO) (that defines alternative IP pools) in many ways, the Pod annotation `ipam.spidernet.io/ippool` is used here to select IP pools. - -Finally, when addresses in IPPool `default-ipv4-ippool` are used up, the IPPool `backup-ipv4-ippool` takes over. - -```bash -kubectl get se -NAME INTERFACE IPV4POOL IPV4 IPV6POOL IPV6 NODE CREATETION TIME -dummy eth0 default-ipv4-ippool 172.18.41.41/24 spider-worker 1m20s -multi-ippool-deploy-669bf7cf79-4x88m eth0 default-ipv4-ippool 172.18.41.40/24 spider-worker 2m31s -multi-ippool-deploy-669bf7cf79-k7zkk eth0 backup-ipv4-ippool 172.18.42.41/24 spider-worker 2m31s -``` - -### Clean up - -Clean the relevant resources so that you can run this tutorial again. - -```bash -kubectl delete \ --f https://raw.githubusercontent.com/spidernet-io/spiderpool/main/docs/example/ippool-multi/test-ipv4-ippools.yaml \ --f https://raw.githubusercontent.com/spidernet-io/spiderpool/main/docs/example/ippool-multi/dummy-pod.yaml \ --f https://raw.githubusercontent.com/spidernet-io/spiderpool/main/docs/example/ippool-multi/multi-ippool-deploy.yaml \ ---ignore-not-found=true -``` diff --git a/docs/usage/ippool-namespace.md b/docs/usage/ippool-namespace.md deleted file mode 100644 index 50ec85aa53..0000000000 --- a/docs/usage/ippool-namespace.md +++ /dev/null @@ -1,70 +0,0 @@ -# Namespace default IPPool - -*Spiderpool provides default IP pools at Namespace level. A Pod not configured with a [pool selection rule](TODO) of higher priority will be assigned with IP addresses from the default IP pools of its Namespace.* - -## Set up Spiderpool - -If you have not deployed Spiderpool yet, follow the guide [installation](./install/underlay/get-started-kind.md) for instructions on how to deploy and easily configure Spiderpool. - -## Get started - -1. Create a Namespace named as `test-ns1`. - - ```bash - kubectl create ns test-ns1 - ``` - -2. Create an IPPool to be bound with Namespace `test-ns1`. - - ```bash - kubectl apply -f https://raw.githubusercontent.com/spidernet-io/spiderpool/main/docs/example/ippool-namespace/ns1-default-ipv4-ippool.yaml - ``` - -3. Check the status of this IPPool with the following command. - - ```bash - kubectl get sp -l case=ns - NAME VERSION SUBNET ALLOCATED-IP-COUNT TOTAL-IP-COUNT DISABLE - ns1-default-ipv4-ippool 4 172.18.41.0/24 0 4 false - ``` - -4. Specify pool selection rules for Namespace `test-ns1` with the following command and annotation. - - ```bash - kubectl patch ns test-ns1 --patch-file https://raw.githubusercontent.com/spidernet-io/spiderpool/main/docs/example/ippool-namespace/ns1-ippool-selection-patch.yaml - ``` - - ```yaml - metadata: - annotations: - ipam.spidernet.io/default-ipv4-ippool: '["ns1-default-ipv4-ippool"]' - ``` - -5. Create a Deployment with 3 replicas in the Namespace `test-ns1`. - - ```bash - kubectl apply -f https://raw.githubusercontent.com/spidernet-io/spiderpool/main/docs/example/ippool-namespace/ns1-default-ippool-deploy.yaml - ``` - -Now, all Pods in the Namespace should have been assigned with an IP address from the specified IPPool. Verify it with the following command: - -```bash -kubectl get se -n test-ns1 -NAME INTERFACE IPV4POOL IPV4 IPV6POOL IPV6 NODE CREATETION TIME -ns1-default-ippool-deploy-7cd5449c88-9xncm eth0 ns1-default-ipv4-ippool 172.18.41.41/24 spider-worker 57s -ns1-default-ippool-deploy-7cd5449c88-dpfjs eth0 ns1-default-ipv4-ippool 172.18.41.43/24 spider-worker 57s -ns1-default-ippool-deploy-7cd5449c88-vjtdd eth0 ns1-default-ipv4-ippool 172.18.41.42/24 spider-worker 58s -``` - -The Namespace annotation `ipam.spidernet.io/defaultv4ippool` also supports the syntax of [alternative IP pools](ippool-multi.md), which means **you can specify multiple default IP pools for a Namespace**. In addition, one IPPool can be specified as the default IP pool for different Namespaces. - -> If you want to bind an IPPool to a specific Namespace in an **exclusive** way, it means that no Namespace other than this (or a group of Namespaces) has permission to use this IPPool, please refer to [SpiderIPPool namespace affinity](https://github.com/spidernet-io/spiderpool/blob/main/docs/usage/spider-affinity.md). - -## Clean up - -Clean relevant resources so that you can run this tutorial again. - -```bash -kubectl delete ns test-ns1 -kubectl delete -f https://raw.githubusercontent.com/spidernet-io/spiderpool/main/docs/example/ippool-namespace/ns1-default-ipv4-ippool.yaml --ignore-not-found=true -``` diff --git a/docs/usage/ipv6.md b/docs/usage/ipv6.md deleted file mode 100644 index 63b3ac8104..0000000000 --- a/docs/usage/ipv6.md +++ /dev/null @@ -1,211 +0,0 @@ -# IPv6 support - -## Description - -Spiderpool supports: - -- **Dual stack** - - Each workload can get IPv4 and IPv6 addresses, and can communicate over IPv4 or IPv6. - -- **IPv4 only** - - Each workload can acquire IPv4 addresses, and can communicate over IPv4. - -- **IPv6 only** - - Each workload can acquire IPv6 addresses, and can communicate over IPv6. - -## Get Started - -### Set up Spiderpool - -follow the guide [installation](./install/underlay/get-started-kind.md) to install Spiderpool. - -### Create SpiderSubnet - -Create a SpiderSubnet and allocate IP addresses from the IPPool. - -```bash -kubectl apply -f https://raw.githubusercontent.com/spidernet-io/spiderpool/main/docs/example/basic/custom-ipv4-subnet.yaml - -kubectl apply -f https://raw.githubusercontent.com/spidernet-io/spiderpool/main/docs/example/basic/custom-ipv6-subnet.yaml -``` - -```yaml -apiVersion: spiderpool.spidernet.io/v2beta1 -kind: SpiderSubnet -metadata: - name: custom-ipv4-subnet -spec: - subnet: 172.18.41.0/24 - ips: - - 172.18.41.40-172.18.41.50 -``` - -```yaml -apiVersion: spiderpool.spidernet.io/v2beta1 -kind: SpiderSubnet -metadata: - name: custom-ipv6-subnet -spec: - subnet: fd00:172:18::/64 - ips: - - fd00:172:18::40-fd00:172:18::50 - -``` - -### Create Deployment By Subnet - -create a Deployment whose Pods are setting the Pod annotation `ipam.spidernet.io/subnet` to explicitly specify the subnet. - -```bash -kubectl apply -f https://raw.githubusercontent.com/spidernet-io/spiderpool/main/docs/example/basic/custom-dual-subnet-deploy.yaml -``` - -```yaml -apiVersion: apps/v1 -kind: Deployment -metadata: - name: custom-dual-subnet-deploy -spec: - replicas: 3 - selector: - matchLabels: - app: custom-dual-subnet-deploy - template: - metadata: - annotations: - ipam.spidernet.io/subnet: |- - { - "ipv4": ["custom-ipv4-subnet"],"ipv6": ["custom-ipv6-subnet"] - } - labels: - app: custom-dual-subnet-deploy - spec: - containers: - - name: custom-dual-subnet-deploy - image: busybox - imagePullPolicy: IfNotPresent - command: ["/bin/sh", "-c", "trap : TERM INT; sleep infinity & wait"] - -``` - -The Pods are running. - -```bash -kubectl get pod -l app=custom-dual-subnet-deploy -owide -NAME READY STATUS RESTARTS AGE IP NODE NOMINATED NODE READINESS GATES -custom-dual-subnet-deploy-7fdbccfbb8-h5l4d 1/1 Running 0 33s 172.18.41.41 controller-node-1 -custom-dual-subnet-deploy-7fdbccfbb8-rhdbd 1/1 Running 0 33s 172.18.41.42 controller-node-1 -custom-dual-subnet-deploy-7fdbccfbb8-t6m5c 1/1 Running 0 33s 172.18.41.40 controller-node-1 -``` - -View all IPs of Pods - -```bash -kubectl get pod -l app=custom-dual-subnet-deploy -o go-template='{{range .items}}{{.metadata.name}}: {{range .status.podIPs}}{{.}} {{end}}{{"\n"}}{{end}}' -custom-dual-subnet-deploy-7fdbccfbb8-h5l4d: map[ip:172.18.41.41] map[ip:fd00:172:18::42] -custom-dual-subnet-deploy-7fdbccfbb8-rhdbd: map[ip:172.18.41.42] map[ip:fd00:172:18::41] -custom-dual-subnet-deploy-7fdbccfbb8-t6m5c: map[ip:172.18.41.40] map[ip:fd00:172:18::40] -``` - -### Create Deployment By IPPool - -1. Create IPPool - - ```bash - kubectl apply -f https://raw.githubusercontent.com/spidernet-io/spiderpool/main/docs/example/basic/custom-ipv4-ippool.yaml - - kubectl apply -f https://raw.githubusercontent.com/spidernet-io/spiderpool/main/docs/example/basic/custom-ipv6-ippool.yaml - ``` - - ```yaml - apiVersion: spiderpool.spidernet.io/v2beta1 - kind: SpiderIPPool - metadata: - name: custom-ipv4-ippool - spec: - subnet: 172.18.41.0/24 - ips: - - 172.18.41.40-172.18.41.50 - ``` - - ```yaml - apiVersion: spiderpool.spidernet.io/v2beta1 - kind: SpiderIPPool - metadata: - name: custom-ipv6-ippool - spec: - subnet: fd00:172:18::/64 - ips: - - fd00:172:18::40-fd00:172:18::50 - ``` - -2. Create Deployment - - create a Deployment whose Pods are setting the Pod annotation `ipam.spidernet.io/ippool` to explicitly specify the pool. - - ```bash - kubectl apply -f https://raw.githubusercontent.com/spidernet-io/spiderpool/main/docs/example/basic/custom-dual-ippool-deploy.yaml - ``` - - ```yaml - apiVersion: apps/v1 - kind: Deployment - metadata: - name: custom-dual-ippool-deploy - spec: - replicas: 3 - selector: - matchLabels: - app: custom-dual-ippool-deploy - template: - metadata: - annotations: - ipam.spidernet.io/ippool: |- - { - "ipv4": ["custom-ipv4-ippool"],"ipv6": ["custom-ipv6-ippool"] - } - labels: - app: custom-dual-ippool-deploy - spec: - containers: - - name: custom-dual-ippool-deploy - image: busybox - imagePullPolicy: IfNotPresent - command: ["/bin/sh", "-c", "trap : TERM INT; sleep infinity & wait"] - ``` - - The Pods are running. - - ```bash - kubectl get pod -owide -l app=custom-dual-ippool-deploy - NAME READY STATUS RESTARTS AGE IP NODE NOMINATED NODE READINESS GATES - custom-dual-ippool-deploy-9bb6696c4-6wjnl 1/1 Running 0 76s 172.18.41.42 controller-node-1 - custom-dual-ippool-deploy-9bb6696c4-8vtpf 1/1 Running 0 76s 172.18.41.45 controller-node-1 - custom-dual-ippool-deploy-9bb6696c4-zbknv 1/1 Running 0 76s 172.18.41.43 controller-node-1 - ``` - - View all IPs of Pods - - ```bash - kubectl get pod -l app=custom-dual-ippool-deploy -o go-template='{{range .items}}{{.metadata.name}}: {{range .status.podIPs}}{{.}} {{end}}{{"\n"}}{{end}}' - custom-dual-ippool-deploy-9bb6696c4-6wjnl: map[ip:172.18.41.42] map[ip:fd00:172:18::4d] - custom-dual-ippool-deploy-9bb6696c4-8vtpf: map[ip:172.18.41.45] map[ip:fd00:172:18::4e] - custom-dual-ippool-deploy-9bb6696c4-zbknv: map[ip:172.18.41.43] map[ip:fd00:172:18::46] - ``` - -### Clean up - -Clean the relevant resources so that you can run this tutorial again - - ```bash - kubectl delete \ - -f https://raw.githubusercontent.com/spidernet-io/spiderpool/main/docs/example/basic/custom-ipv4-subnet.yaml \ - -f https://raw.githubusercontent.com/spidernet-io/spiderpool/main/docs/example/basic/custom-ipv6-subnet.yaml \ - -f https://raw.githubusercontent.com/spidernet-io/spiderpool/main/docs/example/basic/custom-ipv4-ippool.yaml \ - -f https://raw.githubusercontent.com/spidernet-io/spiderpool/main/docs/example/basic/custom-ipv6-ippool.yaml \ - -f https://raw.githubusercontent.com/spidernet-io/spiderpool/main/docs/example/basic/custom-dual-ippool-deploy.yaml \ - --ignore-not-found=true - ``` diff --git a/docs/usage/readme-zh_CN.md b/docs/usage/readme-zh_CN.md index b0eee1a40d..3df18107fc 100644 --- a/docs/usage/readme-zh_CN.md +++ b/docs/usage/readme-zh_CN.md @@ -93,7 +93,7 @@ - 可以通过 IP 池和 Pod annotaiton 等多种方式定制自定义路由，可参考[例子](./route.md)。 -- 应用可设置多个 IP 池，实现 IP 资源的备用效果。可参考[例子](./ippool-multi.md)。 +- 应用可设置多个 IP 池，实现 IP 资源的备用效果。可参考[例子](./spider-ippool-zh_CN.md)。 - 设置全局的预留 IP，让 IPAM 不分配出这些 IP 地址，这样能避免与集群外部的已用 IP 冲突。 可参考[例子](./reserved-ip.md)。 @@ -143,4 +143,4 @@ - 支持 AMD64 和 ARM64 -- 所有的功能都能够在 ipv4-only、ipv6-only、dual-stack 场景下工作。可参考[例子](./ipv6.md)。 +- 所有的功能都能够在 ipv4-only、ipv6-only、dual-stack 场景下工作。可参考[例子](./spider-ippool.md)。 diff --git a/docs/usage/readme.md b/docs/usage/readme.md index e17211a142..954fcb657d 100644 --- a/docs/usage/readme.md +++ b/docs/usage/readme.md @@ -95,7 +95,7 @@ For instructions on how to upgrade Spiderpool, please refer to the [upgrade guid - Custom routing can be achieved through IP pools, Pod annotations, and other methods. Refer to the [example](./route.md) for details. -- Multiple IP pools can be configured by applications to provide redundancy for IP resources. Refer to the [example](./ippool-multi.md) for details.. +- Multiple IP pools can be configured by applications to provide redundancy for IP resources. Refer to the [example](./spider-ippool.md) for details.. - Global reserved IP addresses can be specified to prevent IPAM from allocating those addresses, thereby avoiding conflicts with externally used IPs. Refer to the [example](./reserved-ip.md) for details. @@ -137,4 +137,4 @@ For instructions on how to upgrade Spiderpool, please refer to the [upgrade guid - Support for AMD64 and ARM64 architectures -- All features are compatible with ipv4-only, ipv6-only, and dual-stack scenarios. Refer to the [example](./ipv6.md) for use cases. +- All features are compatible with ipv4-only, ipv6-only, and dual-stack scenarios. Refer to the [example](./spider-ippool.md) for use cases. diff --git a/docs/usage/route-zh_CN.md b/docs/usage/route-zh_CN.md index e69de29bb2..45f971359c 100644 --- a/docs/usage/route-zh_CN.md +++ b/docs/usage/route-zh_CN.md @@ -0,0 +1,65 @@ +# 路由支持 + +**简体中文** ｜ [**English**](./route.md) + +## 介绍 + +Spiderpool 提供了为 Pod 配置路由信息的功能。 + +### 搭配网关配置默认路由 + +当我们为 SpiderIPPool 资源设置**网关地址**(`spec.gateway`)后，我们会根据该网关地址为 Pod 生成一条默认路由： + +```yaml +apiVersion: spiderpool.spidernet.io/v2beta1 +kind: SpiderIPPool +metadata: + name: ipv4-ippool-route +spec: + subnet: 172.18.41.0/24 + ips: + - 172.18.41.51-172.18.41.60 + gateway: 172.18.41.0 +``` + +### 继承 IP 池路由 + +我们也可为 SpiderIPPool 资源配置路由(`spec.routes`)，创建 Pod 时会继承该路由： + +> 注意： +> - 当 SpiderIPPool 资源配置了网关地址后，请勿为路由字段配置默认路由。 +> - `dst` 和 `gw` 字段都为必填 + +```yaml +apiVersion: spiderpool.spidernet.io/v2beta1 +kind: SpiderIPPool +metadata: + name: ipv4-ippool-route +spec: + subnet: 172.18.41.0/24 + ips: + - 172.18.41.51-172.18.41.60 + gateway: 172.18.41.0 + routes: + - dst: 172.18.42.0/24 + gw: 172.18.41.1 +``` + +### 自定义路由 + +我们也支持为应用配置自定义路由的功能，只需为 Pod 打上注解 `ipam.spidernet.io/routes`: + +> 注意： +> - 当 SpiderIPPool 资源中配置了网关地址、或配置了默认路由后，请勿为 Pod 配置默认路由。 +> - `dst` 和 `gw` 字段都为必填 + +```yaml +ipam.spidernet.io/routes: |- + [{ + "dst": "10.0.0.0/16", + "gw": "192.168.1.1" + },{ + "dst": "172.10.40.0/24", + "gw": "172.18.40.1" + }] +``` diff --git a/docs/usage/spider-affinity-zh_CN.md b/docs/usage/spider-affinity-zh_CN.md index 03225772af..14ab7da879 100644 --- a/docs/usage/spider-affinity-zh_CN.md +++ b/docs/usage/spider-affinity-zh_CN.md @@ -6,6 +6,39 @@ SpiderIPPool 资源代表 IP 地址的集合，一个 Subnet 中的不同 IP 地址，可分别存储到不同的 IPPool 实例中（Spiderpool 会校验 IPPool 之间的地址集合不重叠）。因此，依据需求，SpiderIPPool 中的 IP 集合可大可小。能很好的应对 underlay 网络的 IP 地址资源有限情况，且这种设计特点，能够通过各种亲和性规则让不同的应用、租户来绑定不同的 SpiderIPPool，也能分享相同的 SpiderIPPool，既能够让所有应用共享使用同一个子网，又能够实现 "微隔离"。 +## 快速入门 + +在 [SpiderIPPool CRD](./../reference/crd-spiderippool.md) 里，我们有定义很多的字段来搭配亲和性使用，如: + +- `spec.podAffinity` 字段可控制该池是否可被 Pod 使用 +- `spec.namespaceName` 和 `spec.namespaceAffinity` 字段会校验是否与 Pod 的Namespace相匹配，若不匹配则不可使用。(`namespaceName` 优先级高于 `namespaceAffinity`) +- `spec.nodeName` 和 `spec.nodeAffinity` 字段会校验是否与 Pod 所在的节点相匹配，若不匹配则不可使用。(`nodeName` 优先级高于 `nodeAffinity`) +- `multusName` 字段会判断当前网卡是否与 multus 的 net-attach-def 资源使用的 CNI 配置相匹配，若不匹配则不可使用。 + +这些字段不仅起到**过滤**的作用，同时也会起到一个**排序**的效果，若匹配的字段越多，越优先使用该 IP 池。 + +```yaml +apiVersion: spiderpool.spidernet.io/v2beta1 +kind: SpiderIPPool +metadata: + name: test-pod-ippool +spec: + subnet: 10.6.0.0/16 + ips: + - 10.6.168.151-10.6.168.160 + podAffinity: + matchLabels: + app: test-app-3 + nodeName: + - master + - worker1 + namespaceName: + - kube-system + - default + multusName: + - kube-system/macvlan-vlan0 +``` + ## 应用亲和性 在集群中，防火墙通常用于管理南北向通信，即集群内部和外部网络之间的通信。为了实现安全管控，防火墙需要对通信流量进行检查和过滤，并对出口通信进行限制。由于防火墙安全管控，一组 Deployment 它的所有 Pod 期望能够在一个固定的 IP 地址范围内轮滚分配 IP 地址，以配合防火墙的放行策略，从而实现 Underlay 网络下的南北通信。 diff --git a/docs/usage/spider-ippool-zh_CN.md b/docs/usage/spider-ippool-zh_CN.md new file mode 100644 index 0000000000..6cd2412971 --- /dev/null +++ b/docs/usage/spider-ippool-zh_CN.md @@ -0,0 +1,174 @@ +# SpiderIPPool + +**简体中文** | [**English**](./spider-ippool.md) + +## 介绍 + +SpiderIPPool 资源代表 Spiderpool 为 Pod 分配 IP 的 IP 地址范围。 请参照 [SpiderIPPool CRD](./../reference/crd-spiderippool.md) 为你的集群创建 SpiderIPPool 资源。 + +## SpiderIPPool 功能 + +- 单双栈以及 IPv6 支持 +- IP 地址范围控制 +- 网关路由控制 +- 仅用以及全局缺省池控制 +- 搭配各种资源亲和性使用控制 + +## 使用介绍 + +### 单双栈控制 + +Spiderpool 支持 IPv4-only, IPv6-only, 双栈这三种 IP 地址分配方式，可通过 [configmap](./../reference/configmap.md) 配置来控制。 + +> 通过 Helm 安装时可配置参数来指定： `--set ipam.enableIPv4=true --set ipam.enableIPv6=true`。 + +当我们 Spiderpool 环境开启双栈配置后，我们可以手动指定使用哪些 IPv4 和 IPv6 池来分配 IP 地址： + +> 在双栈环境下，你也可为pod只分配IPv4/IPv6的IP，如: `ipam.spidernet.io/ippool: '{"ipv4": ["custom-ipv4-ippool"]}'` + +```yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: custom-dual-ippool-deploy +spec: + replicas: 3 + selector: + matchLabels: + app: custom-dual-ippool-deploy + template: + metadata: + annotations: + ipam.spidernet.io/ippool: |- + { + "ipv4": ["custom-ipv4-ippool"],"ipv6": ["custom-ipv6-ippool"] + } + labels: + app: custom-dual-ippool-deploy + spec: + containers: + - name: custom-dual-ippool-deploy + image: busybox + imagePullPolicy: IfNotPresent + command: ["/bin/sh", "-c", "trap : TERM INT; sleep infinity & wait"] +``` + + +### 指定 IPPool 为应用分配 IP 地址 + +> 对于以下指定使用 SpiderIPPool 规则的优先级，请参考 [IP 候选池规则](./../concepts/ipam-zh_CN.md#获取候选池) + +#### 使用 Pod Annotation 指定使用IP池 + +我们可借助注解 `ipam.spidernet.io/ippool` 或 `ipam.spidernet.io/ippools` 标记在 Pod 的 Annotation上来指定 Pod 使用哪些 IP 池, 注解 `ipam.spidernet.io/ippools` 多用于多网卡指定。此外我们可以指定多个 IP 池以供备选，当某个池的 IP 被用完后，可继续从你指定的其他池中分配地址。 + +```yaml +ipam.spidernet.io/ippool: |- + { + "ipv4": ["demo-v4-ippool1", "backup-ipv4-ippool"], + "ipv6": ["demo-v6-ippool1", "backup-ipv6-ippool"] + } +``` + +```yaml +ipam.spidernet.io/ippools: |- + [{ + "interface": "eth0", + "ipv4": ["demo-v4-ippool1"], + "ipv6": ["demo-v6-ippool1"], + "cleangateway": true + },{ + "interface": "net1", + "ipv4": ["demo-v4-ippool2"], + "ipv6": ["demo-v6-ippool2"], + "cleangateway": false + }] +``` + +#### 使用 Namespace 注解指定池 + +我们可以为 Namespace 打上注解 `ipam.spidernet.io/default-ipv4-ippool` 和 `ipam.spidernet.io/default-ipv6-ippool`, 当应用部署的时，可从应用所在 Namespace 的注解中选择 IP 池使用： + +> 注意：未使用 Pod Annotation 指定使用IP池时，优先使用此处 Namespace 注解规则。 + +```yaml + +apiVersion: v1 +kind: Namespace +metadata: + annotations: + ipam.spidernet.io/default-ipv4-ippool: '["ns-v4-ippool1","ns-v4-ippool2"]' + ipam.spidernet.io/default-ipv6-ippool: '["ns-v6-ippool1","ns-v6-ippool2"]' + name: kube-system +... +``` + +#### 使用 CNI 配置文件指定池 + +我们可以在 CNI 配置文件中，指定缺省的 IPv4 和 IPv6 池以供应用选择该 CNI 配置时使用，具体可参照 [CNI配置](./../reference/plugin-ipam.md) + +> 注意：未使用 Pod Annotation 指定使用IP池，且没有通过 Namespace 注解指定 IP 池时，将优先使用此处 CNI 配置文件指定池规则。 + +```yaml +{ + "name": "macvlan-vlan0", + "type": "macvlan", + "master": "eth0", + "ipam": { + "type": "spiderpool", + "default_ipv4_ippool":["default-v4-ippool","backup-ipv4-ippool"], + "default_ipv6_ippool":["default-v6-ippool","backup-ipv6-ippool"] + } +} +``` + +#### 为 SpiderIPPool 设置集群默认级别 + +在 [SpiderIPPool CRD](./../reference/crd-spiderippool.md) 中我们可以看到 `spec.default` 字段是一个 bool 类型，当我们没有通过 Annotation 或 CNI 配置文件指定 IPPool 时，系统会根据该字段挑选出集群默认池使用: + +> 注意： +> - 未使用 Pod Annotation 指定使用IP池，没有通过 Namespace 注解指定 IP 池时，且未在 CNI 配置文件中指定 IP 池时，此处会生效。 +> - 可为多个 IPPool 资源设置为集群默认级别。 + +```yaml +apiVersion: spiderpool.spidernet.io/v2beta1 +kind: SpiderIPPool +metadata: + name: master-172 +spec: + default: true +... +``` + +### SpiderIPPool 搭配亲和性使用 + +具体请参考 [IP 池亲和性搭配](./spider-affinity-zh_CN.md) + +### SpiderIPPool 网关与路由配置 + +具体请参考 [路由功能](./route-zh_CN.md) + +因此 Pod 会拿到基于网关的默认路由，以及此 IP 池上的自定义路由。(若 IP 池不设置网关，则不会生效默认路由) + +### 命令行工作(kubectl)查看扩展字段 + +为了更简单方便的查看 SpiderIPPool 资源的相关属性，我们补充了一些扩展字段可让用户通过 `kubectl get sp -o wide` 查看: + +- `ALLOCATED-IP-COUNT` 字段表示该池已分配的 IP 数量 +- `TOTAL-IP-COUNT` 字段表示该池的总 IP 数量 +- `DEFAULT` 字段表示该池是否为集群默认级别 +- `DISABLE` 字段表示该池是否被禁用 +- `NODENAME` 字段表示与该池亲和的节点 +- `MULTUSNAME` 字段表示与该池亲和的 multus 实例 +- `APP-NAMESPACE` 字段属于 [SpiderSubnet](./spider-subnet-zh_CN.md) 功能独有，表明该池是一个系统自动创建的池，同时该字段表明其对应应用的命名空间。 + +```shell +~# kubectl get sp -o wide +NAME VERSION SUBNET ALLOCATED-IP-COUNT TOTAL-IP-COUNT DEFAULT DISABLE NODENAME MULTUSNAME APP-NAMESPACE +auto4-demo-deploy-subnet-eth0-fcca4 4 172.100.0.0/16 1 2 false false kube-system +test-pod-ippool 4 10.6.0.0/16 0 10 false false ["master","worker1"] ["kube-system/macvlan-vlan0"] +``` + +### 指标(metric) + +我们也为 SpiderIPPool 资源补充了相关的指标信息，详情请看 [metric](./../reference/metrics.md) diff --git a/docs/usage/spider-ippool.md b/docs/usage/spider-ippool.md new file mode 100644 index 0000000000..6d8b31fe4a --- /dev/null +++ b/docs/usage/spider-ippool.md @@ -0,0 +1,3 @@ +# SpiderIPPool + +**English** ｜ [**简体中文**](./spider-ippool-zh_CN.md) \ No newline at end of file