docs: update installtion for spidercoordinator

ty-dc · Mar 20, 2024 · 2b2942a · 2b2942a
1 parent f0ce6ce
commit 2b2942a
Show file tree

Hide file tree

Showing 4 changed files with 239 additions and 12 deletions.
diff --git a/docs/usage/install/underlay/get-started-macvlan-zh_CN.md b/docs/usage/install/underlay/get-started-macvlan-zh_CN.md
@@ -51,7 +51,65 @@ Spiderpool 可用作 Underlay 网络场景下提供固定 IP 的一种解决方
     >
     > 通过 `multus.multusCNI.defaultCniCRName` 指定 multus 默认使用的 CNI 的 NetworkAttachmentDefinition 实例名。如果 `multus.multusCNI.defaultCniCRName` 选项不为空，则安装后会自动生成一个数据为空的 NetworkAttachmentDefinition 对应实例。如果 `multus.multusCNI.defaultCniCRName` 选项为空，会尝试通过 /etc/cni/net.d 目录下的第一个 CNI 配置文件内容来创建对应的 NetworkAttachmentDefinition 实例，若目录下不存在 CNI 配置文件则会自动生成一个名为 `default` 的 NetworkAttachmentDefinition 实例，以完成 multus 的安装。
 
-2. 创建 SpiderIPPool 实例。
+2. 检查 `Spidercoordinator.status` 中的 Phase 是否为 Synced:
+
+    ```shell
+    ~# kubectl  get spidercoordinators.spiderpool.spidernet.io default -o yaml
+    apiVersion: spiderpool.spidernet.io/v2beta1
+    kind: SpiderCoordinator
+    metadata:
+      creationTimestamp: "2023-10-18T08:31:09Z"
+      finalizers:
+      - spiderpool.spidernet.io
+      generation: 7
+      name: default
+      resourceVersion: "195405"
+      uid: 8bdceced-15db-497b-be07-81cbcba7caac
+    spec:
+      detectGateway: false
+      detectIPConflict: false
+      hijackCIDR:
+      - 169.254.0.0/16
+      hostRPFilter: 0
+      hostRuleTable: 500
+      mode: auto
+      podCIDRType: calico
+      podDefaultRouteNIC: ""
+      podMACPrefix: ""
+      tunePodRoutes: true
+    status:
+      overlayPodCIDR:[]
+      phase: Synced
+      serviceCIDR:
+      - 10.233.0.0/18
+    ```
+
+    如果状态为 `NotReady`,这将会阻止 Pod 被创建。目前 Spiderpool:
+    * 优先通过查询 `kube-system/kubeadm-config` ConfigMap 获取集群的 Pod 和 Service 子网。 
+    * 如果 `kubeadm-config` 不存在导致无法获取集群子网，那么 Spiderpool 会从 `Kube-controller-manager Pod` 中获取集群 Pod 和 Service 的子网。 如果您集群的 Kube-controller-manager 组件以 `systemd` 等方式而不是以静态 Pod 运行。那么 Spiderpool 仍然无法获取集群的子网信息。
+
+    如果上面两种方式都失败，Spiderpool 会同步 status.phase 为 NotReady, 这将会阻止 Pod 被创建。我们可以手动创建 kubeadm-config ConfigMap，并正确配置集群的子网信息:
+
+    ```shell
+    export POD_SUBNET=<YOUR_POD_SUBNET>
+    export SERVICE_SUBNET=<YOUR_SERVICE_SUBNET>
+    cat << EOF | kubectl apply -f -
+    apiVersion: v1
+    kind: ConfigMap
+    metadata:
+      name: kubeadm-config
+      namespace: kube-system
+    data:
+      ClusterConfiguration: |
+        networking:
+          podSubnet: ${POD_SUBNET}
+          serviceSubnet: ${SERVICE_SUBNET}
+    EOF
+    ```
+
+    一旦创建完成，Spiderpool 将会自动同步其状态。
+
+3. 创建 SpiderIPPool 实例。
 
     创建与网络接口 `eth0` 在同一个子网的 IP 池以供 Pod 使用，以下是创建相关的 SpiderIPPool 示例：
 
@@ -71,7 +129,7 @@ Spiderpool 可用作 Underlay 网络场景下提供固定 IP 的一种解决方
     EOF
     ```
 
-3. 验证安装
+4. 验证安装
 
    ```shell
     ~# kubectl get po -n kube-system | grep spiderpool

