acl

Prerequisites

1. CLI installed and logged in (see setup skill).
2. No cluster context required -- these are control-plane operations.
3. The /v2/roles, /v2/members, and /v2/groups routes must be enabled for the caller's endpoint. They are still rolling out: a 404 from any zilliz acl command means the API is not live there yet.

Commands Reference

zilliz acl is a three-level tree -- acl role, acl member, and acl group. It is deliberately absent from zilliz --help and shell completion while the routes roll out, but every command below runs today and every --help under it works.

Roles

# One project's roles: the pre-defined project roles plus that project's
# custom roles. --project-id is required; it is prompted for when omitted.
zilliz acl role list --project-id <project-id>
# Optional: --page <n>, --page-size <n>, --all

# Org roles (--project-id is rejected here: org roles have no project boundary)
zilliz acl role list --type org

zilliz acl role describe <role-id>
# Optional: --project-id <project-id>

zilliz acl role principals <role-id> --all
# Optional: --project-id <project-id>, --page <n>, --page-size <n>
# Lists the members, groups, and API keys the role is bound to.

zilliz acl role delete <role-id>
# Optional: --project-id <project-id>
# Confirms first; pass -y to skip.

--project-id on describe, principals, and delete is the project boundary of a pre-defined project role, which carries none of its own. A custom role is addressed by ID alone.

Create and update a role

zilliz acl role create --name <role-name> --project-id <project-id> \
  --policy project_member:view \
  --policy 'serving_cluster:view,modify=in01-a,in01-b'
# Optional: --description <text>, --policies-file <path>

zilliz acl role update <role-id> --description <text>
# Optional:
#   --name <role-name>
#   --project-id <project-id>
#   --policy <shorthand>
#   --policies-file <path>
#   -y

Only project roles can be created; the API has no org-role create path. update replaces the policy wholesale -- it never merges -- and prompts before shrinking the statement count unless -y is passed.

Writing a policy

Three ways to supply the policy on role create and role update:

1. Shorthand (--policy, repeatable), validated locally before the request:

   RESOURCE:ACTION[,ACTION...][=SELECTION[,SELECTION...]][@cluster=CLUSTER_ID]
   

   --policy project_member:view
   --policy 'serving_cluster:view,modify=in01-a,in01-b'
   --policy 'serving_cluster_data:read=mydb/*@cluster=in01-abc'
   --policy 'volume_data:read,write=*'
   

   SELECTION picks which instances the statement covers; * means all, and data resources also accept the db/collection form. @cluster= is an optional trailing marker, so an @ inside a selection value is left alone.

2. JSON file (--policies-file <path>, - reads stdin), taking the policies array exactly as the API defines it. Mutually exclusive with --policy:

   [
     { "resourceType": "serving_cluster", "privileges": ["view"], "resources": ["in01-a"] },
     { "resourceType": "project_member",  "privileges": ["view"] }
   ]
   

3. Interactive builder: with neither flag on a terminal, role create walks through resource, actions, and selection, then prints the equivalent --policy flags so the run can be scripted next time. Off a terminal with neither flag the command errors instead.

Members

zilliz acl member roles <email|user-id>
zilliz acl member grant <email|user-id> --role <role-id|role-name>
zilliz acl member revoke <email|user-id> --role <role-id|role-name>
# Optional on grant/revoke: --project-id <project-id>; revoke also takes -y

The member argument takes an email or a usr- user ID. An email costs one extra lookup to resolve; a user ID goes straight through.

Groups

zilliz acl group list
# Optional: --name <text>, --page <n>, --page-size <n>, --all

zilliz acl group members <group-id>
# Optional: --page <n>, --page-size <n>, --all

zilliz acl group roles <group-id>
zilliz acl group grant <group-id> --role <role-id|role-name>
zilliz acl group revoke <group-id> --role <role-id|role-name>
# Optional on grant/revoke: --project-id <project-id>; revoke also takes -y

Groups come from SCIM provisioning; this command tree reads them and manages their role bindings, it does not create them.

Project scoping

--project-id is prompted for only where the API genuinely requires it, and the answer is used for that invocation alone -- it is never written to ~/.zilliz/config.

Action catalog

Every RESOURCE:ACTION pair --policy accepts. A selectable resource takes =SELECTION on every action except create, which must never carry one; a resource that is not selectable takes no selection at all.

A resource can appear at both levels with different actions -- read the Level column before composing a statement.

Guidance

• This is cloud-level RBAC, not Milvus RBAC. zilliz acl governs who can act on organizations, projects, clusters, and volumes in Zilliz Cloud. For database users, roles, and privileges inside a Milvus cluster (Search, Insert, CreateCollection, ...) use the user-role skill instead. The two are separate systems and neither grants the other.
• Grant and revoke are not idempotent. Re-granting an existing binding and revoking an absent one are both rejected by the backend. Check acl member roles <member> or acl role principals <role-id> first rather than retrying a failed call.
• --role takes an ID or an exact name. A name is matched against the org roles first and then inside one project, so granting a project role by name needs --project-id off a terminal. An ambiguous name lists the candidates instead of guessing -- pass the role ID to resolve it. Prefer IDs in scripts.
• Org roles are read-only here. The backend defines no org_role create / modify / delete actions, so role create is project-only and updating or deleting an org role always fails. role list --type org and role describe work normally.
• A resource can exist at both levels with different actions. project_role and project appear once as an org-level resource and once as a project-level one. Read the Level column before composing a statement; a level mismatch is reported as an unknown resource for that level.
• Selection rules are enforced locally before the request. An action on a selectable resource needs =SELECTION -- except create, which must never carry one. serving_cluster:create,view=in01-a is valid: the selection binds to view only.
• role update replaces the policy wholesale. To add one statement, read the current policy with role describe and resend the full set, including the statements being kept.
• Deleting a role cascades to its bindings. Confirm the blast radius with role principals <role-id> before deleting, and tell the user who loses access.
• The action catalog above is a snapshot of what the backend seeds. It drives local validation, so when the server rejects a policy this client accepted, surface the server's message verbatim -- it is the authority, not the table.
• A 404 from any zilliz acl command means the ACL routes are not enabled on that endpoint yet. This is a rollout state, not a permissions problem: tell the user to contact support rather than retrying or changing the command.