package mesos.v1.agent

Get desktop application:
View/edit binary Protocol Buffers messages

* Calls that can be sent to the v1 agent API. A call is described using the standard protocol buffer "union" trick, see https://developers.google.com/protocol-buffers/docs/techniques#union.

• optional Call.Type type = 1

• optional Call.GetMetrics get_metrics = 2

• optional Call.SetLoggingLevel set_logging_level = 3

• optional Call.ListFiles list_files = 4

• optional Call.ReadFile read_file = 5

• optional Call.GetContainers get_containers = 20

• optional Call.LaunchNestedContainer launch_nested_container = 6

• optional Call.WaitNestedContainer wait_nested_container = 7

• optional Call.KillNestedContainer kill_nested_container = 8

• optional Call.RemoveNestedContainer remove_nested_container = 12

• optional Call.LaunchNestedContainerSession launch_nested_container_session = 9

• optional Call.AttachContainerInput attach_container_input = 10

• optional Call.AttachContainerOutput attach_container_output = 11

• optional Call.LaunchContainer launch_container = 13

• optional Call.WaitContainer wait_container = 14

• optional Call.KillContainer kill_container = 15

• optional Call.RemoveContainer remove_container = 16

• optional Call.AddResourceProviderConfig add_resource_provider_config = 17

• optional Call.UpdateResourceProviderConfig update_resource_provider_config = 18

• optional Call.RemoveResourceProviderConfig remove_resource_provider_config = 19

• optional Call.PruneImages prune_images = 21

Adds a new resource provider config file. The content of the `info` field will be written into a new config file in the resource provider config directory, and a new resource provider will be launched asynchronously based on the config. Callers must not set the `info.id` field. This call is idempotent, so if a config file identical to the content of the `info` field already exists, this call will return without launching a resource provider. Note that if a config file is placed into the resource provider config directory out-of-band after the agent starts up, it will not be checked against this call. Returns 200 OK if a new config file is created, or an identical config file exists. Returns 400 Bad Request if `info` is not well-formed. Returns 403 Forbidden if the call is not authorized. Returns 409 Conflict if another config file that describes a resource provider of the same type and name exists, but the content is not identical. Returns 500 Internal Server Error if anything goes wrong.

Used in: Call

• required ResourceProviderInfo info = 1

Attaches the caller to the STDIN of the entry point of the container. Clients can use this to stream input data to a container. Note that this call needs to be made on a persistent connection by streaming a CONTAINER_ID message followed by one or more PROCESS_IO messages.

Used in: Call

• optional AttachContainerInput.Type type = 1

• optional ContainerID container_id = 2

• optional ProcessIO process_io = 3

Used in: AttachContainerInput

• UNKNOWN = 0

• CONTAINER_ID = 1

• PROCESS_IO = 2

Attaches the caller to the STDOUT and STDERR of the entrypoint of the container. Clients can use this to stream output/error from the container. This call will result in a streaming response of `ProcessIO`; so this call needs to be made on a persistent connection.

Used in: Call

• required ContainerID container_id = 1

Lists active containers on the agent.

Used in: Call

• optional bool show_nested = 1

• optional bool show_standalone = 2

Provides a snapshot of the current metrics tracked by the agent.

Used in: Call

• optional DurationInfo timeout = 1

  If set, `timeout` would be used to determines the maximum amount of time the API will take to respond. If the timeout is exceeded, some metrics may not be included in the response.

Kills the standalone or nested container. The signal to be sent to the container can be specified in the 'signal' field. Returns 200 OK if the signal is sent successfully. Returns 404 Not Found if the container does not exist.

Used in: Call

• required ContainerID container_id = 1

• optional int32 signal = 2

  Defaults to SIGKILL.

Deprecated in favor of `KillContainer`.

Used in: Call

• required ContainerID container_id = 1

• optional int32 signal = 2