diff --git a/docs/usage/install/underlay/get-started-macvlan.md b/docs/usage/install/underlay/get-started-macvlan.md
@@ -49,7 +49,62 @@ Spiderpool provides a solution for assigning static IP addresses in underlay net
     >
     > Specify the name of the NetworkAttachmentDefinition instance for the default CNI used by Multus via `multus.multusCNI.defaultCniCRName`. If the `multus.multusCNI.defaultCniCRName` option is provided, an empty NetworkAttachmentDefinition instance will be automatically generated upon installation. Otherwise, Multus will attempt to create a NetworkAttachmentDefinition instance based on the first CNI configuration found in the /etc/cni/net.d directory. If no suitable configuration is found, a NetworkAttachmentDefinition instance named `default` will be created to complete the installation of Multus.
 
-2. Create a SpiderIPPool instance.
+2. Please check if `Spidercoordinator.status.phase` is `Synced`:
+
+    ```shell
+    ~# kubectl  get spidercoordinators.spiderpool.spidernet.io default -o yaml
+    apiVersion: spiderpool.spidernet.io/v2beta1
+    kind: SpiderCoordinator
+    metadata:
+      finalizers:
+      - spiderpool.spidernet.io
+      name: default
+    spec:
+      detectGateway: false
+      detectIPConflict: false
+      hijackCIDR:
+      - 169.254.0.0/16
+      hostRPFilter: 0
+      hostRuleTable: 500
+      mode: auto
+      podCIDRType: calico
+      podDefaultRouteNIC: ""
+      podMACPrefix: ""
+      tunePodRoutes: true
+    status:
+      overlayPodCIDR:
+      - 10.244.64.0/18
+      phase: Synced
+      serviceCIDR:
+      - 10.233.0.0/18
+    ```
+
+    At present:
+    * Spiderpool prioritizes obtaining the cluster's Pod and Service subnets by querying the kube-system/kubeadm-config ConfigMap. 
+    * If the kubeadm-config does not exist, causing the failure to obtain the cluster subnet, Spiderpool will attempt to retrieve the cluster Pod and Service subnets from the kube-controller-manager Pod. 
+    
+    If the kube-controller-manager component in your cluster runs in systemd mode instead of as a static Pod, Spiderpool still cannot retrieve the cluster's subnet information.
+
+    If both of the above methods fail, Spiderpool will synchronize the status.phase as NotReady, preventing Pod creation. To address such abnormal situations, we can manually create the kubeadm-config ConfigMap and correctly configure the cluster's subnet information:
+
+    ```shell
+    export POD_SUBNET=<YOUR_POD_SUBNET>
+    export SERVICE_SUBNET=<YOUR_SERVICE_SUBNET>
+    cat << EOF | kubectl apply -f -
+    apiVersion: v1
+    kind: ConfigMap
+    metadata:
+      name: kubeadm-config
+      namespace: kube-system
+    data:
+      ClusterConfiguration: |
+        networking:
+          podSubnet: ${POD_SUBNET}
+          serviceSubnet: ${SERVICE_SUBNET}
+    EOF
+    ```
+
+3. Create a SpiderIPPool instance.
 
     Create an IP Pool in the same subnet as the network interface `eth0` for Pods to use, the following is an example of creating a related SpiderIPPool:
 
@@ -69,7 +124,7 @@ Spiderpool provides a solution for assigning static IP addresses in underlay net
     EOF
     ```
 
-3. Verify installation
+4. Verify installation
 
    ```shell
     ~# kubectl get po -n kube-system | grep spiderpool

diff --git a/docs/usage/install/underlay/get-started-ovs-zh_CN.md b/docs/usage/install/underlay/get-started-ovs-zh_CN.md
@@ -54,7 +54,65 @@ Spiderpool 可用作 Underlay 网络场景下提供固定 IP 的一种解决方
     >
     > 通过 `multus.multusCNI.defaultCniCRName` 指定 multus 默认使用的 CNI 的 NetworkAttachmentDefinition 实例名。如果 `multus.multusCNI.defaultCniCRName` 选项不为空，则安装后会自动生成一个数据为空的 NetworkAttachmentDefinition 对应实例。如果 `multus.multusCNI.defaultCniCRName` 选项为空，会尝试通过 /etc/cni/net.d 目录下的第一个 CNI 配置来创建对应的 NetworkAttachmentDefinition 实例，否则会自动生成一个名为 `default` 的 NetworkAttachmentDefinition 实例，以完成 multus 的安装。
 
