Custom Namespace Roles

Ververica Platform ships three built-in namespace roles: owner, editor, and viewer. When none of them fits, for example a read-only user who can also start and stop deployments, you can define a custom role and bind it in a namespace like a built-in role.

Custom namespace roles are available in Ververica Platform 3.1.4 and later.

A custom role is a set of permission codes. You define it in one of two ways:

• Based on a built-in role: the permission codes of owner, editor, or viewer, plus codes you add, minus codes you remove.
• As a complete list: exactly the permission codes you list.

A custom role belongs to a workspace, and you can bind it in any namespace of that workspace. You create and change custom roles through the API. In the console, custom roles appear in the role picker on the Members page.

Before You Begin

• You need an API token of a user who is owner of the workspace.
• Every request needs the headers Authorization: Bearer <API_TOKEN> and workspace: <WORKSPACE_ID>.
• In the examples on this page, $VVP is the URL of your Ververica Platform installation and $TOKEN is the API token.

Permission Codes

The following table lists the permission codes you can use in a custom role, and which built-in role holds each one.

Base a custom role on a built-in role and add or remove codes, rather than listing every code.

Create a Custom Role

The following example creates a role based on viewer that can also start and stop deployments and session clusters:

1curl -X POST "$VVP/gateway/v2/rbac/custom-role" \
2  -H "Authorization: Bearer $TOKEN" -H "workspace: <WORKSPACE_ID>" \
3  -H "Content-Type: application/json" \
4  -d '{
5        "roleName": "viewer-operator",
6        "description": "Read-only, plus start and stop",
7        "basedOn": "viewer",
8        "policyIds": ["DEPLOYMENT__START_STOP_JOB", "SESSION__START_STOP_SESSION"]
9      }'

When you base a role on editor or owner, add SYSTEM__EDITOR to deniedPolicyIds. For owner, also add SYSTEM__OWNER. For example, the following role is based on editor and can't delete deployments or session clusters:

1curl -X POST "$VVP/gateway/v2/rbac/custom-role" \
2  -H "Authorization: Bearer $TOKEN" -H "workspace: <WORKSPACE_ID>" \
3  -H "Content-Type: application/json" \
4  -d '{
5        "roleName": "editor-no-delete",
6        "basedOn": "editor",
7        "deniedPolicyIds": ["SYSTEM__EDITOR", "DEPLOYMENT__DELETE_DEPLOYMENT", "SESSION__DELETE_SESSION"]
8      }'

A custom role keeps the permission codes it had when you saved it. Later changes to the built-in role it's based on don't change it.

Bind a Custom Role

Bind a custom role on the Members page of the namespace in the console, or through the API:

1curl -X POST "$VVP/rbac/roleBindings" \
2  -H "Authorization: Bearer $TOKEN" -H "workspace: <WORKSPACE_ID>" \
3  -H "namespace: <NAMESPACE>" -H "Content-Type: application/json" \
4  -d '{"userId": "<USER_ID>", "roleId": "viewer-operator"}'

A user who holds several roles in one namespace receives the combined permissions of all of them.

An API token is always created with a built-in role. To give a token a custom role, bind the role to the token with the same request.

View Custom Roles

• List the roles of the workspace: GET $VVP/gateway/v2/rbac/custom-role
• View the permission codes of a role: GET $VVP/gateway/v2/rbac/custom-role/<ROLE_ID>/permissions

Change a Custom Role

To change the description:

1curl -X PUT "$VVP/gateway/v2/rbac/custom-role/viewer-operator" \
2  -H "Authorization: Bearer $TOKEN" -H "workspace: <WORKSPACE_ID>" \
3  -H "Content-Type: application/json" -d '{"description": "Operators of the payments team"}'

To replace the permission codes, send basedOn, policyIds, and deniedPolicyIds as on creation. The request replaces the previous definition:

1curl -X PUT "$VVP/gateway/v2/rbac/custom-role/viewer-operator/permissions" \
2  -H "Authorization: Bearer $TOKEN" -H "workspace: <WORKSPACE_ID>" \
3  -H "Content-Type: application/json" \
4  -d '{"basedOn": "viewer", "policyIds": ["DEPLOYMENT__START_STOP_JOB"]}'

Role and binding changes take effect within about 60 seconds, without a restart.

Delete a Custom Role

Remove the role's role bindings first, then delete it:

1curl -X DELETE "$VVP/gateway/v2/rbac/custom-role/viewer-operator" \
2  -H "Authorization: Bearer $TOKEN" -H "workspace: <WORKSPACE_ID>"

Limitations

• Starting and stopping is isolated in one direction only. A role based on viewer plus the start/stop codes is exact. A role based on editor with the start/stop codes removed can still start a deployment by changing its state through an update request.
• Catalog permissions don't cover SQL. A role that can run SQL can still create and drop catalogs and tables with SQL statements.