Platform Options

Controlling action execution from the client

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.

Setting Platform Options with string options

Example:

rbe_autoconfig(
    name = "engflow_remote_config",
    # ...
    exec_properties = {
        "dockerSiblingContainers": "True",
    },
)

Example:

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")

rbe_autoconfig(
    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": "",
    },
)
2021-09-21