package hashicorp.nomad.plugins.drivers.proto

Get desktop application:
View/edit binary Protocol Buffers messages

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.

• rpc TaskConfigSchema (TaskConfigSchemaRequest, TaskConfigSchemaResponse)

  driver.proto:20

  TaskConfigSchema returns the schema for parsing the driver configuration of a task.

  message TaskConfigSchemaRequest

  driver.proto:93

  (message has no fields)

  message TaskConfigSchemaResponse

  driver.proto:95

  • optional shared.hclspec.Spec spec = 1

    Spec is the configuration schema for the job driver config block

• rpc Capabilities (CapabilitiesRequest, CapabilitiesResponse)

  driver.proto:25

  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.

  message CapabilitiesRequest

  driver.proto:101

  (message has no fields)

  message CapabilitiesResponse

  driver.proto:103

  • optional DriverCapabilities capabilities = 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.

• rpc Fingerprint (FingerprintRequest, stream FingerprintResponse)

  driver.proto:34

  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.

  message FingerprintRequest

  driver.proto:112

  (message has no fields)

  message FingerprintResponse

  driver.proto:114

  • map<string, shared.structs.Attribute> attributes = 1

    Attributes are key/value pairs that annotate the nomad client and can be used in scheduling constraints and affinities.

  • FingerprintResponse.HealthState health = 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

  • string health_description = 3

    HealthDescription is a human readable message describing the current state of driver health

• rpc RecoverTask (RecoverTaskRequest, RecoverTaskResponse)

  driver.proto:38

  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.

  message RecoverTaskRequest

  driver.proto:141

  • string task_id = 1

    TaskId is the ID of the target task

  • optional TaskHandle handle = 2

    Handle is the TaskHandle returned from StartTask

  message RecoverTaskResponse

  driver.proto:150

  (message has no fields)

• rpc StartTask (StartTaskRequest, StartTaskResponse)

  driver.proto:41

  StartTask starts and tracks the task on the implemented runtime

  message StartTaskRequest

  driver.proto:152

  • optional TaskConfig task = 1

    Task configuration to launch

  message StartTaskResponse

  driver.proto:159

  • StartTaskResponse.Result result = 1

    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.

  • string driver_error_msg = 2

    DriverErrorMsg is set if an error occurred

  • optional TaskHandle handle = 3

    Handle is opaque to the client, but must be stored in order to recover the task.

  • optional NetworkOverride network_override = 4

    NetworkOverride is set if the driver sets network settings and the service ip/port needs to be set differently.

• rpc WaitTask (WaitTaskRequest, WaitTaskResponse)

  driver.proto:46

  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.

  message WaitTaskRequest

  driver.proto:189

  • string task_id = 1

    TaskId is the ID of the target task

  message WaitTaskResponse

  driver.proto:195

  • optional ExitResult result = 1

    Result is the exit status of the task

  • string err = 2

    Err is set if any driver error occurred while waiting for the task

• rpc StopTask (StopTaskRequest, StopTaskResponse)

  driver.proto:51

  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.

  message StopTaskRequest

  driver.proto:203

  • string task_id = 1

    TaskId is the ID of the target task

  • optional google.protobuf.Duration timeout = 2

    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.

  • string signal = 3

    Signal can be set to override the Task's configured shutdown signal

  message StopTaskResponse

  driver.proto:217

  (message has no fields)

• rpc DestroyTask (DestroyTaskRequest, DestroyTaskResponse)

  driver.proto:56

  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.

  message DestroyTaskRequest

  driver.proto:219

  • string task_id = 1

    TaskId is the ID of the target task

  • bool force = 2

    Force destroys the task even if it is still in a running state

  message DestroyTaskResponse

  driver.proto:228

  (message has no fields)

