KubeSphere 网络扩展 API 实战指南基于 Calico 的 IPPool 与 NetworkPolicy 管理接口全解【免费下载链接】kubesphereThe container platform tailored for Kubernetes multi-cloud, datacenter, and edge management ⎈ ☁️项目地址: https://gitcode.com/GitHub_Trending/ku/kubesphereKubeSphere 自 4.x 起将 IPPool 与网络策略能力拆分为独立的 network 扩展Extension并回归以 Calico 原生 CRDippools.crd.projectcalico.org为唯一事实源。本文以官方捆绑的 API 参考文档 为主体结合 扩展操作手册、OpenAPI 定义 与 扩展打包元数据完整梳理 IPPool 的 CRUD、占用查询、namespace 绑定、迁移以及 NetworkPolicy 在集群、企业空间、项目三种视角下的全部接口读者可按文中的请求示例直接对接 KubeSphere API Server 完成网络编排。一、背景为什么从 KubeSphere 自管 IPPool 回归 Calico 原生 CRD在 KubeSphere 3.5 之前集群的 IP 池由 KubeSphere 自定义资源ippools.network.kubesphere.io管理再由ks-controller-manager通过该 CRD间接管理 Calico 的ippools.crd.projectcalico.org。这种两层管理方式存在一个现实问题客户可能使用其他运维平台直接管理Calico 的 IPPool。两条管理路径同时操作同一批底层资源会导致网络表现不符合预期、状态互相覆盖最终造成冲突。因此KubeSphere 网络扩展network extension当前打包版本 1.3.0安装模式Multicluster要求 Kubernetes1.19、KubeSphere4.2见 extension.yaml舍弃了ippools.network.kubesphere.io回退为直接管理 Calico 原生ippools.crd.projectcalico.org从根上避免多管理方冲突。这一设计决定了后续所有 API 的形态也是 SKILL.md 中“不要把已废弃的network.kubesphere.ioIPPool CRD 当作 CRUD 事实源”的由来。API 变化总览操作场景旧方式已废弃新方式本文主体创建、修改、删除 IPPoolippools.network.kubesphere.io/apis/crd.projectcalico.org/v1/ippoolsIPPool IP 列表、占用详情KubeSphere 自管 CRD/kapis/network.kubesphere.io/v1alpha2/ippools及/{name}IPPool 被绑定的项目列表自管 CRD 内查询/kapis/resources.kubesphere.io/v1alpha3/namespaces labelSelectornamespace 绑定/取消绑定 IPPool自管 CRD 字段/api/v1/namespaces/{namespace}patch 或 putIPPool 迁移自管 CRD 字段操作/kapis/network.kubesphere.io/v1alpha2/ippoolmigrations事实源约定Calico IPPool、live 集群中的 workspace/namespace 对象、扩展与 InstallPlan 资源是判断一切状态的唯一依据使用前应先读取线上对象再决策。二、IPPool 核心 API以 Calico CRD 为事实源2.1 创建、修改、删除 IPPool所有 CRUD 操作直接落在 Calico 原生 API/apis/crd.projectcalico.org/v1/ippools例如使用kubectl或直接调用 KubeSphere API Server 创建 IPPoolkubectl apply -f - EOF apiVersion: crd.projectcalico.org/v1 kind: IPPool metadata: name: default-ipv4-ippool spec: cidr: 10.244.0.0/16 blockSize: 26 ipipMode: Always natOutgoing: true EOF从 swagger.yaml 的v3.IPPoolSpec定义可以看到 Calico IPPool 支持的核心字段管理界面中的“CIDR、是否禁用 NAT、Overlay 模式、节点选择”等选项均对应这些字段字段类型说明cidrstring必填IPPool 的网段如10.244.0.0/16blockSizeint32分配块大小Calico 将网段切成 block 分配给节点natOutgoing/nat-outgoingboolean是否对出站流量做 NATdisabledboolean是否禁用该 IPPool对应界面上的启用/禁用nodeSelectorstring限制该 IPPool 可被哪些节点使用ipipModestringIPIP 隧道模式ipip.enabled/ipip.modeboolean/stringIPIP 隧道开关与模式vxlanModestringVXLAN 隧道模式allowedUsesarray该 IPPool 允许的使用方式disableBGPExportboolean是否禁用 BGP 导出2.2 IP 列表与占用详情查询查询由network.kubesphere.io组的聚合 API 提供返回带占用统计的 IPPool 视图/kapis/network.kubesphere.io/v1alpha2/ippools # 全部 IPPool 的 IP 使用情况 /kapis/network.kubesphere.io/v1alpha2/ippools/{name} # 指定 IPPool 的 IP 使用情况请求示例# 查看所有 IPPool 的 IP 占用 curl -H Authorization: Bearer $TOKEN \ $KS_APISERVER/kapis/network.kubesphere.io/v1alpha2/ippools # 查看指定 IPPool 的 IP 占用 curl -H Authorization: Bearer $TOKEN \ $KS_APISERVER/kapis/network.kubesphere.io/v1alpha2/ippools/default-ipv4-ippool根据 swagger.yaml 中v1alpha2.IPPool的定义该接口返回的status包含以下关键指标字段类型含义capacityint32IPPool 总容量IP 总数allocationsint32已分配 IP 数量unallocatedint32未分配 IP 数量reservedint32预留 IP 数量tunnelint32隧道占用的 IP 数量namespacesmap[string]int32各 namespace 占用该 IPPool 的 IP 数量注意该聚合视图的响应模型直接内嵌 Calico 的calicov3.IPPoolapiVersion、kind、metadata、spec仅在其上附加了status统计与“直接管理 Calico CRD”的事实源保持一致。三、IPPool 与 namespace 的绑定关系管理3.1 查询 IPPool 被绑定的项目列表使用资源聚合 API 按 labelSelector 过滤 namespace/kapis/resources.kubesphere.io/v1alpha3/namespaces?sortBycreateTimelimit10labelSelectorippool.network.kubesphere.io%2Fippool-2示例curl -H Authorization: Bearer $TOKEN \ $KS_APISERVER/kapis/resources.kubesphere.io/v1alpha3/namespaces?sortBycreateTimelimit10labelSelectorippool.network.kubesphere.io%2Fippool-23.2 查询 IPPool 的容器组占用详情同样通过资源聚合 API用 pod 上的 label 过滤出“使用该 IPPool 的容器组”/kapis/resources.kubesphere.io/v1alpha3/pods?limit6labelSelectorippool.network.kubesphere.io%2Fname%3Ddefault-ipv4-ippoolsortBystartTimecurl -H Authorization: Bearer $TOKEN \ $KS_APISERVER/kapis/resources.kubesphere.io/v1alpha3/pods?limit6labelSelectorippool.network.kubesphere.io%2Fname%3Ddefault-ipv4-ippoolsortBystartTime3.3 namespace 绑定 / 取消绑定 IPPool直接对 namespace 对象打补丁patch 或 put 均可/api/v1/namespaces/{namespace}# 绑定为 namespace 添加 IPPool 标签 curl -X PATCH -H Authorization: Bearer $TOKEN -H Content-Type: application/merge-patchjson \ $KS_APISERVER/api/v1/namespaces/project -d { metadata: { labels: { ippool.network.kubesphere.io/ippool-2: } } } # 取消绑定移除对应标签 curl -X PATCH -H Authorization: Bearer $TOKEN -H Content-Type: application/merge-patchjson \ $KS_APISERVER/api/v1/namespaces/project -d { metadata: { labels: { ippool.network.kubesphere.io/ippool-2: null } } }运维提醒来自 SKILL.md绑定/解绑前务必先kubectl get namespace ns -o yaml查看线上对象保留集群实际使用的 label 或 annotation 格式不要凭文档示例臆造键名。3.4 取消 IPPool 的全部 namespace 绑定流程为两步通过 3.1 的接口获取该 IPPool 当前绑定的所有 namespace逐个遍历 namespace使用 patch 或 put 取消绑定同 3.3。3.5 获取 namespace 可用的 IPPool 列表/kapis/network.kubesphere.io/v1alpha2/namespaces/{namespace}/ippools示例获取defaultnamespace 可用的 IPPoolcurl -H Authorization: Bearer $TOKEN \ $KS_APISERVER/kapis/network.kubesphere.io/v1alpha2/namespaces/default/ippools该接口在 swagger.yaml 中的响应模型为calicov3.IPPoolList说明返回的同样是 Calico 原生 IPPool 对象列表可配合创建工作负载时的“容器组 IP 池”下拉选项使用。四、IPPool 迁移 API当需要把容器组从旧 IP 池迁移到新 IP 池时使用迁移接口而无需逐个重建工作负载POST /kapis/network.kubesphere.io/v1alpha2/ippoolmigrations请求体formData 字段参数类型必填说明oldippoolstring-要迁出的 IPPool 名称newippoolstring-要迁入的 IPPool 名称curl -X POST -H Authorization: Bearer $TOKEN \ $KS_APISERVER/kapis/network.kubesphere.io/v1alpha2/ippoolmigrations \ -d oldippoolold-poolnewippoolnew-pool获取可以迁移的 IPPool 列表即某个 IPPool 可以迁移到的候选池GET /kapis/network.kubesphere.io/v1alpha2/ippools/{name}/migratecurl -H Authorization: Bearer $TOKEN \ $KS_APISERVER/kapis/network.kubesphere.io/v1alpha2/ippools/old-pool/migrate迁移前的安全检查SKILL.md 明确要求先检查源 IPPool、已绑定的 namespace 以及当前的 pod 分配情况再执行迁移。推荐的线上检查命令kubectl get ippools.crd.projectcalico.org kubectl get ippools.crd.projectcalico.org ippool-name -o yaml kubectl get pods -A -o wide五、NetworkPolicy集群视角的网络策略管理标准 KubernetesNetworkPolicynetworking.k8s.io/v1通过 KubeSphere 聚合 API 暴露可在集群级或 namespace 级进行管理查询/kapis/networking.k8s.io/v1/networkpolicies /kapis/networking.k8s.io/v1/namespaces/{namespace}/networkpolicies?page1sortBycreateTimelimit10创建POST /kapis/networking.k8s.io/v1/namespaces/{namespace}/networkpolicies删除DELETE /kapis/networking.k8s.io/v1/namespaces/{namespace}/networkpolicies/{name}示例# 集群视角列出全部网络策略 curl -H Authorization: Bearer $TOKEN \ $KS_APISERVER/kapis/networking.k8s.io/v1/networkpolicies # 在 project namespace 创建网络策略 curl -X POST -H Authorization: Bearer $TOKEN \ $KS_APISERVER/kapis/networking.k8s.io/v1/namespaces/project/networkpolicies \ -d { apiVersion: networking.k8s.io/v1, kind: NetworkPolicy, metadata: { name: allow-nginx }, spec: { podSelector: { matchLabels: { app: nginx } }, policyTypes: [Ingress], ingress: [{ from: [{ podSelector: {} }] }] } }六、网络隔离企业空间与项目视角网络隔离通过 workspace / namespace 上的annotation控制值为enabled表示启用。6.1 企业空间Workspace隔离判断是否启用查看 workspace annotation 中kubesphere.io/workspace-isolate的值——值为enabled表示已启用不存在或其他值表示未启用。启用/禁用patch 或 update workspace 对象PATCH/PUT /apis/tenant.kubesphere.io/v1beta1/workspaces/{name}{ metadata: { annotations: { kubesphere.io/network-isolate: enabled } } }6.2 项目Namespace隔离判断是否启用查看 namespace annotation 中kubesphere.io/workspace-isolate的值判断规则同企业空间。启用/禁用patch namespacePATCH /api/v1/namespaces/{namespace}{ metadata: { annotations: { kubesphere.io/network-isolate: enabled } } }6.3 关键提醒annotation 键名的不一致原 API 文档在“判断是否启用”的叙述中写的键是kubesphere.io/workspace-isolate而给出的 patch 示例请求体使用的是kubesphere.io/network-isolate。捆绑的 SKILL.md 明确指出了这一不一致并给出处理规则patch 之前先读取线上 workspace/namespace 的实际 annotations除非线上集群证明相反否则以示例请求体中的键kubesphere.io/network-isolate: enabled为准。因此在实际操作中务必先执行kubectl get workspace name -o yaml或kubectl get namespace name -o yaml确认现有键名再决定写入network-isolate还是workspace-isolate避免新增一个互不生效的重复键。七、项目视角的 NamespaceNetworkPolicynamespacenetworkpolicies除标准 NetworkPolicy 外网络扩展还提供 KubeSphere 特有的namespacenetworkpolicies资源用于项目namespace级网络策略与隔离CRUD 端点操作端点查询GET /kapis/network.kubesphere.io/v1alpha1/namespaces/{namespace}/namespacenetworkpolicies?sortBycreateTimelimit10创建POST /kapis/network.kubesphere.io/v1alpha1/namespaces/{namespace}/namespacenetworkpolicies编辑PUT /kapis/network.kubesphere.io/v1alpha1/namespaces/{namespace}/namespacenetworkpolicies/{name}删除DELETE /kapis/network.kubesphere.io/v1alpha1/namespaces/{namespace}/namespacenetworkpolicies/{name}7.1 创建时必须携带的标签策略通过两组标签区分流量方向与白名单范围必须原样保留SKILL.md 同样强调这一点标签值含义kubesphere.io/policy-trafficinside内部白名单kubesphere.io/policy-trafficoutside外部白名单kubesphere.io/policy-typeegress出站流量kubesphere.io/policy-typeingress入站流量7.2 示例创建“外部白名单的出站流量”策略{ metadata: { name: allow-egress-outside, labels: { kubesphere.io/policy-type: egress, kubesphere.io/policy-traffic: outside } }, spec: { podSelector: { matchLabels: { app: frontend } }, egress: [{ to: [{ ipBlock: { cidr: 0.0.0.0/0 } }] }] } }创建请求curl -X POST -H Authorization: Bearer $TOKEN \ $KS_APISERVER/kapis/network.kubesphere.io/v1alpha1/namespaces/project-2/namespacenetworkpolicies \ -d { metadata: { name: allow-egress-outside, labels: { kubesphere.io/policy-type: egress, kubesphere.io/policy-traffic: outside } } }7.3 示例按标签过滤查询指定策略查询“外部白名单的出站流量”策略注意 labelSelector 的 URL 编码GET /kapis/network.kubesphere.io/v1alpha1/namespaces/project-2/namespacenetworkpolicies?page1sortBycreateTimelimit10labelSelectorkubesphere.io%2Fpolicy-type%3Degress%2Ckubesphere.io%2Fpolicy-traffic%3Doutsidecurl -H Authorization: Bearer $TOKEN \ $KS_APISERVER/kapis/network.kubesphere.io/v1alpha1/namespaces/project-2/namespacenetworkpolicies?page1sortBycreateTimelimit10labelSelectorkubesphere.io%2Fpolicy-type%3Degress%2Ckubesphere.io%2Fpolicy-traffic%3Doutside八、接口鉴权与调用前提所有/kapis/...聚合接口均要求JWT 鉴权。根据 swagger.yaml 的securityDefinitionssecurityDefinitions: jwt: in: header name: Authorization type: apiKey security: - jwt: []即每个请求都必须在Authorization请求头携带Bearer token。调用前还应确认# 确认 Calico CRD 存在IPPool 操作前提 kubectl get crd ippools.crd.projectcalico.org # 确认扩展与 InstallPlan 状态 kubectl get extension network kubectl get installplan network -o yaml九、扩展功能开关与部署配置网络扩展支持分别开关IPPool 与 NetworkPolicy 两大功能对应 values.yaml 中的默认配置global: ippool: enable: true type: calico # 当前仅支持 calico webhook: true # 为 calico ippool 启用 webhook networkPolicy: enable: trueglobal.ippool.enable是否启用 IPPool 功能global.ippool.typeIPPool 后端类型当前仅支持calicoglobal.ippool.webhook是否为 Calico IPPool 启用准入校验 webhookglobal.networkPolicy.enable是否启用 NetworkPolicy 功能。在通过 扩展安装文档 安装时可在“扩展组件配置”中按需修改这些开关enable 为 true 开启false 关闭。扩展的部署形态为Multicluster前端组件network-extension-frontend在控制面集群Agent 组件network-extension-apiserver、network-extension-controller可分发到成员集群镜像清单见 extension.yaml。十、运维要点与常见坑不要重建旧版 KubeSphere IPPool CRDippools.network.kubesphere.io已废弃不要将其作为 CRUD 事实源否则会与 Calico 原生管理路径产生冲突。升级扩展前检查镜像标签升级时若在配置里显式固定了旧镜像 tag可能导致升级后仍拉取旧镜像而拿不到新功能详见 README_zh.md 的升级注意事项。推荐使用默认配置让系统自动匹配当前版本的镜像标签。annotation 键名以线上为准network-isolate与workspace-isolate的叙述不一致是文档已知问题patch 前先读取线上对象。绑定/迁移前先读现场namespace 的绑定格式、IPPool 的分配情况都要先kubectl get确认再执行变更。故障排查顺序扩展安装/升级卡住时先kubectl describe extension network与kubectl describe installplan network再检查目标 namespace 中的 pod、svc 与 helm 升级 Job 日志。上述所有端点、参数与字段均可在 api_doc.md 与 swagger.yaml 中交叉核对完整字段定义calicov3.IPPool、v3.IPPoolSpec、v1alpha2.ippoolStatus等可直接作为对接 OpenAPI 客户端生成的依据。【免费下载链接】kubesphereThe container platform tailored for Kubernetes multi-cloud, datacenter, and edge management ⎈ ☁️项目地址: https://gitcode.com/GitHub_Trending/ku/kubesphere创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考