open-nomad/plugins/drivers/base/proto/driver.proto

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";

import "github.com/hashicorp/nomad/plugins/shared/hclspec/hcl_spec.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 and cleans
    // up any additional resources created by the driver. 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) {}

    // TaskEvents starts a streaming RPC where all task events emitted by the
    // driver are streamed to the caller.
    rpc TaskEvents(google.protobuf.Empty) returns (stream TaskEvent) {}

    // 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 {

    // Spec is the configuration schema for the job driver config stanza
    hashicorp.nomad.plugins.shared.hclspec.Spec spec = 1;

    // 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 = 2;

    // Attributes are key/value pairs that annotate the nomad client and can be
    // used in scheduling contraints and affinities.
    map<string, string> attributes = 3;

    // Detected signifies if the necessary dependancies of the drive are met for
    // nominal operation.
    bool detected = 4;
}

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 {
    UNKNOWN = 0;
    RUNNING = 1;
    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;
}

message TaskEvent {

    // TaskId is the id of the task for the event
    string task_id = 1;

    // Message is the body of the event
    string message = 2;

    // Annotations allows for additional key/value data to be sent along with the event
    map<string,string> annotations = 3;
}