--- name: kubesphere/kubesphere-network-extension-operations source: https://app.decimal.ai/s/kubesphere-kubesphere-network-extension-operations@1/SKILL.md source_sha256: 570af58cb136 --- # 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: ```bash 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: ```bash 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: ```bash kubectl get crd ippools.crd.projectcalico.org ``` - Before any network isolation mutation, inspect one live object of the same type first: ```bash kubectl get workspace -o yaml kubectl get namespace -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: ```yaml apiVersion: kubesphere.io/v1alpha1 kind: InstallPlan metadata: name: network spec: enabled: true extension: name: network version: upgradeStrategy: Manual ``` Optional config snippet when the user asks to customize features: ```yaml config: | global: ippool: enable: true type: calico webhook: true networkPolicy: enable: true ``` Prefer this inspection flow before install or upgrade: ```bash kubectl get extension network -o yaml kubectl get extensionversion network- -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-occupancy query shapes instead of inventing new label selectors. Suggested live inspection commands: ```bash kubectl get ippools.crd.projectcalico.org kubectl get ippools.crd.projectcalico.org -o yaml kubectl get namespace -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: ```json { "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: ```bash kubectl describe extension network kubectl describe installplan network kubectl get installplan network -o jsonpath='{.status.targetNamespace}{"\n"}' kubectl get pods,svc -n 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.