Skip to main content
In addition to the built-in System, Workspace, and Deployment roles described in User roles and permissions, Astro Private Cloud supports custom roles. A custom role is a role you define yourself, made up of any combination of permissions from the permission catalog, and assigned to users, Teams, or service accounts through the Astro Private Cloud UI. Custom roles differ from the built-in roles in a few ways:
  • You define them through the Astro Private Cloud UI, not your values.yaml file.
  • They’re stored in the platform’s database, not your Helm chart configuration.
  • You can create any number of them.
  • Each one applies at a single scope: System, Cluster, Workspace, or Deployment.
Enabling custom roles doesn’t change the built-in roles. Custom roles are an additional option for organizations that need permission sets the three built-in tiers (Viewer, Editor, Admin) don’t cover. Custom roles are turned off by default. A System Admin enables them at the platform level before anyone can create or assign a custom role. See Enable custom roles.
Astro Private Cloud 2.1This feature was introduced in Astro Private Cloud 2.1. To access this feature, upgrade your Astro Private Cloud installation to 2.1 or later.

​
Prerequisites

  • System Admin access to Astro Private Cloud.
  • Custom roles enabled in your values.yaml file. See Enable custom roles.

​
Enable custom roles

Custom roles are disabled by default. To enable them, add the following to your values.yaml file:
Then, push the configuration change to your platform. See Apply a config change. After the change takes effect, a Roles and Permissions page appears in the platform’s navigation for System Admins.

​
Understand role scope

Every custom role has a scope, set when you create it:
  • System: Applies across the entire platform. A System-scoped role can grant permissions at the System, Cluster, Workspace, or Deployment level.
  • Cluster: Applies to a single cluster. A cluster-scoped role can only grant cluster-level permissions.
  • Workspace: Applies to a single Workspace. A Workspace-scoped role can grant Workspace-level permissions, Deployment-level permissions, or both.
  • Deployment: Applies to a single Deployment. A Deployment-scoped role can only grant Deployment-level permissions.
Scope determines two things: which permissions a role can include, and what happens when you assign it.
If a Workspace-scoped role includes Deployment-level permissions, assigning that role to a user grants them those permissions on all Deployments in the Workspace, including Deployments created after the assignment. Assign Workspace-scoped roles with this in mind.
A role is a reusable template, not tied to a specific Workspace or Deployment. For example, you can create a single Deployment-scoped role named Pipeline Developer and assign it to different users across different Deployments.

​
Create a custom role

1

Open the role builder

In the Astro Private Cloud UI, click Roles and Permissions in the navigation, then click Create Role.
2

Name the role and set its scope

Enter a Role name and, optionally, a Description. Select a Scope from the dropdown. The scope determines which permissions you can select in the following step.
3

(Optional) Start from an existing role

To use another role’s permissions as a starting point, select it from Start from an existing role. You can select any built-in or custom role at the same scope. Its permissions populate the permission picker, where you can add or remove permissions. Select Start from blank to begin with no permissions selected.
4

Select permissions

Select the permissions this role grants. Permissions are grouped by category (for example, Dag Operations, Variables and Connections). Hover over the info icon next to a permission to see what it does.Some permissions depend on others. For example, selecting a permission to update or delete a resource automatically selects the permission to view that resource, since a user can’t act on something they can’t see. Automatically selected permissions display an auto badge and can’t be individually deselected. To remove one, deselect the permission that depends on it first.
Dag-level permissions (for example, in the Dag Operations category) apply on both Airflow 2 and Airflow 3. Airflow 2’s security model uses the Dag-read permission as the parent check for Dag runs, task instances, logs, and more, so it isn’t optional there.
5

Create the role

Click Create Role.

​
Clone a role

Cloning creates a new, independent role with the same permissions as the source. You can clone a built-in role or an existing custom role, and edit the clone afterward without affecting the original.
1

Open the source role

Open the role you want to clone, then click Clone Role.
2

Name the new role

