driver/base: Add initial protobuf spec

plugins/drivers/base/proto/driver.proto

@@ -0,0 +1,403 @@
+syntax = "proto3";
+package hashicorp.nomad.plugins.drivers.base.proto;
+option go_package = "proto";
+
+import "google/protobuf/empty.proto";
+import "google/protobuf/duration.proto";
+import "google/protobuf/timestamp.proto";
+
+// Driver service defines RPCs used to communicate with a nomad runtime driver.
+// Some rpcs may not be implemented by the driver based on it's capabilities.
+service Driver {
+
+    // Fingerprint collects information about the driver including whether the
+    // driver is able to function in the existing environment.
+    rpc Fingerprint(google.protobuf.Empty) returns (FingerprintResponse) {}
+
+    // RecoverTask is used when a task has been started but the driver may not
+    // know about it. Such is the case if the driver restarts or is upgraded.
+    rpc RecoverTask(RecoverTaskRequest) returns (google.protobuf.Empty) {}
+
+    // StartTask starts and tracks the task on the implemented runtime
+    rpc StartTask(StartTaskRequest) returns (StartTaskResponse) {}
+
+    // WaitTask blocks until the given task exits, returning the result of the
+    // task. It may be called after the task has exited, but before the task is
+    // destroyed.
+	rpc WaitTask(WaitTaskRequest) returns (WaitTaskResponse) {}
+
+    // StopTask stops a given task by sending the desired signal to the process.
+    // If the task does not exit on its own within the given timeout, it will be
+    // forcefully killed.
+    rpc StopTask(StopTaskRequest) returns (google.protobuf.Empty) {}
+
+    // DestroyTask removes the task from the driver's internal state. It cannot
+    // be called on a running task.
+    rpc DestroyTask(DestroyTaskRequest)  returns (google.protobuf.Empty) {}
+
+    // ListTasks returns a list of summary information of all the tasks the
+    // driver is tracking.
+    rpc ListTasks(ListTasksRequest) returns (ListTasksResponse) {}
+
+    // InspectTask returns detailed information for the given task
+    rpc InspectTask(InspectTaskRequest) returns (InspectTaskResponse) {}
+
+    // TaskStats collects and returns runtime metrics for the given task
+    rpc TaskStats(TaskStatsRequest) returns (TaskStatsResponse) {}
+
+    // The following RPCs are only implemented if the driver sets the
+    // corresponding capability.
+
+    // SignalTask sends a signal to the task
+    rpc SignalTask(SignalTaskRequest) returns (google.protobuf.Empty) {}
+
+    // ExecTask executes a command inside the tasks execution context
+    rpc ExecTask(ExecTaskRequest) returns (ExecTaskResponse) {}
+}
+
+
+message FingerprintResponse {
+
+    // Capabilities provides a way for the driver to denote if it implements
+    // non-core RPCs. Some Driver service RPCs expose additional information
+    // or functionality outside of the core task management functions. These
+    // RPCs are only implemented if the driver sets the corresponding capability.
+    DriverCapabilities capabilities = 1;
+
+    // Attributes are key/value pairs that annotate the nomad client and can be
+    // used in scheduling contraints and affinities.
+    map<string, string> attributes = 2;
+
+    // Detected signifies if the necessary dependancies of the drive are met for
+    // nominal operation.
+    bool detected = 3;
+}
+
+message RecoverTaskRequest {
+
+    // TaskId is the ID of the target task
+    string task_id = 1;
+
+    // Handle is the TaskHandle returned from StartTask
+    TaskHandle handle = 2;
+}
+
+message StartTaskRequest {
+
+    // Task configuration to launch
+    TaskConfig task = 1;
+}
+
+message StartTaskResponse {
+
+    // Handle is opague to the client, but must be stored in order to potentially
+    // recover the task.
+    TaskHandle handle = 1;
+}
+
+message WaitTaskRequest {
+
+    // TaskId is the ID of the target task
+    string task_id = 1;
+}
+
+message WaitTaskResponse {
+
+    // ExitCode returned from the task on exit
+    int32 exit_code = 1;
+
+    // Signal is set if a signal was sent to the task
+    int32 signal = 2;
+
+    // Err is set if any driver error occured while waiting for the task
+    string err = 3;
+}
+
+message StopTaskRequest {
+
+    // TaskId is the ID of the target task
+    string task_id = 1;
+
+    // Timeout defines the amount of time to wait before forcefully killing
+    // the task. For example, on Unix clients, this means sending a SIGKILL to
+    // the process.
+    google.protobuf.Duration timeout = 2;
+
+    // Signal can be set to override the Task's configured shutdown signal
+    string signal = 3;
+}
+
+message DestroyTaskRequest {
+
+    // TaskId is the ID of the target task
+    string task_id = 1;
+}
+
+message ListTasksRequest {}
+
+message ListTasksResponse {
+
+    // Tasks includes a list of summary information for each task
+    repeated TaskSummary tasks = 1;
+}
+
+message InspectTaskRequest {
+
+    // TaskId is the ID of the target task
+    string task_id = 1;
+}
+
+message InspectTaskResponse {
+
+    // Task details
+    TaskStatus task = 1;
+}
+
+message TaskStatsRequest {
+
+    // TaskId is the ID of the target task
+    string task_id = 1;
+}
+
+message TaskStatsResponse {
+
+    // Stats for the task
+    TaskStats stats = 1;
+}
+
+message SignalTaskRequest {
+
+    // TaskId is the ID of the target task
+    string task_id = 1;
+
+    // Signal is the operating system signal to send to the task. Ex: SIGHUP
+    string signal = 2;
+}
+
+message ExecTaskRequest {
+
+    // TaskId is the ID of the target task
+    string task_id = 1;
+
+    // Command is the command to execute in the task environment
+    repeated string command = 2;
+
+    // Timeout is the amount of time to wait for the command to stop.
+    // Defaults to 0 (run forever)
+    google.protobuf.Duration timeout = 3;
+}
+
+message ExecTaskResponse {}
+
+message DriverCapabilities {
+
+    // SendSignals indicates that the driver can send process signals (ex. SIGUSR1)
+    // to the task.
+    bool send_signals = 1;
+
+    // Exec indicates that the driver supports executing arbitrary commands
+    // in the task's execution environment.
+    bool exec = 2;
+}
+
+message TaskConfig {
+
+    // Id of the task, recommended to the globally unique, must be unique to the driver.
+    // If not set, a UUID is to be generated.
+    string id = 1;
+
+    // Name of the task
+    string name = 2;
+
+    // MsgpackDriverConfig is the encoded driver configuation of the task
+    bytes msgpack_driver_config = 3;
+
+    // Env is the a set of key/value pairs to be set as environment variables
+    map<string, string> env = 4;
+
+    // Resources defines the resources to isolate
+    Resources resources = 5;
+
+    // Mounts is a list of targets to bind mount into the task directory
+    repeated Mount mounts = 6;
+
+    // Devices is a list of system devices to mount into the task's execution
+    // environment.
+    repeated Device devices = 7;
+
+    // User defines the operating system user the tasks should run as
+    string user = 8;
+
+    // AllocDir is the directory on the host where the allocation directory
+    // exists.
+    string alloc_dir = 9;
+}
+
+message Resources {
+    // CPU CFS (Completely Fair Scheduler) period. Default: 0 (not specified)
+    int64 cpu_period = 1;
+    // CPU CFS (Completely Fair Scheduler) quota. Default: 0 (not specified)
+    int64 cpu_quota = 2;
+    // CPU shares (relative weight vs. other containers). Default: 0 (not specified)
+    int64 cpu_shares = 3;
+    // Memory limit in bytes. Default: 0 (not specified)
+    int64 memory_limit_in_bytes = 4;
+    // OOMScoreAdj adjusts the oom-killer score. Default: 0 (not specified)
+    int64 oom_score_adj = 5;
+    // CpusetCpus constrains the allowed set of logical CPUs. Default: "" (not specified)
+    string cpuset_cpus = 6;
+    // CpusetMems constrains the allowed set of memory nodes. Default: "" (not specified)
+    string cpuset_mems = 7;
+}
+
+message Mount {
+
+    // TaskPath is the file path within the task directory to mount to
+    string task_path = 1;
+
+    // HostPath is the file path on the host to mount from
+    string host_path = 2;
+
+    // Readonly if set true, mounts the path in readonly mode
+    bool readonly = 3;
+}
+
+message Device {
+
+    // TaskPath is the file path within the task to mount the device to
+    string task_path = 1;
+
+    // HostPath is the path on the host to the source device
+    string host_path = 2;
+
+    // Permissions defines the Cgroup permissions of the device.
+    // One or more of the following options can be set:
+    //  * r - allows the task to read from the specified device.
+    //  * w - allows the task to write to the specified device.
+    //  * m - allows the task to create device files that do not yet exist.
+    //
+    // Example: "rw"
+    string permissions = 3;
+}
+
+enum TaskState {
+    TASK_UNKNOWN = 0;
+    TASK_RUNNING = 1;
+    TASK_EXITED = 2;
+}
+
+// TaskHandle is created when starting a task and is used to recover task
+message TaskHandle {
+
+    // Driver is the driver which initially created the handle
+    string driver = 1;
+
+    // Config is the TaskConfig for the task
+    TaskConfig config = 2;
+
+    // State is the state of the task's execution
+    TaskState state = 3;
+
+    // DriverState is the encoded state for the specific driver
+    bytes driver_state = 4;
+}
+
+
+// TaskSummary defines summary information of a task, typically used when listing
+// many tasks at once.
+message TaskSummary {
+    string id = 1;
+    string name = 2;
+
+    // State is the state of the task's execution
+    TaskState state = 3;
+
+    // StartedAt is the timestamp when the task was started
+    google.protobuf.Timestamp started_at = 4;
+}
+
+// TaskStatus includes detailed information of a specific task
+message TaskStatus {
+    string id = 1;
+    string name = 2;
+
+    // State is the state of the task's execution
+    TaskState state = 3;
+
+    // StartedAt is the timestamp when the task was started
+    google.protobuf.Timestamp started_at = 4;
+
+    // CompletedAt is the timestamp when the task exited.
+    // If the task is still running, CompletedAt will not be set
+    google.protobuf.Timestamp completed_at = 5;
+
+    // ExitCode should only be used when CompletedAt is set.
+    int32 exit_code = 6;
+
+    // DriverStatus is a set of string/string key value pairs specific to the
+    // implementing driver.
+    map<string, string> driver_status = 7;
+}
+
+message TaskStats {
+
+    // Id of the task
+    string id = 1;
+
+    // Timestamp for which the stats were collected
+    google.protobuf.Timestamp timestamp = 2;
+
+    // AggResourceUsage is the aggreate usage of all processes
+    TaskResourceUsage agg_resource_usage = 3;
+
+    // ResourceUsageByPid breaks the usage stats by process
+    map<string, TaskResourceUsage> resource_usage_by_pid = 4;
+}
+
+message TaskResourceUsage {
+
+    // CPU usage stats
+    CPUUsage cpu = 1;
+
+    // Memory usage stats
+    MemoryUsage memory = 2;
+}
+
+message CPUUsage {
+
+    double system_mode = 1;
+    double user_mode = 2;
+    double total_ticks = 3;
+    uint64 throttled_periods = 4;
+    uint64 throttled_time = 5;
+    double percent = 6;
+
+    enum Fields {
+        SYSTEM_MODE = 0;
+        USER_MODE = 1;
+        TOTAL_TICKS = 2;
+        THROTTLED_PERIODS = 3;
+        THROTTLED_TIME = 4;
+        PERCENT = 5;
+    }
+    // MeasuredFields indicates which fields were actually sampled
+    repeated Fields measured_fields = 7;
+}
+
+message MemoryUsage {
+    uint64 rss = 1;
+    uint64 cache = 2;
+    uint64 max_usage = 3;
+    uint64 kernel_usage = 4;
+    uint64 kernel_max_usage = 5;
+
+    enum Fields {
+        RSS = 0;
+        CACHE = 1;
+        MAX_UASGE = 2;
+        KERNEL_USAGE = 3;
+        KERNEL_MAX_USAGE = 4;
+    }
+    // MeasuredFields indicates which fields were actually sampled
+    repeated Fields measured_fields = 6;
+}