/kubesphere-volcano

name: kubesphere-volcano
description: KubeSphere Volcano job management Skill. Use when user asks to create, list, update, delete Jobs (Volcano Jobs), manage Queues, create PyTorch/TensorFlow/MPI training jobs, or troubleshoot Volcano scheduling issues in KubeSphere. Includes built-in YAML templates, scheduling policy recommendations, and best practices for resource configuration. Handles both KubeSphere API and kubectl operations.

KubeSphere Volcano Management

**Environment (this KubeSphere instance):**

• KubeSphere: Set `KS_HOST` environment variable (e.g., http://<kubesphere-host>:30880)
• Username: admin (default)
• Password: Set `KS_PASSWORD` environment variable
• Clusters: Run `kubectl get clusters` or `ks_api GET /kapis/cluster.kubesphere.io/v1alpha1/clusters`
• Volcano Extension: Run `kubectl get extension volcano -n kubesphere-system` or check via KubeSphere console

Use this skill for the full Volcano lifecycle in KubeSphere:

• Create, list, update, delete Volcano Jobs
• Manage Queues for job scheduling
• Generate YAML templates for PyTorch, TensorFlow, MPI, and batch jobs
• Troubleshoot job pending, pod creation, and scheduling issues

Out of scope by default:

• Advanced Volcano CRDs not requested by the user, such as `JobFlow`, `JobTemplate`, or `Command`
• Deep scheduler configuration without cluster evidence
• Volcano system installation (assume extension is already installed)

If the user explicitly asks for those, acknowledge that they are Volcano capabilities but treat them as a follow-up task.

Response Rules

• Prefer executable output: `Job` YAML, `Queue` YAML, kubectl commands, or a short ordered procedure.
• Use `kind: Job` (not VolcanoJob), the correct resource type in this KubeSphere environment.
• Use `kubectl get jobs.batch.volcano.sh` or short name `vcjob`/`vj` to query jobs.
• For uninstall/delete requests, warn that deleting Job resources will terminate running pods.
• Omit optional fields instead of guessing values.

**IMPORTANT**: The resource type is `Job` (short: vcjob, vj), NOT `VolcanoJob`. Use these names in all kubectl commands.

API Usage

This skill supports two approaches for API operations. See **Discovery Commands** section below for detailed commands.

API Endpoints

KubeSphere provides two API paths for Volcano Job:

Option 1: KubeSphere Extension API (/kapis) - Recommended

Uses `volcanojobs` resource name:

# Job CRUD (namespace-scoped)
GET    /kapis/batch.volcano.sh/v1alpha1/namespaces/{namespace}/volcanojobs
POST   /kapis/batch.volcano.sh/v1alpha1/namespaces/{namespace}/volcanojobs
GET    /kapis/batch.volcano.sh/v1alpha1/namespaces/{namespace}/volcanojobs/{name}
DELETE /kapis/batch.volcano.sh/v1alpha1/namespaces/{namespace}/volcanojobs/{name}

# Job CRUD (cluster-scoped)
GET    /kapis/batch.volcano.sh/v1alpha1/volcanojobs
DELETE /kapis/batch.volcano.sh/v1alpha1/volcanojobs

# PodGroup CRUD (namespace-scoped)
GET    /kapis/batch.volcano.sh/v1alpha1/namespaces/{namespace}/podgroups

# Queue CRUD (user-scoped)
GET    /kapis/scheduling.volcano.sh/v1beta1/users/{user}/queues
POST   /kapis/scheduling.volcano.sh/v1beta1/users/{user}/queues
DELETE /kapis/scheduling.volcano.sh/v1beta1/users/{user}/queues/{name}

Option 2: Kubernetes Native API (/apis)

Uses `jobs` resource name:

# Job CRUD (namespace-scoped)
GET    /apis/batch.volcano.sh/v1alpha1/namespaces/{namespace}/jobs
POST   /apis/batch.volcano.sh/v1alpha1/namespaces/{namespace}/jobs
GET    /apis/batch.volcano.sh/v1alpha1/namespaces/{namespace}/jobs/{name}
DELETE /apis/batch.volcano.sh/v1alpha1/namespaces/{namespace}/jobs/{name}

# Job CRUD (cluster-scoped)
GET    /apis/batch.volcano.sh/v1alpha1/jobs
DELETE /apis/batch.volcano.sh/v1alpha1/jobs

# Queue CRUD (cluster-scoped)
GET    /apis/scheduling.volcano.sh/v1beta1/queues
POST   /apis/scheduling.volcano.sh/v1beta1/queues
DELETE /apis/scheduling.volcano.sh/v1beta1/queues/{name}

> **Note**: Both paths work. Use `/kapis` for KubeSphere extension API (multi-cluster support), use `/apis` for standard Kubernetes API.

> **Note**: Queue API has two views: > - `/kapis/.../users/{user}/queues` returns queues visible to that user (user-scoped) > - `/apis/.../queues` returns all queues in the cluster (cluster-scoped)

# Query Parameters
page      - Page number (default: 1)
limit     - Items per page
ascending - Sort direction (default: false)
sortBy    - Sort field (e.g., createTime)

Discovery Commands

This section provides two approaches for querying Volcano status: 1. **KubeSphere API (curl)** - for extension management and multi-cluster queries 2. **kubectl** - for direct Kubernetes resource operations

Option 1: Using KubeSphere API (curl)

**Environment Variables:**

export KS_HOST="http://<kubesphere-host>:30880"  # KubeSphere console URL (required)
export KS_USERNAME="admin"                         # Username (default)
export KS_PASSWORD="<password>"                    # Password (optional if KS_TOKEN is set)
export KS_TOKEN="<token>"                          # Pre-generated OAuth token (optional, takes priority)

# Get OAuth token - prefer KS_TOKEN if set, otherwise use password
ks_token() {
  # Use KS_TOKEN if it's set and non-empty
  if [ -n "${KS_TOKEN}" ]; then
    echo "$KS_TOKEN"
    return
  fi
  
  # Fall back to password-based token
  if [ -z "${KS_PASSWORD}" ]; then
    echo "Error: KS_TOKEN or KS_PASSWORD must be set" >&2
    return 1
  fi
  
  curl -s -X POST "${KS_HOST}/oauth/token" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "grant_type=password&username=${KS_USERNAME:-admin}&password=$KS_PASSWORD&client_id=kubesphere&client_secret=kubesphere" | jq -r '.access_token'
}

# Make API call (supports multi-cluster with optional cluster parameter)
ks_api() {
  local method=$1
  local path=$2
  local cluster=${3:-host}  # Default to host cluster. Pass 3rd arg for member clusters.
  local body=$4
  local token=$(ks_token)
  
  #