Overview
A BuildGrid deployment consists of a number of gRPC services. These services can be deployed in a single process, or spread across multiple processes for more granular scaling capabilities.
The most basic functional deployment architecture is the subset of the Remote Execution API (REAPI) services required for cache-only workflows.
To fully support remote execution and caching then all of the Remote Execution API services and Remote Workers API (RWAPI) services will need to be deployed.
There are a number of optional services which can improve the experience of users when using BuildGrid.
REAPI Services
Action Cache
The Action Cache is a cache of the results of Actions, which are the units
of execution in the REAPI.
The Action Cache is a key/value store mapping Action digests to the
corresponding ActionResult. It can be configured to store these results
itself, or instead just store the digest of the result and fetch the actual
contents from the Content Addressable Storage (CAS) backend at runtime.
All three of Action Cache, ByteStream, and Content Addressable Storage are needed to have a cache-only BuildGrid instance.
ByteStream
The ByteStream service is used for reading and writing blobs into CAS which are too large to fit into a single gRPC message. A CAS service is not functional without a corresponding ByteStream service configured alongside it.
All three of Action Cache, ByteStream, and Content Addressable Storage are needed to have a cache-only BuildGrid instance.
Content Addressable Storage
The Content Addressable Storage service (CAS) is a content-addressed blob store. This service supports storage and retrieval of arbitrary blobs, but its main purpose is to provide storage for the inputs to executions, as well as storage for the outputs produced by those executions.
The content-addressing is managed via hashing the blobs stored in the CAS. BuildGrid currently only supports using the SHA256 algorithm for hashing blobs.
In the cache-only case, this service is used to store the build outputs that are being cached.
All three of Action Cache, ByteStream, and Content Addressable Storage are needed to have a cache-only BuildGrid instance.
Execution
The Execution service is responsible for validating requests to execute an
Action, and queueing them as jobs to be assigned to a bot. The
Execution service’s scheduler component runs assigners which periodically read
from the job queue and assign a job to a matching bot. These assigners are
configurable to allow different scheduling approaches.
Operations
The Operations service is used to query details about work that has been
submitted to BuildGrid. Each Operation corresponds to an Execute
request that was sent to the Execution service. The Operations service is
also used to cancel in-flight Actions if the work is no longer needed.
RWAPI Services
Bots Interface
The Bots Interface service implements the Remote Workers API. It handles synchronizing bot state updates with the internal representation; this could be reporting progress on execution or informing the bot of a new job it has been assigned to work on.
This service also has a scheduler component, which is configurable in the same way as the Execution service’s scheduler.
Additional Services
Asset
The Asset service implements the Remote Asset API, which is a complementary API to the REAPI. The Asset service allows mapping URIs with optional qualifiers to blobs stored in CAS.
This service is implemented in a separate tool to the main BuildGrid server, which lives in the buildgrid-asset repository.
LogStream
The LogStream service implements the `Remote LogStream API`_, another complementary API to the REAPI. Using this service allows execution clients to retrieve a live stream of logs from the worker machine during remote execution. This allows building workflows which execute remotely with the same user experience as a local build.
This service is also implemented separately to the main BuildGrid server, in the buildgrid-logstream repository.
Introspection
The Introspection service is a BuildGrid-specific service which provides
methods for introspecting the state of BuildGrid’s internals. This allows
querying of the known workers along with being the canonical source for the
ListOperations filter syntax used by BuildGrid’s Operations service
implementation, along with other methods for querying various contents of
BuildGrid’s scheduler database.
Metering
The Metering service is a HTTP 1.1 API which is used to keep track of usage on a per-client basis. The Execution service can be configured to use this service to make decisions about whether or not to throttle access to compute for a particular client identity.
PublishBuildEvents
Warning
This is an experimental service.
This service is an implementation of Bazel’s Build Event Protocol. It is used by Bazel to publish lifecycle events and build information to help future debugging. The implementation in BuildGrid supports this use-case, but is generic enough to also be useful for any non-Bazel event streams using the same protocol.
Query Build Events
Warning
This is an experimental service
The Query Build Events service is a BuildGrid-specific service used to query and retrieve Build Event Protocol event streams from the server after completion of a build. This service is used by BuildGrid Browser to display event stream information in a UI.