• rpc InspectTask (InspectTaskRequest, InspectTaskResponse)

  driver.proto:59

  InspectTask returns detailed information for the given task

  message InspectTaskRequest

  driver.proto:230

  • string task_id = 1

    TaskId is the ID of the target task

  message InspectTaskResponse

  driver.proto:236

  • optional TaskStatus task = 1

    Task details

  • optional TaskDriverStatus driver = 2

    Driver details for task

  • optional NetworkOverride network_override = 3

    NetworkOverride info if set

• rpc TaskStats (TaskStatsRequest, stream TaskStatsResponse)

  driver.proto:62

  TaskStats collects and returns runtime metrics for the given task

  message TaskStatsRequest

  driver.proto:248

  • string task_id = 1

    TaskId is the ID of the target task

  • optional google.protobuf.Duration collection_interval = 2

    CollectionInterval is the interval at which to stream stats to the caller

  message TaskStatsResponse

  driver.proto:257

  • optional TaskStats stats = 1

    Stats for the task

• rpc TaskEvents (TaskEventsRequest, stream DriverTaskEvent)

  driver.proto:66

  TaskEvents starts a streaming RPC where all task events emitted by the driver are streamed to the caller.

  message TaskEventsRequest

  driver.proto:263

  (message has no fields)

  message DriverTaskEvent

  driver.proto:765

  • string task_id = 1

    TaskId is the id of the task for the event

  • string alloc_id = 2

    AllocId of the task for the event

  • string task_name = 3

    TaskName is the name of the task for the event

  • optional google.protobuf.Timestamp timestamp = 4

    Timestamp when the event occurred

  • string message = 5

    Message is the body of the event

  • map<string, string> annotations = 6

    Annotations allows for additional key/value data to be sent along with the event

• rpc SignalTask (SignalTaskRequest, SignalTaskResponse)

  driver.proto:74

  SignalTask sends a signal to the task

  message SignalTaskRequest

  driver.proto:265

  • string task_id = 1

    TaskId is the ID of the target task

  • string signal = 2

    Signal is the operating system signal to send to the task. Ex: SIGHUP

  message SignalTaskResponse

  driver.proto:274

  (message has no fields)

• rpc ExecTask (ExecTaskRequest, ExecTaskResponse)

  driver.proto:77

  ExecTask executes a command inside the tasks execution context

  message ExecTaskRequest

  driver.proto:276

  • string task_id = 1

    TaskId is the ID of the target task

  • repeated string command = 2

    Command is the command to execute in the task environment

  • optional google.protobuf.Duration timeout = 3

    Timeout is the amount of time to wait for the command to stop. Defaults to 0 (run forever)

  message ExecTaskResponse

  driver.proto:289

  • bytes stdout = 1

    Stdout from the exec

  • bytes stderr = 2

    Stderr from the exec

  • optional ExitResult result = 3

    Result from the exec

• rpc ExecTaskStreaming (stream ExecTaskStreamingRequest, stream ExecTaskStreamingResponse)

  driver.proto:82

  ExecTaskStreaming executes a command inside the tasks execution context and streams back results buf:lint:ignore RPC_REQUEST_RESPONSE_UNIQUE

• rpc CreateNetwork (CreateNetworkRequest, CreateNetworkResponse)

  driver.proto:86

  CreateNetwork is implemented when the driver needs to create the network namespace instead of allowing the Nomad client to do.

  message CreateNetworkRequest

  driver.proto:331

  • string alloc_id = 1

    AllocID of the allocation the network is associated with

  • string hostname = 2

    Hostname of the network namespace

  message CreateNetworkResponse

  driver.proto:340

  • optional NetworkIsolationSpec isolation_spec = 1

  • bool created = 2

    created indicates that the network namespace is newly created as a result of this request. if false, the NetworkIsolationSpec value returned is an existing spec.

• rpc DestroyNetwork (DestroyNetworkRequest, DestroyNetworkResponse)

  driver.proto:90

  DestroyNetwork destroys a previously created network. This rpc is only implemented if the driver needs to manage network namespace creation.

  message DestroyNetworkRequest

  driver.proto:350

  • string alloc_id = 1

    AllocID of the allocation the network is associated with

  • optional NetworkIsolationSpec isolation_spec = 2

  message DestroyNetworkResponse

  driver.proto:358

  (message has no fields)

