Nodegroup Agent Skill

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:

• Inspect the current resource.
• Apply the minimal required change.
• Verify the resulting resource and any affected node, namespace, or workspace.
• 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:

• Does the resource exist?
• Does it still have a finalizer?
• Are node labels correct?
• Are namespace or workspace labels/annotations correct?
• Did IPPool annotations or labels fail to sync?
• 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 kubesphere-system -o yaml
kubectl get pods -n kubesphere-system | grep nodegroup

Important constants:

• apps.edgewize.io/nodegroup
• apps.edgewize.io/namespace-
• nodegroup.infra.kubesphere.io/parent
• infra.kubesphere.io/ippool-

Deployment and Config

If the user asks how nodegroup is deployed or configured, inspect these files from the nodegroup source repository root:

• config/nodegroup/templates/nodegroup-apiserver.yml
• config/nodegroup/templates/nodegroup-controller-manager.yaml
• config/nodegroup/templates/nodegroup-config.yaml
• config/nodegroup/values.yaml

ConfigMap key:

• nodegroup.yaml

Notable config sections:

• scheduling
• policy
• rbac
• ippool

API-First Rule

If the user asks for an operation that already has a dedicated nodegroup API, prefer the bundled script and the dedicated nodegroup API semantics over manual label hacking.

Examples:

• node bind/unbind: use python nodegroup_api.py bind node ...
• namespace bind/unbind: use python nodegroup_api.py bind namespace ...
• workspace bind/unbind: use python nodegroup_api.py bind workspace ...
• ad hoc API call: use python nodegroup_api.py request ...

Only fall back to direct manifest edits or label repair when the request is explicitly about low-level repair.

Response Style For This Skill

When using this skill:

• tell the user what operation you are performing
• verify before and after state
• mention any side effects or risks
• if blocked by missing cluster credentials or missing API access, say exactly what is missing
• if the operation is supported in code but cannot be executed in the current environment, provide the exact nodegroup_api.py command or API path to run next