Bring Your Own Build

Remote Build Execution - Bring Your Own Build

Turndown

The shared Bring Your Own Build will be brought down on Oct 12. If you'd like to participate in the RBE Alpha program please join the rbe-alpha-customers Google Group to access the documentation and fill out the Request For Information form.

Getting started

The Bring Your Own Build Event allows you try your build with Google Cloud Platform's Remote Build Execution. Members of Google's RBE team will be on hand to help guide you through the process.

You will be running your builds against a shared instance of RBE available to all other BazelCon attendees, please do not use it for building your high value code. This instance of RBE (and all data within) will be deleted shortly after BazelCon concludes. You can use this time to evaluate if you’d like to join the RBE Alpha program.

Pre-requisites:

  • An open source or low value code base that builds with Bazel.
    • Note that we will be using a shared instance of RBE, which makes it possible for the build artifacts to be seen by other users who join the BYOB session, for this reason we ask you use open source code or code that you don't mind being seen by others.
  • Join the rbe-alpha-customers Google Group, this gives you access to the RBE documentation (access may lag up to an hour after joining the group).
  • Prepare a Linux environment with Bazel installed and the code base that you want to use. We recommend using a Linux Google Compute Engine VM in the us-central1 region and the Bazel Container (see below).
  • Run the "RBE system check" to validate your access to the shared RBE instance, see instructions (see below).
  • Optionally try to run a larger project, see instructions (see below).
  • Try it with your codebase!

Preparing your environment

Please note, that the RBE service runs in Google Cloud's us-central1 region and we recommend that the host machine running Bazel is close (in terms of network latency) and has sufficient bandwidth to us-central1. For the best results we recommend using a GCE VM with the Bazel container.

Alternatively you could run the Bazel Container on your laptop or other hardware machine.

Mac OS

On a Mac OS machine with docker installed (instructions), simply run the docker command from step 5 below (note that this runs docker on a Linux VM on your machine).

Windows

On a Windows machine with docker installed (instructions), simply run the docker command from step 5 below (note that this runs docker on a Linux VM on your machine).

Linux

On a Linux Machine with docker installed (instructions for Ubuntu), simply run the docker command from step 5 below.

Google Compute Engine

The following are instructions on how to set one up on GCE. Note that you must associate a billing account with your project in GCE in order to start a VM, make sure to delete your VM instance once you are done with it to avoid continued charges.

1. If you don't already have it, install gcloud.

2. Create or choose a Google Cloud Project:

$ MY_PROJECT=[project name goes here]
$ gcloud projects create $MY_PROJECT  # create the project if it does not yet exist

3. Go to https://console.cloud.google.com/billing/linkedaccount?project=$MY_PROJECT (substituting your project name) and enable billing, this is required for starting a VM (don't forget to shut down your VM after you are done with it).

4. Finish setting up a VM instance:

$ gcloud init
# ... follow the prompts to setup $MY_PROJECT as the default project that gcloud will reference
$ gcloud services enable compute.googleapis.com
$ gcloud compute instances create bazelcon-test --project $MY_PROJECT --zone us-central1-a \
      --machine-type n1-standard-4 --image-project coreos-cloud --image-family coreos-stable \
      --boot-disk-size=50GB
$ gcloud compute ssh --project $MY_PROJECT --zone us-central1-a bazelcon-test
# ... you may be prompted to create a passphrase, and then enter it to ssh to your instance

If ssh via gcloud fails, you can also SSH through your browser, modify the following URL with your project name (and instance if you used a different instance name):

https://ssh.cloud.google.com/projects/$MY_PROJECT/zones/us-central1-a/instances/bazelcon-test

At this point you have a VM with docker installed.

5. Run the Bazel Container (this may take a few minutes):

$ docker run -it --entrypoint=/bin/bash l.gcr.io/google/bazel:0.17.1

Running the system check

Within the Bazel Container run the following to prep for running the system check (or your code) on RBE:

