1// Copyright 2019 Google LLC. 2// 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 6// 7// http://www.apache.org/licenses/LICENSE-2.0 8// 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. 14// 15 16syntax = "proto3"; 17 18package google.devtools.remoteworkers.v1test2; 19 20option csharp_namespace = "Google.DevTools.RemoteWorkers.V1Test2"; 21option go_package = "google.golang.org/genproto/googleapis/devtools/remoteworkers/v1test2;remoteworkers"; 22option java_multiple_files = true; 23option java_outer_classname = "RemoteWorkersWorker"; 24option java_package = "com.google.devtools.remoteworkers.v1test2"; 25option php_namespace = "Google\\Cloud\\Remoteworkers\\V1test2"; 26option objc_class_prefix = "RW"; 27 28// Describes a worker, which is a list of one or more devices and the 29// connections between them. A device could be a computer, a phone, or even an 30// accelerator like a GPU; it's up to the farm administrator to decide how to 31// model their farm. For example, if a farm only has one type of GPU, the GPU 32// could be modelled as a "has_gpu" property on its host computer; if it has 33// many subproperties itself, it might be better to model it as a separate 34// device. 35// 36// The first device in the worker is the "primary device" - that is, the device 37// running a bot and which is responsible for actually executing commands. All 38// other devices are considered to be attached devices, and must be controllable 39// by the primary device. 40// 41// This message (and all its submessages) can be used in two contexts: 42// 43// * Status: sent by the bot to report the current capabilities of the device to 44// allow reservation matching. 45// * Request: sent by a client to request a device with certain capabilities in 46// a reservation. 47// 48// Several of the fields in this message have different semantics depending on 49// which of which of these contexts it is used. These semantics are described 50// below. 51// 52// Several messages in Worker and its submessages have the concept of keys and 53// values, such as `Worker.Property` and `Device.Property`. All keys are simple 54// strings, but certain keys are "standard" keys and should be broadly supported 55// across farms and implementations; these are listed below each relevant 56// message. Bot implementations or farm admins may add *additional* keys, but 57// these SHOULD all begin with an underscore so they do not conflict with 58// standard keys that may be added in the future. 59// 60// Keys are not context sensitive. 61// 62// See http://goo.gl/NurY8g for more information on the Worker message. 63message Worker { 64 // A global property; see the `properties` field for more information. 65 message Property { 66 // For general information on keys, see the documentation to `Worker`. 67 // 68 // The current set of standard keys are: 69 // 70 // * pool: different workers can be reserved for different purposes. For 71 // example, an admin might want to segregate long-running integration tests 72 // from short-running unit tests, so unit tests will always get some 73 // throughput. To support this, the server can assign different values for 74 // `pool` (such as "itest" and "utest") to different workers, and then have 75 // jobs request workers from those pools. 76 string key = 1; 77 78 // The property's value. 79 string value = 2; 80 } 81 82 // A configuration request or report; see the `configs` field for more 83 // information. 84 message Config { 85 // For general information on keys, see the documentation to `Worker`. 86 // 87 // The current set of standard keys are: 88 // 89 // * DockerImage: the image of the container. When being reported by the 90 // bot, the empty value should always be included if the bot is able to pull 91 // its own images; the bot may optionally *also* report images that are 92 // present in its cache. When being requested in a lease, the value is the 93 // URI of the image (eg `gcr.io/user/image@sha256:hash`). 94 string key = 1; 95 96 // The configuration's value. 97 string value = 2; 98 } 99 100 // A list of devices; the first device is the primary device. See the `Device` 101 // message for more information. 102 repeated Device devices = 1; 103 104 // A worker may contain "global" properties. For example, certain machines 105 // might be reserved for certain types of jobs, like short-running compilation 106 // versus long-running integration tests. This property is known as a "pool" 107 // and is not related to any one device within the worker; rather, it applies 108 // to the worker as a whole. 109 // 110 // The behaviour of repeated keys is identical to that of Device.Property. 111 repeated Property properties = 2; 112 113 // Bots can be configured in certain ways when accepting leases. For example, 114 // many leases are executed inside a Docker container. To support this, the 115 // bot needs to be able to report that it has Docker installed (and knows how 116 // to execute something inside a container), and the task submitter needs to 117 // specify which image should be used to start the container. Similarly, a 118 // lease may be able to run as one of several users on the worker; in such 119 // cases, the bot needs to report what users are available, and the submitter 120 // needs to choose one. 121 // 122 // Therefore, when this message is reported by the bot to the service, each 123 // key represents a *type* of configuration that the bot knows how to set, 124 // while each *value* represents a legal value for that configuration (the 125 // empty string is interpretted as a wildcard, such as for Docker images). 126 // When this message is sent by the server to the bot in the context of a 127 // lease, it represents a command to the bot to apply the setting. Keys may 128 // be repeated during reporting but not in a lease. 129 repeated Config configs = 3; 130} 131 132// Any device, including computers, phones, accelerators (e.g. GPUs), etc. All 133// names must be unique. 134message Device { 135 // A device property; see `properties` for more information. 136 message Property { 137 // For general information on keys, see the documentation to `Worker`. 138 // 139 // The current set of standard keys are: 140 // 141 // * os: a human-readable description of the OS. Examples include `linux`, 142 // `ubuntu` and `ubuntu 14.04` (note that a bot may advertise itself as more 143 // than one). This will be replaced in the future by more well-structured 144 // keys and values to represent OS variants. 145 // 146 // * has-docker: "true" if the bot has Docker installed. This will be 147 // replaced in the future by a more structured message for Docker support. 148 string key = 1; 149 150 // The property's value. 151 string value = 2; 152 } 153 154 // The handle can be thought of as the "name" of the device, and must be 155 // unique within a Worker. 156 // 157 // In the Status context, the handle should be some human-understandable name, 158 // perhaps corresponding to a label physically written on the device to make 159 // it easy to locate. In the Request context, the name should be the 160 // *logical* name expected by the task. The bot is responsible for mapping the 161 // logical name expected by the task to a machine-readable name that the task 162 // can actually use, such as a USB address. The method by which this mapping 163 // is communicated to the task is not covered in this API. 164 string handle = 1; 165 166 // Properties of this device that don't change based on the tasks that are 167 // running on it, e.g. OS, CPU architecture, etc. 168 // 169 // Keys may be repeated, and have the following interpretation: 170 // 171 // * Status context: the device can support *any* the listed values. For 172 // example, an "ISA" property might include "x86", "x86-64" and "sse4". 173 // 174 // * Request context: the device *must* support *all* of the listed values. 175 repeated Property properties = 2; 176} 177