KubeSphere Network Extension Operations
Operate the network extension and its related resources with kubectl plus the bundled references in this skill. Prefer the live cluster state first, then use the copied extension references here to resolve packaging details, API shapes, and product behavior.
When to Use
- Install, upgrade, enable, disable, or inspect the
network extension
- Edit
InstallPlan.spec.config for IPPool or NetworkPolicy feature toggles
- Verify packaging details such as version, images, dependencies, or installation mode
- Manage Calico
IPPool resources, namespace bindings, occupancy, and migration flows
- Manage cluster, workspace, or project network isolation behavior
- Create, inspect, or troubleshoot Kubernetes
NetworkPolicy and namespace-level network isolation policies
Do Not Use
- Manage unrelated extensions
- Assume deprecated
network.kubesphere.io IPPool CRDs are still the CRUD source of truth
- Assume a non-Calico IPPool backend; the extension values currently support only
calico
- Patch workspace, namespace, or IPPool binding metadata without reading the current live object first
Read First
Read only the references needed for the current request:
Useful rg patterns for the larger references:
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
Fixed Facts
- Extension name:
network
- InstallPlan name:
network
- Installation mode from packaging:
Multicluster
- Current packaged version in the copied reference:
1.3.0
- Supported IPPool backend in values:
global.ippool.type=calico
- Main feature toggles:
global.ippool.enableglobal.ippool.webhookglobal.networkPolicy.enable
Workflow
- Read the matching bundled references for the request.
- Inspect the current live extension, InstallPlan, and relevant cluster resources.
- Apply the smallest change that satisfies the request.
- Re-read the changed resources and verify the post-change state.
Preflight Checks
kubectl must already be configured for the target cluster.- Before any mutation, confirm the live extension state:
kubectl get extension network
kubectl get installplan network -o yaml
kubectl get extensionversion.kubesphere.io -l kubesphere.io/extension-ref=network
- Before any IPPool CRUD, confirm the Calico CRD exists:
kubectl get crd ippools.crd.projectcalico.org
- Before any network isolation mutation, inspect one live object of the same type first:
kubectl get workspace <workspace-name> -o yaml
kubectl get namespace <namespace-name> -o yaml
Extension Management
Use fixed resource names:
- extension:
network
- InstallPlan:
network
When creating or updating an InstallPlan:
- Use the exact version requested by the user.
- Keep
metadata.name and spec.extension.name both equal to network.
- Use
upgradeStrategy: Manual.
- Add
clusterScheduling only when the user explicitly needs agent placement in member clusters.
- Omit
spec.config unless the user asked for non-default settings.
- On upgrade, inspect the current config first and remove or update any pinned old image tags. The bundled README warns that stale tags can block new images from being deployed.
Minimal default example:
apiVersion: kubesphere.io/v1alpha1
kind: InstallPlan
metadata:
name: network
spec:
enabled: true
extension:
name: network
version: <exact-version>
upgradeStrategy: Manual
Optional config snippet when the user asks to customize features:
config: |
global:
ippool:
enable: true
type: calico
webhook: true
networkPolicy:
enable: true
Prefer this inspection flow before install or upgrade:
kubectl get extension network -o yaml
kubectl get extensionversion network-<exact-version> -o yaml
kubectl get installplan network -o yaml
IPPool Operations
Treat Calico IPPools as the CRUD source of truth:
- Create, update, delete:
/apis/crd.projectcalico.org/v1/ippools
- IP usage and occupancy details:
/kapis/network.kubesphere.io/v1alpha2/ippools/kapis/network.kubesphere.io/v1alpha2/ippools/{name}
- Migration:
POST /kapis/network.kubesphere.io/v1alpha2/ippoolmigrationsGET /kapis/network.kubesphere.io/v1alpha2/ippools/{name}/migrate
- Namespace available IPPools:
GET /kapis/network.kubesphere.io/v1alpha2/namespaces/{namespace}/ippools
Operational rules:
- Do not recreate old KubeSphere-managed IPPool CRDs from
network.kubesphere.io.
- Before binding or unbinding a namespace to an IPPool, inspect a currently bound namespace and preserve the live label or annotation format already used by the cluster.
- Before migrating an IPPool, inspect the source IPPool, bound namespaces, and current pod allocations first.
- Use the examples in references/api_doc.md for bound-namespace and pod-occupancy query shapes instead of inventing new label selectors.
Suggested live inspection commands:
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
NetworkPolicy Operations
Cluster-Scope and Namespace-Scope Kubernetes NetworkPolicy
Use Kubernetes networking.k8s.io/v1 endpoints for standard NetworkPolicy CRUD:
- List:
/kapis/networking.k8s.io/v1/networkpolicies/kapis/networking.k8s.io/v1/namespaces/{namespace}/networkpolicies
- Create:
POST /kapis/networking.k8s.io/v1/namespaces/{namespace}/networkpolicies
- Delete:
DELETE /kapis/networking.k8s.io/v1/namespaces/{namespace}/networkpolicies/{name}
Workspace and Project Isolation
The bundled API document uses inconsistent prose for the annotation key: its status-check text mentions kubesphere.io/workspace-isolate, while its patch examples use kubesphere.io/network-isolate.
Follow this rule:
- Inspect the live workspace or namespace annotations before patching.
- Unless the live cluster proves otherwise, use the example payload key
kubesphere.io/network-isolate: enabled.
Typical patch body:
{
"metadata": {
"annotations": {
"kubesphere.io/network-isolate": "enabled"
}
}
}
Namespace-Level Network Isolation Policies
Use the KubeSphere API for project-specific isolation policies:
- List:
GET /kapis/network.kubesphere.io/v1alpha1/namespaces/{namespace}/namespacenetworkpolicies
- Create:
POST /kapis/network.kubesphere.io/v1alpha1/namespaces/{namespace}/namespacenetworkpolicies
- Update:
PUT /kapis/network.kubesphere.io/v1alpha1/namespaces/{namespace}/namespacenetworkpolicies/{name}
- Delete:
DELETE /kapis/network.kubesphere.io/v1alpha1/namespaces/{namespace}/namespacenetworkpolicies/{name}
When creating or filtering these policies, preserve these labels exactly:
kubesphere.io/policy-type=egresskubesphere.io/policy-type=ingresskubesphere.io/policy-traffic=insidekubesphere.io/policy-traffic=outside
Troubleshooting
When the extension install or upgrade is stuck, gather state in this order:
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
If the InstallPlan already points to a target namespace, inspect the Helm job pod logs and any extension pods in that namespace before changing manifests again.
Rules
- Keep answers grounded in the bundled references and current live resource state.
- Prefer exact version numbers and explicit resource reads over assumptions such as "latest" or "default" without verification.
- Surface ambiguity when the copied docs and the live cluster object shape disagree.
- Treat
extension, installplan, Calico IPPools, and the live workspace or namespace objects as the source of truth.