Move pkg/kubelet/pluginregistration and deviceplugin

Change-Id: I06adcb43bd278b430ffad2010869e1524c8cc4ff

Kubernetes-commit: d30c489c54c5e6d41ae3a1e1fcd96d24dba4fc51

pkg/apis/deviceplugin/OWNERS

@@ -0,0 +1,7 @@
+# See the OWNERS docs at https://go.k8s.io/owners
+
+reviewers:
+- jiayingz
+- mindprince
+- RenaudWasTaken
+- vishh

pkg/apis/deviceplugin/v1alpha/api.proto

@@ -0,0 +1,125 @@
+// To regenerate api.pb.go run hack/update-device-plugin.sh
+syntax = 'proto3';
+
+package deviceplugin;
+
+import "github.com/gogo/protobuf/gogoproto/gogo.proto";
+
+option (gogoproto.goproto_stringer_all) = false;
+option (gogoproto.stringer_all) =  true;
+option (gogoproto.goproto_getters_all) = true;
+option (gogoproto.marshaler_all) = true;
+option (gogoproto.sizer_all) = true;
+option (gogoproto.unmarshaler_all) = true;
+option (gogoproto.goproto_unrecognized_all) = false;
+
+
+// Registration is the service advertised by the Kubelet
+// Only when Kubelet answers with a success code to a Register Request
+// may Device Plugins start their service
+// Registration may fail when device plugin version is not supported by
+// Kubelet or the registered resourceName is already taken by another
+// active device plugin. Device plugin is expected to terminate upon registration failure
+service Registration {
+	rpc Register(RegisterRequest) returns (Empty) {}
+}
+
+message RegisterRequest {
+	// Version of the API the Device Plugin was built against
+	string version = 1;
+	// Name of the unix socket the device plugin is listening on
+	// PATH = path.Join(DevicePluginPath, endpoint)
+	string endpoint = 2;
+	// Schedulable resource name. As of now it's expected to be a DNS Label
+	string resource_name = 3;
+}
+
+message Empty {
+}
+
+// DevicePlugin is the service advertised by Device Plugins
+service DevicePlugin {
+	// ListAndWatch returns a stream of List of Devices
+	// Whenever a Device state changes or a Device disappears, ListAndWatch
+	// returns the new list
+	rpc ListAndWatch(Empty) returns (stream ListAndWatchResponse) {}
+
+	// Allocate is called during container creation so that the Device
+	// Plugin can run device specific operations and instruct Kubelet
+	// of the steps to make the Device available in the container
+	rpc Allocate(AllocateRequest) returns (AllocateResponse) {}
+}
+
+// ListAndWatch returns a stream of List of Devices
+// Whenever a Device state changes or a Device disappears, ListAndWatch
+// returns the new list
+message ListAndWatchResponse {
+	repeated Device devices = 1;
+}
+
+/* E.g:
+* struct Device {
+*    ID: "GPU-fef8089b-4820-abfc-e83e-94318197576e",
+*    State: "Healthy",
+*} */
+message Device {
+	// A unique ID assigned by the device plugin used
+	// to identify devices during the communication
+	// Max length of this field is 63 characters
+	string ID = 1;
+	// Health of the device, can be healthy or unhealthy, see constants.go
+	string health = 2;
+}
+
+// - Allocate is expected to be called during pod creation since allocation
+//   failures for any container would result in pod startup failure.
+// - Allocate allows kubelet to exposes additional artifacts in a pod's
+//   environment as directed by the plugin.
+// - Allocate allows Device Plugin to run device specific operations on
+//   the Devices requested
+message AllocateRequest {
+	repeated string devicesIDs = 1;
+}
+
+// AllocateResponse includes the artifacts that needs to be injected into
+// a container for accessing 'deviceIDs' that were mentioned as part of
+// 'AllocateRequest'.
+// Failure Handling:
+// if Kubelet sends an allocation request for dev1 and dev2.
+// Allocation on dev1 succeeds but allocation on dev2 fails.
+// The Device plugin should send a ListAndWatch update and fail the
+// Allocation request
+message AllocateResponse {
+  	// List of environment variable to be set in the container to access one of more devices.
+	map<string, string> envs = 1;
+	// Mounts for the container.
+	repeated Mount mounts = 2;
+	// Devices for the container.
+	repeated DeviceSpec devices = 3;
+	// Container annotations to pass to the container runtime
+	map<string, string> annotations = 4;
+}
+
+// Mount specifies a host volume to mount into a container.
+// where device library or tools are installed on host and container
+message Mount {
+	// Path of the mount within the container.
+	string container_path = 1;
+	// Path of the mount on the host.
+	string host_path = 2;
+	// If set, the mount is read-only.
+	bool read_only = 3;
+}
+
+// DeviceSpec specifies a host device to mount into a container.
+message DeviceSpec {
+    // Path of the device within the container.
+    string container_path = 1;
+    // Path of the device on the host.
+    string host_path = 2;
+    // Cgroups permissions of the device, candidates are one or more of
+    // * r - allows container to read from the specified device.
+    // * w - allows container to write to the specified device.
+    // * m - allows container to create device files that do not yet exist.
+    string permissions = 3;
+}