Launches a either a "standalone" container on this agent or a nested container within another tree of containers. A standalone container is launched by specifying a ContainerID with no parent. Standalone containers bypass the normal offer cycle between the master and agent. Unlike other containers, a standalone container does not have an executor or any tasks. This means the standalone container does not report back to Mesos or any framework and must be supervised separately. A nested container is launched by specifying a ContainerID with another existing container (including standalone containers) as the parent. Returns 200 OK if the new container launch succeeds. Returns 202 Accepted if the requested ContainerID is already in use by a standalone or nested container. Returns 400 Bad Request if the container launch fails.

Used in: Call

• required ContainerID container_id = 1

  NOTE: Some characters cannot be used in the ID. All characters must be valid filesystem path characters. In addition, '/' and '.' are reserved.

• optional CommandInfo command = 2

• repeated Resource resources = 3

  NOTE: Nested containers may not specify resources and instead share resources with its parent container. TODO(josephw): These resources are purely used for isolation and are not accounted for by the Mesos master (if connected). It is the caller's responsibility to ensure that resources are not overcommitted (e.g. CPU and memory) or conflicting (e.g. ports and volumes). Once there is support for preempting tasks and a way to update the resources advertised by the agent, these standalone container resources should be accounted for by the master.

• optional ContainerInfo container = 4

Deprecated in favor of `LaunchContainer`.

Used in: Call

• required ContainerID container_id = 1

• optional CommandInfo command = 2

• optional ContainerInfo container = 3

Launches a nested container within an executor's tree of containers. The differences between this call and `LaunchNestedContainer` are: 1) The container's life-cycle is tied to the lifetime of the connection used to make this call, i.e., if the connection ever breaks, the container will be destroyed. 2) The nested container shares the same namespaces and cgroups as its parent container. 3) Results in a streaming response of type `ProcessIO`. So the call needs to be made on a persistent connection.

Used in: Call

• required ContainerID container_id = 1

• optional CommandInfo command = 2

• optional ContainerInfo container = 3

Provides the file listing for a directory.

Used in: Call

• required string path = 1

Prune unused container images from image store. Images and layers referenced by active containers as well as image references specified in `excluded_images` will not be pruned.

Used in: Call

• repeated Image excluded_images = 1

Reads data from a file.

Used in: Call

• required string path = 1

  The path of file.

• required uint64 offset = 2

  Initial offset in file to start reading from.

• optional uint64 length = 3

  The maximum number of bytes to read. The read length is capped at 16 memory pages.

Removes a container's artifacts (runtime and sandbox directories). For nested containers, it is important to use this call if multiple nested containers are launched under the same parent container, because garbage collection only takes place at the parent container. Artifacts belonging to nested containers will not be garbage collected while the parent container is running. TODO(josephw): A standalone container's runtime directory is currently garbage collected as soon as the container exits. To allow the user to retrieve the exit status reliably, the runtime directory cannot be garbage collected immediately. Instead, the user will eventually be required to make this call after the standalone container has exited. Also, a standalone container's sandbox directory is currently not garbage collected and is only deleted via this call. Returns 200 OK if the removal is successful or if the parent container (for nested containers) does not exist. Returns 500 Internal Server Error if anything goes wrong, including if the container is still running or does not exist. TODO(josephw): Consider returning a 400 Bad Request instead of 500 Internal Server Error when the user tries to remove a running or nonexistent nested container.

Used in: Call

• required ContainerID container_id = 1

Deprecated in favor of `RemoveContainer`.

Used in: Call

• required ContainerID container_id = 1

Removes a config file from the resource provider config directory. The config file that describes the resource provider of the specified type and name will be removed, and the corresponding resource provider will be terminated asynchronously. This call is idempotent, so if no matching config file exists, this call will return without terminating any resource provider. Note that if a config file is placed into the resource provider config directory out-of-band after the agent starts up, it will not be checked against this call. Returns 200 OK if the config file is removed, or no matching config file exists. Returns 403 Forbidden if the call is not authorized. Returns 500 Internal Server Error if anything goes wrong.

Used in: Call

• required string type = 1

• required string name = 2

