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.

Permission Codes for Console Actions

The following table lists console actions and the permission code a role needs for each one. To open a SQL script in the SQL editor, a role also needs SQL__LIST_DRAFTS.

Custom connectors and formats, UDF registration, and API tokens have no permission code. Only built-in roles can create, change, or delete them.

Validate and Debug Without Editing

Starting with Ververica Platform 3.1.5, a role with SQL__FULLY_CHECK_DRAFT can use Validate on SQL scripts and YAML drafts, and a role with SQL__DEBUG_DRAFT and SQL__FULLY_CHECK_DRAFT can use Debug on SQL scripts. This works on any script its user can open, without SQL__CREATE_MODIFY_DRAFT or the edit lock of the script. For a role without SQL__CREATE_MODIFY_DRAFT, the console validates or debugs the script as last saved and doesn't save it. Editing a script still requires SQL__CREATE_MODIFY_DRAFT, and deploying it requires SQL__DEPLOY_DRAFT. A role with SQL__LIST_DRAFTS but without SQL__FULLY_CHECK_DRAFT can open scripts but can't validate or debug them.

For example, a role based on viewer plus SQL__FULLY_CHECK_DRAFT and SQL__DEBUG_DRAFT can validate and debug SQL scripts without changing them.

A user whose role doesn't have SQL__CREATE_MODIFY_DRAFT can't change the script, which has the following effects:

• If a script variable has no value, Validate and Debug report that all variables need a value, and the user can't fill it in.
• Debug offers only session clusters whose engine version matches the engine version of the script, and the user can't change the engine version of the script.

A custom role with SQL__CREATE_MODIFY_DRAFT can't take over the edit lock of a script that another user holds. On such a script, Validate and Debug stay disabled for that role. A built-in role such as editor can take over the lock.

In Ververica Platform 3.1.4, the console enables Validate and Debug only for the user who holds the edit lock of the script, which requires SQL__CREATE_MODIFY_DRAFT.

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.