pkg/apis/deviceplugin/v1alpha/constants.go

@@ -0,0 +1,33 @@
+/*
+Copyright 2017 The Kubernetes Authors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package deviceplugin
+
+const (
+	// Healthy means that the device is healthy
+	Healthy = "Healthy"
+	// Unhealthy means that the device is unhealthy
+	Unhealthy = "Unhealthy"
+
+	// Version is the current version of the API supported by kubelet
+	Version = "v1alpha2"
+	// DevicePluginPath is the folder the Device Plugin is expecting sockets to be on
+	// Only privileged pods have access to this path
+	// Note: Placeholder until we find a "standard path"
+	DevicePluginPath = "/var/lib/kubelet/device-plugins/"
+	// KubeletSocket is the path of the Kubelet registry socket
+	KubeletSocket = DevicePluginPath + "kubelet.sock"
+)

pkg/apis/deviceplugin/v1beta1/api.proto

@@ -0,0 +1,174 @@
+// To regenerate api.pb.go run hack/update-device-plugin.sh
+syntax = 'proto3';
+
+package v1beta1;
+
+import "github.com/gogo/protobuf/gogoproto/gogo.proto";
+
+option (gogoproto.goproto_stringer_all) = false;
+option (gogoproto.stringer_all) =  true;
+option (gogoproto.goproto_getters_all) = true;
+option (gogoproto.marshaler_all) = true;
+option (gogoproto.sizer_all) = true;
+option (gogoproto.unmarshaler_all) = true;
+option (gogoproto.goproto_unrecognized_all) = false;
+
+
+// Registration is the service advertised by the Kubelet
+// Only when Kubelet answers with a success code to a Register Request
+// may Device Plugins start their service
+// Registration may fail when device plugin version is not supported by
+// Kubelet or the registered resourceName is already taken by another
+// active device plugin. Device plugin is expected to terminate upon registration failure
+service Registration {
+	rpc Register(RegisterRequest) returns (Empty) {}
+}
+
+message DevicePluginOptions {
+        // Indicates if PreStartContainer call is required before each container start
+	bool pre_start_required = 1;
+}
+
+message RegisterRequest {
+	// Version of the API the Device Plugin was built against
+	string version = 1;
+	// Name of the unix socket the device plugin is listening on
+	// PATH = path.Join(DevicePluginPath, endpoint)
+	string endpoint = 2;
+	// Schedulable resource name. As of now it's expected to be a DNS Label
+	string resource_name = 3;
+        // Options to be communicated with Device Manager
+        DevicePluginOptions options = 4;
+}
+
+message Empty {
+}
+
+// DevicePlugin is the service advertised by Device Plugins
+service DevicePlugin {
+	// GetDevicePluginOptions returns options to be communicated with Device
+        // Manager
+	rpc GetDevicePluginOptions(Empty) returns (DevicePluginOptions) {}
+
+	// ListAndWatch returns a stream of List of Devices
+	// Whenever a Device state change or a Device disappears, ListAndWatch
+	// returns the new list
+	rpc ListAndWatch(Empty) returns (stream ListAndWatchResponse) {}
+
+	// Allocate is called during container creation so that the Device
+	// Plugin can run device specific operations and instruct Kubelet
+	// of the steps to make the Device available in the container
+	rpc Allocate(AllocateRequest) returns (AllocateResponse) {}
+
+        // PreStartContainer is called, if indicated by Device Plugin during registeration phase,
+        // before each container start. Device plugin can run device specific operations
+        // such as reseting the device before making devices available to the container
+	rpc PreStartContainer(PreStartContainerRequest) returns (PreStartContainerResponse) {}
+}
+
+// ListAndWatch returns a stream of List of Devices
+// Whenever a Device state change or a Device disappears, ListAndWatch
+// returns the new list
+message ListAndWatchResponse {
+	repeated Device devices = 1;
+}
+
+message TopologyInfo {
+	repeated NUMANode nodes = 1;
+}
+
+message NUMANode {
+    int64 ID = 1;
+}
+
+/* E.g:
+* struct Device {
+*    ID: "GPU-fef8089b-4820-abfc-e83e-94318197576e",
+*    State: "Healthy",
+*    Topology: 
+*      Node: 
+         ID: 1 
+*} */
+message Device {
+	// A unique ID assigned by the device plugin used
+	// to identify devices during the communication
+	// Max length of this field is 63 characters
+	string ID = 1;
+	// Health of the device, can be healthy or unhealthy, see constants.go
+	string health = 2;
+	// Topology for device
+	TopologyInfo topology = 3;
+}
+
+// - PreStartContainer is expected to be called before each container start if indicated by plugin during registration phase.
+// - PreStartContainer allows kubelet to pass reinitialized devices to containers.
+// - PreStartContainer allows Device Plugin to run device specific operations on
+//   the Devices requested
+message PreStartContainerRequest {
+        repeated string devicesIDs = 1;
+}
+
+// PreStartContainerResponse will be send by plugin in response to PreStartContainerRequest
+message PreStartContainerResponse {
+}
+
+// - Allocate is expected to be called during pod creation since allocation
+//   failures for any container would result in pod startup failure.
+// - Allocate allows kubelet to exposes additional artifacts in a pod's
+//   environment as directed by the plugin.
+// - Allocate allows Device Plugin to run device specific operations on
+//   the Devices requested
+message AllocateRequest {
+	repeated ContainerAllocateRequest container_requests = 1;
+}
+
+message ContainerAllocateRequest {
+	repeated string devicesIDs = 1;
+}
+
+// AllocateResponse includes the artifacts that needs to be injected into
+// a container for accessing 'deviceIDs' that were mentioned as part of
+// 'AllocateRequest'.
+// Failure Handling:
+// if Kubelet sends an allocation request for dev1 and dev2.
+// Allocation on dev1 succeeds but allocation on dev2 fails.
+// The Device plugin should send a ListAndWatch update and fail the
+// Allocation request
+message AllocateResponse {
+	repeated ContainerAllocateResponse container_responses = 1;
+}
+
+message ContainerAllocateResponse {
+  	// List of environment variable to be set in the container to access one of more devices.
+	map<string, string> envs = 1;
+	// Mounts for the container.
+	repeated Mount mounts = 2;
+	// Devices for the container.
+	repeated DeviceSpec devices = 3;
+	// Container annotations to pass to the container runtime
+	map<string, string> annotations = 4;
+}
+
+// Mount specifies a host volume to mount into a container.
+// where device library or tools are installed on host and container
+message Mount {
+	// Path of the mount within the container.
+	string container_path = 1;
+	// Path of the mount on the host.
+	string host_path = 2;
+	// If set, the mount is read-only.
+	bool read_only = 3;
+}
+
+// DeviceSpec specifies a host device to mount into a container.
+message DeviceSpec {
+    // Path of the device within the container.
+    string container_path = 1;
+    // Path of the device on the host.
+    string host_path = 2;
+    // Cgroups permissions of the device, candidates are one or more of
+    // * r - allows container to read from the specified device.
+    // * w - allows container to write to the specified device.
+    // * m - allows container to create device files that do not yet exist.
+    string permissions = 3;
+}