Sets the logging verbosity level for a specified duration. Mesos uses [glog](https://github.com/google/glog) for logging. The library only uses verbose logging which means nothing will be output unless the verbosity level is set (by default it's 0, libprocess uses levels 1, 2, and 3).

Used in: Call

• required uint32 level = 1

  The verbosity level.

• required DurationInfo duration = 2

  The duration to keep verbosity level toggled. After this duration, the verbosity level of log would revert to the original level.

If a call of type `Call::FOO` requires additional parameters they can be included in the corresponding `Call::Foo` message. Similarly, if a call receives a synchronous response it will be returned as a `Response` message of type `Response::FOO`; see `Call::LaunchNestedContainerSession` and `Call::AttachContainerOutput` for exceptions.

Used in: Call

• UNKNOWN = 0

• GET_HEALTH = 1

  Retrieves the agent's health status.

• GET_FLAGS = 2

  Retrieves the agent's flag configuration.

• GET_VERSION = 3

  Retrieves the agent's version information.

• GET_METRICS = 4

  See 'GetMetrics' below.

• GET_LOGGING_LEVEL = 5

  Retrieves the agent's logging level.

• SET_LOGGING_LEVEL = 6

  See 'SetLoggingLevel' below.

• LIST_FILES = 7

• READ_FILE = 8

  See 'ReadFile' below.

• GET_STATE = 9

• GET_CONTAINERS = 10

• GET_FRAMEWORKS = 11

  Retrieves the information about known frameworks.

• GET_EXECUTORS = 12

  Retrieves the information about known executors.

• GET_OPERATIONS = 31

  Retrieves the information about known operations.

• GET_TASKS = 13

  Retrieves the information about known tasks.

• GET_AGENT = 20

  Retrieves the agent information.

• GET_RESOURCE_PROVIDERS = 26

  Retrieves the information about known resource providers.

• LAUNCH_NESTED_CONTAINER = 14

  Calls for managing nested containers underneath an executor's container. Some of these calls are deprecated in favor of the calls for both standalone or nested containers further below.

• WAIT_NESTED_CONTAINER = 15

• KILL_NESTED_CONTAINER = 16

• REMOVE_NESTED_CONTAINER = 21

• LAUNCH_NESTED_CONTAINER_SESSION = 17

  See 'LaunchNestedContainerSession' below.

• ATTACH_CONTAINER_INPUT = 18

  See 'AttachContainerInput' below.

• ATTACH_CONTAINER_OUTPUT = 19

  see 'AttachContainerOutput' below.

• LAUNCH_CONTAINER = 22

  Calls for managing standalone containers or containers nested underneath another container.

  See 'LaunchContainer' below.

• WAIT_CONTAINER = 23

  See 'WaitContainer' below.

• KILL_CONTAINER = 24

  See 'KillContainer' below.

• REMOVE_CONTAINER = 25

  See 'RemoveContainer' below.

• ADD_RESOURCE_PROVIDER_CONFIG = 27

  See 'AddResourceProviderConfig' below. // NOLINT

• UPDATE_RESOURCE_PROVIDER_CONFIG = 28

  See 'UpdateResourceProviderConfig' below. // NOLINT

• REMOVE_RESOURCE_PROVIDER_CONFIG = 29

  See 'RemoveResourceProviderConfig' below. // NOLINT

• PRUNE_IMAGES = 30

  Prune unused container images.

Updates an existing resource provider config file. The content of the `info` field will be written into an existing config file that describes a resource provider of the specified type and name in the resource provider config directory, and the corresponding resource provider will be relaunched asynchronously to reflect the changes in the config. Callers must not set the `info.id` field. This call is idempotent, so if there is no change in the config, this call will return without relaunching the resource provider. Note that if a config file is placed into the resource provider config directory out-of-band after the agent starts up, it will not be checked against this call. Returns 200 OK if an existing config file is updated, or there is no change in the config file. Returns 400 Bad Request if `info` is not well-formed. Returns 403 Forbidden if the call is not authorized. Returns 404 Not Found if no config file describes a resource provider of the same type and name exists. Returns 500 Internal Server Error if anything goes wrong.

Used in: Call

• required ResourceProviderInfo info = 1

Waits for the standalone or nested container to terminate and returns the exit status. Returns 200 OK if and when the container exits. Returns 404 Not Found if the container does not exist.

Used in: Call

• required ContainerID container_id = 1

Deprecated in favor of `WaitContainer`.

Used in: Call

• required ContainerID container_id = 1

* Streaming response to `Call::LAUNCH_NESTED_CONTAINER_SESSION` and `Call::ATTACH_CONTAINER_OUTPUT`. This message is also used to stream request data for `Call::ATTACH_CONTAINER_INPUT`.

Used in: Call.AttachContainerInput

• optional ProcessIO.Type type = 1

• optional ProcessIO.Data data = 2

• optional ProcessIO.Control control = 3

Used in: ProcessIO

• optional Control.Type type = 1

• optional TTYInfo tty_info = 2

• optional Control.Heartbeat heartbeat = 3

Used in: Control

• optional DurationInfo interval = 1

Used in: Control

• UNKNOWN = 0

• TTY_INFO = 1

• HEARTBEAT = 2

Used in: ProcessIO

• optional Data.Type type = 1

• optional bytes data = 2

Used in: Data

• UNKNOWN = 0

• STDIN = 1

• STDOUT = 2

• STDERR = 3

Used in: ProcessIO

• UNKNOWN = 0

• DATA = 1

• CONTROL = 2

* Synchronous responses for all calls made to the v1 agent API.

• optional Response.Type type = 1

• optional Response.GetHealth get_health = 2

• optional Response.GetFlags get_flags = 3

• optional Response.GetVersion get_version = 4

• optional Response.GetMetrics get_metrics = 5

• optional Response.GetLoggingLevel get_logging_level = 6

• optional Response.ListFiles list_files = 7

• optional Response.ReadFile read_file = 8

• optional Response.GetState get_state = 9

• optional Response.GetContainers get_containers = 10

• optional Response.GetFrameworks get_frameworks = 11

• optional Response.GetExecutors get_executors = 12

• optional Response.GetOperations get_operations = 18

• optional Response.GetTasks get_tasks = 13

• optional Response.GetAgent get_agent = 15

• optional Response.GetResourceProviders get_resource_providers = 17

• optional Response.WaitNestedContainer wait_nested_container = 14

• optional Response.WaitContainer wait_container = 16

Contains the agent's information.

Used in: Response

• optional AgentInfo agent_info = 1

Information about containers running on this agent. It contains ContainerStatus and ResourceStatistics along with some metadata of the containers.

Used in: Response

• repeated GetContainers.Container containers = 1

Used in: GetContainers

• optional FrameworkID framework_id = 1

• optional ExecutorID executor_id = 2

• optional string executor_name = 3

• required ContainerID container_id = 4

• optional ContainerStatus container_status = 5

• optional ResourceStatistics resource_statistics = 6

Lists information about all the executors known to the agent at the current time.

Used in: Response, GetState

• repeated GetExecutors.Executor executors = 1

• repeated GetExecutors.Executor completed_executors = 2

Used in: GetExecutors

• required ExecutorInfo executor_info = 1

Contains the flag configuration of the agent.

Used in: Response

• repeated Flag flags = 1

Information about all the frameworks known to the agent at the current time.

Used in: Response, GetState

• repeated GetFrameworks.Framework frameworks = 1

• repeated GetFrameworks.Framework completed_frameworks = 2

Used in: GetFrameworks

• required FrameworkInfo framework_info = 1

`healthy` would be true if the agent is healthy. Delayed responses are also indicative of the poor health of the agent.

Used in: Response

• required bool healthy = 1

Contains the logging level of the agent.

Used in: Response

• required uint32 level = 1

Contains a snapshot of the current metrics.

Used in: Response

• repeated Metric metrics = 1

Lists information about all operations known to the agent at the current time.

Used in: Response

• repeated Operation operations = 1

Lists information about all resource providers known to the agent at the current time.

Used in: Response

• repeated GetResourceProviders.ResourceProvider resource_providers = 1

Used in: GetResourceProviders

• required ResourceProviderInfo resource_provider_info = 1

• repeated Resource total_resources = 2

Contains full state of the agent i.e. information about the tasks, frameworks and executors running in the cluster.

Used in: Response

• optional GetTasks get_tasks = 1

• optional GetExecutors get_executors = 2

• optional GetFrameworks get_frameworks = 3

Lists information about all the tasks known to the agent at the current time.

Used in: Response, GetState

• repeated Task pending_tasks = 1

  Tasks that are pending in the agent's queue before an executor is launched.

• repeated Task queued_tasks = 2

  Tasks that are enqueued for a launched executor that has not yet registered.

• repeated Task launched_tasks = 3

  Tasks that are running.

• repeated Task terminated_tasks = 4

  Tasks that are terminated but pending updates.

• repeated Task completed_tasks = 5

  Tasks that are terminated and updates acked.

Contains the version information of the agent.

Used in: Response

• required VersionInfo version_info = 1

Contains the file listing(similar to `ls -l`) for a directory.

Used in: Response

• repeated FileInfo file_infos = 1

Contains the file data.

Used in: Response

• required uint64 size = 1

  The size of file (in bytes).

• required bytes data = 2

Each of the responses of type `FOO` corresponds to `Foo` message below.

Used in: Response

• UNKNOWN = 0

• GET_HEALTH = 1

  See 'GetHealth' below.

• GET_FLAGS = 2

  See 'GetFlags' below.

• GET_VERSION = 3

  See 'GetVersion' below.

• GET_METRICS = 4

  See 'GetMetrics' below.

• GET_LOGGING_LEVEL = 5

  See 'GetLoggingLevel' below.

• LIST_FILES = 6

• READ_FILE = 7

  See 'ReadFile' below.

• GET_STATE = 8

• GET_CONTAINERS = 9

• GET_FRAMEWORKS = 10

  See 'GetFrameworks' below.

• GET_EXECUTORS = 11

  See 'GetExecutors' below.

• GET_OPERATIONS = 17

  See 'GetOperations' below.

• GET_TASKS = 12

  See 'GetTasks' below.

• GET_AGENT = 14

  See 'GetAgent' below.

• GET_RESOURCE_PROVIDERS = 16

  See 'GetResourceProviders' below.

• WAIT_NESTED_CONTAINER = 13

• WAIT_CONTAINER = 15

  See 'WaitContainer' below.

Returns termination information about the standalone or nested container.

Used in: Response

• optional int32 exit_status = 1

  Wait status of the lead process in the container. Note that this is the return value of `wait(2)`, so callers must use the `wait(2)` family of macros to extract whether the process exited cleanly and what the exit code was.

• optional TaskState state = 2

  The `state` and `reason` fields may be populated if the Mesos agent terminates the container. In the absence of any special knowledge, executors should propagate this information via the `status` field of an `Update` call for the corresponding TaskID.

• optional TaskStatus.Reason reason = 3

• optional TaskResourceLimitation limitation = 4

  This field will be populated if the task was terminated due to a resource limitation.

• optional string message = 5

Returns termination information about the nested container.

Used in: Response

• optional int32 exit_status = 1

  Wait status of the lead process in the container. Note that this is the return value of `wait(2)`, so callers must use the `wait(2)` family of macros to extract whether the process exited cleanly and what the exit code was.

• optional TaskState state = 2

  The `state` and `reason` fields may be populated if the Mesos agent terminates the container. In the absence of any special knowledge, executors should propagate this information via the `status` field of an `Update` call for the corresponding TaskID.

• optional TaskStatus.Reason reason = 3

• optional TaskResourceLimitation limitation = 4

  This field will be populated if the task was terminated due to a resource limitation.

• optional string message = 5