Kubesphere kubesphere-multi-tenant-management

Name: kubesphere-multi-tenant-management
Author: kubesphere

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.

install

source · Clone the upstream repo

git clone https://github.com/kubesphere/kubesphere

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/kubesphere/kubesphere "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/kubesphere-multi-tenant-management" ~/.claude/skills/kubesphere-kubesphere-kubesphere-multi-tenant-management && rm -rf "$T"

manifest: skills/kubesphere-multi-tenant-management/SKILL.md

source content

KubeSphere Multi-Tenant Management

Security Guidelines

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:
- New user creation: default to
```
platform-regular
```
  (not platform-admin)
- Inviting user to workspace: default to
```
<workspace-name>-regular
```
  (not admin)
- Inviting user to project: default to
```
viewer
```
  (not admin)
- Only escalate permissions when explicitly requested

Core Concepts

Workspace

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.

Project

KubeSphere's enhanced Kubernetes namespace, representing a specific application, environment, or workload within a workspace. Each project maps to a separate namespace.

User & Role

User: KubeSphere account entity, can be platform admin, workspace member, or project member
Role: Permission set defined in KubeSphere's three-tier RBAC:

Project Roles (

roles.iam.kubesphere.io

```
admin
```
: Full access to all resources
```
operator
```
: Create/update/delete resources, cannot manage roles
```
viewer
```
: Read-only access

Workspace 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 workspace

Platform Roles (GlobalRole,

globalroles.iam.kubesphere.io

```
platform-admin
```
: Full access to all resources
```
platform-regular
```
: Limited platform access
```
platform-self-provisioner
```
: Can create workspaces

Role Binding (KubeSphere API endpoints, binds roles to Users):

Project-level:

/namespacemembers

API, binds

roles.iam.kubesphere.io

to User

Workspace-level:

/workspacemembers

API, binds

workspaceroles.iam.kubesphere.io

to User

Platform-level:
```
/users/<username>
```
API, binds
```
globalroles.iam.kubesphere.io
```
to User via annotation

Step-by-Step Guide

Prerequisites

Set 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

1. Create Workspace

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:

Workspace name (required)
Manager (required, default to current login user)
Clusters (required) - which cluster(s) to assign the workspace to

2. Create Project within Workspace

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:

Project name (required)
Workspace name (required) - which workspace to create the project in
Cluster name (required) - which cluster to create the project in

3. Create User

Required parameters:

```
username
```
: Username for the new user
```
email
```
: User's email address
```
password
```
: 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:

Username (required)
Email address (required)
Platform role: If not specified, default to
```
platform-regular
```

4. Invite User to Workspace/Project

For 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:

Username to invite (required)
Target: workspace or project (required)
Role: If not specified, default to
```
<workspace-name>-regular
```
for workspace or
```
viewer
```
for project

5. Modify User Permissions

Modify user roles at three levels: platform, workspace, and project.

For Platform Role (global role):

```
username
```
: Username to modify (required)
```
globalrole
```
: New platform role (required)
Note: Must first GET the user to get current metadata, then PUT with updated annotation

# 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:

Username to modify (required)
Scope: platform / workspace / project (required)
New role: Only use built-in roles provided by KubeSphere

6. Query Resources

List Workspaces

python ks_api.py GET /kapis/tenant.kubesphere.io/v1beta1/workspacetemplates

List Users

python ks_api.py GET /kapis/iam.kubesphere.io/v1beta1/users

List Workspace Members

python ks_api.py GET /kapis/iam.kubesphere.io/v1beta1/workspaces/<workspace-name>/workspacemembers

List Project Members

python ks_api.py GET /clusters/<cluster-name>/kapis/iam.kubesphere.io/v1beta1/namespaces/<project-name>/namespacemembers

List Projects in Workspace

python ks_api.py GET /clusters/<cluster-name>/kapis/tenant.kubesphere.io/v1beta1/workspaces/<workspace-name>/namespaces

Get User Details

python ks_api.py GET /kapis/iam.kubesphere.io/v1beta1/users/<username>

Error Handling

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 --quiet

Check token:
```
python ks_api.py
```

References

Related Skills

```
kubesphere-core
```
- Core platform architecture
```
kubesphere-cluster-management
```
- Cluster operations