/kubesphere-network-extension-operations

name: kubesphere-network-extension-operations
description: Operate the KubeSphere network extension. Use when Codex needs to install, upgrade, configure, enable, disable, or inspect the `network` extension; manage Calico `IPPool` resources, namespace bindings, migrations, or network isolation flows; or consult the bundled network extension references in this skill.

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](references/README_zh.md)
• IPPool and NetworkPolicy API flows: [references/api_doc.md](references/api_doc.md)
• Extension defaults and feature toggles: [references/values.yaml](references/values.yaml)
• Packaging facts such as version, dependencies, images, and installation mode: [references/extension.yaml](references/extension.yaml)
• Full endpoint schema details only when request or response fields matter: [references/swagger.yaml](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](references/api_doc.md) for bound-namespace and pod-occupa