Improve buildbarn documentation #179

stagnation · 2023-04-18T11:46:42Z

Improve the example with instructions for how to deploy buildbarn locally with bb-deploymens.
And a workaround for instance name prefixes.

I will write an issue to track that, and we should refer to that issue in the example README.

facebook-github-bot · 2023-04-18T11:46:46Z

Hi @stagnation!

Thank you for your pull request and welcome to our community.

Action Required

In order to merge any pull request (code, docs, etc.), we require contributors to sign our Contributor License Agreement, and we don't seem to have one on file for you.

Process

In order for us to review and merge your suggested changes, please sign at https://code.facebook.com/cla. If you are contributing on behalf of someone else (eg your employer), the individual CLA may not be sufficient and your employer may need to sign the corporate CLA.

Once the CLA is signed, our tooling will perform checks and validations. Afterwards, the pull request will be tagged with CLA signed. The tagging process may take up to 1 hour after signing. Please give it that time before contacting us about it.

If you have received this in error or have any questions, please contact us at cla@meta.com. Thanks!

examples/remote_execution/buildbarn/README.md

stagnation · 2023-04-18T12:01:10Z

examples/remote_execution/buildbarn/README.md


 In this document, we will go over the key configs used in this setup.
+Using a local docker-compose deployment from the [example deployment repo](https://github.com/buildbarn/bb-deployments)


We may want some connective tissue here, to say that with a ready Buildbarn deployment the deploy section can be skipped. But for those who want to test remote execution, I think it's good to have instructions for that.
We can make it more succinct after we fix the instance-name prefix issue. But I would like to help people avoid that speed bump.

That landed, can you add it?

meroton-benjamin · 2023-04-18T12:29:34Z

examples/remote_execution/buildbarn/.buckconfig

@@ -2,13 +2,10 @@
 root = .
 prelude = prelude

-[buck2]
-digest_algorithms = SHA256


Tangentially related thought, shouldn't buck2 pick a suitable algorithm that matches one of the supported ones from the REV2 GetCapabilities call?
https://github.com/bazelbuild/remote-apis/blob/35aee1c4a4250d3df846f7ba3e4a4e66cb014ecd/build/bazel/remote/execution/v2/remote_execution.proto#L1960

Possibly, though I think it's a bit unlikely that we'd make this a priority — we've got no use for it internally is a small reason, but the bigger reason would be be that this is a pretty substantial overhaul of how we start up things, since we need this config very early on, which is not true of the RE client, for ultimately fairly little payoff (at least at the moment, all RE providers we're aware of support SHA256, which is the default we use in the OSS build).

At the moment that's true, there's not much gain in consuming GetCapabilities only to look at which digest function to use when SHA256 is pretty much universally supported.

But looking forward a little, the RE api recently adopted SHA256TREE as a digest function which is a precursor to add new functionality to the remote api ConcatenateBlobs and SplitBlobs. Those will allow partial transfer of larger blobs and ultimately become a more efficient replacement of bytestream.write.

There is of course no hurry, I just thought it might be worth poking the project on a trajectory that meshes well with how the protocol is moving.

But looking forward a little, the RE api recently adopted bazelbuild/remote-apis#235 as a digest function which is a precursor to add new functionality to the remote api bazelbuild/remote-apis#233. Those will allow partial transfer of larger blobs and ultimately become a more efficient replacement of bytestream.write.

Sure, my point there is primarily that actually configuring the hashing scheme you use is rather the trivial bit, there's a lot more to actually implementing describing what you're doing than inferring the configuration.

facebook-github-bot · 2023-04-18T12:55:58Z

Thank you for signing our Contributor License Agreement. We can now accept your code for this (and any) Meta Open Source project. Thanks!

thoughtpolice · 2023-04-18T18:25:53Z

I wonder if this should be on the homepage on http://buck2.build, right? Then it can just point to this directory as an example. It was definitely non-obvious to me at first!

krallin · 2023-04-19T08:31:30Z

examples/remote_execution/buildbarn/.buckconfig

-action_cache_address = http://localhost:8980
-engine_address = http://localhost:8980
-cas_address = http://localhost:8980
+action_cache_address = grpc://localhost:8980


I'd rather keep this as http://.

Neither of those are actually valid as per the GRPC spec for URIs, but grpc:// appears to be more used for when TLS is desired, so I intend to change #174 to respect that (at which point this would break)

Actually, let's keep this as-is, and add a separate config field for TLS. I'll update #174 with that.

krallin · 2023-04-19T08:31:54Z

examples/remote_execution/buildbarn/README.md


