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.
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¶

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¶

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 the IAM API (or any gRPC-based API) conveniently using grpcurl or grpcui.

For example, a CreateRole request to create a role named alpha-user with a typical level of access to the tenant alpha looks like this:

{
  "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.

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 whose role grants them access to a tenant. For example, if your OIDC provider sets the engflow_roles custom claim to ["alpha-user"], then the user has the alpha-user role created above and can access the alpha tenant.
Generate credentials with engflow_auth login example.cluster.engflow.com, replacing the cluster host name with your own.
Ensure Bazel is configured to use engflow_auth with a line in your .bazelrc file:
.bazelrc
```
common:engflow --credential_helper=example.cluster.engflow.com=engflow_auth
```
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
```
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.