Loading
KubeSphere multi-tenant management Skill. Use when user requests to create users, workspaces, projects, or assign roles/permissions. Supports user lifecycle management, workspace configuration, projec
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-multi-tenant-management -a cursor -y
KubeSphere multi-tenant management Skill. Use when user requests to create users, workspaces, projects, or assign roles/permissions. Supports user lifecycle management, workspace configuration, project creation, role binding. Do not perform any delete operations, do not create custom roles.
KubeSphere multi-tenant management Skill. Use when user requests to create users, workspaces, projects, or assign roles/permissions. Supports user lifecycle management, workspace configuration, project creation, role binding. Do not perform any delete operations, do not create custom roles.
Never use kubectl edit/delete - Do NOT use kubectl edit, kubectl delete, or similar commands to modify or delete workspaces, projects, users, roles, or role bindings. These operations are sensitive and should be performed via KubeSphere Console with proper approval workflow.
Never perform delete operations via API - Do NOT delete users, workspaces, projects, roles, or role bindings via API. These operations must be performed manually via KubeSphere Console with proper approval workflow. Only use this skill for creating and querying resources.
Never create custom roles - Do NOT create custom roles (Role, WorkspaceRole, GlobalRole). Only use built-in roles provided by KubeSphere. If custom permissions are needed, instruct the user to configure them via KubeSphere Console.
Default to least privilege - When creating users or assigning permissions, always use the minimum required access level:
platform-regular (not platform-admin)<workspace-name>-regular (not admin)viewer (not admin)The top-level organizational unit in KubeSphere, representing a team, department, or business unit. A workspace can contain multiple projects and serves as the basic boundary for resource grouping and access control. Workspaces can span multiple clusters, enabling centralized management of resources distributed across different clusters.
KubeSphere's enhanced Kubernetes namespace, representing a specific application, environment, or workload within a workspace. Each project maps to a separate namespace.
Project Roles (roles.iam.kubesphere.io):
admin: Full access to all resourcesoperator: Create/update/delete resources, cannot manage rolesviewer: Read-only accessWorkspace Roles (WorkspaceRole, workspaceroles.iam.kubesphere.io):
<workspace-name>-admin: Full access to workspace and all projects<workspace-name>-regular: Limited workspace access<workspace-name>-self-provisioner: Create projects in workspace<workspace-name>-viewer: Read-only access to workspacePlatform Roles (GlobalRole, globalroles.iam.kubesphere.io):
platform-admin: Full access to all resourcesplatform-regular: Limited platform accessplatform-self-provisioner: Can create workspacesRole Binding (KubeSphere API endpoints, binds roles to Users):
/namespacemembers API, binds roles.iam.kubesphere.io to User/workspacemembers API, binds workspaceroles.iam.kubesphere.io to User/users/<username> API, binds globalroles.iam.kubesphere.io to User via annotationSet up authentication using the provided CLI tool. First, navigate to the scripts directory:
# Navigate to the skill's scripts directory
# Example path (replace with your actual kubesphere-skills location):
cd ~/kubesphere-skills/core/kubesphere-core/scripts
# Install required Python package
pip install requests
# Set host endpoint (optional, defaults to http://ks-apiserver.kubesphere-system)
export KUBESPHERE_HOST="http://<kubesphere-host>"
# Login to get token (token will be cached)
python ks_api.py --login --username admin --password <your-password>
# Token is cached in ~/.kubesphere_token and auto-refreshed
# Optional: Clear cached token
python ks_api.py --clear-cache
Required parameters:
workspace-name: Name for the workspace (maps to metadata.name)manager: Workspace manager (maps to spec.template.spec.manager, default to current login user)creator: Creator name (maps to metadata.annotations["kubesphere.io/creator"])clusters: List of cluster names to host this workspace (maps to spec.placement.clusters)# Create workspace via Python CLI
python ks_api.py POST /kapis/tenant.kubesphere.io/v1beta1/workspacetemplates '{
"apiVersion": "iam.kubesphere.io/v1beta1",
"kind": "WorkspaceTemplate",
"metadata": {
"name": "<workspace-name>",
"annotations": {
"kubesphere.io/creator": "<creator>"
}
},
"spec": {
"template": {
"spec": {
"manager": "<manager>"
},
"metadata": {
"annotations": {
"kubesphere.io/creator": "<creator>"
}
}
},
"placement": {
"clusters": [
{"name": "<cluster-name>"}
]
}
}
}'
Note: Before creating a workspace, always ask the user for:
Required parameters:
project-name: Name for the project (maps to metadata.name)workspace-name: Name of the workspace to create the project in (maps to metadata.labels["kubesphere.io/workspace"])cluster-name: Cluster name to create the project in (maps to URI path and cluster field)creator: Creator name (maps to metadata.annotations["kubesphere.io/creator"])# Create project within workspace via Python CLI
python ks_api.py POST /clusters/<cluster-name>/kapis/tenant.kubesphere.io/v1beta1/workspaces/<workspace-name>/namespaces '{
"apiVersion": "v1",
"kind": "Namespace",
"metadata": {
"labels": {
"kubesphere.io/workspace": "<workspace-name>",
"kubesphere.io/managed": "true"
},
"name": "<project-name>",
"annotations": {
"kubesphere.io/creator": "<creator>"
}
},
"cluster": "<cluster-name>"
}'
Note: Before creating a project, always ask the user for:
Required parameters:
username: Username for the new useremail: User's email addresspassword: User's password (must meet KubeSphere password policy)Optional parameters:
globalrole: Platform role (default: platform-regular)# Create user via Python CLI
python ks_api.py POST /kapis/iam.kubesphere.io/v1beta1/users '{
"apiVersion": "iam.kubesphere.io/v1beta1",
"kind": "User",
"metadata": {
"annotations": {
"iam.kubesphere.io/uninitialized": "true",
"iam.kubesphere.io/globalrole": "platform-regular",
"kubesphere.io/creator": "admin"
},
"name": "<username>"
},
"spec": {
"email": "<email>",
"password": "<password>"
}
}'
Note: Before creating a user, always ask the user for:
platform-regularFor Workspace invitation:
username: Username to invite (required)workspace-name: Target workspace name (required)role: Workspace role (default: <workspace-name>-regular)For Project invitation:
username: Username to invite (required)project-name: Target project name (required)cluster-name: Cluster name (required)role: Project role (default: viewer)# Invite user to workspace (default role: <workspace-name>-regular)
python ks_api.py POST /kapis/iam.kubesphere.io/v1beta1/workspaces/<workspace-name>/workspacemembers '[{"username":"<username>","roleRef":"<workspace-name>-regular"}]'
# Invite user to project (default role: viewer)
python ks_api.py POST /clusters/<cluster-name>/kapis/iam.kubesphere.io/v1beta1/namespaces/<project-name>/namespacemembers '[{"username":"<username>","roleRef":"viewer"}]'
Note: Before inviting a user, always ask the user for:
<workspace-name>-regular for workspace or viewer for projectModify user roles at three levels: platform, workspace, and project.
For Platform Role (global role):
username: Username to modify (required)globalrole: New platform role (required)# Step 1: Get current user info (required before modification)
python ks_api.py GET /kapis/iam.kubesphere.io/v1beta1/users/<username>
# Step 2: Update global role annotation
python ks_api.py PUT /kapis/iam.kubesphere.io/v1beta1/users/<username> '{
"apiVersion": "iam.kubesphere.io/v1beta1",
"kind": "User",
"metadata": {
"name": "<username>",
"annotations": {
"iam.kubesphere.io/globalrole": "<new-global-role>"
}
}
}'
For Workspace Role:
username: Username to modify (required)workspace-name: Target workspace name (required)roleRef: New workspace role (required)# Modify user role in workspace
python ks_api.py PUT /kapis/iam.kubesphere.io/v1beta1/workspaces/<workspace-name>/workspacemembers/<username> '{"username":"<username>","roleRef":"<workspace-name>-<role>"}'
For Project Role:
username: Username to modify (required)project-name: Target project name (required)cluster-name: Cluster name (required)roleRef: New project role (required)# Modify user role in project
python ks_api.py PUT /clusters/<cluster-name>/kapis/iam.kubesphere.io/v1beta1/namespaces/<project-name>/namespacemembers/<username> '{"username":"<username>","roleRef":"<role>"}'
Note: Before modifying permissions, always ask the user for:
python ks_api.py GET /kapis/tenant.kubesphere.io/v1beta1/workspacetemplates
python ks_api.py GET /kapis/iam.kubesphere.io/v1beta1/users
python ks_api.py GET /kapis/iam.kubesphere.io/v1beta1/workspaces/<workspace-name>/workspacemembers
python ks_api.py GET /clusters/<cluster-name>/kapis/iam.kubesphere.io/v1beta1/namespaces/<project-name>/namespacemembers
python ks_api.py GET /clusters/<cluster-name>/kapis/tenant.kubesphere.io/v1beta1/workspaces/<workspace-name>/namespaces
python ks_api.py GET /kapis/iam.kubesphere.io/v1beta1/users/<username>
| Error Code | Cause | Solution |
|---|---|---|
401 Unauthorized | Token expired | python ks_api.py --clear-cache && python ks_api.py --login --username admin --password <password> |
403 Forbidden | No permission | Use admin account |
409 Conflict | Resource already exists | Use different name |
404 Not Found | Resource not found | Verify name/workspace/cluster is correct |
400 Bad Request | Invalid parameters | Check error message for details (email format, password policy, naming rules) |
| Connection refused/timeout | API unreachable | Verify KUBESPHERE_HOST is correct |
Debugging:
--quiet flag for cleaner output: python ks_api.py GET /users --quietpython ks_api.pykubesphere-core - Core platform architecturekubesphere-cluster-management - Cluster operations