1. Download the credentials needed to run against the shared RBE instance:

$ curl -X GET -o /tmp/key.json "https://www.googleapis.com/storage/v1/b/bazel_key/o/key.json?alt=media"

2. Create a directory for the system check source code

$ mkdir -p /tmp/rbe-system-check && cd /tmp/rbe-system-check/

3. Download the code for the RBE system check

$ git clone https://github.com/bazelbuild/bazel-toolchains.git && cd bazel-toolchains

4. Run the RBE system check against the shared instance

$ bazel --bazelrc=bazelrc/latest.bazelrc \
    test //examples/remotebuildexecution/rbe_system_check/cc:rbe_system_check_test \
    --config=remote --jobs=100 \
    --remote_instance_name=projects/bazelcon18-rbe-shared/instances/default_instance \
    --auth_credentials=/tmp/key.json

You should see a result similar to the following, note that the "3 remote" string indicates that all actions executed remotely.

INFO: 3 processes: 3 remote.
INFO: Build completed successfully, 7 total actions
//examples/remotebuildexecution/rbe_system_check/cc:rbe_system_check_test PASSED in 4.0s

Executed 1 out of 1 test: 1 test passes.

Alternatively you might get the following in your output:

INFO: 3 processes: 3 remote cache hit.

If this the case: congratulations! You just had your first cache hit from the shared cache (recall that you are running against a shared instance and the exact build you are now running is very likely to be cached on the server).

Running a larger build

You can try running a build of the abseil-cpp project against RBE. To do so follow these steps:

  1. Clone the repo:
$ cd /tmp && git clone https://github.com/abseil/abseil-cpp.git && cd abseil-cpp/

2. Run the build. Note that this references the bazelrc from the bazel-toolchains repo you cloned above.

$ bazel \
--bazelrc=/tmp/rbe-system-check/bazel-toolchains/bazelrc/latest.bazelrc \
build //absl/... \
--config=remote --jobs=100 \
--remote_instance_name=projects/bazelcon18-rbe-shared/instances/default_instance \
--auth_credentials=/tmp/key.json

You should see output similar to the following, note that the “440 remote” part indicates that all actions executed on RBE.

INFO: Analysed 204 targets (41 packages loaded).
INFO: Found 204 targets...
INFO: Elapsed time: 64.969s, Critical Path: 34.38s
INFO: 440 processes: 440 remote.
INFO: Build completed successfully, 924 total actions

You may also get a fully cached build, congrats!

Trying your own build

You should be able to adopt the steps above to try RBE with your own build. Please start by reviewing the onboarding strategy to understand what parts of your build would be a good starting point. You may also want to read through Remote-Compatible Builds to understand what portions of your build that may not be compatible to start.

In order to build/test your codebase on RBE you will need to add the following to your WORKSPACE file and use the bazelrc file provided in the bazel-toolchains repo which you cloned above. The bazelrc file uses this bazel_toolchains repo in the definition of the remote configuration (selected via --config=remote).

# 0.17.1
COMMIT = "bc09b995c137df042bb80a395b73d7ce6f26afbe"
SHA256 = "4329663fe6c523425ad4d3c989a8ac026b04e1acedeceb56aa4b190fa7f3973c"

http_archive(
 name = "bazel_toolchains",
 urls = [
   "https://mirror.bazel.build/github.com/bazelbuild/bazel-toolchains/archive/"+COMMIT+".tar.gz",
   "https://github.com/bazelbuild/bazel-toolchains/archive/"+COMMIT+".tar.gz",
 ],
 strip_prefix = "bazel-toolchains-"+COMMIT,
 sha256 = SHA256
)

Cleanup

If you used a GCE VM consider shutting it down to avoid ongoing charges (note: this will lose all state on the VM):

$ gcloud compute instances delete bazelcon-test --zone us-central1-a --project $MY_PROJECT

Otherwise you simply exist from your container on your local machine.