Migrate to Starburst access control#
This page describes how to move to Starburst access control from the following setups:
A Control Plane that used catalogs in the private preview
SEP clusters that use built-in access control
Upgrade from the private preview#
If you used Control Plane catalogs in the private preview, make the following changes when you upgrade.
In the Control Plane config.properties file:
Remove the
catalogs.enabledandcontrol-plane.access-control.enabledproperties, and setcontrol-plane.enabled=trueinstead. If a removed property is still set, the Control Plane fails to start with an error such asConfiguration property 'catalogs.enabled' was not used.The following properties now require
control-plane.enabled=true. If you set one of them without it, the Control Plane fails to start:ai-models.enabledbackground-work.enabledcontext-studio.enableddata-products.enabledicehouse-tasks.enabledmcp.enabledresource-groups.enabledstarburst.users.provisioning.type
On each cluster, remove the catalog.management=LIVE property, and run the
cluster in managed mode instead, with the deployment.mode=MANAGED and
deployment.manager.uri properties. LIVE is no longer a valid value.
After the upgrade:
Catalogs that existed in the Control Plane are delegated and owned by the
accountadminrole. Starburst access control doesn’t control access to them. Load built-in access control alongside Starburst access control, as described in Configuration, or switch the catalogs to governed.The Control Plane has a built-in catalog named
starburst, which appears in the catalog list. You can’t create, rename, alter, or drop a catalog with that name.
Move from built-in access control#
You move from built-in access control to Starburst access control one catalog at a time. Delegated catalogs keep using built-in access control while you set up Starburst access control, and you switch each catalog to governed when its Starburst access control rules are ready.
Enable Starburst access control, and load built-in access control alongside it on each coordinator. For more information, see Configuration.
Grant location privileges in Starburst access control to the roles that create schemas or tables with an explicit location. Starburst access control checks storage locations in every catalog, including delegated catalogs, and built-in access control location grants stop applying. If the
starburst.access-control.location.enabledproperty is set, the cluster ignores it and logs a warning. For more information, see Privileges.Make sure that your catalogs are delegated, so that their built-in access control grants keep working. New catalogs are governed by default, and SQL
CREATE CATALOGstatements always create governed catalogs. Switch these catalogs to delegated.Update the role settings of your clients, as described in Role settings.
Recreate the roles, privileges, column masks, and row filters of each catalog in Starburst access control. No tool copies them for you, and the two systems use different privilege names.
Switch the catalogs to governed one at a time.
Assign a Starburst access control owner to the objects that were created while each catalog was delegated, as described in When you switch a catalog.
Role settings#
With Starburst access control enabled, the system role of a session is a Starburst access control role. Clients that select a built-in access control role as a system role stop working:
Client setting |
Result with Starburst access control |
Use instead |
|---|---|---|
|
Fails with |
The |
|
Fails with |
The |
|
Fails with HTTP 403 |
The |
|
Fails with HTTP 400 |
One Starburst access control role |
By default, users have the privileges of all their built-in access control
roles in delegated catalogs. For more information about the $biac-role extra
credential, see
Compare with built-in access control.
When you switch a catalog#
The change applies to the next statement, including on open connections.
No grants are deleted. Built-in access control keeps its grants, and they apply again if you switch the catalog back to delegated.
Schemas, tables, and views created while the catalog was delegated have no Starburst access control owner. Starburst access control treats the owner of the schema, or else the owner of the catalog, as their owner. To give one of these objects a Starburst access control owner, run
ALTER ... SET AUTHORIZATION ROLE.SECURITY DEFINERviews created while the catalog was delegated fail until you give them a Starburst access control owner. For more information, see View privileges.
Built-in access control stores grants and ownership by catalog name:
If you drop a delegated catalog and create a catalog with the same name, the new catalog gets the built-in access control grants of the old one.
If you rename a delegated catalog, its built-in access control grants stay with the old name and don’t apply to the renamed catalog.
Roll back#
To roll back a catalog, switch it back to delegated. Its built-in access control grants apply again from the next statement.