-2. 在每个节点上配置 Open vSwitch 网桥。
+2. 检查 `Spidercoordinator.status` 中的 Phase 是否为 Synced:
+
+    ```shell
+    ~# kubectl  get spidercoordinators.spiderpool.spidernet.io default -o yaml
+    apiVersion: spiderpool.spidernet.io/v2beta1
+    kind: SpiderCoordinator
+    metadata:
+      creationTimestamp: "2023-10-18T08:31:09Z"
+      finalizers:
+      - spiderpool.spidernet.io
+      generation: 7
+      name: default
+      resourceVersion: "195405"
+      uid: 8bdceced-15db-497b-be07-81cbcba7caac
+    spec:
+      detectGateway: false
+      detectIPConflict: false
+      hijackCIDR:
+      - 169.254.0.0/16
+      hostRPFilter: 0
+      hostRuleTable: 500
+      mode: auto
+      podCIDRType: calico
+      podDefaultRouteNIC: ""
+      podMACPrefix: ""
+      tunePodRoutes: true
+    status:
+      overlayPodCIDR:[]
+      phase: Synced
+      serviceCIDR:
+      - 10.233.0.0/18
+    ```
+
+    如果状态为 `NotReady`,这将会阻止 Pod 被创建。目前 Spiderpool:
+    * 优先通过查询 `kube-system/kubeadm-config` ConfigMap 获取集群的 Pod 和 Service 子网。 
+    * 如果 `kubeadm-config` 不存在导致无法获取集群子网，那么 Spiderpool 会从 `Kube-controller-manager Pod` 中获取集群 Pod 和 Service 的子网。 如果您集群的 Kube-controller-manager 组件以 `systemd` 等方式而不是以静态 Pod 运行。那么 Spiderpool 仍然无法获取集群的子网信息。
+
+    如果上面两种方式都失败，Spiderpool 会同步 status.phase 为 NotReady, 这将会阻止 Pod 被创建。我们可以手动创建 kubeadm-config ConfigMap，并正确配置集群的子网信息:
+
+    ```shell
+    export POD_SUBNET=<YOUR_POD_SUBNET>
+    export SERVICE_SUBNET=<YOUR_SERVICE_SUBNET>
+    cat << EOF | kubectl apply -f -
+    apiVersion: v1
+    kind: ConfigMap
+    metadata:
+      name: kubeadm-config
+      namespace: kube-system
+    data:
+      ClusterConfiguration: |
+        networking:
+          podSubnet: ${POD_SUBNET}
+          serviceSubnet: ${SERVICE_SUBNET}
+    EOF
+    ```
+
+    一旦创建完成，Spiderpool 将会自动同步其状态。
+
+3. 在每个节点上配置 Open vSwitch 网桥。
 
     创建网桥并配置网桥，以 `eth0` 为例。
 
@@ -84,7 +142,7 @@ Spiderpool 可用作 Underlay 网络场景下提供固定 IP 的一种解决方
         ovs_version: "2.17.3"
     ```
 
-3. 创建 SpiderIPPool 实例。
+4. 创建 SpiderIPPool 实例。
 
     Pod 会从该 IP 池中获取 IP，进行 Underlay 的网络通讯，所以该 IP 池的子网需要与接入的 Underlay 子网对应。以下是创建相关的 SpiderIPPool 示例：
 
@@ -104,7 +162,7 @@ Spiderpool 可用作 Underlay 网络场景下提供固定 IP 的一种解决方
     EOF
     ```
 
-4. 验证安装：
+5. 验证安装：
 
     ```bash
     ~# kubectl get po -n kube-system |grep spiderpool
@@ -119,7 +177,7 @@ Spiderpool 可用作 Underlay 网络场景下提供固定 IP 的一种解决方
     ~# 
     ```
 
-5. Spiderpool 为简化书写 JSON 格式的 Multus CNI 配置，它提供了 SpiderMultusConfig CR 来自动管理 Multus NetworkAttachmentDefinition CR。如下是创建 Ovs SpiderMultusConfig 配置的示例：
+6. Spiderpool 为简化书写 JSON 格式的 Multus CNI 配置，它提供了 SpiderMultusConfig CR 来自动管理 Multus NetworkAttachmentDefinition CR。如下是创建 Ovs SpiderMultusConfig 配置的示例：
 
     * 确认 ovs-cni 所需的网桥名称，本例子以 br1 为例:
 

