Skip to content

DashboardBuilders

Jump to bottom
Heschi Kreinick edited this page Oct 10, 2023 · 82 revisions

Table of contents

  1. Coordinator Builders
    1. How to set up a builder
    2. Builder Requirements
    3. Security notes
  2. LUCI Builders
    1. How to set up a builder
    2. Builder Requirements

Coordinator Builders

Build configs (at the top) and host configs (bottom) are listed here:

https://farmer.golang.org/builders

A builder runs on a certain host type. (e.g. linux-386-387 is a build type. It runs on host-linux-kubestd, a Kubernetes-based linux/amd64 host)

They come from the file https://github.com/golang/build/blob/master/dashboard/builders.go

For design details about the coordinator, see https://go.dev/s/builderplan

Information about builder machines, how many are running and their status can be found at https://farmer.golang.org/

How to set up a builder

  1. Talk to golang-dev@ to get a builder host type & hash (they can get one from using the golang.org/x/build/cmd/genbuilderkey tool), and put that in ~/.gobuildkey or ~/.gobuildkey-host-foo-bar or the file pointed to by env var $GO_BUILD_KEY_PATH.
  2. Define your new builder in https://github.com/golang/build/blob/master/dashboard/builders.go with a new HostConfig and BuildConfig.
  3. Have golang-dev deploy the build coordinator rebuilt with the dashboard/builders.go change
  4. Have golang-dev modify golang.org/x/build/cmd/buildlet/Makefile to add your port and to uploads its buildlet binary to Google Cloud Storage (you can do this step out of order if your compiler changes aren't yet upstream)
  5. Verify you can see the new host & build configs at https://farmer.golang.org/builders
  6. (Interm/testing step) Test that your builder key works and you can register:
    1. go get -u golang.org/x/build/cmd/buildlet
    2. buildlet -coordinator=farmer.golang.org -reverse-type=host-foo-bar -reboot=false
    3. verify it shows up at https://farmer.golang.org/#pools in "Reverse pool summary" and "Reverse pool machine detail"
  7. Modify the golang.org/x/build/cmd/buildlet/stage0 binary if/as needed to pass the right flags to the buildlet binary.
  8. Put your stage0 binary on your builder, run in a loop under your operating system's process supervisor (systemd, etc). The stage0 binary is responsible for conditionally re-downloading the buildlet binary from Google Cloud Storage for each build. (This lets us evolve the build system without involving each machine owner)

For WIP ports, the steps above can be done out of order as needed. But as a port matures, be sure each step above is done. In particular, make sure that you're not just running a fixed copy of the buildlet binary in a loop forever. We need to be able to update it over time without your involvement. You should be running the stage0 binary (or equivalent shell script or similar for your platform) in a loop instead.

Builder Requirements

  • Internet connection (at least be able to access Google and https://farmer.golang.org)
  • Preferably two or more (V)CPUs
  • At least 512MiB of memory (1GB or more highly recommended. 512MB might need a small GOGC setting to avoid thrashing.)

Security notes

Generally, community-run builders only run code that's already been reviewed & submitted. We only enable pre-submit testing for builders run by the Go team that have a lot of hardware available. However, the Gomote tool is available for a number of people on the Go team and in the Go community that lets them have arbitrary access to the builders for development & debugging.

For paranoia reasons, you might want to run your builder in an isolated network that can't access any of your internal resources.

LUCI Builders

The Go team is migrating the testing pipeline from a custom solution, the coordinator, to LUCI. LUCI is an open source continuous integration system created by the Chrome open source team at Google. The Go team has adopted the use of LUCI in order to leverage a continuous integration solution which is used and supported by a larger group of developers. This should enable the team to provide a more featureful solution to the community.

The LUCI system requires builders to run two applications which authenticate to LUCI and receive and process builds. LUCI token daemon generates a token needed to authenticate. The swarming bot uses the token to connect to LUCI and process builds.

Builder Requirements

  • An internet connection with the ability to connect to:
  • Resources
    • At least 512MB of memory. 1GB or more is highly recommended.
    • 20GB disk space is ideal.
    • Preferably with 2 or more (V)CPUs.
  • Python3 installed and in the PATH.
  • Permissions
    • The bot should be run as the swarming user (without root rights).
    • The bot automatically updates itself. It should have permissions to do so.
    • The bot periodically restarts the machine. It should have permissions to do so (via sudo).

How to set up a builder

  1. Create an issue on the Go Issue tracker requesting the addition of a new builder and assign it yourself.

    1. The title of the issue should be in the format: x/build: add LUCI <os-arch> builder.
    2. Choose a hostname.
    3. Add the label "new-builder". (You can post a comment on the issue stating @gopherbot, please add label new-builder. in the issue to have gopherbot add it for you.)

  2. Use golang.org/x/build/cmd/genbotcert to generate both a certificate signing request (hostname.csr) and a TLS private key (hostname.key) using the hostname (chosen beforehand) as input. Attach the certificate signing request (hostname.csr) to the GitHub issue. A team member will attach the resulting certificate (hostname.cert) to the GitHub issue.

    1. genbotcert -bot-hostname <hostname>

  3. A Go team member will define your new builder in LUCI. A comment will be added to the issue when this is completed.

  4. The Machine Token Daemon communicates with the Token Server to generate and renew a LUCI machine token. Install go.chromium.org/luci/tokenserver/cmd/luci_machine_tokend and configure it to run every 10 minutes via cron. The private key shouldn't be readable by the swarming user, so the cron job should run as a separate user.

    1. luci_machine_tokend -backend luci-token-server.appspot.com -cert-pem <path-to-the-certificate> -pkey-pem <path-to-the-private-key> -token-file=/var/lib/luci_machine_tokend/token.json
    2. If /var/lib isn't a suitable place for the token, change it as you see fit and pass -token-file-path to bootstrapswarm below to match.

  5. Install golang.org/x/build/cmd/bootstrapswarm and configure it to run in a loop under your operating system's process supervisor (systemd, etc) as the swarming user. Bootstrapswarm downloads the initial version of the swarming bot and ensures that it is always running.

    1. bootstrapswarm -hostname <hostname>

  6. Verify the bot starts up without any errors in the logs.

Clone this wiki locally