-First, the Build Barn endpoint and certificate should be configured as the following:
+This is mostly a turn-key solution, with just one modification.


Let's maybe just remove this and wait for #181 to get merged.

Yes! Great point. I originally wrote this last week, when we had no timeline for a solution.
And then an in-review Pull Request would be a good location for other confused developers to find the information. I planned to remove this after the solution, so the final artifact would not have it.

I'm fine with wating for 181, so I can remove the mention from here.

krallin · 2023-04-19T08:32:25Z

examples/remote_execution/buildbarn/README.md

 ```

-### Relevant configs in `ExecutionPlatformInfo`
+No TLS is used in this example (for history see this [issue](https://github.com/facebook/buck2/issues/156)).


What do we think the user should learn from this history? Can we either omit this entirely, or make that clearer?

Yepp, with your work to solve it we do not need any mention of the problems.

I will remove it.

krallin · 2023-04-19T08:33:30Z

examples/remote_execution/buildbarn/README.md


-The execution platform used in this project `root//platforms:platforms` do so.
+The Buildbarn workers take in a Docker image as their execution platform.


I think using "execution platform" here is a little confusing. To my knowledge, this is not a term Build Barn uses, but it is a term Buck2 uses, and that's not what it means in Buck2. I think "worker" did seem more appropriate (since that is terminology Build Barn uses)

krallin · 2023-04-19T08:33:56Z

examples/remote_execution/buildbarn/platforms/defs.bzl

@@ -21,6 +21,8 @@ def _platforms(ctx):
            # Set those up based on what workers you've registered with Build Barn.
            remote_execution_properties = {
                "OSFamily": "Linux",
+                # This could be any Docker image.


I don't think it can actually be any Docker image? It's got to be the one you did start your Build Barn cluster with, no?

No, you are right, and your base example did not have the comment. I just copy-pasted it from the Engflow example.

I'll remove it.

krallin · 2023-04-19T08:37:56Z

examples/remote_execution/buildbarn/.buckconfig

@@ -2,13 +2,10 @@
 root = .
 prelude = prelude

-[buck2]
-digest_algorithms = SHA256


Possibly, though I think it's a bit unlikely that we'd make this a priority — we've got no use for it internally is a small reason, but the bigger reason would be be that this is a pretty substantial overhaul of how we start up things, since we need this config very early on, which is not true of the RE client, for ultimately fairly little payoff (at least at the moment, all RE providers we're aware of support SHA256, which is the default we use in the OSS build).

krallin · 2023-05-03T08:54:08Z

examples/remote_execution/buildbarn/.buckconfig

-cas_address = http://localhost:8980
+action_cache_address = grpc://localhost:8980
+engine_address = grpc://localhost:8980
+cas_address = grpc://localhost:8980


Let's add tls = false here

Yes, though you already did in the commit that added it.

krallin · 2023-05-03T08:54:22Z

examples/remote_execution/buildbarn/README.md


 In this document, we will go over the key configs used in this setup.