pkg/apis/deviceplugin/v1beta1/constants.go

@@ -0,0 +1,37 @@
+/*
+Copyright 2018 The Kubernetes Authors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package v1beta1
+
+const (
+	// Healthy means that the device is healthy
+	Healthy = "Healthy"
+	// UnHealthy means that the device is unhealthy
+	Unhealthy = "Unhealthy"
+
+	// Current version of the API supported by kubelet
+	Version = "v1beta1"
+	// DevicePluginPath is the folder the Device Plugin is expecting sockets to be on
+	// Only privileged pods have access to this path
+	// Note: Placeholder until we find a "standard path"
+	DevicePluginPath = "/var/lib/kubelet/device-plugins/"
+	// KubeletSocket is the path of the Kubelet registry socket
+	KubeletSocket = DevicePluginPath + "kubelet.sock"
+	// Timeout duration in secs for PreStartContainer RPC
+	KubeletPreStartContainerRPCTimeoutInSecs = 30
+)
+
+var SupportedVersions = [...]string{"v1beta1"}

pkg/apis/pluginregistration/v1/api.proto

@@ -0,0 +1,60 @@
+// To regenerate api.pb.go run hack/update-generated-kubelet-plugin-registration.sh
+syntax = 'proto3';
+
+package pluginregistration;
+
+import "github.com/gogo/protobuf/gogoproto/gogo.proto";
+
+option (gogoproto.goproto_stringer_all) = false;
+option (gogoproto.stringer_all) =  true;
+option (gogoproto.goproto_getters_all) = true;
+option (gogoproto.marshaler_all) = true;
+option (gogoproto.sizer_all) = true;
+option (gogoproto.unmarshaler_all) = true;
+option (gogoproto.goproto_unrecognized_all) = false;
+
+// PluginInfo is the message sent from a plugin to the Kubelet pluginwatcher for plugin registration
+message PluginInfo {
+	// Type of the Plugin. CSIPlugin or DevicePlugin
+	string type = 1;
+	// Plugin name that uniquely identifies the plugin for the given plugin type.
+	// For DevicePlugin, this is the resource name that the plugin manages and
+	// should follow the extended resource name convention.
+	// For CSI, this is the CSI driver registrar name.
+	string name = 2;
+	// Optional endpoint location. If found set by Kubelet component,
+	// Kubelet component will use this endpoint for specific requests.
+	// This allows the plugin to register using one endpoint and possibly use
+	// a different socket for control operations. CSI uses this model to delegate
+	// its registration external from the plugin.
+	string endpoint = 3;
+	// Plugin service API versions the plugin supports.
+	// For DevicePlugin, this maps to the deviceplugin API versions the
+	// plugin supports at the given socket.
+	// The Kubelet component communicating with the plugin should be able
+	// to choose any preferred version from this list, or returns an error
+	// if none of the listed versions is supported.
+	repeated string supported_versions = 4;
+}
+
+// RegistrationStatus is the message sent from Kubelet pluginwatcher to the plugin for notification on registration status
+message RegistrationStatus {
+	// True if plugin gets registered successfully at Kubelet
+	bool plugin_registered  = 1;
+	// Error message in case plugin fails to register, empty string otherwise
+	string error  = 2;
+}
+
+// RegistrationStatusResponse is sent by plugin to kubelet in response to RegistrationStatus RPC
+message RegistrationStatusResponse {
+}
+
+// InfoRequest is the empty request message from Kubelet
+message InfoRequest {
+}
+
+// Registration is the service advertised by the Plugins.
+service Registration {
+	rpc GetInfo(InfoRequest) returns (PluginInfo) {}
+	rpc NotifyRegistrationStatus(RegistrationStatus) returns (RegistrationStatusResponse) {}
+}

pkg/apis/pluginregistration/v1/constants.go

@@ -0,0 +1,24 @@
+/*
+Copyright 2018 The Kubernetes Authors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package pluginregistration
+
+const (
+	// CSIPlugin identifier for registered CSI plugins
+	CSIPlugin = "CSIPlugin"
+	// DevicePlugin identifier for registered device plugins
+	DevicePlugin = "DevicePlugin"
+)

pkg/apis/pluginregistration/v1alpha1/api.proto

@@ -0,0 +1,60 @@
+// To regenerate api.pb.go run hack/update-generated-kubelet-plugin-registration.sh
+syntax = 'proto3';
+
+package pluginregistration;
+
+import "github.com/gogo/protobuf/gogoproto/gogo.proto";
+
+option (gogoproto.goproto_stringer_all) = false;
+option (gogoproto.stringer_all) =  true;
+option (gogoproto.goproto_getters_all) = true;
+option (gogoproto.marshaler_all) = true;
+option (gogoproto.sizer_all) = true;
+option (gogoproto.unmarshaler_all) = true;
+option (gogoproto.goproto_unrecognized_all) = false;
+
+// PluginInfo is the message sent from a plugin to the Kubelet pluginwatcher for plugin registration
+message PluginInfo {
+	// Type of the Plugin. CSIPlugin or DevicePlugin
+	string type = 1;
+	// Plugin name that uniquely identifies the plugin for the given plugin type.
+	// For DevicePlugin, this is the resource name that the plugin manages and
+	// should follow the extended resource name convention.
+	// For CSI, this is the CSI driver registrar name.
+	string name = 2;
+	// Optional endpoint location. If found set by Kubelet component,
+	// Kubelet component will use this endpoint for specific requests.
+	// This allows the plugin to register using one endpoint and possibly use
+	// a different socket for control operations. CSI uses this model to delegate
+	// its registration external from the plugin.
+	string endpoint = 3;
+	// Plugin service API versions the plugin supports.
+	// For DevicePlugin, this maps to the deviceplugin API versions the
+	// plugin supports at the given socket.
+	// The Kubelet component communicating with the plugin should be able
+	// to choose any preferred version from this list, or returns an error
+	// if none of the listed versions is supported.
+	repeated string supported_versions = 4;
+}
+
+// RegistrationStatus is the message sent from Kubelet pluginwatcher to the plugin for notification on registration status
+message RegistrationStatus {
+	// True if plugin gets registered successfully at Kubelet
+	bool plugin_registered  = 1;
+	// Error message in case plugin fails to register, empty string otherwise
+	string error  = 2;
+}
+
+// RegistrationStatusResponse is sent by plugin to kubelet in response to RegistrationStatus RPC
+message RegistrationStatusResponse {
+}
+
+// InfoRequest is the empty request message from Kubelet
+message InfoRequest {
+}
+
+// Registration is the service advertised by the Plugins.
+service Registration {
+	rpc GetInfo(InfoRequest) returns (PluginInfo) {}
+	rpc NotifyRegistrationStatus(RegistrationStatus) returns (RegistrationStatusResponse) {}
+}

pkg/apis/pluginregistration/v1alpha1/constants.go

@@ -0,0 +1,24 @@
+/*
+Copyright 2018 The Kubernetes Authors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package pluginregistration
+
+const (
+	// CSIPlugin identifier for registered CSI plugins
+	CSIPlugin = "CSIPlugin"
+	// DevicePlugin identifier for registered device plugins
+	DevicePlugin = "DevicePlugin"
+)

pkg/apis/pluginregistration/v1beta1/api.proto

@@ -0,0 +1,60 @@
+// To regenerate api.pb.go run hack/update-generated-kubelet-plugin-registration.sh
+syntax = 'proto3';
+
+package pluginregistration;
+
+import "github.com/gogo/protobuf/gogoproto/gogo.proto";
+
+option (gogoproto.goproto_stringer_all) = false;
+option (gogoproto.stringer_all) =  true;
+option (gogoproto.goproto_getters_all) = true;
+option (gogoproto.marshaler_all) = true;
+option (gogoproto.sizer_all) = true;
+option (gogoproto.unmarshaler_all) = true;
+option (gogoproto.goproto_unrecognized_all) = false;
+
+// PluginInfo is the message sent from a plugin to the Kubelet pluginwatcher for plugin registration
+message PluginInfo {
+	// Type of the Plugin. CSIPlugin or DevicePlugin
+	string type = 1;
+	// Plugin name that uniquely identifies the plugin for the given plugin type.
+	// For DevicePlugin, this is the resource name that the plugin manages and
+	// should follow the extended resource name convention.
+	// For CSI, this is the CSI driver registrar name.
+	string name = 2;
+	// Optional endpoint location. If found set by Kubelet component,
+	// Kubelet component will use this endpoint for specific requests.
+	// This allows the plugin to register using one endpoint and possibly use
+	// a different socket for control operations. CSI uses this model to delegate
+	// its registration external from the plugin.
+	string endpoint = 3;
+	// Plugin service API versions the plugin supports.
+	// For DevicePlugin, this maps to the deviceplugin API versions the
+	// plugin supports at the given socket.
+	// The Kubelet component communicating with the plugin should be able
+	// to choose any preferred version from this list, or returns an error
+	// if none of the listed versions is supported.
+	repeated string supported_versions = 4;
+}
+
+// RegistrationStatus is the message sent from Kubelet pluginwatcher to the plugin for notification on registration status
+message RegistrationStatus {
+	// True if plugin gets registered successfully at Kubelet
+	bool plugin_registered  = 1;
+	// Error message in case plugin fails to register, empty string otherwise
+	string error  = 2;
+}
+
+// RegistrationStatusResponse is sent by plugin to kubelet in response to RegistrationStatus RPC
+message RegistrationStatusResponse {
+}
+
+// InfoRequest is the empty request message from Kubelet
+message InfoRequest {
+}
+
+// Registration is the service advertised by the Plugins.
+service Registration {
+	rpc GetInfo(InfoRequest) returns (PluginInfo) {}
+	rpc NotifyRegistrationStatus(RegistrationStatus) returns (RegistrationStatusResponse) {}
+}

pkg/apis/pluginregistration/v1beta1/constants.go

@@ -0,0 +1,24 @@
+/*
+Copyright 2018 The Kubernetes Authors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package pluginregistration
+
+const (
+	// CSIPlugin identifier for registered CSI plugins
+	CSIPlugin = "CSIPlugin"
+	// DevicePlugin identifier for registered device plugins
+	DevicePlugin = "DevicePlugin"
+)