api.proto 4.4 KB

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