Skip to content

Commit c440246

Browse files
author
Renaud Gaubert
committed
Added Device plugin API
Signed-off-by: Renaud Gaubert <[email protected]>
1 parent f6929fc commit c440246

File tree

3 files changed

+161
-0
lines changed

3 files changed

+161
-0
lines changed

‎hack/.golint_failures

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -233,6 +233,7 @@ pkg/kubelet
233233
pkg/kubelet/apis
234234
pkg/kubelet/apis/cri/testing
235235
pkg/kubelet/apis/cri/v1alpha1/runtime
236+
pkg/kubelet/apis/deviceplugin/v1alpha1
236237
pkg/kubelet/apis/kubeletconfig
237238
pkg/kubelet/apis/kubeletconfig/v1alpha1
238239
pkg/kubelet/cadvisor

‎pkg/kubelet/apis/deviceplugin/v1alpha1/api.proto

Lines changed: 127 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,127 @@
1+
// To regenerate api.pb.go run hack/update-device-plugin.sh
2+
syntax = 'proto3';
3+
4+
package deviceplugin;
5+
6+
import "github.com/gogo/protobuf/gogoproto/gogo.proto";
7+
8+
option (gogoproto.goproto_stringer_all) = false;
9+
option (gogoproto.stringer_all) = true;
10+
option (gogoproto.goproto_getters_all) = true;
11+
option (gogoproto.marshaler_all) = true;
12+
option (gogoproto.sizer_all) = true;
13+
option (gogoproto.unmarshaler_all) = true;
14+
option (gogoproto.goproto_unrecognized_all) = false;
15+
16+
17+
// Registration is the service advertised by the Kubelet
18+
// Only when Kubelet answers with a success code to a Register Request
19+
// may Device Plugins start their service
20+
// Registration may fail when device plugin version is not supported by
21+
// Kubelet or the registered resourceName is already taken by another
22+
// active device plugin. Device plugin is expected to terminate upon registration failure
23+
service Registration {
24+
rpc Register(RegisterRequest) returns (Empty) {}
25+
}
26+
27+
message RegisterRequest {
28+
// Version of the API the Device Plugin was built against
29+
string version = 1;
30+
// Name of the unix socket the device plugin is listening on
31+
// PATH = path.Join(DevicePluginPath, endpoint)
32+
string endpoint = 2;
33+
// Schedulable resource name. As of now it's expected to be a DNS Label
34+
string resource_name = 3;
35+
}
36+
37+
message Empty {
38+
}
39+
40+
// DevicePlugin is the service advertised by Device Plugins
41+
service DevicePlugin {
42+
// ListAndWatch returns a stream of List of Devices
43+
// Whenever a Device state change or a Device disapears, ListAndWatch
44+
// returns the new list
45+
rpc ListAndWatch(Empty) returns (stream ListAndWatchResponse) {}
46+
47+
// Allocate is called during container creation so that the Device
48+
// Plugin can run device specific operations and instruct Kubelet
49+
// of the steps to make the Device available in the container
50+
rpc Allocate(AllocateRequest) returns (AllocateResponse) {}
51+
}
52+
53+
// ListAndWatch returns a stream of List of Devices
54+
// Whenever a Device state change or a Device disapears, ListAndWatch
55+
// returns the new list
56+
message ListAndWatchResponse {
57+
repeated Device devices = 1;
58+
}
59+
60+
/* E.g:
61+
* struct Device {
62+
* ID: "GPU-fef8089b-4820-abfc-e83e-94318197576e",
63+
* State: "Healthy",
64+
*} */
65+
message Device {
66+
// A unique ID assigned by the device plugin used
67+
// to identify devices during the communication
68+
// Max length of this field is 63 characters
69+
string ID = 1;
70+
// Health of the device, can be healthy or unhealthy, see constants.go
71+
string health = 2;
72+
}
73+
74+
// - Allocate is expected to be called during pod creation since allocation
75+
// failures for any container would result in pod startup failure.
76+
// - Allocate allows kubelet to exposes additional artifacts in a pod's
77+
// environment as directed by the plugin.
78+
// - Allocate allows Device Plugin to run device specific operations on
79+
// the Devices requested
80+
message AllocateRequest {
81+
repeated string devicesIDs = 1;
82+
}
83+
84+
// Failure Handling:
85+
// if Kubelet sends an allocation request for dev1 and dev2.
86+
// Allocation on dev1 succeeds but allocation on dev2 fails.
87+
// The Device plugin should send a ListAndWatch update and fail the
88+
// Allocation request
89+
message AllocateResponse {
90+
repeated DeviceRuntimeSpec spec = 1;
91+
}
92+
93+
// The list to be added to the CRI spec
94+
message DeviceRuntimeSpec {
95+
// ID of the Device
96+
string ID = 1;
97+
// List of environment variable to set in the container.
98+
map<string, string> envs = 2;
99+
// Mounts for the container.
100+
repeated Mount mounts = 3;
101+
// Devices for the container
102+
repeated DeviceSpec devices = 4;
103+
}
104+
105+
// Mount specifies a host volume to mount into a container.
106+
// where device library or tools are installed on host and container
107+
message Mount {
108+
// Path of the mount within the container.
109+
string container_path = 1;
110+
// Path of the mount on the host.
111+
string host_path = 2;
112+
// If set, the mount is read-only.
113+
bool read_only = 3;
114+
}
115+
116+
// DeviceSpec specifies a host device to mount into a container.
117+
message DeviceSpec {
118+
// Path of the device within the container.
119+
string container_path = 1;
120+
// Path of the device on the host.
121+
string host_path = 2;
122+
// Cgroups permissions of the device, candidates are one or more of
123+
// * r - allows container to read from the specified device.
124+
// * w - allows container to write to the specified device.
125+
// * m - allows container to create device files that do not yet exist.
126+
string permissions = 3;
127+
}

‎pkg/kubelet/apis/deviceplugin/v1alpha1/constants.go

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
/*
2+
Copyright 2017 The Kubernetes Authors.
3+
4+
Licensed under the Apache License, Version 2.0 (the "License");
5+
you may not use this file except in compliance with the License.
6+
You may obtain a copy of the License at
7+
8+
http://www.apache.org/licenses/LICENSE-2.0
9+
10+
Unless required by applicable law or agreed to in writing, software
11+
distributed under the License is distributed on an "AS IS" BASIS,
12+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
See the License for the specific language governing permissions and
14+
limitations under the License.
15+
*/
16+
17+
package deviceplugin
18+
19+
const (
20+
// Healthy means that the device is healty
21+
Healthy = "Healthy"
22+
// UnHealthy means that the device is unhealty
23+
Unhealthy = "Unhealthy"
24+
25+
// Version is the API version
26+
Version = "0.1"
27+
// DevicePluginPath is the folder the Device Plugin is expecting sockets to be on
28+
// Only privileged pods have access to this path
29+
// Note: Placeholder until we find a "standard path"
30+
DevicePluginPath = "/var/lib/kubelet/device-plugins/"
31+
// KubeletSocket is the path of the Kubelet registry socket
32+
KubeletSocket = DevicePluginPath + "kubelet.sock"
33+
)

0 commit comments

Comments
 (0)