Used in: AllocatedTaskResources

• int64 cpu_shares = 1

Used in: AllocatedTaskResources

• int64 memory_mb = 2

• int64 memory_max_mb = 3

Used in: Resources

• optional AllocatedCpuResources cpu = 1

• optional AllocatedMemoryResources memory = 2

• repeated NetworkResource networks = 5

Used in: TaskResourceUsage

• double system_mode = 1

• double user_mode = 2

• double total_ticks = 3

• uint64 throttled_periods = 4

• uint64 throttled_time = 5

• double percent = 6

• repeated CPUUsage.Fields measured_fields = 7

  MeasuredFields indicates which fields were actually sampled

Used in: CPUUsage

• SYSTEM_MODE = 0

• USER_MODE = 1

• TOTAL_TICKS = 2

• THROTTLED_PERIODS = 3

• THROTTLED_TIME = 4

• PERCENT = 5

Used in: TaskConfig

• repeated string servers = 1

• repeated string searches = 2

• repeated string options = 3

Used in: TaskConfig, executor.proto.LaunchRequest

• string task_path = 1

  TaskPath is the file path within the task to mount the device to

• string host_path = 2

  HostPath is the path on the host to the source device

• string cgroup_permissions = 3

  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"

Used in: CapabilitiesResponse

• bool send_signals = 1

  SendSignals indicates that the driver can send process signals (ex. SIGUSR1) to the task.

• bool exec = 2

  Exec indicates that the driver supports executing arbitrary commands in the task's execution environment.

• DriverCapabilities.FSIsolation fs_isolation = 3

  FsIsolation indicates what kind of filesystem isolation a driver supports.

• repeated NetworkIsolationSpec.NetworkIsolationMode network_isolation_modes = 4

• bool must_create_network = 5

• DriverCapabilities.MountConfigs mount_configs = 6

  MountConfigs indicates whether the driver supports mount configurations.

• bool disable_log_collection = 8

  disable_log_collection indicates whether the driver has the capability of disabling log collection

• bool dynamic_workload_users = 9

  dynamic_workload_users indicates the task is capable of using UID/GID assigned from the Nomad client as user credentials for the task.

Used in: DriverCapabilities

• NONE = 0

• CHROOT = 1

• IMAGE = 2

• UNVEIL = 3

Used in: DriverCapabilities

• UNKNOWN_MOUNTS = 0

  treated as ANY_MOUNTS for backwards compatibility

• ANY_MOUNTS = 0

• NO_MOUNTS = 1

Used in: ExecTaskStreamingRequest, ExecTaskStreamingResponse

• bytes data = 1

• bool close = 2

Used as request type in: Driver.ExecTaskStreaming, executor.proto.Executor.ExecStreaming

• optional ExecTaskStreamingRequest.Setup setup = 1

• optional ExecTaskStreamingRequest.TerminalSize tty_size = 2

• optional ExecTaskStreamingIOOperation stdin = 3

Used in: ExecTaskStreamingRequest

• string task_id = 1

• repeated string command = 2

• bool tty = 3

Used in: ExecTaskStreamingRequest

• int32 height = 1

• int32 width = 2

Used as response type in: Driver.ExecTaskStreaming, executor.proto.Executor.ExecStreaming

• optional ExecTaskStreamingIOOperation stdout = 1

• optional ExecTaskStreamingIOOperation stderr = 2

• bool exited = 3

• optional ExitResult result = 4

ExitResult contains information about the exit status of a task

Used in: ExecTaskResponse, ExecTaskStreamingResponse, TaskStatus, WaitTaskResponse

• int32 exit_code = 1

  ExitCode returned from the task on exit

• int32 signal = 2

  Signal is set if a signal was sent to the task

• bool oom_killed = 3

  OomKilled is true if the task exited as a result of the OOM Killer

