---

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/extensionversions | jq -r '.items[].metadata.name' | grep -i fluid

# Get Fluid extension details
ks_api GET /kapis/kubesphere.io/v1alpha1/extensions/fluid | jq

# Get cluster connection status
ks_api GET /kapis/cluster.kubesphere.io/v1alpha1/clusters/<cluster>/status | jq '.conditions'

Multi-Cluster Resource Query:

# Get datasets in host cluster
ks_api GET /clusters/host/kapis/data.fluid.io/v1alpha1/namespaces/<namespace>/datasets

# Get alluxioruntimes in host cluster
ks_api GET /clusters/host/kapis/data.fluid.io/v1alpha1/namespaces/<namespace>/alluxioruntimes

# Get all runtimes (Alluxio + JuiceFS + Thin)
ks_api GET /clusters/host/kapis/data.fluid.io/v1alpha1/namespaces/<namespace>/allruntimes

# Get specific dataset
ks_api GET /clusters/host/kapis/data.fluid.io/v1alpha1/namespaces/<namespace>/datasets/<name>

# Get CRDs in cluster
ks_api GET /clusters/host/apis/apiextensions.k8s.io/v1/customresourcedefinitions | jq -r '.items[] | select(.metadata.name | contains("fluid")) | .metadata.name'

API Path Format:

# For KubeSphere extension management:
/kapis/kubesphere.io/v1alpha1/extensions
/kapis/cluster.kubesphere.io/v1alpha1/clusters

# For Fluid resources in namespace:
/clusters/{cluster}/kapis/data.fluid.io/v1alpha1/namespaces/{namespace}/{resources}
/clusters/{cluster}/kapis/data.fluid.io/v1alpha1/namespaces/{namespace}/{resources}/{name}

Query Parameters:

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

Supported Resource Types:

• datasets
• alluxioruntimes
• juicefsruntimes
• dataloads
• thinruntimes
• allruntimes

CRUD Operations via KubeSphere API

Create Operations:

# Create Dataset
DATASET_JSON='{
  "apiVersion": "data.fluid.io/v1alpha1",
  "kind": "Dataset",
  "metadata": {
    "name": "<name>",
    "namespace": "<namespace>"
  },
  "spec": {
    "mounts": [{
      "mountPoint": "<mountPoint>",
      "name": "<mountName>"
    }]
  }
}'

ks_api POST /clusters/host/kapis/data.fluid.io/v1alpha1/namespaces/$NAMESPACE/datasets "$DATASET_JSON"

# Or use kubectl:
# kubectl apply -f examples/dataset.yaml

Read Operations:

# List all datasets in namespace
ks_api GET /clusters/host/kapis/data.fluid.io/v1alpha1/namespaces/$NAMESPACE/datasets

# Get specific dataset
ks_api GET /clusters/host/kapis/data.fluid.io/v1alpha1/namespaces/$NAMESPACE/datasets/<name>

Update Operations (Scale Runtime):

# Scale AlluxioRuntime via PUT
RUNTIME_UPDATE='{"spec":{"replicas":<new-replicas>}}'
ks_api PUT /clusters/host/kapis/data.fluid.io/v1alpha1/namespaces/$NAMESPACE/alluxioruntimes/<name> "$RUNTIME_UPDATE"

# Or use kubectl:
# kubectl scale alluxioruntime <name> -n <namespace> --replicas=<n>

Delete Operations:

# Delete dataset
ks_api DELETE /clusters/host/kapis/data.fluid.io/v1alpha1/namespaces/$NAMESPACE/datasets/<name>

# Delete alluxioruntime
ks_api DELETE /clusters/host/kapis/data.fluid.io/v1alpha1/namespaces/$NAMESPACE/thinruntimes/<name>
ks_api DELETE /clusters/host/kapis/data.fluid.io/v1alpha1/namespaces/$NAMESPACE/alluxioruntimes/<name>

Option 2: Using kubectl (Direct Cluster Access)

Use kubectl for direct Kubernetes resource operations.

# Extension and version discovery in KubeSphere
kubectl get extensions.kubesphere.io | grep -i fluid
kubectl get extensionversions.kubesphere.io | grep -i fluid

# InstallPlan and extension status
kubectl get installplans.kubesphere.io
kubectl get installplan fluid -o yaml
kubectl describe extension fluid
kubectl describe extensionversion fluid-<version>

# Fluid runtime resources
kubectl api-resources --api-group data.fluid.io
kubectl get crd | grep -E 'datasets.data.fluid.io|alluxioruntimes.data.fluid.io'
kubectl get pods -A | grep -i fluid
kubectl get datasets.data.fluid.io -A
kubectl get alluxioruntimes.data.fluid.io -A

Option 3: Using ksctl CLI

# List available datasets
ksctl get dataset -n <namespace>

# Create dataset with runtime
ksctl create dataset -f dataset.yaml

# Check status
ksctl describe dataset <name> -n <namespace>

When to Use Which Approach

| Scenario | Recommended Approach | |----------|---------------------| | Query KubeSphere extension status | KubeSphere API (curl) | | List available clusters | KubeSphere API (curl) | | Query host cluster Kubernetes resources | kubectl | | Query member cluster Kubernetes resources | kubeconfig extraction | | Create/apply Dataset/Runtime | kubectl | | Get extension version info | KubeSphere API (curl) | | Quick status check | ksctl |

KubeSphere UI relation:

• Users can also discover and enable the extension from the KubeSphere Extension Marketplace UI
• When the user asks for repeatable or reviewable operations, prefer InstallPlan manifests and kubectl
• When the user explicitly wants console steps, explain the equivalent UI path instead of forcing YAML

---

Example Files

This skill includes ready-to-use example manifests in the examples/ directory:

| File | Description | |------|-------------| | examples/dataset.yaml | Minimal Dataset manifest | | examples/alluxioruntime.yaml | Dataset + AlluxioRuntime with tiered storage | | examples/juicefs.yaml | Dataset + JuiceFSRuntime | | examples/thinruntime.yaml | Dataset + ThinRuntime | | examples/dataload.yaml | DataLoad for cache warming | | examples/installplan.yaml | InstallPlan for Fluid extension |

---

Install Fluid in KubeSphere

1. Pre-check

kubectl get extension fluid
kubectl get extensionversions.kubesphere.io -l kubesphere.io/extension-ref=fluid
kubectl describe extensionversion fluid-<exact-version>

Check:

• The extension resource exists
• The exact extension version exists
• Whether the extension is single-cluster or multi-cluster
• Whether the user needs custom config

2. InstallPlan Template

Use this when the user has a