KubeSphere Network Extension Operations

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:

• Product behavior and upgrade caveats: references/​README_zh.md
• IPPool and NetworkPolicy API flows: references/​api_doc.md
• Extension defaults and feature toggles: references/​values.yaml
• Packaging facts such as version, dependencies, images, and installation mode: references/​extension.yaml
• Full endpoint schema details only when request or response fields matter: references/​swagger.yaml

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.enable
  • global.ippool.webhook
  • global.networkPolicy.enable

Workflow

1. Read the matching bundled references for the request.
2. Inspect the current live extension, InstallPlan, and relevant cluster resources.
3. Apply the smallest change that satisfies the request.
4. 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/​ippoolmigrations
  • GET /​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=egress
• kubesphere.io/​policy-type=ingress
• kubesphere.io/​policy-traffic=inside
• kubesphere.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.