Merge pull request spidernet-io#2550 from spidernet-io/doc/ippool

doc: add en ippool
ty-dc · Nov 7, 2023 · f577fad · f577fad
2 parents 6ff4554 + ac0f89c
commit f577fad
Show file tree

Hide file tree

Showing 2 changed files with 177 additions and 10 deletions.
diff --git a/docs/usage/spider-ippool-zh_CN.md b/docs/usage/spider-ippool-zh_CN.md
@@ -20,11 +20,11 @@ SpiderIPPool 资源代表 Spiderpool 为 Pod 分配 IP 的 IP 地址范围。
 
 Spiderpool 支持 IPv4-only, IPv6-only, 双栈这三种 IP 地址分配方式，可通过 [configmap](./../reference/configmap.md) 配置来控制。
 
-> 通过 Helm 安装时可配置参数来指定： `--set ipam.enableIPv4=true --set ipam.enableIPv6=true`。
+> 通过 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"]}'`
+> 在双栈环境下，你也可为 Pod 只分配 IPv4/IPv6 的IP，如: `ipam.spidernet.io/ippool: '{"ipv4": ["custom-ipv4-ippool"]}'`
 
 ```yaml
 apiVersion: apps/v1
@@ -58,7 +58,7 @@ spec:
 
 > 对于以下指定使用 SpiderIPPool 规则的优先级，请参考 [IP 候选池规则](./../concepts/ipam-zh_CN.md#获取候选池)
 
-#### 使用 Pod Annotation 指定使用IP池
+#### 使用 Pod Annotation 指定使用 IP 池
 
 我们可借助注解 `ipam.spidernet.io/ippool` 或 `ipam.spidernet.io/ippools` 标记在 Pod 的 Annotation上来指定 Pod 使用哪些 IP 池, 注解 `ipam.spidernet.io/ippools` 多用于多网卡指定。此外我们可以指定多个 IP 池以供备选，当某个池的 IP 被用完后，可继续从你指定的其他池中分配地址。
 
@@ -87,9 +87,9 @@ ipam.spidernet.io/ippools: |-
 
 #### 使用 Namespace 注解指定池
 
-我们可以为 Namespace 打上注解 `ipam.spidernet.io/default-ipv4-ippool` 和 `ipam.spidernet.io/default-ipv6-ippool`, 当应用部署的时，可从应用所在 Namespace 的注解中选择 IP 池使用：
+我们可以为 Namespace 打上注解 `ipam.spidernet.io/default-ipv4-ippool` 和 `ipam.spidernet.io/default-ipv6-ippool`, 当应用部署时，可从应用所在 Namespace 的注解中选择 IP 池使用：
 
-> 注意：未使用 Pod Annotation 指定使用IP池时，优先使用此处 Namespace 注解规则。
+> 未使用 Pod Annotation 指定使用 IP 池时，优先使用此处 Namespace 注解规则。
 
 ```yaml
 
@@ -107,7 +107,7 @@ metadata:
 
 我们可以在 CNI 配置文件中，指定缺省的 IPv4 和 IPv6 池以供应用选择该 CNI 配置时使用，具体可参照 [CNI配置](./../reference/plugin-ipam.md)
 
-> 注意：未使用 Pod Annotation 指定使用IP池，且没有通过 Namespace 注解指定 IP 池时，将优先使用此处 CNI 配置文件指定池规则。
+> 未使用 Pod Annotation 指定使用 IP 池，且没有通过 Namespace 注解指定 IP 池时，将优先使用此处 CNI 配置文件指定池规则。
 
 ```yaml
 {
@@ -126,10 +126,8 @@ metadata:
 
 在 [SpiderIPPool CRD](./../reference/crd-spiderippool.md) 中我们可以看到 `spec.default` 字段是一个 bool 类型，当我们没有通过 Annotation 或 CNI 配置文件指定 IPPool 时，系统会根据该字段挑选出集群默认池使用:
 
-> 注意：
->
 > - 未使用 Pod Annotation 指定使用IP池，没有通过 Namespace 注解指定 IP 池时，且未在 CNI 配置文件中指定 IP 池时，此处会生效。
-> - 可为多个 IPPool 资源设置为集群默认级别。 
+> - 可为多个 IPPool 资源设置为集群默认级别。
 
 ```yaml
 apiVersion: spiderpool.spidernet.io/v2beta1
@@ -151,7 +149,7 @@ spec:
 
 因此 Pod 会拿到基于网关的默认路由，以及此 IP 池上的自定义路由。(若 IP 池不设置网关，则不会生效默认路由)
 
-### 命令行工作(kubectl)查看扩展字段
+### 命令行工作 (kubectl) 查看扩展字段
 
 为了更简单方便的查看 SpiderIPPool 资源的相关属性，我们补充了一些扩展字段可让用户通过 `kubectl get sp -o wide` 查看:
 

diff --git a/docs/usage/spider-ippool.md b/docs/usage/spider-ippool.md
@@ -1,3 +1,172 @@
 # SpiderIPPool
 
 **English** ｜ [**简体中文**](./spider-ippool-zh_CN.md)
