1e3c3cb287
IOPS have been modelled as a resource since Nomad 0.1 but has never actually been detected and there is no plan in the short term to add detection. This is because IOPS is a bit simplistic of a unit to define the performance requirements from the underlying storage system. In its current state it adds unnecessary confusion and can be removed without impacting any users. This PR leaves IOPS defined at the jobspec parsing level and in the api/ resources since these are the two public uses of the field. These should be considered deprecated and only exist to allow users to stop using them during the Nomad 0.9.x release. In the future, there should be no expectation that the field will exist.
577 lines
16 KiB
Protocol Buffer
577 lines
16 KiB
Protocol Buffer
syntax = "proto3";
|
|
package hashicorp.nomad.plugins.drivers.proto;
|
|
option go_package = "proto";
|
|
|
|
import "google/protobuf/duration.proto";
|
|
import "google/protobuf/timestamp.proto";
|
|
|
|
import "github.com/hashicorp/nomad/plugins/shared/hclspec/hcl_spec.proto";
|
|
import "github.com/hashicorp/nomad/plugins/shared/structs/proto/attribute.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 {
|
|
|
|
// TaskConfigSchema returns the schema for parsing the driver
|
|
// configuration of a task.
|
|
rpc TaskConfigSchema(TaskConfigSchemaRequest) returns (TaskConfigSchemaResponse) {}
|
|
|
|
// Capabilities returns a set of features which the driver implements. Some
|
|
// RPCs are not possible to implement on some runtimes, this allows the
|
|
// driver to indicate if it doesn't support these RPCs and features.
|
|
rpc Capabilities(CapabilitiesRequest) returns (CapabilitiesResponse) {}
|
|
|
|
// Fingerprint starts a stream which emits information about the driver
|
|
// including whether the driver healthy and able to function in the
|
|
// existing environment.
|
|
//
|
|
// The driver should immediately stream a FingerprintResponse when the RPC
|
|
// is initially called, then send any additional responses if there is a
|
|
// change in the driver's state.
|
|
rpc Fingerprint(FingerprintRequest) returns (stream 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 (RecoverTaskResponse) {}
|
|
|
|
// 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 (StopTaskResponse) {}
|
|
|
|
// 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, unless force is set to true.
|
|
rpc DestroyTask(DestroyTaskRequest) returns (DestroyTaskResponse) {}
|
|
|
|
// 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(TaskEventsRequest) returns (stream DriverTaskEvent) {}
|
|
|
|
// The following RPCs are only implemented if the driver sets the
|
|
// corresponding capability.
|
|
|
|
// SignalTask sends a signal to the task
|
|
rpc SignalTask(SignalTaskRequest) returns (SignalTaskResponse) {}
|
|
|
|
// ExecTask executes a command inside the tasks execution context
|
|
rpc ExecTask(ExecTaskRequest) returns (ExecTaskResponse) {}
|
|
}
|
|
|
|
message TaskConfigSchemaRequest {}
|
|
|
|
message TaskConfigSchemaResponse {
|
|
|
|
// Spec is the configuration schema for the job driver config stanza
|
|
hashicorp.nomad.plugins.shared.hclspec.Spec spec = 1;
|
|
}
|
|
|
|
message CapabilitiesRequest {}
|
|
|
|
message CapabilitiesResponse {
|
|
|
|
// 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;
|
|
}
|
|
|
|
message FingerprintRequest {}
|
|
|
|
message FingerprintResponse {
|
|
|
|
|
|
// Attributes are key/value pairs that annotate the nomad client and can be
|
|
// used in scheduling contraints and affinities.
|
|
map<string, hashicorp.nomad.plugins.shared.structs.Attribute> attributes = 1;
|
|
|
|
enum HealthState {
|
|
UNDETECTED = 0;
|
|
UNHEALTHY = 1;
|
|
HEALTHY = 2;
|
|
|
|
}
|
|
|
|
// Health is used to determine the state of the health the driver is in.
|
|
// Health can be one of the following states:
|
|
// * UNDETECTED: driver dependencies are not met and the driver can not start
|
|
// * UNHEALTHY: driver dependencies are met but the driver is unable to
|
|
// perform operations due to some other problem
|
|
// * HEALTHY: driver is able to perform all operations
|
|
HealthState health = 2;
|
|
|
|
// HealthDescription is a human readable message describing the current
|
|
// state of driver health
|
|
string health_description = 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 RecoverTaskResponse {}
|
|
|
|
message StartTaskRequest {
|
|
|
|
// Task configuration to launch
|
|
TaskConfig task = 1;
|
|
|
|
}
|
|
|
|
message StartTaskResponse {
|
|
|
|
enum Result {
|
|
SUCCESS = 0;
|
|
RETRY = 1;
|
|
FATAL = 2;
|
|
}
|
|
|
|
// Result is set depending on the type of error that occurred while starting
|
|
// a task:
|
|
//
|
|
// * SUCCESS: No error occurred, handle is set
|
|
// * RETRY: An error occurred, but is recoverable and the RPC should be retried
|
|
// * FATAL: A fatal error occurred and is not likely to succeed if retried
|
|
//
|
|
// If Result is not successful, the DriverErrorMsg will be set.
|
|
Result result = 1;
|
|
|
|
// DriverErrorMsg is set if an error occurred
|
|
string driver_error_msg = 2;
|
|
|
|
// Handle is opaque to the client, but must be stored in order to recover
|
|
// the task.
|
|
TaskHandle handle = 3;
|
|
|
|
// NetworkOverride is set if the driver sets network settings and the service ip/port
|
|
// needs to be set differently.
|
|
NetworkOverride network_override = 4;
|
|
}
|
|
|
|
message WaitTaskRequest {
|
|
|
|
// TaskId is the ID of the target task
|
|
string task_id = 1;
|
|
}
|
|
|
|
message WaitTaskResponse {
|
|
|
|
// Result is the exit status of the task
|
|
ExitResult result = 1;
|
|
// Err is set if any driver error occurred while waiting for the task
|
|
string err = 2;
|
|
}
|
|
|
|
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 StopTaskResponse {}
|
|
|
|
message DestroyTaskRequest {
|
|
|
|
// TaskId is the ID of the target task
|
|
string task_id = 1;
|
|
|
|
// Force destroys the task even if it is still in a running state
|
|
bool force = 2;
|
|
}
|
|
|
|
message DestroyTaskResponse {}
|
|
|
|
message InspectTaskRequest {
|
|
|
|
// TaskId is the ID of the target task
|
|
string task_id = 1;
|
|
}
|
|
|
|
message InspectTaskResponse {
|
|
|
|
// Task details
|
|
TaskStatus task = 1;
|
|
|
|
// Driver details for task
|
|
TaskDriverStatus driver = 2;
|
|
|
|
// NetworkOverride info if set
|
|
NetworkOverride network_override = 3;
|
|
}
|
|
|
|
message TaskStatsRequest {
|
|
|
|
// TaskId is the ID of the target task
|
|
string task_id = 1;
|
|
}
|
|
|
|
message TaskStatsResponse {
|
|
|
|
// Stats for the task
|
|
TaskStats stats = 1;
|
|
}
|
|
|
|
message TaskEventsRequest {}
|
|
|
|
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 SignalTaskResponse {}
|
|
|
|
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 {
|
|
|
|
// Stdout from the exec
|
|
bytes stdout = 1;
|
|
|
|
// Stderr from the exec
|
|
bytes stderr = 2;
|
|
|
|
// Result from the exec
|
|
ExitResult result = 3;
|
|
}
|
|
|
|
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;
|
|
|
|
enum FSIsolation {
|
|
NONE = 0;
|
|
CHROOT = 1;
|
|
IMAGE = 2;
|
|
}
|
|
// FsIsolation indicates what kind of filesystem isolation a driver supports.
|
|
FSIsolation fs_isolation = 3;
|
|
}
|
|
|
|
message TaskConfig {
|
|
|
|
// Id of the task, recommended to the globally unique, must be unique to the driver.
|
|
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;
|
|
|
|
// StdoutPath is the path to the file to open and write task stdout to
|
|
string stdout_path = 10;
|
|
|
|
// StderrPath is the path to the file to open and write task stderr to
|
|
string stderr_path = 11;
|
|
|
|
// TaskGroupName is the name of the task group which this task is a member of
|
|
string task_group_name = 12;
|
|
|
|
// JobName is the name of the job of which this task is part of
|
|
string job_name = 13;
|
|
|
|
// AllocId is the ID of the associated allocation
|
|
string alloc_id = 14;
|
|
}
|
|
|
|
message Resources {
|
|
|
|
// RawResources are the resources set for the task
|
|
RawResources raw_resources = 1;
|
|
|
|
// LinuxResources are the computed values to set for specific Linux features
|
|
LinuxResources linux_resources = 2;
|
|
}
|
|
|
|
message RawResources {
|
|
int64 cpu = 1;
|
|
int64 memory = 2;
|
|
int64 disk = 3;
|
|
repeated NetworkResource networks = 5;
|
|
}
|
|
|
|
message NetworkResource {
|
|
string device = 1;
|
|
string cidr = 2;
|
|
string ip = 3;
|
|
int32 mbits = 4;
|
|
repeated NetworkPort reserved_ports = 5;
|
|
repeated NetworkPort dynamic_ports = 6;
|
|
}
|
|
|
|
message NetworkPort {
|
|
string label = 1;
|
|
int32 value = 2;
|
|
}
|
|
|
|
message LinuxResources {
|
|
|
|
// 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_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;
|
|
// PercentTicks is a compatibility option for docker and should not be used
|
|
double PercentTicks = 8;
|
|
}
|
|
|
|
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;
|
|
|
|
// CgroupPermissions 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 cgroup_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 {
|
|
|
|
// Config is the TaskConfig for the task
|
|
TaskConfig config = 1;
|
|
|
|
// State is the state of the task's execution
|
|
TaskState state = 2;
|
|
|
|
// DriverState is the encoded state for the specific driver
|
|
bytes driver_state = 3;
|
|
}
|
|
|
|
// NetworkOverride contains network settings which the driver may override
|
|
// for the task, such as when the driver is setting up the task's network.
|
|
message NetworkOverride {
|
|
|
|
// PortMap can be set to replace ports with driver-specific mappings
|
|
map<string,int32> port_map = 1;
|
|
|
|
// Addr is the IP address for the task created by the driver
|
|
string addr = 2;
|
|
|
|
// AutoAdvertise indicates whether the driver thinks services that choose
|
|
// to auto_advertise_addresses should use this IP instead of the host's.
|
|
bool auto_advertise = 3;
|
|
}
|
|
|
|
// ExitResult contains information about the exit status of a task
|
|
message ExitResult {
|
|
|
|
// 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;
|
|
|
|
// OomKilled is true if the task exited as a result of the OOM Killer
|
|
bool oom_killed = 3;
|
|
|
|
}
|
|
|
|
// TaskStatus includes 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;
|
|
|
|
// Result is set when CompletedAt is set.
|
|
ExitResult result = 6;
|
|
}
|
|
|
|
message TaskDriverStatus {
|
|
|
|
// Attributes is a set of string/string key value pairs specific to the
|
|
// implementing driver
|
|
map<string, string> attributes = 1;
|
|
}
|
|
|
|
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_USAGE = 2;
|
|
KERNEL_USAGE = 3;
|
|
KERNEL_MAX_USAGE = 4;
|
|
}
|
|
// MeasuredFields indicates which fields were actually sampled
|
|
repeated Fields measured_fields = 6;
|
|
}
|
|
|
|
message DriverTaskEvent {
|
|
|
|
// TaskId is the id of the task for the event
|
|
string task_id = 1;
|
|
|
|
// Timestamp when the event occurred
|
|
google.protobuf.Timestamp timestamp = 2;
|
|
|
|
// Message is the body of the event
|
|
string message = 3;
|
|
|
|
// Annotations allows for additional key/value data to be sent along with the event
|
|
map<string,string> annotations = 4;
|
|
}
|