Skip to content

Roles, Policies, and Permissions

EngFlow clusters use roles, policies, and permissions to control what clients can do:

  • A permission names a single action, like reading from the cache or executing remote actions. The full list is below.
  • A policy bundles permissions for a group of resources.
  • A role combines one or more policies into a name like user or admin. Clients are assigned roles, not individual permissions.

When a client authenticates, the cluster determines which roles the client has. The combined permissions from those roles determine what actions the client is allowed to perform. Role names are referenced throughout the cluster, in --principal_based_permissions, in --oidc_role_mapping, in the engflow_roles custom claim, and in the IAM API for custom roles.

This page covers:

Assigning roles

You can configure the role mapping with the --principal_based_permissions flag for principals or the --oidc_role_mapping flag for OIDC federation. See Authentication for details.

You can also assign user roles through your OIDC provider with the engflow_roles custom claim, which may be set to either an array of role name strings or a string containing a comma-separated list of role names.

If the cluster is managed by EngFlow, contact support to reassign roles.

Defining custom roles

You can define custom roles for your clients using the IAM gRPC API. There is currently no UI, but you can generate a client in your language of choice with gRPC, or you can use grpcurl. Custom role names work everywhere built-in role names do. However, you cannot redefine the built-in roles.

Please contact support if you would like to enable this feature.

List of built-in roles

EngFlow supports the following pre-defined roles. These roles are meant to cover common use cases for clusters with a single tenant.

  • none: Has no permissions. Used to block access in some cases.
  • viewer: Only has UI access, used as a default for some public clusters.
  • cache-reader: Limited access for cache analysis tools.
    • Can read CAS files.
    • Can read AC entries.
    • Can write BES.
  • cache-writer: Limited access for cache-only builds.
    • Can read and write CAS files.
    • Can read and write AC entries.
    • Can write BES.
  • user: Common role for interactive users and remote execution builds.
    • Can read and write CAS files.
    • Can read AC entries.
    • Can execute actions.
    • Can write BES.
    • Can read from Event Store and Result Store.
    • Can read invocation profiles.
    • Can view invocations and status in the Build and Test UI.
    • Can generate client credentials like mTLS certificates if supported.
  • admin: Role with elevated permissions for cluster administrators.
    • Can perform all actions on a single tenant.
  • global-admin: Role with elevated permissions for multitenant cluster administrators.
    • Can perform all actions on all tenants.
    • Can define and edit roles.

List of permissions

EngFlow supports the following permissions. This list is subject to change.

  • actioncache:Read: read action cache entries.
  • actioncache:Write: write action cache entries.
  • actioncache:Delete: delete action cache entries.
  • buildeventservice:Write: write build event service events.
  • cluster:GetInfo: retrieve cluster metadata with the Cluster API.
  • contentaddressablestorage:Read: read content addressable storage files.
  • contentaddressablestorage:Write: write content addressable storage files.
  • eventstore:GetBuild: read build event streams.
  • eventstore:GetInvocation: read invocation event streams.
  • http:any: access the Build and Test UI.
  • http:ReportMetrics: UI can report page load metrics and unexpected errors.
  • http:GenerateJwt: generate JWT credentials in the UI for the current user, if supported.
  • http:GenerateMtlsCertificate: generate mTLS certificates in the UI for the current user, if supported.
  • iam:CreateRole: create roles with the IAM API.
  • iam:DeleteRole: delete roles with the IAM API.
  • iam:GetRole: read roles with the IAM API.
  • iam:ListRoles: list role names with the IAM API.
  • iam:UpdateRole: modify roles with the IAM API.
  • notification:Pull: take events from the Notification Queue API.
  • profiling:GetInvocationProfile: read invocation profiles.
  • remoteexecution:Run: execute remote actions.
  • resultstore:GetInvocation: read results of invocations.
  • resultstore:GetLogs: read logs.
  • cistatus:List: list all CI runners, if supported.