Used in: FingerprintResponse

• UNDETECTED = 0

• UNHEALTHY = 1

• HEALTHY = 2

Used in: NetworkIsolationSpec

• string hostname = 1

• string address = 2

Used in: Resources

• int64 cpu_period = 1

  CPU CFS (Completely Fair Scheduler) period. Default: 0 (not specified)

• int64 cpu_quota = 2

  CPU CFS (Completely Fair Scheduler) quota. Default: 0 (not specified)

• int64 cpu_shares = 3

  CPU shares (relative weight vs. other containers). Default: 0 (not specified)

• int64 memory_limit_bytes = 4

  Memory limit in bytes. Default: 0 (not specified)

• int64 oom_score_adj = 5

  OOMScoreAdj adjusts the oom-killer score. Default: 0 (not specified)

• string cpuset_cpus = 6

  CpusetCpus constrains the allowed set of logical CPUs. Default: "" (not specified) This field exists to support drivers which can't set a cgroup path.

• string cpuset_cgroup = 9

  CpusetCgroup is the path to the cpuset cgroup managed by the client

• double PercentTicks = 8

  PercentTicks is a compatibility option for docker and should not be used buf:lint:ignore FIELD_LOWER_SNAKE_CASE

Used in: TaskResourceUsage

• uint64 rss = 1

• uint64 cache = 2

• uint64 max_usage = 3

• uint64 kernel_usage = 4

• uint64 kernel_max_usage = 5

• uint64 usage = 7

• uint64 swap = 8

• repeated MemoryUsage.Fields measured_fields = 6

  MeasuredFields indicates which fields were actually sampled

Used in: MemoryUsage

• RSS = 0

• CACHE = 1

• MAX_USAGE = 2

• KERNEL_USAGE = 3

• KERNEL_MAX_USAGE = 4

• USAGE = 5

• SWAP = 6

Used in: TaskConfig, executor.proto.LaunchRequest

• string task_path = 1

  TaskPath is the file path within the task directory to mount to

• string host_path = 2

  HostPath is the file path on the host to mount from

• bool readonly = 3

  Readonly if set true, mounts the path in readonly mode

• string propagation_mode = 4

  Propagation mode for the mount. Not exactly the same as the unix mount propagation flags. See callsite usage for details.

• string selinux_label = 5

Used in: CreateNetworkResponse, DestroyNetworkRequest, TaskConfig, executor.proto.LaunchRequest

• NetworkIsolationSpec.NetworkIsolationMode mode = 1

• string path = 2

• map<string, string> labels = 3

• optional HostsConfig hostsConfig = 4

Used in: DriverCapabilities, NetworkIsolationSpec

• HOST = 0

• GROUP = 1

• TASK = 2

• NONE = 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.

Used in: InspectTaskResponse, StartTaskResponse

• map<string, int32> port_map = 1

  PortMap can be set to replace ports with driver-specific mappings

• string addr = 2

  Addr is the IP address for the task created by the driver

• bool auto_advertise = 3

  AutoAdvertise indicates whether the driver thinks services that choose to auto_advertise_addresses should use this IP instead of the host's.

Used in: NetworkResource

• string label = 1

• int32 value = 2

Used in: AllocatedTaskResources

• string device = 1

• string cidr = 2

• string ip = 3

• int32 mbits = 4

• repeated NetworkPort reserved_ports = 5

• repeated NetworkPort dynamic_ports = 6

Used in: Resources

• string label = 1

• int32 value = 2

• int32 to = 3

• string host_ip = 4

Used in: TaskConfig, executor.proto.LaunchRequest, executor.proto.UpdateResourcesRequest

• optional AllocatedTaskResources allocated_resources = 1

  AllocatedResources are the resources set for the task

• optional LinuxResources linux_resources = 2

  LinuxResources are the computed values to set for specific Linux features

• repeated PortMapping ports = 3

  Ports are the allocated port mappings for the allocation. A task may use these to manually configure port mapping if shared network namespaces aren't being used.

