KubeSphere 网络扩展network运维实战指南Calico IPPool 与 NetworkPolicy 的完整操作手册【免费下载链接】kubesphereThe container platform tailored for Kubernetes multi-cloud, datacenter, and edge management ⎈ ☁️项目地址: https://gitcode.com/GitHub_Trending/ku/kubesphere导读本文是面向 KubeSphere 平台管理员与开发者的网络扩展运维指南核心主题是network扩展——一个基于 Calico 的 Pod IP 池IPPool与网络策略NetworkPolicyUI 管理组件。你将掌握该扩展的安装、升级、配置、卸载全流程Calico IPPool 的 CRUD、命名空间绑定、占用查询与迁移操作以及集群/企业空间/项目三个视角下的网络隔离与网络策略管理 API。文中所有命令、配置与 API 均来自当前仓库中 SKILL.md 及其随附参考文档并给出对应的仓库源码路径供进一步查证。扩展定位基于 Calico 的 IPPool 与 NetworkPolicy 管理界面根据 references/README_zh.mdnetwork扩展是一个基于 Calico 的 IPPool 和 NetworkPolicy 的 UI 管理界面允许用户通过友好界面管理和配置 Calico 的 IPPool 与 NetworkPolicy。扩展的能力边界非常清晰IPPool 管理支持创建、更新和删除 IPPool并可查看每个 IPPool 的详细信息包括其 CIDR、是否禁用 NATnat-outgoing等NetworkPolicy 管理支持创建、更新和删除 NetworkPolicy并可查看每个策略的选择器、规则等详情。从 references/extension.yaml 的打包元数据可以确认该扩展的核心事实扩展名称networkInstallPlan 名称同为network当前打包版本1.3.0安装模式installationModeMulticluster多集群模式需要向成员集群下发 Agent 组件组件组成frontendExtension 组件即 UI 前端与networkAgent 组件包含 apiserver 与 controller兼容性约束kubeVersion: 1.19.0-0ksVersion: 4.2.0-0即需要 Kubernetes 1.19 与 KubeSphere 4.2.0镜像清单docker.io/kubesphere/network-extension-frontend:v1.3.0、docker.io/kubesphere/network-extension-apiserver:v1.3.0、docker.io/kubesphere/network-extension-controller:v1.3.0以及辅助镜像kubesphere/kubectl:v1.27.12和kubesphere/ks-extension-upgrade:v0.3.2。需要特别强调的是该扩展目前只支持 Calico 作为 IPPool 后端。在 references/values.yaml 中global.ippool.type被固定为calico注释明确写着only support calico now。因此在运维时不要假设存在非 Calico 的 IPPool 后端。扩展安装、升级与卸载通过扩展中心安装按照 references/README_zh.md 的安装指引UI 侧操作流程为在扩展中心页面点击KubeSphere 网络点击安装选择最新版本按需修改扩展组件配置配置完成后点击开始安装静待安装完成在集群选择页面勾选需要安装 Agent 的集群对应Multicluster安装模式在差异化配置页面按需编辑集群 Agent 配置点击确认开始安装集群 Agent。升级时的镜像标签陷阱references/README_zh.md 对升级给出了明确的警告新版本通常会使用新的镜像标签如果您在配置中显式指定了旧的镜像标签可能会导致升级后仍拉取旧版本镜像无法获得最新功能或修复。因此升级前必须检查并移除手动设置的镜像标签或更新为新版本所需标签推荐使用默认配置让系统自动匹配与当前版本一致的镜像标签。这一点在 SKILL.md 的 Extension Management 章节被列为强制检查项——升级时需先检查当前spec.config删除或更新其中固定的旧镜像标签。从源码层面印证values.yaml中三个核心组件镜像的tag字段默认均为注释状态如# tag: v1.3.0这正是由安装器按版本自动注入标签的设计手动写死标签反而会破坏升级语义。卸载在扩展中心页面点击KubeSphere 网络点击已安装旁边的图标选择卸载即可开始卸载流程。扩展配置功能开关与组件镜像参数扩展的配置集中在 references/values.yaml 中安装或升级时可通过 InstallPlan 的spec.config覆盖。核心配置分为两大部分。全局功能开关globalglobal: # 覆盖所有组件的镜像仓库与标签如 registry.cn-beijing.aliyuncs.com 或 docker.io imageRegistry: imagePullSecrets: [] upgradeConfig: enabled: true installCrds: true upgradeCrds: true # mergeValues: false # failurePolicy: 0 # dynamicOptions: # key: value ippool: enable: true type: calico # only support calico now webhook: true # enable webhook for calico ippool networkPolicy: enable: true各开关含义配置项默认值说明global.ippool.enabletrue是否开启 IPPool 功能true开启、false关闭global.ippool.typecalicoIPPool 后端类型当前仅支持calicoglobal.ippool.webhooktrue是否为 Calico IPPool 启用准入 Webhook用于校验/默认值注入global.networkPolicy.enabletrue是否开启 NetworkPolicy 功能组件镜像与资源配额frontend: image: registry: docker.io repository: kubesphere/network-extension-frontend # tag: v1.3.0 pullPolicy: IfNotPresent resources: limits: { cpu: 100m, memory: 200Mi } requests: { cpu: 10m, memory: 50Mi } hook: image: registry: docker.io repository: kubesphere/kubectl tag: v1.27.12 pullPolicy: IfNotPresent network: apiserver: image: registry: docker.io repository: kubesphere/network-extension-apiserver # tag: v1.3.0 pullPolicy: IfNotPresent resources: limits: { cpu: 100m, memory: 200Mi } requests: { cpu: 5m, memory: 50Mi } controller: image: registry: docker.io repository: kubesphere/network-extension-controller # tag: v1.3.0 pullPolicy: IfNotPresent resources: limits: { cpu: 100m, memory: 200Mi } requests: { cpu: 10m, memory: 50Mi }可见扩展由前端frontend、网络 API Servernetwork.apiserver与网络控制器network.controller三部分组成均为轻量级组件CPU 请求最低仅 5m。hook.image使用kubesphere/kubectl:v1.27.12用于安装/升级时在集群内执行辅助命令如 CRD 安装。扩展管理的命令行操作Extension 与 InstallPlan操作前置检查PreflightSKILL.md 要求所有变更操作前先确认集群状态# 确认扩展与 InstallPlan 的实时状态 kubectl get extension network kubectl get installplan network -o yaml kubectl get extensionversion.kubesphere.io -l kubesphere.io/extension-refnetwork # 任何 IPPool CRUD 之前确认 Calico CRD 存在 kubectl get crd ippools.crd.projectcalico.org # 任何网络隔离变更之前先读取同类型的一个实时对象 kubectl get workspace workspace-name -o yaml kubectl get namespace namespace-name -o yaml最小化 InstallPlan 示例创建或更新 InstallPlan 时SKILL.md 给出以下硬性规则使用用户指定的精确版本号不要使用latest之类的模糊值metadata.name与spec.extension.name都必须等于network使用upgradeStrategy: Manual仅在用户明确需要成员集群 Agent 调度时才添加clusterScheduling除非用户要求非默认配置否则省略spec.config。apiVersion: kubesphere.io/v1alpha1 kind: InstallPlan metadata: name: network spec: enabled: true extension: name: network version: exact-version upgradeStrategy: Manual定制功能时的 config 片段当需要定制功能开关时通过spec.config注入config: | global: ippool: enable: true type: calico webhook: true networkPolicy: enable: true安装/升级前的检查流kubectl get extension network -o yaml kubectl get extensionversion network-exact-version -o yaml kubectl get installplan network -o yamlSKILL.md 给出的标准工作流是读取匹配的参考文档 → 检查扩展/InstallPlan/相关集群资源的实时状态 → 施加满足需求的最小变更 → 重新读取变更后的资源验证状态。任何场景下都应优先读取集群实时状态随附参考文档只用于解决打包细节、API 形态与产品行为问题。IPPool 运维以 Calico 为唯一真相源为什么放弃 KubeSphere 自有的 IPPool CRDreferences/api_doc.md 明确解释了架构演进的背景KubeSphere 3.5 之前使用ippools.network.kubesphere.io管理 IPPool由ks-controller-manager间接管理 Calico 的ippools.crd.projectcalico.org。但客户可能使用其他运维平台直接管理 Calico 的 IPPool两种管理方式并存会导致网络表现不符合预期、产生冲突。因此扩展舍弃了 KubeSphere 自有的ippools.network.kubesphere.io回退为直接管理 Calico 的ippools.crd.projectcalico.org。这带来一个明确的运维纪律SKILL.md 的 Do Not Use 部分不要假设已废弃的network.kubesphere.ioIPPool CRD 仍是 CRUD 的真相源不要重新创建旧版 KubeSphere 管理的network.kubesphere.ioIPPool CRD。IPPool 相关 API 总览根据 references/api_doc.md 与 references/swagger.yamlIPPool 相关端点如下操作API 端点说明创建/修改/删除 IPPool/apis/crd.projectcalico.org/v1/ippools直接操作 Calico 原生 CRD真相源IP 使用量/占用详情GET /kapis/network.kubesphere.io/v1alpha2/ippools返回全部 IPPool 的 IP 使用情况单个 IPPool 占用详情GET /kapis/network.kubesphere.io/v1alpha2/ippools/{name}按名称查询 IP 使用情况IPPool 绑定的项目列表GET /kapis/resources.kubesphere.io/v1alpha3/namespaces?labelSelectorippool.network.kubesphere.io%2Fippool-2通过 label selector 查询绑定命名空间IPPool 的 Pod 占用详情GET /kapis/resources.kubesphere.io/v1alpha3/pods?labelSelectorippool.network.kubesphere.io%2Fname%3Ddefault-ipv4-ippool按 IPPool 名称筛选 PodNamespace 绑定/解绑 IPPoolPATCH/PUT /api/v1/namespaces/{namespace}修改命名空间上的绑定标签/注解迁移 IPPoolPOST /kapis/network.kubesphere.io/v1alpha2/ippoolmigrationsbodyoldippoolxxx newippoolxxx获取可迁移的 IPPool 列表GET /kapis/network.kubesphere.io/v1alpha2/ippools/{name}/migrate返回可迁入的目标池列表获取 Namespace 可用 IPPoolGET /kapis/network.kubesphere.io/v1alpha2/namespaces/{namespace}/ippools按命名空间过滤可用池从 swagger 的v1alpha2.ippoolStatus定义可以看到 IPPool 状态字段allocations已分配数、capacity容量、namespaces各命名空间占用数映射、reserved保留、tunnel隧道占用、unallocated未分配。v3.IPPoolSpec则展示了 Calico IPPool 的核心规格字段cidr必填、blockSize、ipipMode、vxlanMode、natOutgoing是否禁用 NAT 出站注意同时兼容nat-outgoing写法、disabled、nodeSelector、allowedUses等。迁移 IPPool 的实操规则SKILL.md 规定迁移前的检查顺序先检查源 IPPool → 已绑定的命名空间 → 当前 Pod 分配情况然后再执行迁移。建议的实时检查命令kubectl get ippools.crd.projectcalico.org kubectl get ippools.crd.projectcalico.org ippool-name -o yaml kubectl get namespace namespace-name -o yaml kubectl get pods -A -o wide命名空间绑定/解绑的纪律绑定或解绑命名空间前必须先读取一个已绑定的命名空间对象保留集群中现用的 label 或 annotation 格式不同集群的绑定表达方式可能不同不要凭空发明 label selector。SKILL.md 明确要求参考 references/api_doc.md 中的绑定命名空间与 Pod 占用查询示例来构造查询而不是自行臆造 selector。取消全部命名空间绑定流程为先获取 IPPool 绑定的所有 Namespace 列表再逐个遍历 Namespace使用PATCH/PUT /api/v1/namespaces/{namespace}取消绑定。NetworkPolicy 运维集群、企业空间与项目三层视角集群视角标准 Kubernetes NetworkPolicy集群范围内的网络策略直接使用 Kubernetesnetworking.k8s.io/v1端点进行标准 CRUD列表GET /kapis/networking.k8s.io/v1/networkpolicies集群级GET /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}企业空间与项目隔离annotation 关键点的辨析references/api_doc.md 在描述判断是否启用时提到根据 workspace/namespace 的kubesphere.io/workspace-isolate注解值判断enabled为启用不存在或其他值为未启用但其 patch 示例使用的键是kubesphere.io/network-isolate。SKILL.md 明确指出这是原文档行文不一致并给出了处理规则patch 之前先检查 workspace 或 namespace 的实时注解除非实时集群证明相反否则使用示例 payload 的键kubesphere.io/network-isolate: enabled。典型的 patch body企业空间使用/apis/tenant.kubesphere.io/v1beta1/workspaces/{name}项目使用/api/v1/namespaces/{namespace}{ metadata: { annotations: { kubesphere.io/network-isolate: enabled } } }该注解值即网络隔离开关enabled表示启用网络隔离默认拒绝出/入站流量配合下方白名单策略放行移除或改为其他值则关闭。项目视角Namespace 级网络隔离策略KubeSphere 提供项目专用的网络隔离策略 APInamespacenetworkpolicies列表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}创建或过滤这类策略时必须原样保留以下四个标签它们决定了策略的语义方向标签取值含义kubesphere.io/policy-typeegress出站出方向白名单kubesphere.io/policy-typeingress入站入方向白名单kubesphere.io/policy-trafficinside内部白名单项目/企业空间内部流量kubesphere.io/policy-trafficoutside外部白名单项目/企业空间外部流量例如创建外部白名单的出站流量策略labels 部分应为labels: { kubesphere.io/policy-type: egress, kubesphere.io/policy-traffic: outside }对应的查询示例带 URL 编码的 labelSelectorGET /kapis/network.kubesphere.io/v1alpha1/namespaces/project-2/namespacenetworkpolicies?page1sortBycreateTimelimit10labelSelectorkubesphere.io%2Fpolicy-type%3Degress%2Ckubesphere.io%2Fpolicy-traffic%3DoutsideUI 中的功能入口安装完成后扩展的功能入口references/README_zh.md集群左侧导航栏显示服务与网络菜单可配置网络策略、容器组 IP 池企业空间左侧导航栏显示服务与网络菜单可查看项目网络策略、配置企业空间和项目的网络隔离创建工作负载或任务时高级设置页签显示容器组 IP 池选项可为容器组指定所属 IP 池分配该池中的 IP 地址。网络隔离与 IP 池的使用语义网络策略用于控制集群中容器组的访问与被访问权限允许在同个集群内实现网络隔离可以只允许容器组访问特定的其他容器组或网段也可以只允许容器组被特定的其他容器组或网段访问。网络隔离则用于控制企业空间和项目中容器组的出站和入站流量——两者配合构成从集群到项目层级的完整网络管控体系。容器组 IP 池用于为容器组分配 IP 地址每个池包含一个可在集群内部访问的私网 IP 网段。在集群的容器组 IP 池菜单下可以创建、查看、编辑、禁用和启用 IP 池将池分配到项目编辑 Overlay 模式并为池自动匹配合适的节点。当工作负载/任务通过高级设置 → 容器组 IP 池指定池后其创建的容器组会从该池中获取 IP。故障排查安装或升级卡住时的状态收集当扩展安装或升级停滞时SKILL.md 建议按以下顺序收集状态kubectl describe extension network kubectl describe installplan network kubectl get installplan network -o jsonpath{.status.targetNamespace}{\n} kubectl get pods,svc -n target-namespace kubectl get jobs -A | rg helm-upgrade-network|network kubectl get pods -n kubesphere-system排查要点如果 InstallPlan 已经指向目标命名空间status.targetNamespace有值先检查该命名空间下Helm job Pod 的日志和扩展自身的 Pod再考虑修改 manifest重点检查是否存在helm-upgrade-network相关的 Job安装/升级由 Helm 作业驱动关注kubesphere-system中控制面 Pod 的状态。运维纪律与真相源优先级综合 SKILL.md 的 Rules 章节网络扩展运维必须遵守以下纪律一切回答以随附参考文档 集群实时资源状态为准不依赖记忆或猜测优先使用精确版本号和显式资源读取避免未经验证的latest/default假设当随附文档与实时集群对象形态不一致时主动暴露歧义如上面workspace-isolate与network-isolate的差异而不是替用户默默消化将以下对象视为唯一真相源extension、installplan、CalicoIPPoolippools.crd.projectcalico.org、以及实时的 workspace/namespace 对象做最小变更每次变更后重新读取资源验证状态。速查仓库内随附参考资源本指南对应的完整操作技能与全部参考文档均位于仓库skills/kubesphere-network-extension-operations/目录下可直接查阅SKILL.md操作技能主文档references/README_zh.md产品行为与升级注意事项references/api_doc.mdIPPool 与 NetworkPolicy API 流程references/values.yaml扩展默认值与功能开关references/extension.yaml打包事实版本、依赖、镜像、安装模式references/swagger.yaml完整端点 Schema在大型参考文档中快速定位时可使用以下rg模式rg -n ippool|networkpol|isolate skills/kubesphere-network-extension-operations/references/api_doc.md rg -n ^ /(kapis|apis)/.*(ippool|networkpol) skills/kubesphere-network-extension-operations/references/swagger.yaml【免费下载链接】kubesphereThe container platform tailored for Kubernetes multi-cloud, datacenter, and edge management ⎈ ☁️项目地址: https://gitcode.com/GitHub_Trending/ku/kubesphere创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
KubeSphere 网络扩展（network）运维实战指南：Calico IPPool 与 NetworkPolicy 的完整操作手册
KubeSphere 网络扩展network运维实战指南Calico IPPool 与 NetworkPolicy 的完整操作手册【免费下载链接】kubesphereThe container platform tailored for Kubernetes multi-cloud, datacenter, and edge management ⎈ ☁️项目地址: https://gitcode.com/GitHub_Trending/ku/kubesphere导读本文是面向 KubeSphere 平台管理员与开发者的网络扩展运维指南核心主题是network扩展——一个基于 Calico 的 Pod IP 池IPPool与网络策略NetworkPolicyUI 管理组件。你将掌握该扩展的安装、升级、配置、卸载全流程Calico IPPool 的 CRUD、命名空间绑定、占用查询与迁移操作以及集群/企业空间/项目三个视角下的网络隔离与网络策略管理 API。文中所有命令、配置与 API 均来自当前仓库中 SKILL.md 及其随附参考文档并给出对应的仓库源码路径供进一步查证。扩展定位基于 Calico 的 IPPool 与 NetworkPolicy 管理界面根据 references/README_zh.mdnetwork扩展是一个基于 Calico 的 IPPool 和 NetworkPolicy 的 UI 管理界面允许用户通过友好界面管理和配置 Calico 的 IPPool 与 NetworkPolicy。扩展的能力边界非常清晰IPPool 管理支持创建、更新和删除 IPPool并可查看每个 IPPool 的详细信息包括其 CIDR、是否禁用 NATnat-outgoing等NetworkPolicy 管理支持创建、更新和删除 NetworkPolicy并可查看每个策略的选择器、规则等详情。从 references/extension.yaml 的打包元数据可以确认该扩展的核心事实扩展名称networkInstallPlan 名称同为network当前打包版本1.3.0安装模式installationModeMulticluster多集群模式需要向成员集群下发 Agent 组件组件组成frontendExtension 组件即 UI 前端与networkAgent 组件包含 apiserver 与 controller兼容性约束kubeVersion: 1.19.0-0ksVersion: 4.2.0-0即需要 Kubernetes 1.19 与 KubeSphere 4.2.0镜像清单docker.io/kubesphere/network-extension-frontend:v1.3.0、docker.io/kubesphere/network-extension-apiserver:v1.3.0、docker.io/kubesphere/network-extension-controller:v1.3.0以及辅助镜像kubesphere/kubectl:v1.27.12和kubesphere/ks-extension-upgrade:v0.3.2。需要特别强调的是该扩展目前只支持 Calico 作为 IPPool 后端。在 references/values.yaml 中global.ippool.type被固定为calico注释明确写着only support calico now。因此在运维时不要假设存在非 Calico 的 IPPool 后端。扩展安装、升级与卸载通过扩展中心安装按照 references/README_zh.md 的安装指引UI 侧操作流程为在扩展中心页面点击KubeSphere 网络点击安装选择最新版本按需修改扩展组件配置配置完成后点击开始安装静待安装完成在集群选择页面勾选需要安装 Agent 的集群对应Multicluster安装模式在差异化配置页面按需编辑集群 Agent 配置点击确认开始安装集群 Agent。升级时的镜像标签陷阱references/README_zh.md 对升级给出了明确的警告新版本通常会使用新的镜像标签如果您在配置中显式指定了旧的镜像标签可能会导致升级后仍拉取旧版本镜像无法获得最新功能或修复。因此升级前必须检查并移除手动设置的镜像标签或更新为新版本所需标签推荐使用默认配置让系统自动匹配与当前版本一致的镜像标签。这一点在 SKILL.md 的 Extension Management 章节被列为强制检查项——升级时需先检查当前spec.config删除或更新其中固定的旧镜像标签。从源码层面印证values.yaml中三个核心组件镜像的tag字段默认均为注释状态如# tag: v1.3.0这正是由安装器按版本自动注入标签的设计手动写死标签反而会破坏升级语义。卸载在扩展中心页面点击KubeSphere 网络点击已安装旁边的图标选择卸载即可开始卸载流程。扩展配置功能开关与组件镜像参数扩展的配置集中在 references/values.yaml 中安装或升级时可通过 InstallPlan 的spec.config覆盖。核心配置分为两大部分。全局功能开关globalglobal: # 覆盖所有组件的镜像仓库与标签如 registry.cn-beijing.aliyuncs.com 或 docker.io imageRegistry: imagePullSecrets: [] upgradeConfig: enabled: true installCrds: true upgradeCrds: true # mergeValues: false # failurePolicy: 0 # dynamicOptions: # key: value ippool: enable: true type: calico # only support calico now webhook: true # enable webhook for calico ippool networkPolicy: enable: true各开关含义配置项默认值说明global.ippool.enabletrue是否开启 IPPool 功能true开启、false关闭global.ippool.typecalicoIPPool 后端类型当前仅支持calicoglobal.ippool.webhooktrue是否为 Calico IPPool 启用准入 Webhook用于校验/默认值注入global.networkPolicy.enabletrue是否开启 NetworkPolicy 功能组件镜像与资源配额frontend: image: registry: docker.io repository: kubesphere/network-extension-frontend # tag: v1.3.0 pullPolicy: IfNotPresent resources: limits: { cpu: 100m, memory: 200Mi } requests: { cpu: 10m, memory: 50Mi } hook: image: registry: docker.io repository: kubesphere/kubectl tag: v1.27.12 pullPolicy: IfNotPresent network: apiserver: image: registry: docker.io repository: kubesphere/network-extension-apiserver # tag: v1.3.0 pullPolicy: IfNotPresent resources: limits: { cpu: 100m, memory: 200Mi } requests: { cpu: 5m, memory: 50Mi } controller: image: registry: docker.io repository: kubesphere/network-extension-controller # tag: v1.3.0 pullPolicy: IfNotPresent resources: limits: { cpu: 100m, memory: 200Mi } requests: { cpu: 10m, memory: 50Mi }可见扩展由前端frontend、网络 API Servernetwork.apiserver与网络控制器network.controller三部分组成均为轻量级组件CPU 请求最低仅 5m。hook.image使用kubesphere/kubectl:v1.27.12用于安装/升级时在集群内执行辅助命令如 CRD 安装。扩展管理的命令行操作Extension 与 InstallPlan操作前置检查PreflightSKILL.md 要求所有变更操作前先确认集群状态# 确认扩展与 InstallPlan 的实时状态 kubectl get extension network kubectl get installplan network -o yaml kubectl get extensionversion.kubesphere.io -l kubesphere.io/extension-refnetwork # 任何 IPPool CRUD 之前确认 Calico CRD 存在 kubectl get crd ippools.crd.projectcalico.org # 任何网络隔离变更之前先读取同类型的一个实时对象 kubectl get workspace workspace-name -o yaml kubectl get namespace namespace-name -o yaml最小化 InstallPlan 示例创建或更新 InstallPlan 时SKILL.md 给出以下硬性规则使用用户指定的精确版本号不要使用latest之类的模糊值metadata.name与spec.extension.name都必须等于network使用upgradeStrategy: Manual仅在用户明确需要成员集群 Agent 调度时才添加clusterScheduling除非用户要求非默认配置否则省略spec.config。apiVersion: kubesphere.io/v1alpha1 kind: InstallPlan metadata: name: network spec: enabled: true extension: name: network version: exact-version upgradeStrategy: Manual定制功能时的 config 片段当需要定制功能开关时通过spec.config注入config: | global: ippool: enable: true type: calico webhook: true networkPolicy: enable: true安装/升级前的检查流kubectl get extension network -o yaml kubectl get extensionversion network-exact-version -o yaml kubectl get installplan network -o yamlSKILL.md 给出的标准工作流是读取匹配的参考文档 → 检查扩展/InstallPlan/相关集群资源的实时状态 → 施加满足需求的最小变更 → 重新读取变更后的资源验证状态。任何场景下都应优先读取集群实时状态随附参考文档只用于解决打包细节、API 形态与产品行为问题。IPPool 运维以 Calico 为唯一真相源为什么放弃 KubeSphere 自有的 IPPool CRDreferences/api_doc.md 明确解释了架构演进的背景KubeSphere 3.5 之前使用ippools.network.kubesphere.io管理 IPPool由ks-controller-manager间接管理 Calico 的ippools.crd.projectcalico.org。但客户可能使用其他运维平台直接管理 Calico 的 IPPool两种管理方式并存会导致网络表现不符合预期、产生冲突。因此扩展舍弃了 KubeSphere 自有的ippools.network.kubesphere.io回退为直接管理 Calico 的ippools.crd.projectcalico.org。这带来一个明确的运维纪律SKILL.md 的 Do Not Use 部分不要假设已废弃的network.kubesphere.ioIPPool CRD 仍是 CRUD 的真相源不要重新创建旧版 KubeSphere 管理的network.kubesphere.ioIPPool CRD。IPPool 相关 API 总览根据 references/api_doc.md 与 references/swagger.yamlIPPool 相关端点如下操作API 端点说明创建/修改/删除 IPPool/apis/crd.projectcalico.org/v1/ippools直接操作 Calico 原生 CRD真相源IP 使用量/占用详情GET /kapis/network.kubesphere.io/v1alpha2/ippools返回全部 IPPool 的 IP 使用情况单个 IPPool 占用详情GET /kapis/network.kubesphere.io/v1alpha2/ippools/{name}按名称查询 IP 使用情况IPPool 绑定的项目列表GET /kapis/resources.kubesphere.io/v1alpha3/namespaces?labelSelectorippool.network.kubesphere.io%2Fippool-2通过 label selector 查询绑定命名空间IPPool 的 Pod 占用详情GET /kapis/resources.kubesphere.io/v1alpha3/pods?labelSelectorippool.network.kubesphere.io%2Fname%3Ddefault-ipv4-ippool按 IPPool 名称筛选 PodNamespace 绑定/解绑 IPPoolPATCH/PUT /api/v1/namespaces/{namespace}修改命名空间上的绑定标签/注解迁移 IPPoolPOST /kapis/network.kubesphere.io/v1alpha2/ippoolmigrationsbodyoldippoolxxx newippoolxxx获取可迁移的 IPPool 列表GET /kapis/network.kubesphere.io/v1alpha2/ippools/{name}/migrate返回可迁入的目标池列表获取 Namespace 可用 IPPoolGET /kapis/network.kubesphere.io/v1alpha2/namespaces/{namespace}/ippools按命名空间过滤可用池从 swagger 的v1alpha2.ippoolStatus定义可以看到 IPPool 状态字段allocations已分配数、capacity容量、namespaces各命名空间占用数映射、reserved保留、tunnel隧道占用、unallocated未分配。v3.IPPoolSpec则展示了 Calico IPPool 的核心规格字段cidr必填、blockSize、ipipMode、vxlanMode、natOutgoing是否禁用 NAT 出站注意同时兼容nat-outgoing写法、disabled、nodeSelector、allowedUses等。迁移 IPPool 的实操规则SKILL.md 规定迁移前的检查顺序先检查源 IPPool → 已绑定的命名空间 → 当前 Pod 分配情况然后再执行迁移。建议的实时检查命令kubectl get ippools.crd.projectcalico.org kubectl get ippools.crd.projectcalico.org ippool-name -o yaml kubectl get namespace namespace-name -o yaml kubectl get pods -A -o wide命名空间绑定/解绑的纪律绑定或解绑命名空间前必须先读取一个已绑定的命名空间对象保留集群中现用的 label 或 annotation 格式不同集群的绑定表达方式可能不同不要凭空发明 label selector。SKILL.md 明确要求参考 references/api_doc.md 中的绑定命名空间与 Pod 占用查询示例来构造查询而不是自行臆造 selector。取消全部命名空间绑定流程为先获取 IPPool 绑定的所有 Namespace 列表再逐个遍历 Namespace使用PATCH/PUT /api/v1/namespaces/{namespace}取消绑定。NetworkPolicy 运维集群、企业空间与项目三层视角集群视角标准 Kubernetes NetworkPolicy集群范围内的网络策略直接使用 Kubernetesnetworking.k8s.io/v1端点进行标准 CRUD列表GET /kapis/networking.k8s.io/v1/networkpolicies集群级GET /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}企业空间与项目隔离annotation 关键点的辨析references/api_doc.md 在描述判断是否启用时提到根据 workspace/namespace 的kubesphere.io/workspace-isolate注解值判断enabled为启用不存在或其他值为未启用但其 patch 示例使用的键是kubesphere.io/network-isolate。SKILL.md 明确指出这是原文档行文不一致并给出了处理规则patch 之前先检查 workspace 或 namespace 的实时注解除非实时集群证明相反否则使用示例 payload 的键kubesphere.io/network-isolate: enabled。典型的 patch body企业空间使用/apis/tenant.kubesphere.io/v1beta1/workspaces/{name}项目使用/api/v1/namespaces/{namespace}{ metadata: { annotations: { kubesphere.io/network-isolate: enabled } } }该注解值即网络隔离开关enabled表示启用网络隔离默认拒绝出/入站流量配合下方白名单策略放行移除或改为其他值则关闭。项目视角Namespace 级网络隔离策略KubeSphere 提供项目专用的网络隔离策略 APInamespacenetworkpolicies列表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}创建或过滤这类策略时必须原样保留以下四个标签它们决定了策略的语义方向标签取值含义kubesphere.io/policy-typeegress出站出方向白名单kubesphere.io/policy-typeingress入站入方向白名单kubesphere.io/policy-trafficinside内部白名单项目/企业空间内部流量kubesphere.io/policy-trafficoutside外部白名单项目/企业空间外部流量例如创建外部白名单的出站流量策略labels 部分应为labels: { kubesphere.io/policy-type: egress, kubesphere.io/policy-traffic: outside }对应的查询示例带 URL 编码的 labelSelectorGET /kapis/network.kubesphere.io/v1alpha1/namespaces/project-2/namespacenetworkpolicies?page1sortBycreateTimelimit10labelSelectorkubesphere.io%2Fpolicy-type%3Degress%2Ckubesphere.io%2Fpolicy-traffic%3DoutsideUI 中的功能入口安装完成后扩展的功能入口references/README_zh.md集群左侧导航栏显示服务与网络菜单可配置网络策略、容器组 IP 池企业空间左侧导航栏显示服务与网络菜单可查看项目网络策略、配置企业空间和项目的网络隔离创建工作负载或任务时高级设置页签显示容器组 IP 池选项可为容器组指定所属 IP 池分配该池中的 IP 地址。网络隔离与 IP 池的使用语义网络策略用于控制集群中容器组的访问与被访问权限允许在同个集群内实现网络隔离可以只允许容器组访问特定的其他容器组或网段也可以只允许容器组被特定的其他容器组或网段访问。网络隔离则用于控制企业空间和项目中容器组的出站和入站流量——两者配合构成从集群到项目层级的完整网络管控体系。容器组 IP 池用于为容器组分配 IP 地址每个池包含一个可在集群内部访问的私网 IP 网段。在集群的容器组 IP 池菜单下可以创建、查看、编辑、禁用和启用 IP 池将池分配到项目编辑 Overlay 模式并为池自动匹配合适的节点。当工作负载/任务通过高级设置 → 容器组 IP 池指定池后其创建的容器组会从该池中获取 IP。故障排查安装或升级卡住时的状态收集当扩展安装或升级停滞时SKILL.md 建议按以下顺序收集状态kubectl describe extension network kubectl describe installplan network kubectl get installplan network -o jsonpath{.status.targetNamespace}{\n} kubectl get pods,svc -n target-namespace kubectl get jobs -A | rg helm-upgrade-network|network kubectl get pods -n kubesphere-system排查要点如果 InstallPlan 已经指向目标命名空间status.targetNamespace有值先检查该命名空间下Helm job Pod 的日志和扩展自身的 Pod再考虑修改 manifest重点检查是否存在helm-upgrade-network相关的 Job安装/升级由 Helm 作业驱动关注kubesphere-system中控制面 Pod 的状态。运维纪律与真相源优先级综合 SKILL.md 的 Rules 章节网络扩展运维必须遵守以下纪律一切回答以随附参考文档 集群实时资源状态为准不依赖记忆或猜测优先使用精确版本号和显式资源读取避免未经验证的latest/default假设当随附文档与实时集群对象形态不一致时主动暴露歧义如上面workspace-isolate与network-isolate的差异而不是替用户默默消化将以下对象视为唯一真相源extension、installplan、CalicoIPPoolippools.crd.projectcalico.org、以及实时的 workspace/namespace 对象做最小变更每次变更后重新读取资源验证状态。速查仓库内随附参考资源本指南对应的完整操作技能与全部参考文档均位于仓库skills/kubesphere-network-extension-operations/目录下可直接查阅SKILL.md操作技能主文档references/README_zh.md产品行为与升级注意事项references/api_doc.mdIPPool 与 NetworkPolicy API 流程references/values.yaml扩展默认值与功能开关references/extension.yaml打包事实版本、依赖、镜像、安装模式references/swagger.yaml完整端点 Schema在大型参考文档中快速定位时可使用以下rg模式rg -n ippool|networkpol|isolate skills/kubesphere-network-extension-operations/references/api_doc.md rg -n ^ /(kapis|apis)/.*(ippool|networkpol) skills/kubesphere-network-extension-operations/references/swagger.yaml【免费下载链接】kubesphereThe container platform tailored for Kubernetes multi-cloud, datacenter, and edge management ⎈ ☁️项目地址: https://gitcode.com/GitHub_Trending/ku/kubesphere创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
