Skip to content

Secrets

EngFlow supports secrets: confidential key-value pairs that may be passed to remotely executed actions as environment variables. Secrets are never stored in content addressable storage (CAS) in plaintext.

Types of secrets

  • An instance secret is a key-value pair managed by a user administrator through the Secret gRPC API. Instance secrets are shared by all users with access to an instance, if authorized by their permissions. This means instance secrets are appropriate for values not specific to any user, like external Docker registry credentials or shared bot account keys. On multitenant clusters, secrets in one instance are isolated from other instances. On single tenant clusters (most clusters), secrets are effectively global.
  • A user secret is a key-value pair secret to an individual user, not shared with other users. User secrets are passed securely to remotely executed actions and are not stored persistently on the cluster.
  • An on-demand secret is a unique secret generated for each action when it is requested. Currently only the ENGFLOW_RPC_CREDENTIALS secret is supported.

Service configuration

As of EngFlow 2.167.0, instance secrets and the ENGFLOW_RPC_CREDENTIALS on-demand secret are enabled by default. No additional configuration is necessary. These features may be disabled with the --enable_tenant_secrets and --enable_ondemand_secrets flags.

Permissions and roles

Access to secrets is managed through EngFlow roles, permissions, and policies. There are three permissions relevant to instance secrets:

  • secret:Read: list secret names with List and read values of secrets with Get.
  • secret:Write: create or update secrets with Set or delete secrets with Delete.
  • secret:Execute: execute actions using secrets.

When writing policies, use the resource name secret/{NAME} to grant access to a specific secret, replacing {NAME} with the secret name.

The following built-in roles have access to secrets by default:

  • The user role has secret:Execute permission on all secrets in the default tenant.
  • The admin role has all permissions in the default tenant.
  • The global-admin has all permissions on all tenants.

No permissions are needed for user secrets or on-demand secrets.

Manage instance secrets with the Secret API

The Secret gRPC API is defined in secret.proto. It supports four operations:

  • List: get names of all secrets within a tenant. Supports pagination.
  • Get: read the value of a particular secret.
  • Set: create a new secret or update an existing secret's value.
  • Delete: delete a secret.

Manage instance secrets with the ef command line tool

See ef: Instance secrets.

Execute actions with secrets

To execute an action with secrets, set the engflow:secrets platform property to a comma-separated list of secret names. The action will execute with environment variables set to secret values. For example, if the DOCKER_CREDS secret is requested, an environment variable named DOCKER_CREDS is set to its value. The client must have secret:Execute permission to access all requested secrets.

The value of the secret is only available at run-time and is not stored in plaintext in content addressable storage (CAS) or the action cache (AC). However, the name of each requested secret is stored in CAS. An action that uses secrets may be cached, though secret values are not cached unless the action writes them to output files. Changing the value of a secret does not invalidate AC entries for actions that executed using the old value, so rotating a secret won't cause a performance penalty.

Bazel

To request secrets for a specific Bazel target, set its exec_properties:

sh_test(
    name = "dockertest",
    ...
    exec_properties = {
        "engflow:secrets": "DOCKER_CREDS",
    }
)

To request a secret for all actions from the Bazel command line, use --remote_default_exec_properties:

bazel build --remote_default_exec_properties=engflow:secrets=DOCKER_CREDS //:target

ef run

To remotely execute a command using an instance secret:

ef run -instance_secret=DOCKER_CREDS docker run ...

Access the cluster within an action with ENGFLOW_RPC_CREDENTIALS

To execute an action that can access the EngFlow cluster, request the secret ENGFLOW_RPC_CREDENTIALS using one of the methods above. This is an on-demand secret: it does not need to be stored ahead of time. When requested, the ENGFLOW_RPC_CREDENTIALS environment variable is set to a bearer token that can be used to authenticate to an EngFlow cluster.

When using ef run with Bazel and -mode=git (enabled by default when invoked inside a Git repository), no additional configuration is needed. ef run automatically configures a Bazel credential helper to use ENGFLOW_RPC_CREDENTIALS.

To use ENGFLOW_RPC_CREDENTIALS within other actions, set the x-engflow-auth-method gRPC metadata to jwt-v0 and x-engflow-auth-token to the value of ENGFLOW_RPC_CREDENTIALS.

The token is issued with the same principal and roles as the requesting client, so the remote action can do the same things the user can. However, the token has a short lifetime, limited to the maximum action duration on the pool where the action is executed.