Platform Options

Platform options are set in the remote execution protocol and control how the corresponding actions are executed by the service. This document provides examples for configuring Bazel to set the various platform options.

See Docker platform options for the full list of supported platform options.

Server-side Platform Parsing

By default, the EngFlow Remote Execution service performs strict platform parsing: it generates an error for unknown platform options and illegal platform settings.

Unused platform options are silently ignored. For example, an action that is run in a docker container ignores all sandbox platform options. As another example, if the service is configured to never use docker containers, then it ignores all docker platform options.

Keep in mind that unused platform options are still part of the action cache key: two actions that are otherwise equal but have different settings for an unused platform option are treated as separate actions.

Docker Capability Handling

Every docker container starts with Docker's own default set of Linux capabilities. The server flag --docker_drop_capabilities lists capabilities to drop from that default set, on top of what Docker already excludes by default.

The dockerDropCapabilities platform option lets a client drop additional capabilities from its own action's container. This is in addition to the server's default-drop list above.

Adding capabilities is gated separately, by the server flag --docker_allow_requesting_capabilities, which defaults to true. The table below walks through what happens for different settings of a client's dockerAddCapabilities request and the server's capability-restriction flags:

dockerAddCapabilities request	Server configuration	Result
Unset	(any)	No capabilities added. Container keeps Docker's default set, minus any --docker_drop_capabilities.
A specific capability, e.g. DAC_READ_SEARCH	--docker_allow_requesting_capabilities=true (default); capability not on --docker_disallowed_capabilities	Granted, even if the capability is also on --docker_drop_capabilities: naming it explicitly overrides the default drop.
A specific capability	Capability is on --docker_disallowed_capabilities	Rejected: the Execute call returns INVALID_ARGUMENT. The action never runs.
ALL	--docker_allow_requesting_capabilities=true (default); --docker_disallowed_capabilities is empty	Every capability is granted except any on --docker_drop_capabilities: Docker removes those from the set it grants for ALL.
ALL	--docker_disallowed_capabilities is non-empty	Rejected: the Execute call returns INVALID_ARGUMENT. The action never runs, regardless of which capabilities are listed.
Any value, named or ALL	--docker_allow_requesting_capabilities=false	Rejected: the Execute call returns INVALID_ARGUMENT. The action never runs. Only adding is disabled; dockerDropCapabilities still works.

The deny-list (--docker_disallowed_capabilities) has no exception for ALL: once any capability is on it, both a request naming that capability and a request of ALL are rejected. The default-drop list (--docker_drop_capabilities) is the one with an asymmetry left: a client overrides it for a specific capability by naming that capability explicitly in dockerAddCapabilities, but a request of ALL cannot override it, since Docker itself removes these capabilities from the set it computes for ALL.

Setting Platform Options with string options

With manual platform configuration

platform(
    name = "engflow",
    # ...
    exec_properties = {
        "dockerNetwork": "standard",
    },
)

Setting platform options on a particular target

sh_test(
    name = "docker_sibling",
    srcs = ["docker_sibling.sh"],
    exec_properties = {
        "dockerSiblingContainers": "True",
        "dockerNetwork": "standard",
    },
)

Using create_rbe_exec_properties_dict

The create_rbe_exec_properties_dict macro from the bazel-toolchains repository can be used to type-check the platform settings on the client, rather than relying on server-side checks. However, the macro does not support all platform options that are supported by the EngFlow Remote Execution service.

Example

load("@bazel_toolchains//rules/exec_properties:exec_properties.bzl", "create_rbe_exec_properties_dict")

platform(
    name = "engflow_remote_config",
    # ...
    exec_properties = create_rbe_exec_properties_dict(docker_sibling_containers = True),
)

Example

load("@bazel_toolchains//rules/exec_properties:exec_properties.bzl", "create_rbe_exec_properties_dict")

sh_test(
    name = "docker_sibling",
    srcs = ["docker_sibling.sh"],
    exec_properties = create_rbe_exec_properties_dict(
        docker_sibling_containers = True,
        docker_network = "standard",
    ),
)

Disabling Docker Execution

Bazel automatically merges execution properties set at the WORKSPACE level with those set at the rule level, but does not provide a way to remove one. In order to disable Docker execution, you can set an empty container-image setting:

sh_test(
    name = "sandboxed_test",
    srcs = ["sandboxed_test.sh"],
    exec_properties = {
        "container-image": "",
    },
)