/nodegroup

name: nodegroup
description: NodeGroup operation Skill for the edgewize nodegroup project. Use this whenever the user wants to query, create, update, delete, bind, unbind, or troubleshoot NodeGroup resources, including node binding, namespace binding, workspace binding, and deployment/config inspection for nodegroup.

NodeGroup Operations

Purpose

Use this skill to perform real `nodegroup`-related operations in the `edgewize-io/nodegroup` environment.

This skill should help with:

• listing and inspecting `NodeGroup`
• creating, updating, patching, and deleting `NodeGroup`
• binding and unbinding nodes
• binding and unbinding namespaces
• binding and unbinding workspaces
• troubleshooting failed or incomplete nodegroup sync
• checking deployment config under `config/nodegroup`

Prefer using the bundled script `scripts/nodegroup_api.py` for authenticated KAPI operations. Use `kubectl` only as a verification or fallback tool when the API path is unavailable.

Prerequisites

Use the bundled script:

• `scripts/nodegroup_api.py`

Authentication model:

• logs in against `/oauth/token`
• stores token in `~/.kubesphere_token`
• uses `KUBESPHERE_HOST`, `KUBESPHERE_USERNAME`, `KUBESPHERE_PASSWORD`, and `KUBESPHERE_TOKEN`

Setup:

cd scripts
pip install requests
export KUBESPHERE_HOST="http://<kubesphere-host>"
python nodegroup_api.py login --username admin --password <password>

Token helpers:

python nodegroup_api.py clear-cache
python nodegroup_api.py request GET /kapis/infra.kubesphere.io/v1alpha1/nodegroups

Source of Truth

When you need to confirm how an operation works, read these files first from the nodegroup source repository root:

• `pkg/kapis/infra/v1alpha1/register.go`
• `pkg/kapis/infra/v1alpha1/handler.go`
• `pkg/kapis/infra/v1alpha1/workspace_handler.go`
• `pkg/controller/nodegroup/nodegroup_controller.go`
• `pkg/constants/constants.go`

Do not invent unsupported operations. Base the workflow on the source repository.

Main Resources

NodeGroup

Cluster-scoped resource.

Important fields:

• `spec.alias`
• `spec.description`
• `spec.manager`
• `status.state`

Safe Operating Rules

• Read-only requests: prefer `python nodegroup_api.py ...` query commands.
• Write requests: perform only the exact requested change.
• Do not delete resources unless the user explicitly asks for deletion.
• For destructive or potentially disruptive actions such as node unbind or delete, confirm impact in your response if the request is ambiguous.
• When changing bindings, verify the current state first, then apply the change, then verify the result.

Preferred Operation Flow

For any write operation, follow this order:

1. Inspect the current resource. 2. Apply the minimal required change. 3. Verify the resulting resource and any affected node, namespace, or workspace. 4. If sync looks wrong, inspect labels, annotations, and controller behavior.

Core Commands

1. Query NodeGroups

python nodegroup_api.py nodegroup list
python nodegroup_api.py nodegroup get <name>

2. Create a NodeGroup

python nodegroup_api.py nodegroup create \
  --name <nodegroup-name> \
  --alias "<alias>" \
  --description "<description>" \
  --manager "<manager>"
python nodegroup_api.py nodegroup get <nodegroup-name>

3. Update or Patch a NodeGroup

Prefer patching for small changes.

python nodegroup_api.py nodegroup patch <name> \
  --alias "<new-alias>" \
  --description "<new-description>" \
  --manager "<manager>"
python nodegroup_api.py nodegroup get <name>

For unsupported fields or ad hoc testing, use raw request mode.

For `PATCH`, send a JSON Patch array:

python nodegroup_api.py request PATCH /kapis/infra.kubesphere.io/v1alpha1/nodegroups/<name> '[{"op":"add","path":"/spec/alias","value":"<new-alias>"}]'

4. Delete a NodeGroup

Only do this when explicitly requested.

python nodegroup_api.py nodegroup delete <name>

If delete hangs, inspect finalizers:

python nodegroup_api.py nodegroup get <name>

Relevant finalizer:

• `finalizers.nodegroups.kubesphere.io`

5. Bind or Unbind a Node

Node binding is implemented through nodegroup APIs and reflected with label:

• `apps.edgewize.io/nodegroup=<nodegroup-name>`

Read current state:

kubectl get node <node-name> --show-labels
kubectl get nodes -l apps.edgewize.io/nodegroup=<nodegroup-name>

Operate through the bundled script:

python nodegroup_api.py bind node --nodegroup <nodegroup-name> --node <node-name>
python nodegroup_api.py unbind node --nodegroup <nodegroup-name> --node <node-name>

# Verify
kubectl get nodes -l apps.edgewize.io/nodegroup=<nodegroup-name>
kubectl get node <node-name> -o yaml

6. Bind or Unbind a Namespace

Read current state:

kubectl get ns <namespace> --show-labels

Operate through the bundled script:

python nodegroup_api.py bind namespace --nodegroup <nodegroup-name> --namespace <namespace>
python nodegroup_api.py unbind namespace --nodegroup <nodegroup-name> --namespace <namespace>

# Verify
python nodegroup_api.py nodegroup get <nodegroup-name>
kubectl get ns <namespace> -o yaml

7. Bind or Unbind a Workspace

python nodegroup_api.py bind workspace --nodegroup <nodegroup-name> --workspace <workspace>
python nodegroup_api.py unbind workspace --nodegroup <nodegroup-name> --workspace <workspace>

Troubleshooting Checklist

When an operation appears to succeed but state is wrong, check these in order:

1. Does the resource exist? 2. Does it still have a finalizer? 3. Are node labels correct? 4. Are namespace or workspace labels/annotations correct? 5. Did IPPool annotations or labels fail to sync? 6. Is the feature enabled in nodegroup config?

Useful checks:

python nodegroup_api.py nodegroup get <name>
kubectl get node <node-name> -o yaml
kubectl get ns <namespace> -o yaml
kubectl get cm nodegroup-config -n kubesphe