1 // Copyright 2018 Google LLC
3 // Licensed under the Apache License, Version 2.0 (the "License");
4 // you may not use this file except in compliance with the License.
5 // You may obtain a copy of the License at
7 // http://www.apache.org/licenses/LICENSE-2.0
9 // Unless required by applicable law or agreed to in writing, software
10 // distributed under the License is distributed on an "AS IS" BASIS,
11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 // See the License for the specific language governing permissions and
13 // limitations under the License.
17 package google.devtools.remoteworkers.v1test2;
19 option csharp_namespace = "Google.DevTools.RemoteWorkers.V1Test2";
20 option go_package = "google.golang.org/genproto/googleapis/devtools/remoteworkers/v1test2;remoteworkers";
21 option java_multiple_files = true;
22 option java_outer_classname = "RemoteWorkersWorker";
23 option java_package = "com.google.devtools.remoteworkers.v1test2";
24 option objc_class_prefix = "RW";
26 // Describes a worker, which is a list of one or more devices and the
27 // connections between them. A device could be a computer, a phone, or even an
28 // accelerator like a GPU; it's up to the farm administrator to decide how to
29 // model their farm. For example, if a farm only has one type of GPU, the GPU
30 // could be modelled as a "has_gpu" property on its host computer; if it has
31 // many subproperties itself, it might be better to model it as a separate
34 // The first device in the worker is the "primary device" - that is, the device
35 // running a bot and which is responsible for actually executing commands. All
36 // other devices are considered to be attached devices, and must be controllable
37 // by the primary device.
39 // This message (and all its submessages) can be used in two contexts:
41 // * Status: sent by the bot to report the current capabilities of the device to
42 // allow reservation matching.
43 // * Request: sent by a client to request a device with certain capabilities in
46 // Several of the fields in this message have different semantics depending on
47 // which of which of these contexts it is used. These semantics are described
50 // Several messages in Worker and its submessages have the concept of keys and
51 // values, such as `Worker.Property` and `Device.Property`. All keys are simple
52 // strings, but certain keys are "standard" keys and should be broadly supported
53 // across farms and implementations; these are listed below each relevant
54 // message. Bot implementations or farm admins may add *additional* keys, but
55 // these SHOULD all begin with an underscore so they do not conflict with
56 // standard keys that may be added in the future.
58 // Keys are not context sensitive.
60 // See http://goo.gl/NurY8g for more information on the Worker message.
62 // A global property; see the `properties` field for more information.
64 // For general information on keys, see the documentation to `Worker`.
66 // The current set of standard keys are:
68 // * pool: different workers can be reserved for different purposes. For
69 // example, an admin might want to segregate long-running integration tests
70 // from short-running unit tests, so unit tests will always get some
71 // throughput. To support this, the server can assign different values for
72 // `pool` (such as "itest" and "utest") to different workers, and then have
73 // jobs request workers from those pools.
76 // The property's value.
80 // A configuration request or report; see the `configs` field for more
83 // For general information on keys, see the documentation to `Worker`.
85 // The current set of standard keys are:
87 // * DockerImage: the image of the container. When being reported by the
88 // bot, the empty value should always be included if the bot is able to pull
89 // its own images; the bot may optionally *also* report images that are
90 // present in its cache. When being requested in a lease, the value is the
91 // URI of the image (eg `gcr.io/user/image@sha256:hash`).
94 // The configuration's value.
98 // A list of devices; the first device is the primary device. See the `Device`
99 // message for more information.
100 repeated Device devices = 1;
102 // A worker may contain "global" properties. For example, certain machines
103 // might be reserved for certain types of jobs, like short-running compilation
104 // versus long-running integration tests. This property is known as a "pool"
105 // and is not related to any one device within the worker; rather, it applies
106 // to the worker as a whole.
108 // The behaviour of repeated keys is identical to that of Device.Property.
109 repeated Property properties = 2;
111 // Bots can be configured in certain ways when accepting leases. For example,
112 // many leases are executed inside a Docker container. To support this, the
113 // bot needs to be able to report that it has Docker installed (and knows how
114 // to execute something inside a container), and the task submitter needs to
115 // specify which image should be used to start the container. Similarly, a
116 // lease may be able to run as one of several users on the worker; in such
117 // cases, the bot needs to report what users are available, and the submitter
118 // needs to choose one.
120 // Therefore, when this message is reported by the bot to the service, each
121 // key represents a *type* of configuration that the bot knows how to set,
122 // while each *value* represents a legal value for that configuration (the
123 // empty string is interpretted as a wildcard, such as for Docker images).
124 // When this message is sent by the server to the bot in the context of a
125 // lease, it represents a command to the bot to apply the setting. Keys may
126 // be repeated during reporting but not in a lease.
127 repeated Config configs = 3;
130 // Any device, including computers, phones, accelerators (e.g. GPUs), etc. All
131 // names must be unique.
133 // A device property; see `properties` for more information.
135 // For general information on keys, see the documentation to `Worker`.
137 // The current set of standard keys are:
139 // * os: a human-readable description of the OS. Examples include `linux`,
140 // `ubuntu` and `ubuntu 14.04` (note that a bot may advertise itself as more
141 // than one). This will be replaced in the future by more well-structured
142 // keys and values to represent OS variants.
144 // * has-docker: "true" if the bot has Docker installed. This will be
145 // replaced in the future by a more structured message for Docker support.
148 // The property's value.
152 // The handle can be thought of as the "name" of the device, and must be
153 // unique within a Worker.
155 // In the Status context, the handle should be some human-understandable name,
156 // perhaps corresponding to a label physically written on the device to make
157 // it easy to locate. In the Request context, the name should be the
158 // *logical* name expected by the task. The bot is responsible for mapping the
159 // logical name expected by the task to a machine-readable name that the task
160 // can actually use, such as a USB address. The method by which this mapping
161 // is communicated to the task is not covered in this API.
164 // Properties of this device that don't change based on the tasks that are
165 // running on it, e.g. OS, CPU architecture, etc.
167 // Keys may be repeated, and have the following interpretation:
169 // * Status context: the device can support *any* the listed values. For
170 // example, an "ISA" property might include "x86", "x86-64" and "sse4".
172 // * Request context: the device *must* support *all* of the listed values.
173 repeated Property properties = 2;