Role Management

v3.0.0+

The tcb role command has been available since v3.0.0.

The tcb role command is used to manage access control roles in the CloudBase environment, including system preset roles and custom roles.

Relationship Between Roles and Permissions

• Permission (Permission): Controls resource-level read and write access (tcb permission)
• Role (Role): Binds users and policies to control access permissions at the gateway routing layer.
• Both perform their respective duties and collectively form the CloudBase access control system.

System Preset Policies

When creating a custom role, you can reference the following preset policies:

policy Code	Effect	Description
AdministratorAccess	allow	Full administrator access
FunctionsAccess	allow	SCF access
StoragesAccess	allow	Cloud storage access
CloudrunAccess	allow	Cloud Run access
FunctionsDeny	deny	Deny access to SCF
StoragesDeny	deny	Deny access to Cloud storage
CloudrunDeny	deny	Deny access to Cloud Run

deny policy takes precedence over allow, and when both exist, deny takes precedence.

---

tcb role list

Query all roles in the environment (system roles + custom roles).

tcb role list [options]

Parameters

Parameter	Description	Default Value
-e, --env-id <envId>	Environment ID	—
--type <type>	Filter type: system / custom	all
--limit <n>	Maximum number of items to return	20
--offset <n>	Number of items to skip	0
--detail	Display both the member list and policy details simultaneously	—
--json	Output JSON	—

Example

# View all roles
tcb role list -e my-env-id

# View only custom roles
tcb role list --type custom -e my-env-id

# Display details (including members and policies)
tcb role list --detail -e my-env-id

---

tcb role get

Query the details of the specified role.

tcb role get --id <roleId> [options]
tcb role get --identity <identity> [options]
tcb role get --name <name> [options]

Select one of the three query methods (required):

Parameter	Description
--id <roleId>	Exact match by role ID
--identity <identity>	Exact match by role identifier
--name <name>	Fuzzy match by role name
--detail	Display members and policy details
-e, --env-id <envId>	Environment ID

Example

# Query by ID
tcb role get --id 2032299359962361858 -e my-env-id

# Query by identifier (including details)
tcb role get --identity administrator --detail -e my-env-id

---

tcb role create

Create a custom role.

tcb role create --name <name> --identity <identity> [options]

Parameters

Parameter	Description	Constraint
--name <name>	Role name (required)	2–32 characters, start with a Chinese character/letter
--identity <identity>	Role identifier (required, unique)	Letters/numbers/_-:@.
--description <desc>	Role description	Up to 255 characters
--users <uids>	Initial member UIDs, comma-separated	Up to 100
--policies <json>	Policy JSON array (see format below)	Up to 50 policies
-e, --env-id <envId>	Environment ID	—

--policies Format

The policy array supports mixed use of preset policy strings and custom policy objects:

[
  "FunctionsAccess",
  {
    "code": "custom_api",
    "name": "API Path Policy",
    "description": "Only allow access to the /api path",
    "effect": "allow",
    "expression": {
      "version": "1.0",
      "statement": [
        {
          "action": "functions:/api/*",
          "resource": "*",
          "effect": "allow"
        }
      ]
    }
  }
]

Custom Policy Object Fields:

Field	Description	Required
code	Policy unique identifier	✅
effect	allow or deny	✅
name	Policy name	No
description	Description	No
expression	Policy expression (including version + statement array)	No

statement Sub-statement Fields:

Field	Description	Example
action	<feature type>:<path>, * indicates all	functions:* / functions:/api/*
resource	Resource scope, * indicates all	*
effect	allow or deny	allow

Feature type enumeration: storages / functions / cloudrun / model

Example

# Minimal Creation
tcb role create --name Developer --identity developer -e my-env-id

# Create and Assign Initial Members
tcb role create --name Developer --identity developer --users "1003,1005" -e my-env-id

# Using Preset Policies
tcb role create --name Gateway Role --identity gateway_role \
  --policies '["FunctionsAccess","StoragesDeny"]' \
  -e my-env-id

# Combining Preset + Custom Policies
tcb role create \
  --name Full-stack Developer \
  --identity fullstack_dev \
  --policies '[
    "FunctionsAccess",
    {
      "code": "custom_api",
      "name": "API Path Policy",
      "effect": "allow",
      "expression": {
        "version": "1.0",
        "statement": [{"action": "functions:/api/*", "resource": "*", "effect": "allow"}]
      }
    }
  ]' \
  --users "1003,1005,1007" \
  -e my-env-id

---

tcb role update

Update role information (name, description, members, policy).

tcb role update --id <roleId> [options]

System Role Modification Restrictions

• Administrator Role: Can only modify members, cannot modify policies
• Registered Users/Organization Members/Anonymous Users/All Users: Can only modify policies, cannot modify members
• All System Roles: Role names cannot be modified
• Custom Role: All of the above can be modified

Parameters

Parameter	Description
--id <roleId>	role ID (required)
--name <name>	Modify the role name (for custom roles only)
--description <desc>	Modify the role description
--add-users <uids>	Add members, comma-separated UIDs
--remove-users <uids>	Remove members, comma-separated UIDs
--add-policies <json>	Add policies, same format as role create --policies
--remove-policies <json>	Remove policies, pass an array of policy code strings
-e, --env-id <envId>	Environment ID

Example

# Modifying the Role Name
tcb role update --id 2032299359962361858 --name "Senior Developer" -e my-env-id

# Simultaneously Adding/Removing Members
tcb role update --id 2032299359962361858 \
  --add-users "1001,1002" \
  --remove-users "1003" \
  -e my-env-id

# Modifying Policies
tcb role update --id 2032299359962361858 \
  --add-policies '["FunctionsAccess"]' \
  --remove-policies '["StoragesDeny"]' \
  -e my-env-id

---

tcb role delete

Delete custom roles (irreversible; system roles cannot be deleted).

tcb role delete <roleId...> [options]

Example

# Deleting a Single Role
tcb role delete 2037415874111574018 -e my-env-id

# Batch Delete (Up to 100)
tcb role delete 2037415874111574018 2037420918731018242 -e my-env-id

---

Related Commands

• tcb permission — Manage resource-level access permissions
• tcb user — Manage end users