Enter a name for the new role, then click Clone Role to confirm.
Cloning copies only the role’s permissions. It doesn’t copy any assignments from the source role.
Cloning a built-in role is the only way to customize it beyond what values.yaml allows, since built-in roles themselves can’t be edited directly. See User roles and permissions for the default permissions of each built-in role.

​
Edit a custom role

Open the role and change its name, description, or permissions, then click Save changes. Built-in roles are read-only. To customize a built-in role’s permissions, clone it first. Editing a role doesn’t change who is assigned to it. Adding or removing permissions updates the effective permissions of everyone currently assigned to that role.

​
Delete a custom role

Open the role and click Delete role. If the role has active assignments, you must revoke them first. Deleting a role can’t be undone. Built-in roles can’t be deleted.

​
Assign a role to a user, Team, or service account

You can assign both built-in and custom roles to users, Teams, and service accounts from the same interface. On the Users, Teams, or Service Accounts list for a System, Workspace, or Deployment, click Edit roles next to a principal to open the role assignment panel. The panel shows the roles currently assigned at that scope, plus a preview of the principal’s effective permissions. Select or deselect roles, then click Save changes.
You can only assign a role that grants permissions you hold yourself. If a role includes a permission you don’t have, assigning it fails. This applies only to assigning a role, not to creating or editing one: a System Admin can build a role with any available permissions, but can only assign it up to their own level of access.
Creating, updating, or deleting a custom role always requires System-scope role-management permissions, regardless of what scope the role itself targets. A Workspace or Deployment Admin can be assigned a Workspace- or Deployment-scoped role, but authoring the role definition itself is a System Admin action.

​
Revoke a role assignment

From the same role assignment panel, deselect the role and click Save changes. You can’t revoke an assignment if doing so leaves a System, Workspace, Deployment, or cluster without an admin.
This guard applies to revoking a role assignment. It doesn’t apply to editing a role’s permissions. If you remove an admin-granting permission from a role that’s currently assigned to someone, nothing stops you from leaving that scope without an admin. Always confirm another admin exists before narrowing a role that grants admin-level access, especially at System scope: if no one retains System Admin permissions, you can lock your organization out of platform administration entirely.

​
Known issues and limitations

  • On Airflow 2, a custom webserver_config.py file can be silently overwritten. If you maintain your own webserver_config.py on an Airflow 2 Deployment — for example, to connect the Airflow UI to your company’s LDAP or single sign-on system — those settings can be overwritten without warning. This can happen whenever a Deployment is deployed or brought under Astronomer’s management (adopted), whether or not custom roles are turned on. If you maintain a custom webserver_config.py on an Airflow 2 Deployment, check after any deploy or adoption that its settings are still in effect. A fix that lets your file and ours coexist is planned for a future release.
  • On Airflow 2, there’s currently no way to confirm that a custom role is actually being enforced. In rare cases, the platform can fail to fully set up enforcement for a custom role on an Airflow 2 Deployment. Today, that failure isn’t shown anywhere — not during deploy, not in the platform. If it happens, the person just gets the broader default access level (Viewer, Editor, or Admin) instead of the narrower access their custom role was meant to give them, with nothing to indicate that’s what happened. We’re planning a fix that makes this visible instead of silent. Until then, after assigning a custom role on an Airflow 2 Deployment, it’s worth confirming the person actually has only the access the role grants, not more.
  • Not all custom roles are visible on the Roles and Permissions screen when you have many of them. If you’ve created a large number of custom roles, some of them can be cut off and hidden on the Roles and Permissions screen. Until this is fixed, use the Scope dropdown to filter roles by scope (for example, Workspace) to bring the missing roles into view.
  • Editing a custom role’s permissions may not update the UI right away. After you change a custom role’s permissions, other views that show that role — user, Team, and service account lists, role assignments, and admin views — can keep showing the old permissions until you refresh or navigate away and back. The change is saved; only the display is stale. Refresh the page to see the current permissions.
  • Role assignments may not appear in the Show all view right away. On the Roles and Permissions screen, newly assigned roles can be missing from the Show all view until you refresh the page or toggle the Hide others button. The assignment is saved; only the display is stale.
These are known and already scoped for a future release.

​
What’s next