Skip to content

Roles, Policies, and Permissions

Each EngFlow cluster allows users to perform actions based on their designated roles. A role consists of a set of policies, defining what users assigned that role are allowed to do. A policy is a set of permissions, listing actions that may be performed on a set of resources.

Defining roles and policies

Experimental

Defining custom roles is experimental and is disabled by default. Please contact support if you would like to enable this feature.

You can define custom roles for your users 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.

Assigning roles to users

EngFlow does not yet provide an API to map roles to users. Most clusters configure this mapping with the --principal_based_permissions scheduler flag. Please contact support if you need to reassign user roles using this flag.

It is also possible to assign user roles through your OIDC provider with the engflow_roles custom claim, which may be set to a list of role names (strings). This is experimental functionality, so please contact support if you'd like to assign roles using this mechanism.

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, status, and analytics 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 tenants.
  • global-admin: Role with elevated permissions for multi-tenant 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: access build analytics in the UI.
  • 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:UpdateRoles: 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.

Example of a custom role

The example below shows a role written in text proto format. See role.proto for the full specification. This creates a role named beta-user which grants a typical set of permissions to users of the tenant beta.

Text Only
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
name: "beta-user"

description: "Normal user of beta tenant"

policy {
  name: "all"

  action: "actioncache:Write"
  action: "actioncache:Read"
  action: "actioncache:Delete"
  action: "contentaddressablestorage:Write"
  action: "contentaddressablestorage:Read"
  action: "buildeventservice:Write"
  action: "eventstore:GetBuild"
  action: "eventstore:GetInvocation"
  action: "resultstore:GetInvocation"
  action: "resultstore:GetLogs"
  action: "http:any"
  action: "http:ReportMetrics"
  action: "http:GenerateMtlsCertificate"
  action: "notification:Pull"
  action: "http:GenerateJwt"
  action: "cluster:GetInfo"
  action: "profiling:GetInvocationProfile"
  action: "remoteexecution:Run"

  resource: "engflow:platform:*:beta:*:*"
}