docs: update bcs-netservice-controller docs (TencentBlueKing#2493)

* docs: 添加bcs-netservice-controller设计文档 * docs: update bcs-netservice-controller docs --------- Co-authored-by: hitozhang <[email protected]>
testwill · Aug 29, 2023 · c40163e · c40163e
1 parent e850a2b
commit c40163e
Show file tree

Hide file tree

Showing 3 changed files with 121 additions and 56 deletions.
diff --git a/bcs-runtime/bcs-k8s/bcs-component/bcs-netservice-controller/api/v1/bcsnetip_types.go b/bcs-runtime/bcs-k8s/bcs-component/bcs-netservice-controller/api/v1/bcsnetip_types.go
@@ -36,7 +36,7 @@ type BCSNetIPStatus struct {
 	Fixed bool `json:"fixed,omitempty"`
 	// 容器ID
 	ContainerID string `json:"containerID,omitempty"`
-	// BCSNetIPClaim名称
+	// BCSNetIPClaim信息，格式为"命名空间/名称"
 	IPClaimKey   string      `json:"ipClaimKey,omitempty"`
 	PodName      string      `json:"podName,omitempty"`
 	PodNamespace string      `json:"podNamespace,omitempty"`

diff --git a/docs/features/bcs-netservice-controller/bcs-netservice-controller.md b/docs/features/bcs-netservice-controller/bcs-netservice-controller.md
@@ -2,11 +2,13 @@
 
 ## 背景
 
-原bcs-netservice部署复杂，多用于Mesos集群，且需要使用ZK作为后端存储。
+原bcs-netservice部署复杂，多用于Mesos集群，且需要使用ZK作为后端存储。现在通过创建K8S CRD（BCSNetPool、BCSNetIP、BCSNetIPClaim），并使用bcs-netservice-controller进行维护，来替换和优化原有功能。
 
 ## 功能
 
-- 维护BCSNetPool和BCSNetIP，在K8S集群中部署和管理相应资源
+- 同步BCSNetPool
+- 根据BCSNetPool的配置创建和同步BCSNetIP
+- 同步BCSNetIPClaim，用于申请固定IP
 - 提供接口供cni插件申请和删除IP
 
 ## 架构设计
@@ -15,7 +17,7 @@
 
 ## 数据结构
 
-如前面所述，我们定义了BCSNetPool和BCSNetIP两种资源。bcs-netservice-controller会根据用户创建的BCSNetPool实例，自动创建BCSNetIP实例，用户不会直接创建BCSNetIP资源。
+如前面所述，我们定义了BCSNetPool、BCSNetIP和BCSNetIPClaim三种资源。bcs-netservice-controller会根据用户创建的BCSNetPool实例，自动创建BCSNetIP实例，用户不会直接创建BCSNetIP资源。当用户申请固定IP时，可以创建BCSNetIPClaim来实现。
 
 ### BCSNetPool
 
@@ -41,29 +43,11 @@ type BCSNetPoolSpec struct {
 // BCSNetPoolStatus defines the observed state of BCSNetPool
 type BCSNetPoolStatus struct {
 	// Initializing --初始化中，Normal --正常
-	Status     string `json:"status,omitempty"`
-	UpdateTime string `json:"updateTime,omitempty"`
+	Phase      string      `json:"phase,omitempty"`
+	UpdateTime metav1.Time `json:"updateTime,omitempty"`
 }
 ```
 
-```
-apiVersion: networkextension.bkbcs.tencent.com/v1
-kind: BCSNetPool
-metadata:
-  name: 10.xx.xx.0
-spec:
-  net: 10.xx.xx.0
-  mask: 24
-  gateway: 10.xx.xx.1
-  hosts:
-  - 10.xx.xx.11
-  - 10.xx.xx.12
-  availableIPs:
-  - 10.xx.xx.20
-  - 10.xx.xx.21
-  - 10.xx.xx.22
-```
-
 ### BCSNetIP
 
 表明某个IP的基本信息和状态。cni插件通过bcs-netservice-controller暴露的接口进行IP的申请和删除。
@@ -73,8 +57,8 @@ bcs-netservice-controller会根据cni插件请求中传递的podNamespace、podN
 ```
 // BCSNetIPSpec defines the desired state of BCSNetIP
 type BCSNetIPSpec struct {
-	// 所属Pool
-	Pool string `json:"pool"`
+	// 所属网段
+	Net string `json:"net"`
 	// 网段掩码
 	Mask int `json:"mask"`
 	// 网段网关
@@ -84,30 +68,42 @@ type BCSNetIPSpec struct {
 // BCSNetIPStatus defines the observed state of BCSNetIP
 type BCSNetIPStatus struct {
 	// Active --已使用，Available --可用, Reserved --保留
-	Status string `json:"status,omitempty"`
+	Phase string `json:"phase,omitempty"`
 	// 对应主机信息
 	Host string `json:"host,omitempty"`
 	// 是否被用作固定IP
 	Fixed bool `json:"fixed,omitempty"`
 	// 容器ID
-	ContainerID        string `json:"containerID,omitempty"`
-	PodPrimaryKey      string `json:"podPrimaryKey,omitempty"`
-	PodName            string `json:"podName,omitempty"`
-	PodNamespace       string `json:"podNamespace,omitempty"`
-	UpdateTime         string `json:"updateTime,omitempty"`
-	FixedIPExpiredTime string `json:"fixedIPExpiredTime,omitempty"`
+	ContainerID string `json:"containerID,omitempty"`
+	// BCSNetIPClaim信息，格式为"命名空间/名称"
+	IPClaimKey   string      `json:"ipClaimKey,omitempty"`
+	PodName      string      `json:"podName,omitempty"`
+	PodNamespace string      `json:"podNamespace,omitempty"`
+	UpdateTime   metav1.Time `json:"updateTime,omitempty"`
+	KeepDuration string      `json:"keepDuration,omitempty"`
 }
 ```
 
+### BCSNetIPClaim
+
+用于为Pod申请固定IP时，绑定BCSNetIP实例。可以在创建BCSNetIPClaim时通过spec.bcsNetIPName指定想要绑定的IP地址，如果不指定，controller会自动绑定一个可用的BCSNetIP。当Pod被删除后，如果BCSNetIPClaim设置了spec.expiredDuration，则会为Pod保留使用的IP，直到超过了spec.expiredDuration设置的时间。如果不设置超时时间，默认永久保留IP。
+
 ```
-apiVersion: networkextension.bkbcs.tencent.com/v1
-kind: BCSNetIP
-metadata:
-  name: 10.xx.xx.20
-spec:
-  pool: 10.xx.xx.0
-  mask: 24
-  gateway: 10.xx.xx.1
+// BCSNetIPClaimSpec defines the desired state of BCSNetIPClaim
+type BCSNetIPClaimSpec struct {
+	// BCSNetIPName sets the name for BCSNetIP will be bounded with this claim
+	BCSNetIPName string `json:"bcsNetIPName,omitempty"`
+	// ExpiredDuration defines expired duration for this claim after claimed IP is released
+	ExpiredDuration string `json:"expiredDuration,omitempty"`
+}
+
+// BCSNetIPClaimStatus defines the observed state of BCSNetIPClaim
+type BCSNetIPClaimStatus struct {
+	// BCSNetIPName is name for BCSNetIP bounded with this claim
+	BoundedIP string `json:"boundedIP"`
+	// Phase represents the state of this claim
+	Phase string `json:"phase,omitempty"`
+}
 ```
 
 ## 接口
@@ -183,24 +179,93 @@ Response:
 }
 ```
 
-### 释放主机所有IP地址
+## 部署及使用
 
-Method：DELETE
+推荐使用helm部署：
 
-URL： http://localhost:8090/netservicecontroller/v1/allocator/host/{hostip}
+离线helm包：https://github.com/TencentBlueKing/bk-bcs/tree/master/install/helm/bcs-netservice-controller
 
-**hostip**: 需要释放IP地址的物理主机
+### 场景一：创建BCSNetPool及BCSNetIP
 
-Response:
+1. 创建BCSNetPool
 
-```
-{
-    "code": 0,
-    "message": "xxx",
-    "result": true,
-    "data": [],
-    "request_id": "xxx"
-}
-```
+   ```
+   kubectl apply -f bcsnetpool.yaml
+   ```
+
+   bcsnetpool.yaml参考
+
+   ```
+   apiVersion: networkextension.bkbcs.tencent.com/v1
+   kind: BCSNetPool
+   metadata:
+     name: 10.xx.xx.0
+   spec:
+     net: 10.xx.xx.0
+     mask: 24
+     gateway: 10.xx.xx.1
+     hosts:
+     - 10.xx.xx.11
+     - 10.xx.xx.12
+     availableIPs:
+     - 10.xx.xx.20
+     - 10.xx.xx.21
+     - 10.xx.xx.22
+   ```
+
+2. 查看BCSNetPool和BCSNetIP
+
+   ```
+   kubectl get bcsnetpools
+   kubectl get bcsnetips
+   ```
+
+### 场景二：Pod申请固定IP
+
+1. 创建BCSNetIPClaim
+
+   ```
+   kubectl apply -f bcsnetipclaim.yaml
+   ```
+
+   bcsnetipclaim.yaml参考，其中命名空间bcs-demo需要与Pod的命名空间相同
+
+   ```
+   apiVersion: netservice.bkbcs.tencent.com/v1
+   kind: BCSNetIPClaim
+     name: bcsnetipclaim-sample
+     namespace: bcs-demo
+   spec:
+     expiredDuration: 10h
+   ```
+
+2. 查看BCSNetIPClaim状态
+
+   ```
+   kubectl get bcsnetipclaims -n bcs-demo bcsnetipclaim-sample -oyaml
+   ```
+
+   确保claim处于Bound状态，实例
+
+   ```
+   apiVersion: netservice.bkbcs.tencent.com/v1
+   kind: BCSNetIPClaim
+   metadata:
+     finalizers:
+     - netservicecontroller.bkbcs.tencent.com
+     name: bcsnetipclaim-sample
+     namespace: default
+   spec:
+     expiredDuration: 10h
+   status:
+     boundedIP: 10.xx.xx.20
+     phase: Bound
+   ```
+
+3. 在Deployment/StatefulSet的Pod模版spec.template.metadata.annotations中添加申请固定IP的annotation
+
+   ```
+   netservicecontroller.bkbcs.tencent.com/ipclaim: <claimName>
+   ```
 
-### 
+4. Pod创建完成后，查看其IP是否与claim绑定的IP地址一致
diff --git a/docs/features/bcs-netservice-controller/bcs-netservice-controller.png b/docs/features/bcs-netservice-controller/bcs-netservice-controller.png