Loading
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 ThinRuntim
The skill file stays in the publisher's repository.
Paste the copied command in a terminal. It installs this SKILL.md into that agent.
npx skills add kubesphere/kubesphere --skill kubesphere-fluid -a cursor -y
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 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.
Use this skill for the full Fluid lifecycle in KubeSphere:
InstallPlanDataset manifests with mount configurationAlluxioRuntime, JuiceFSRuntime, or ThinRuntime manifests for cachingOut of scope by default:
DataBackup or GooseFSIf the user explicitly asks for those, acknowledge that they are Fluid capabilities but treat them as a follow-up task.
InstallPlan YAML, Dataset YAML, AlluxioRuntime YAML, kubectl commands, or a short ordered procedure.InstallPlan.fluid only if the user context or cluster output does not expose a different resource name.upgradeStrategy: Manual unless the user explicitly asks for something else.kubectl api-resources --api-group data.fluid.io
data.fluid.io/v1alpha1data.fluid.io/v1alpha1data.fluid.io/v1alpha1data.fluid.io/v1alpha1ALWAYS 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
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:
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.
This section provides three approaches for querying Fluid status:
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 pageascending - Sort direction (default: false)sortBy - Sort field (e.g., createTime)Supported Resource Types:
datasetsalluxioruntimesjuicefsruntimesdataloadsthinruntimesallruntimesCreate 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>
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
# 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>
| 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:
InstallPlan manifests and kubectlThis 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 |
kubectl get extension fluid
kubectl get extensionversions.kubesphere.io -l kubesphere.io/extension-ref=fluid
kubectl describe extensionversion fluid-<exact-version>
Check:
Use this when the user has already confirmed the extension name and version.
# See examples/installplan.yaml for the template
kubectl apply -f examples/installplan.yaml
kubectl get installplan fluid -w
kubectl describe installplan fluid
kubectl get extension fluid -o yaml
# See examples/dataset.yaml
# Key fields:
# - spec.mounts[].mountPoint: Data source (s3://, oss://, pvc://, https://) - USE EXACT VALUE FROM USER
# - spec.mounts[].name: Mount identifier
# - spec.mounts[].readOnly: Read-only mount (default: false)
IMPORTANT: When user provides mountPoint, use it EXACTLY. Do not substitute.
Common operations:
kubectl apply -f examples/dataset.yaml
kubectl get dataset <name> -n <namespace>
kubectl describe dataset <name> -n <namespace>
kubectl delete dataset <name> -n <namespace>
When user asks to create AlluxioRuntime ONLY, generate ONLY AlluxioRuntime YAML:
apiVersion: data.fluid.io/v1alpha1
kind: AlluxioRuntime
metadata:
name: {{name}}
namespace: {{namespace}}
spec:
replicas: {{replicas}}
tieredstore:
levels:
- mediumtype: {{mediumType}}
path: {{path}}
quota: {{quota}}
high: "{{high}}"
low: "{{low}}"
When user explicitly asks for "Dataset with Runtime", generate both:
# See examples/alluxioruntime.yaml
spec.replicas: Number of Alluxio workers - USE USER'S VALUEspec.tieredstore.levels: Storage configuration
mediumtype: MEM, SSD, or HDD - USE USER'S VALUE or default to MEMpath: Storage path - USE USER'S VALUE or default to /dev/shmquota: Storage size - USE USER'S VALUEhigh/low: Watermark ratiosCommon operations:
kubectl apply -f examples/alluxioruntime.yaml
kubectl get alluxioruntime <name> -n <namespace> -o wide
kubectl describe alluxioruntime <name> -n <namespace>
# Scale via kubectl
kubectl scale alluxioruntime <name> -n <namespace> --replicas=<n>
# Scale via kubectl patch
kubectl patch alluxioruntime <name> -n <namespace> -p '{"spec":{"replicas":<n>}}'
# Verify
kubectl get alluxioruntime <name> -n <namespace> -o wide
When user asks to create JuiceFSRuntime ONLY, generate ONLY JuiceFSRuntime YAML:
apiVersion: data.fluid.io/v1alpha1
kind: JuiceFSRuntime
metadata:
name: {{name}}
namespace: {{namespace}}
spec:
volume:
name: {{juicefsVolume}}
secret: {{secretName}}
When user explicitly asks for "Dataset with JuiceFS", generate both:
# See examples/juicefs.yaml
spec.volume.name: JuiceFS volume name - USE USER'S VALUEspec.volume.secret: Credentials secret - USE USER'S VALUECommon operations:
kubectl apply -f examples/juicefs.yaml
kubectl get juicefsruntime <name> -n <namespace> -o wide
kubectl describe juicefsruntime <name> -n <namespace>
ALWAYS include all required fields:
apiVersion: data.fluid.io/v1alpha1
kind: DataLoad
metadata:
name: {{name}}
namespace: {{namespace}}
spec:
dataset:
name: {{datasetName}} # REQUIRED - target dataset name
namespace: {{datasetNamespace}} # REQUIRED - target dataset namespace
loadMetadata: {{loadMetadata}} # REQUIRED - boolean (default: false)
target: # REQUIRED - array of paths to load
- path: {{targetPath}} # Path to load, e.g., /data
Field requirements:
spec.dataset.name: REQUIRED - must be provided by userspec.dataset.namespace: REQUIRED - must be provided by userspec.loadMetadata: REQUIRED - default to false if user doesn't specifyspec.target: REQUIRED - array of paths, minimum one entryspec.target[].path: REQUIRED - the path to load (e.g., /data, /user/home)Common operations:
kubectl apply -f examples/dataload.yaml
kubectl get dataload <name> -n <namespace>
kubectl describe dataload <name> -n <namespace>
Check whether datasets or runtimes still exist:
kubectl get datasets.data.fluid.io -A
kubectl get alluxioruntimes.data.fluid.io -A
kubectl get juicefsruntimes.data.fluid.io -A
kubectl get thinruntimes.data.fluid.io -A
If these resources still exist, tell the user to migrate or remove them first.
kubectl delete installplan fluid
kubectl get installplan fluid
kubectl get pods -n fluid-system | grep -i fluid
If the user wants full cleanup, remind them to handle application resources first.
kubectl describe installplan fluid
kubectl get installplan fluid -o jsonpath='{.status.conditions}'
kubectl get extension fluid -o yaml
kubectl get extensionversion fluid-<version> -o yaml
kubectl get pods -A | grep -i fluid
kubectl describe pod -n fluid-system <pod-name>
kubectl logs -n fluid-system deploy/alluxio-runtime-controller --tail=200
kubectl logs -n fluid-system deploy/juicefs-runtime-controller --tail=200
kubectl get events -n fluid-system --sort-by=.lastTimestamp
kubectl get crd datasets.data.fluid.io alluxioruntimes.data.fluid.io juicefsruntimes.data.fluid.io thinruntimes.data.fluid.io
kubectl describe crd datasets.data.fluid.io
kubectl api-resources --api-group data.fluid.io
Likely causes:
Safe next actions:
InstallPlan state and conditionskubectl get alluxioruntime <name> -n <namespace>
kubectl describe alluxioruntime <name> -n <namespace>
kubectl get pods -n <namespace> -l release=<runtime>
Likely causes:
kubectl describe dataset <name> -n <namespace>
kubectl get dataset <name> -n <namespace> -o yaml
Likely causes:
kubectl get dataload <name> -n <namespace>
kubectl describe dataload <name> -n <namespace>
kubectl get dataset <dataset-name> -n <namespace>
kubectl describe alluxioruntime <name> -n <namespace> | grep -A5 "Scaling"
kubectl describe resourcequota -n <namespace>
kubectl describe nodes | grep -A10 "Allocated resources"
Match the answer to the user intent:
InstallPlan manifestkubectl commands, grouped by purposeWhen user asks to create ThinRuntime ONLY, generate ONLY ThinRuntime YAML:
apiVersion: data.fluid.io/v1alpha1
kind: ThinRuntime
metadata:
name: {{name}}
namespace: {{namespace}}
spec:
mountPoint: {{mountPoint}}
thin:
profile: {{profileName}}
credentials: {{secretName}}
When user explicitly asks for "Dataset with ThinRuntime", generate both:
# See examples/thinruntime.yaml
spec.mountPoint: Under storage path - USE USER'S VALUEspec.thin.profile: Thin runtime profile name - USE USER'S VALUEspec.thin.credentials: Secret containing credentials - USE USER'S VALUECommon operations:
kubectl apply -f examples/thinruntime.yaml
kubectl get thinruntime <name> -n <namespace> -o wide
kubectl describe thinruntime <name> -n <namespace>