+
+## Introduction
+
+SpiderIPPool resources represent the IP address ranges allocated by Spiderpool for Pods. To create SpiderIPPool resources in your cluster, refer to the [SpiderIPPool CRD](./../reference/crd-spiderippool.md).
+
+## SpiderIPPool Features
+
+- Single-stack, dual-stack, and IPv6 Support
+- IP address range control
+- Gateway route control
+- Exclusive or global default pool control
+- Compatible with various resource affinity settings
+
+## Usage
+
+### Single-stack and Dual-stack Control
+
+Spiderpool supports three modes of IP address allocation: IPv4-only, IPv6-only, and dual-stack. Refer to [configmap](./../reference/configmap.md) for details.
+
+> When installing Spiderpool via Helm, you can use configuration parameters to specify: `--set ipam.enableIPv4=true --set ipam.enableIPv6=true`.
+
+If dual-stack mode is enabled, you can manually specify which IPv4 and IPv6 pools should be used for IP address allocation:
+
+> In a dual-stack environment, you can also configure Pods to only receive IPv4 or IPv6 addresses using the annotation `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"]
+```
+
+### Specify IPPool to Allocate IP Addresses to Applications
+
+> For the priority rules when specifying the SpiderIPPool, refer to the [Candidate Pool Acquisition](../concepts/ipam.md#candidate-pool-acquisition).
+
+#### Use Pod Annotation to Specify IP Pool
+
+You can use annotations like `ipam.spidernet.io/ippool` or `ipam.spidernet.io/ippools` on a Pod's annotation to indicate which IP pools should be used. The `ipam.spidernet.io/ippools` annotation is primarily used for specifying multiple network interfaces. Additionally, you can specify multiple pools as fallback options. If one pool's IP addresses are exhausted, addresses can be allocated from the other specified pools.
+
+```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
+  }]
+```
+
+#### Use Namespace Annotation to Specify IP Pool
+
+You can annotate the Namespace with `ipam.spidernet.io/default-ipv4-ippool` and `ipam.spidernet.io/default-ipv6-ippool`. When deploying applications, IP pools can be selected based on these annotations of the application's namespace:
+
+> If IP pool is not explicitly specified, rules defined in the Namespace annotation take precedence.
+
+```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
+...
+```
+
+#### Use CNI Configuration File to Specify IP Pool
+
+You can specify the default IPv4 and IPv6 pools for an application in the CNI configuration file. For more details, refer to [CNI Configuration](./../reference/plugin-ipam.md)
+
+> If IP pool is not explicitly specified using Pod Annotation and no IP pool is specified through Namespace annotation, the rules defined in the CNI configuration file take precedence.
+
+```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"]
+    }
+}
+```
+
+#### Set Cluster Default Level for SpiderIPPool
+
+In the [SpiderIPPool CRD](./../reference/crd-spiderippool.md), the `spec.default` field is a boolean type. It determines the cluster default pool when no specific IPPool is specified through annotations or the CNI configuration file:
+
+> - If no IP pool is specified using Pod annotations, and no IP pool is specified through Namespace annotations, and no IP pool is specified in the CNI configuration file, the system will use the pool defined by this field as the cluster default.
+> - Multiple IPPool resources can be set as the cluster default level.
+
+```yaml
+apiVersion: spiderpool.spidernet.io/v2beta1
+kind: SpiderIPPool
+metadata:
+  name: master-172
+spec:
+  default: true
+...
+```
+
+### Use SpiderIPPool with Affinity
+
+Refer to [SpiderIPPool Affinity](./spider-affinity.md) for details.
+
+### SpiderIPPool Gateway and Route Configuration
+
+Refer to [Route Support](./route.md) for details.
+
+As a result, Pods will receive the default route based on the gateway, as well as custom routes defined in the IP pool. If the IP pool does not have a gateway configured, the default route will not take effect.
+
+### View Extended Fields with Command Line (kubectl)
+
+To simplify the viewing of properties related to SpiderIPPool resources, we have added some additional fields that can be displayed using the `kubectl get sp -o wide` command:
+
+- `ALLOCATED-IP-COUNT` represents the number of allocated IP addresses in the pool.
+- `TOTAL-IP-COUNT` represents the total number of IP addresses in the pool.
+- `DEFAULT` indicates whether the pool is set as the cluster default level.
+- `DISABLE` indicates whether the pool is disabled.
+- `NODENAME` indicates the nodes have an affinity with the pool.
+- `MULTUSNAME` indicates the Multus instances have an affinity with the pool.
+- `APP-NAMESPACE` is specific to the [SpiderSubnet](./spider-subnet.md) feature. It signifies that the pool is automatically created by the system and corresponds to the namespace of the associated application.
+
+```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"]   
+```
+
+### Metrics
+
+We have also supplemented SpiderIPPool resources with relevant metric information. For more details, refer to [metric](./../reference/metrics.md)