Getting started¶

This page explains how you can prepare your organization and your projects to start using multitenancy.

In summary, you'll need to:

Contact support to enable multitenancy APIs.
Optional: Configure your OIDC provider to return custom roles.
Define custom roles with the IAM API.
Verify you can execute actions and access the cache on new tenants.

Contact support to enable multitenancy¶

Before you begin, contact support to enable multitenancy on your cluster. Multitenancy requires some APIs that are not enabled by default.

IAM API: lets cluster administrators define roles that grant access to specific tenants to different sets of users.
Resource Usage API (optional): lets cluster administrators monitor usage of the cluster, aggregated by tenant.

Configure your OIDC provider¶

Optional

This step is optional and is only necessary if you want to manage the mapping between user email addresses and EngFlow roles yourself. If you have a small number of tenants and a simple mapping between emails and roles, you can contact support to configure this mapping on the backend.

On a single tenant cluster, users are assigned a built-in role like admin, user, or cache-reader that grants access only to the default tenant. To create and access other tenants, you'll need to assign roles to users through your OIDC provider, and you'll need to create custom roles using the IAM API (in the next section).

In particular, you'll need to configure your OIDC provider to return the engflow_roles custom claim when a user logs into EngFlow. This claim may be either a string or a list of strings (preferred). Each string is the name of a role.

The steps to create and assign custom claims vary depending on your OIDC provider. Please contact support for help.

You should initially assign the global-admin role to a small number of people to act as cluster administrators. This role grants all permissions including the ability to use the IAM API to create custom roles.

Create custom roles¶

Custom roles must be enabled per-cluster; contact support if you would like to enable this feature.

A user with the global-admin role must create at least one custom role for users of each tenant using the IAM API. You can call the IdentityAndAccessManagement/CreateRole method to create new roles.

You can call this (or any gRPC API in engflowapis) directly with grpcurl, authenticating with an mTLS certificate or JWT bearer token from your cluster UI's Getting Started page. See Calling APIs with grpcurl in the engflowapis README for setup and authentication details.

List of relevant RPC endpoints

CreateRole: create a new role. Fails with ALREADY_EXISTS if a role or built-in role with that name already exists.
GetRole: read a role by name. Fails with NOT_FOUND if it doesn't exist.
ListRoles: list the names of every role on the cluster, including built-in roles.
UpdateRole: replace a role's description and policy fields entirely. Fails with NOT_FOUND if the role doesn't exist. You cannot update built-in roles.
DeleteRole: delete a role by name. Fails with NOT_FOUND if it doesn't exist. You cannot delete built-in roles. Deleting a role that's still assigned to a user or group removes that access.

Write the JSON needed to create the role you want using the IdentityAndAccessManagement/CreateRole API and save this in a file named create-role.json. For example, the request below creates a custom role named alpha-user that has access to the alpha tenant.

create-role.json

{
  "role": {
    "name": "alpha-user",
    "description": "Normal user of alpha tenant",
    "policy": [
      {
        "name": "all",
        "action": [
          "actioncache:Write",
          "actioncache:Read",
          "actioncache:Delete",
          "contentaddressablestorage:Write",
          "contentaddressablestorage:Read",
          "buildeventservice:Write",
          "eventstore:GetBuild",
          "eventstore:GetInvocation",
          "resultstore:GetInvocation",
          "resultstore:GetLogs",
          "http:any",
          "http:ReportMetrics",
          "http:GenerateMtlsCertificate",
          "notification:Pull",
          "http:GenerateJwt",
          "cluster:GetInfo",
          "profiling:GetInvocationProfile",
          "remoteexecution:Run"
        ],
        "resource": ["engflow:platform:*:alpha:*:*"]
      }
    ]
  }
}

See List of permissions for a list of all permissions supported by EngFlow. Then call CreateRole with this file as input, and verify the role was created successfully by calling GetRole with {"name":"alpha-user"}.

Verify access to tenants¶

A tenant is basically a namespace for resources. No special access needs to be taken to create a tenant, other than granting users permission to create resources inside it.

To verify access to a tenant:

Log in as a user you want to verify.
Generate credentials, either by visiting the Getting Started page to download an mTLS certificate or by running engflow_auth (see the link for install and setup instructions).

Build a Bazel project with remote flags that set the tenant name. (Other remote execution clients often have similar flags).

.bazelrc

common:engflow --remote_instance_name=alpha
common:engflow --bes_instance_name=alpha
common:engflow --bes_results_url=https://<CLUSTER_ENDPOINT>/invocations/alpha

Open the cluster UI and verify you can see new invocations on your tenant. If you have access to multiple tenants, you can filter invocations by instance name. Remember to log out and back in if you have made changes to the roles/permissions.