+Using a local docker-compose deployment from the [example deployment repo](https://github.com/buildbarn/bb-deployments)


That landed, can you add it?

Add instructions for a simple local Buildbarn deployment to test with.

stagnation · 2023-05-04T07:59:35Z

examples/remote_execution/buildbarn/.buckconfig

 tls = false
+instance_name = fuse


For the record: inline toml comments are parsed as part of the string.
I presume this is a toml file, but you can disregard this if inline comments are not meant to work.

Internal error (stage: remote_call_error): Remote Execution Error (GRPC-SESSION-ID): RE: execution with digest 9a8db5f5c0ba0b07866989dafa06b9914c25483dfedba2b0f53d06251191bdfc:142: Failed to start remote execution: status: Unavailable, message: "No workers exist for instance name prefix \"fuse # or \\\"hardlinking\\\"\" platform {\"properties\ ":[{\"name\":\"OSFamily\",\"value\":\"Linux\"},{\"name\":\"container-image\",\"value\":\"docker://ghcr.io/catthehacker/ubuntu:act22.04@sha256:5f9c35c25db1d51a8ddaae5c0ba8d3c163c5e9a4a6cc97acd409ac7eae239448\"}]}", details: [], metadata: MetadataMap { headers: {"content-type": "application/grpc"} }

"No workers exist for instance name prefix \"fuse # or \\\"hardlinking\\\"\"

It's not really a toml file, no. I thin kit'd be good if we used a more robust format for this, but it's not the case currently

facebook-github-bot · 2023-05-04T08:04:50Z

@krallin has imported this pull request. If you are a Meta employee, you can view this diff on Phabricator.

stagnation commented Apr 18, 2023

View reviewed changes

examples/remote_execution/buildbarn/README.md Outdated Show resolved Hide resolved

stagnation changed the title ~~Feature/improve build barn documentation~~ Feature: improve buildbarn documentation Apr 18, 2023

stagnation changed the title ~~Feature: improve buildbarn documentation~~ Draft: Improve buildbarn documentation Apr 18, 2023

stagnation commented Apr 18, 2023

View reviewed changes

meroton-benjamin reviewed Apr 18, 2023

View reviewed changes

facebook-github-bot added the CLA Signed This label is managed by the Facebook bot. Authors need to sign the CLA before a PR can be reviewed. label Apr 18, 2023

stagnation force-pushed the feature/improve-BuildBarn-documentation branch from 0b69e45 to 4b6363c Compare April 18, 2023 15:14

stagnation mentioned this pull request Apr 18, 2023

buck2: don't add tls_config when URI does not call for it #174

Closed

stagnation changed the title ~~Draft: Improve buildbarn documentation~~ Improve buildbarn documentation Apr 18, 2023

krallin requested changes Apr 19, 2023

View reviewed changes

stagnation force-pushed the feature/improve-BuildBarn-documentation branch from 4b6363c to 36e1e37 Compare April 19, 2023 09:54

krallin requested changes May 3, 2023

View reviewed changes

stepancheg assigned krallin May 3, 2023

stagnation added 2 commits May 4, 2023 09:45

chore: fix typos

a663a93

Improve documentation for the Buildbarn example

5e23235

Add instructions for a simple local Buildbarn deployment to test with.

stagnation force-pushed the feature/improve-BuildBarn-documentation branch from 36e1e37 to 5e23235 Compare May 4, 2023 07:56

stagnation commented May 4, 2023

View reviewed changes

facebook-github-bot closed this in 43f8e87 May 4, 2023

stagnation deleted the feature/improve-BuildBarn-documentation branch June 29, 2023 15:52

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Improve buildbarn documentation #179

Improve buildbarn documentation #179

stagnation commented Apr 18, 2023

facebook-github-bot commented Apr 18, 2023

stagnation Apr 18, 2023

krallin May 3, 2023

stagnation May 4, 2023

meroton-benjamin Apr 18, 2023

krallin Apr 19, 2023 •

edited

Loading

meroton-benjamin Apr 19, 2023

krallin Apr 25, 2023 •

edited

Loading

facebook-github-bot commented Apr 18, 2023

thoughtpolice commented Apr 18, 2023 •

edited

Loading

krallin Apr 19, 2023

krallin Apr 19, 2023 •

edited

Loading

krallin Apr 19, 2023

stagnation Apr 19, 2023

krallin Apr 19, 2023

stagnation Apr 19, 2023

krallin Apr 19, 2023

stagnation Apr 19, 2023

krallin Apr 19, 2023

stagnation Apr 19, 2023

krallin Apr 19, 2023 •

edited

Loading

krallin May 3, 2023

stagnation May 4, 2023

krallin May 3, 2023

stagnation May 4, 2023 •

edited

Loading

krallin May 4, 2023

facebook-github-bot commented May 4, 2023


		In this document, we will go over the key configs used in this setup.
		Using a local docker-compose deployment from the [example deployment repo](https://github.com/buildbarn/bb-deployments)


		First, the Build Barn endpoint and certificate should be configured as the following:
		This is mostly a turn-key solution, with just one modification.


		The execution platform used in this project `root//platforms:platforms` do so.
		The Buildbarn workers take in a Docker image as their execution platform.

Improve buildbarn documentation #179

Improve buildbarn documentation #179

Conversation

stagnation commented Apr 18, 2023

facebook-github-bot commented Apr 18, 2023

Action Required

Process

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

krallin Apr 19, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

krallin Apr 25, 2023 • edited Loading

Choose a reason for hiding this comment

facebook-github-bot commented Apr 18, 2023

thoughtpolice commented Apr 18, 2023 • edited Loading

Choose a reason for hiding this comment

krallin Apr 19, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

krallin Apr 19, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

stagnation May 4, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

facebook-github-bot commented May 4, 2023

krallin Apr 19, 2023 •

edited

Loading

krallin Apr 25, 2023 •

edited

Loading

thoughtpolice commented Apr 18, 2023 •

edited

Loading

krallin Apr 19, 2023 •

edited

Loading

krallin Apr 19, 2023 •

edited

Loading

stagnation May 4, 2023 •

edited

Loading