Buildbarn Remote Execution + BuildFetch Cache

Architecture

Buildbarn Remote Execution can be configured to work with BuildFetch Cache acting as its fully compatible REAPI Remote Cache layer: Action Cache (AC) and Content-Addressable Storage (CAS).

In such setup, Buildbarn owns Remote Execution while BuildFetch Cache provides Remote Cache for Buildbarn, Bazel and other build systems:

• Bazel first writes the Action, Command, and input tree/blobs to BuildFetch CAS through --remote_cache.
• Bazel then sends Execute through --remote_executor to a bb_storage frontend, which forwards it to bb_scheduler.
• bb_scheduler reads the Action from BuildFetch CAS and queues it for bb_workers.
• bb_worker reads the Command and input tree/blobs from BuildFetch CAS, invokes bb_runner, then writes outputs to CAS and cacheable ActionResults to BuildFetch AC.
• bb_runner executes the prepared command.

Works with both Cloud and On-Prem version of BuildFetch Cache. We maintain end-to-end automatic integration tests verifying this configuration.

                                   Bazel
                          /                       \
                         /                         \
                 Remote Execution             Remote Cache
                     /                               \
                    v                                 v
  +-----------------------+                     +-----------------------+
  |    Buildbarn RBE      |                     |   BuildFetch Cache    |
  |-----------------------|                     |-----------------------|
  |      bb_storage       |                     |   Action Cache (AC)   |
  |           |           |                     |                       |
  |           v           |                     |  Content-Addressable  |
  |     bb_scheduler      | <---  AC / CAS ---> |     Storage (CAS)     | <-----    More
  |           |           |                     |                       |       build systems
  |           v           |                     |  Shared Remote Cache  |
  | bb_worker / bb_runner |                     |                       |
  +-----------------------+                     +-----------------------+

Configure Bazel Remote Cache and Remote Execution

Before setting up the integration, ensure you have created a BuildFetch Project and Token(s).

Point --remote_executor at Buildbarn and --remote_cache at BuildFetch Cache (Bazel gRPC Project Type). Use --remote_cache_header for the BuildFetch credential:

build --remote_instance_name=reapi/bazel/<PROJECT_ID>

build --remote_cache=grpcs://<cache.region.buildfetch.com>
build --remote_cache_header='Authorization=Bearer <BUILDFETCH_TOKEN>'

build --remote_executor=grpcs://buildbarn.example.com
build --remote_exec_header='Authorization=Bearer <BUILDBARN_TOKEN>'

Bazel sends the same --remote_instance_name value to both Remote Cache and Remote Execution, so your Buildbarn must accept BuildFetch reapi/bazel/<PROJECT_ID> as an execution instance.

Configure Buildbarn CAS and Action Cache backends

Cache Access

BuildBarn workers must read inputs and upload action outputs, so the BuildBarn backend requires a cache:readwrite Token.

For Token management, rotation, and Open Source guidance, see Set up BuildFetch Cache Project.

Read-write

Use a BuildFetch cache:readwrite Token for BUILDFETCH_CACHE_TOKEN and keep it in your secret-management system rather than committing it to source control.

local buildFetchCache = {
  grpc: {
    client: {
      address: '<cache.region.buildfetch.com>:443',
      tls: {},
      addMetadata: [{
        header: 'authorization',
        values: ['Bearer <BUILDFETCH_CACHE_TOKEN>'],
      }],
    },
  },
};

{
  blobstore: {
    contentAddressableStorage: buildFetchCache,
    actionCache: {
      completenessChecking: {
        backend: buildFetchCache,
        maximumTotalTreeSizeBytes: 64 * 1024 * 1024,
      },
    },
  },
}

Buildbarn passes --remote_instance_name value it receives from Bazel to its configured Remote Cache, BuildFetch uses --remote_instance_name=reapi/bazel/<PROJECT_ID> along with token to authorize access to a particular BuildFetch Cache Project.

This allows you to configure Buildbarn + BuildFetch Cache in two ways:

1. Single Bazel Remote Cache project in BuildFetch Cache:
   1. Create "Common Buildbarn project" of type Bazel in BuildFetch Cache
   2. Issue cache:readwrite token targeting just this Project in BuildFetch Cache
   3. Wire up the Project token to BUILDFETCH_CACHE_TOKEN of Buildbarn, this will allow all Buildbarn requests to BuildFetch Cache to be authenticated properly for this one shared Project.
2. Multiple Bazel Remote Cache projects in BuildFetch Cache:
   1. Create "Buildbarn Project A" and Project B of type Bazel in BuildFetch Cache
   2. Issue cache:readwrite token targeting the Org (key part) in BuildFetch Cache
   3. Wire up the Org token to BUILDFETCH_CACHE_TOKEN of Buildbarn, this will allow all Buildbarn requests to BuildFetch Cache to be authenticated properly for both Projects while --remote_instance_name=reapi/bazel/<PROJECT_ID> set in respective .bazelrc of each project will match it to particular project.
   4. For developer machines the --remote_cache_header='Authorization=Bearer <BUILDFETCH_TOKEN>' can still be Project-specific or User-specific token that allows Bazel to directly talk only to allowed BuildFetch Cache project.

End-to-end tested: BuildFetch integration suite runs this exact multi-project topology with one Buildbarn backend using a single Org-scoped cache:readwrite token for two distinct BuildFetch Projects, while each Bazel client keeps its own Project-scoped token and --remote_instance_name.

Verified Compatibility Matrix

BuildFetch has end-to-end CI tests that deploy real Buildbarn bb_storage, bb_scheduler, bb_worker, and bb_runner setup against BuildFetch Cache.

Current validated combinations are:

See Also

• Buildbarn
• Bazel Remote Execution API Specification
• BuildFetch Bazel Remote Caching
• BuildFetch Cache Architecture