/kubesphere-fluid

name: kubesphere-fluid
description: KubeSphere Fluid management Skill. Use when user asks to install or enable Fluid, check Fluid status, view Fluid pods/logs/CRDs, create or update Dataset, AlluxioRuntime, JuiceFSRuntime, or ThinRuntime, perform DataLoad or cache warming, scale runtime, or troubleshoot Fluid issues in KubeSphere.

KubeSphere Fluid Management

Use this skill for the full Fluid lifecycle in KubeSphere:

• Install or upgrade the Fluid extension through `InstallPlan`
• Query extension status, CRDs, Pods, and logs
• Generate `Dataset` manifests with mount configuration
• Generate `AlluxioRuntime`, `JuiceFSRuntime`, or `ThinRuntime` manifests for caching
• Perform DataLoad for cache warming
• Scale runtime replicas
• Uninstall the Fluid extension
• Troubleshoot Fluid Pods, CRDs, and mount issues

Out of scope by default:

• Advanced Fluid operations not requested by the user, such as `DataBackup` or `GooseFS`
• Deep tiered storage configuration without user requirements

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

Response Rules

• Prefer executable output: `InstallPlan` YAML, `Dataset` YAML, `AlluxioRuntime` YAML, kubectl commands, or a short ordered procedure.
• Verify the extension name and exact version before generating a final `InstallPlan`.
• Default the extension name to `fluid` only if the user context or cluster output does not expose a different resource name.
• Use `upgradeStrategy: Manual` unless the user explicitly asks for something else.
• Omit optional fields instead of guessing values.
• Before generating Dataset or Runtime, prefer checking the installed API versions:

kubectl api-resources --api-group data.fluid.io

• If the cluster version is unknown and the user only wants an example, use:
• Dataset: `data.fluid.io/v1alpha1`
• AlluxioRuntime: `data.fluid.io/v1alpha1`
• JuiceFSRuntime: `data.fluid.io/v1alpha1`
• ThinRuntime: `data.fluid.io/v1alpha1`
• For uninstall requests, warn that deleting CRDs or CR instances can remove application configuration.

CRITICAL: Parameter Handling

**ALWAYS use the exact values provided by the user. Never substitute or guess values.**

When generating YAML manifests:

| Parameter | Rule | |-----------|------| | `name` | MUST use user's value exactly | | `namespace` | MUST use user's value exactly | | `mountPoint` | MUST use user's value exactly (e.g., s3://bucket, oss://bucket, pvc://, https://) | | `replicas` | MUST use user's value exactly | | `quota` | MUST use user's value exactly | | `mediumType` | Use user's value, default to MEM if not specified | | `path` | Use user's value, default to /dev/shm if not specified |

**WRONG**: Using `pvc://` when user specified `s3://mybucket/spark-data` **RIGHT**: Using exactly what user provided: `s3://mybucket/spark-data`

CRITICAL: Operation Scope

**Each operation has a specific scope. Do NOT create additional resources unless user explicitly asks.**

| User Request | Output Scope | |--------------|--------------| | "Create Dataset" | Only Dataset YAML | | "Create AlluxioRuntime" | Only AlluxioRuntime YAML (NOT Dataset) | | "Create JuiceFSRuntime" | Only JuiceFSRuntime YAML (NOT Dataset) | | "Create ThinRuntime" | Only ThinRuntime YAML (NOT Dataset) | | "Create Dataset with Runtime" | Both Dataset + Runtime YAML | | "Create DataLoad" | Only DataLoad YAML |

**Example:**

• User says: "Create an AlluxioRuntime" → Output ONLY AlluxioRuntime YAML
• User says: "Create a Dataset with AlluxioRuntime" → Output both Dataset and AlluxioRuntime YAML

Version Mapping Discovery

When the user asks for precision, prove the version mapping first:

# Discover KubeSphere extension version
kubectl get extensionversions.kubesphere.io -l kubesphere.io/extension-ref=fluid
kubectl get extensionversion fluid-<version> -o yaml

# Discover Fluid runtime image or controller version
kubectl get pods -n fluid-system -o wide
kubectl get deploy -n fluid-system alluxio-runtime-controller -o jsonpath='{.spec.template.spec.containers[*].image}'
kubectl describe pod -n fluid-system <fluid-pod>

If these commands disagree with assumed mappings, prefer cluster output over defaults.

Discovery Commands

This section provides three approaches for querying Fluid status: 1. **KubeSphere API (curl)** - for extension management and multi-cluster queries 2. **kubectl** - for direct Kubernetes resource operations 3. **ksctl CLI** - KubeSphere command-line tool

Option 1: Using KubeSphere API (curl)

Use curl with environment variables for querying KubeSphere extension status and multi-cluster resources.

**Environment Variables:**

export KS_HOST="http://<kubesphere-host>"     # KubeSphere console URL (required)
export KS_USERNAME="admin"                     # Username (default: admin)
export KS_PASSWORD="<password>"                # Password (required)

**Helper Functions (add to ~/.bashrc or use directly):**

# Get OAuth token
ks_token() {
  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: ks_api GET/POST/PUT/DELETE <path> [body]
ks_api() {
  local method=${1:-GET}
  local path=$2
  local body=$3
  local token=$(ks_token)
  
  curl -s -X "$method" \
    -H "Authorization: Bearer $token" \
    -H "Content-Type: application/json" \
    ${body:+-d "$body"} \
    "$KS_HOST$path"
}

**Query Commands:**

# List all clusters (host + member clusters)
ks_api GET /kapis/cluster.kubesphere.io/v1alpha1/clusters | jq -r '.items[].metadata.name'

# List installed extensions
ks_api GET /kapis/kubesphere.io/v1alpha1/extensions | jq -r '.items[].metadata.name' | grep -i fluid

# List available extension versions
ks_api GET /kapis/kubesphere.io/v1alpha1/