Used in: StartTaskResponse

• SUCCESS = 0

• RETRY = 1

• FATAL = 2

Used in: StartTaskRequest, TaskHandle

• string id = 1

  Id of the task, recommended to the globally unique, must be unique to the driver.

• string name = 2

  Name of the task

• bytes msgpack_driver_config = 3

  MsgpackDriverConfig is the encoded driver configuation of the task

• map<string, string> env = 4

  Env is the a set of key/value pairs to be set as environment variables

• map<string, string> device_env = 5

  DeviceEnv is the set of environment variables that are defined by device plugins. This allows the driver to differentiate environment variables set by the device plugins and those by the user. When populating the task's environment env should be used.

• optional Resources resources = 6

  Resources defines the resources to isolate

• repeated Mount mounts = 7

  Mounts is a list of targets to bind mount into the task directory

• repeated Device devices = 8

  Devices is a list of system devices to mount into the task's execution environment.

• string user = 9

  User defines the operating system user the tasks should run as

• string alloc_dir = 10

  AllocDir is the directory on the host where the allocation directory exists.

• string stdout_path = 11

  StdoutPath is the path to the file to open and write task stdout to

• string stderr_path = 12

  StderrPath is the path to the file to open and write task stderr to

• string task_group_name = 13

  TaskGroupName is the name of the task group which this task is a member of

• string job_name = 14

  JobName is the name of the job of which this task is part of

• string alloc_id = 15

  AllocId is the ID of the associated allocation

• optional NetworkIsolationSpec network_isolation_spec = 16

  NetworkIsolationSpec specifies the configuration for the network namespace to use for the task. *Only supported on Linux

• optional DNSConfig dns = 17

  DNSConfig is the configuration for task DNS resolvers and other options

• string job_id = 18

  JobId is the ID of the job of which this task is part of

• string namespace = 19

  Namespace is the namespace of the job of which this task is part of

• string node_name = 20

  NodeName is the name of the node where the associated allocation is running

• string node_id = 21

  NodeId is the ID of the node where the associated allocation is running

• string parent_job_id = 22

  ParentJobID is the parent id for dispatch and periodic jobs

Used in: InspectTaskResponse

• map<string, string> attributes = 1

  Attributes is a set of string/string key value pairs specific to the implementing driver

TaskHandle is created when starting a task and is used to recover task

Used in: RecoverTaskRequest, StartTaskResponse

• int32 version = 1

  Version is used by the driver to version the DriverState schema. Version 0 is reserved by Nomad and should not be used.

• optional TaskConfig config = 2

  Config is the TaskConfig for the task

• TaskState state = 3

  State is the state of the task's execution

• bytes driver_state = 4

  DriverState is the encoded state for the specific driver

Used in: TaskStats

• optional CPUUsage cpu = 1

  CPU usage stats

• optional MemoryUsage memory = 2

  Memory usage stats

Used in: TaskHandle, TaskStatus

• UNKNOWN = 0

• RUNNING = 1

• EXITED = 2

Used in: TaskStatsResponse, executor.proto.StatsResponse

• string id = 1

  Id of the task

• optional google.protobuf.Timestamp timestamp = 2

  Timestamp for which the stats were collected

• optional TaskResourceUsage agg_resource_usage = 3

  AggResourceUsage is the aggreate usage of all processes

• map<string, TaskResourceUsage> resource_usage_by_pid = 4

  ResourceUsageByPid breaks the usage stats by process

TaskStatus includes information of a specific task

Used in: InspectTaskResponse

• string id = 1

• string name = 2

• TaskState state = 3

  State is the state of the task's execution

• optional google.protobuf.Timestamp started_at = 4

  StartedAt is the timestamp when the task was started

• optional google.protobuf.Timestamp completed_at = 5

  CompletedAt is the timestamp when the task exited. If the task is still running, CompletedAt will not be set

• optional ExitResult result = 6

  Result is set when CompletedAt is set.