diff --git a/docs/usage/install/underlay/get-started-ovs.md b/docs/usage/install/underlay/get-started-ovs.md
@@ -54,7 +54,63 @@ Spiderpool can be used as a solution to provide fixed IPs in an Underlay network
     >
     > Specify the name of the NetworkAttachmentDefinition instance for the default CNI used by Multus via `multus.multusCNI.defaultCniCRName`. If the `multus.multusCNI.defaultCniCRName` option is provided, an empty NetworkAttachmentDefinition instance will be automatically generated upon installation. Otherwise, Multus will attempt to create a NetworkAttachmentDefinition instance based on the first CNI configuration found in the /etc/cni/net.d directory. If no suitable configuration is found, a NetworkAttachmentDefinition instance named `default` will be created to complete the installation of Multus.
 
-2. To configure Open vSwitch bridges on each node:
+2. Please check if `Spidercoordinator.status.phase` is `Synced`:
+
+    ```shell
+    ~# kubectl  get spidercoordinators.spiderpool.spidernet.io default -o yaml
+    apiVersion: spiderpool.spidernet.io/v2beta1
+    kind: SpiderCoordinator
+    metadata:
+      finalizers:
+      - spiderpool.spidernet.io
+      name: default
+    spec:
+      detectGateway: false
+      detectIPConflict: false
+      hijackCIDR:
+      - 169.254.0.0/16
+      hostRPFilter: 0
+      hostRuleTable: 500
+      mode: auto
+      podCIDRType: calico
+      podDefaultRouteNIC: ""
+      podMACPrefix: ""
+      tunePodRoutes: true
+    status:
+      overlayPodCIDR:
+      - 10.244.64.0/18
+      phase: Synced
+      serviceCIDR:
+      - 10.233.0.0/18
+    ```
+
+    At present:
+
+    * Spiderpool prioritizes obtaining the cluster's Pod and Service subnets by querying the kube-system/kubeadm-config ConfigMap. 
+    * If the kubeadm-config does not exist, causing the failure to obtain the cluster subnet, Spiderpool will attempt to retrieve the cluster Pod and Service subnets from the kube-controller-manager Pod. 
+    
+    If the kube-controller-manager component in your cluster runs in systemd mode instead of as a static Pod, Spiderpool still cannot retrieve the cluster's subnet information.
+
+    If both of the above methods fail, Spiderpool will synchronize the status.phase as NotReady, preventing Pod creation. To address such abnormal situations, we can manually create the kubeadm-config ConfigMap and correctly configure the cluster's subnet information:
+
+    ```shell
+    export POD_SUBNET=<YOUR_POD_SUBNET>
+    export SERVICE_SUBNET=<YOUR_SERVICE_SUBNET>
+    cat << EOF | kubectl apply -f -
+    apiVersion: v1
+    kind: ConfigMap
+    metadata:
+      name: kubeadm-config
+      namespace: kube-system
+    data:
+      ClusterConfiguration: |
+        networking:
+          podSubnet: ${POD_SUBNET}
+          serviceSubnet: ${SERVICE_SUBNET}
+    EOF
+    ```
+
+3. To configure Open vSwitch bridges on each node:
 
     Create a bridge and configure it using `eth0`` as an example.
 
@@ -84,7 +140,7 @@ Spiderpool can be used as a solution to provide fixed IPs in an Underlay network
         ovs_version: "2.17.3"
     ```
 
-3. Create a SpiderIPPool instance.
+4. Create a SpiderIPPool instance.
 
     The Pod will obtain an IP address from the IP pool for underlying network communication, so the subnet of the IP pool needs to correspond to the underlying subnet being accessed.
 
@@ -106,7 +162,7 @@ Spiderpool can be used as a solution to provide fixed IPs in an Underlay network
     EOF
     ```
 
-4. Verify the installation：
+5. Verify the installation：
 
     ```bash
     ~# kubectl get po -n kube-system |grep spiderpool
@@ -121,7 +177,7 @@ Spiderpool can be used as a solution to provide fixed IPs in an Underlay network
     ~# 
     ```
 
-5. To simplify writing Multus CNI configuration in JSON format, Spiderpool provides SpiderMultusConfig CR to automatically manage Multus NetworkAttachmentDefinition CR. Here is an example of creating an ovs-cni SpiderMultusConfig configuration:
+6. To simplify writing Multus CNI configuration in JSON format, Spiderpool provides SpiderMultusConfig CR to automatically manage Multus NetworkAttachmentDefinition CR. Here is an example of creating an ovs-cni SpiderMultusConfig configuration:
 
     * Confirm the bridge name for ovs-cni. Take the host bridge: `br1` as an example: