package mesos.v1.master

Get desktop application:
View/edit binary Protocol Buffers messages

* Calls that can be sent to the v1 master 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.UpdateWeights update_weights = 6

• optional Call.ReserveResources reserve_resources = 7

• optional Call.UnreserveResources unreserve_resources = 8

• optional Call.CreateVolumes create_volumes = 9

• optional Call.DestroyVolumes destroy_volumes = 10

• optional Call.GrowVolume grow_volume = 18

• optional Call.ShrinkVolume shrink_volume = 19

• optional Call.UpdateMaintenanceSchedule update_maintenance_schedule = 11

• optional Call.StartMaintenance start_maintenance = 12

• optional Call.StopMaintenance stop_maintenance = 13

• optional Call.SetQuota set_quota = 14

• optional Call.RemoveQuota remove_quota = 15

• optional Call.Teardown teardown = 16

• optional Call.MarkAgentGone mark_agent_gone = 17

Create persistent volumes on reserved resources. The request is forwarded asynchronously to the Mesos agent where the reserved resources are located. That asynchronous message may not be delivered or creating the volumes at the agent might fail. Volume creation can be verified by sending a `GET_VOLUMES` call.

Used in: Call

• required AgentID agent_id = 1

• repeated Resource volumes = 2

Destroy persistent volumes. The request is forwarded asynchronously to the Mesos agent where the reserved resources are located. That asynchronous message may not be delivered or destroying the volumes at the agent might fail. Volume deletion can be verified by sending a `GET_VOLUMES` call.

Used in: Call

• required AgentID agent_id = 1

• repeated Resource volumes = 2

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

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.

Grow a volume by an additional disk resource. NOTE: This is currently experimental and only for persistent volumes created on ROOT/PATH disks.

Used in: Call

• optional AgentID agent_id = 1

  `agent_id` must be set if `volume` is an agent-local resource, and must be unset if `volume` is an external resource.

• required Resource volume = 2

• required Resource addition = 3

Provides the file listing for a directory.

Used in: Call

• required string path = 1

Mark an agent as gone. This can be used by an operator to assert that the agent instance has failed and is never coming back (e.g., ephemeral instance from cloud provider). The master would shutdown the agent and send 'TASK_GONE_BY_OPERATOR' updates for all the running tasks. The persistent volumes/reservations on the agent won't be accessible anymore. NOTE: It is possible that the tasks might still be running if the operator's assertion was wrong and the agent was partitioned away from the master. The agent would be shutdown when it tries to reregister with the master when the partition heals.

Used in: Call

• required AgentID agent_id = 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.

Used in: Call

• required string role = 1

Reserve resources dynamically on a specific agent.

Used in: Call

• required AgentID agent_id = 1

• repeated Resource resources = 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.

Sets the quota for resources to be used by a particular role.

Used in: Call

• required quota.QuotaRequest quota_request = 1

Shrink a volume by the size specified in the `subtract` field. NOTE: This is currently experimental and only for persistent volumes created on ROOT/PATH disks.

Used in: Call

• optional AgentID agent_id = 1

  `agent_id` must be set if `volume` is an agent-local resource, and must be unset if `volume` is an external resource.

• required Resource volume = 2

• required Value.Scalar subtract = 3

  See comments in `Value.Scalar` for maximum precision supported.

Starts the maintenance of the cluster, this would bring a set of machines down.

Used in: Call

• repeated MachineID machines = 1

Stops the maintenance of the cluster, this would bring a set of machines back up.

Used in: Call

• repeated MachineID machines = 1

Tears down a running framework by shutting down all tasks/executors and removing the framework.

Used in: Call

• required FrameworkID framework_id = 1

Used in: Call

• UNKNOWN = 0

  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`. Currently all calls except `Call::SUBSCRIBE` receive synchronous responses; `Call::SUBSCRIBE` returns a streaming response of `Event`.

• GET_HEALTH = 1

  Retrieves the master's health status.

• GET_FLAGS = 2

  Retrieves the master's flag configuration.

• GET_VERSION = 3

  Retrieves the master's version information.

• GET_METRICS = 4

  See 'GetMetrics' below.

• GET_LOGGING_LEVEL = 5

  Retrieves the master's logging level.

• SET_LOGGING_LEVEL = 6

  See 'SetLoggingLevel' below.

• LIST_FILES = 7

• READ_FILE = 8

  See 'ReadFile' below.

• GET_STATE = 9

• GET_AGENTS = 10

• GET_FRAMEWORKS = 11

• GET_EXECUTORS = 12

  Retrieves the information about all executors.

• GET_OPERATIONS = 33

  Retrieves the information about known operations.

• GET_TASKS = 13

  Retrieves the information about all known tasks.

• GET_ROLES = 14

  Retrieves the information about roles.

• GET_WEIGHTS = 15

  Retrieves the information about role weights.

• UPDATE_WEIGHTS = 16

• GET_MASTER = 17

  Retrieves the master's information.

• SUBSCRIBE = 18

  Subscribes the master to receive events.

• RESERVE_RESOURCES = 19

• UNRESERVE_RESOURCES = 20

• CREATE_VOLUMES = 21

  See 'CreateVolumes' below.

• DESTROY_VOLUMES = 22

  See 'DestroyVolumes' below.

• GROW_VOLUME = 34

  See 'GrowVolume' below.

• SHRINK_VOLUME = 35

  See 'ShrinkVolume' below.

• GET_MAINTENANCE_STATUS = 23

  Retrieves the cluster's maintenance status.

• GET_MAINTENANCE_SCHEDULE = 24

  Retrieves the cluster's maintenance schedule.

• UPDATE_MAINTENANCE_SCHEDULE = 25

  See 'UpdateMaintenanceSchedule' below.

• START_MAINTENANCE = 26

  See 'StartMaintenance' below.

• STOP_MAINTENANCE = 27

  See 'StopMaintenance' below.

• GET_QUOTA = 28

• SET_QUOTA = 29

  See 'SetQuota' below.

• REMOVE_QUOTA = 30

  See 'RemoveQuota' below.

• TEARDOWN = 31

  See 'Teardown' below.

• MARK_AGENT_GONE = 32

  See 'MarkAgentGone' below.

Unreserve resources dynamically on a specific agent.

Used in: Call

• required AgentID agent_id = 1

• repeated Resource resources = 2

Updates the cluster's maintenance schedule.

Used in: Call

• required maintenance.Schedule schedule = 1

Used in: Call

• repeated WeightInfo weight_infos = 1

* Streaming response to `Call::SUBSCRIBE` made to the master.

• optional Event.Type type = 1

• optional Event.Subscribed subscribed = 2

• optional Event.TaskAdded task_added = 3

• optional Event.TaskUpdated task_updated = 4

• optional Event.AgentAdded agent_added = 5

• optional Event.AgentRemoved agent_removed = 6

• optional Event.FrameworkAdded framework_added = 7

• optional Event.FrameworkUpdated framework_updated = 8

• optional Event.FrameworkRemoved framework_removed = 9

Forwarded by the master when an agent becomes known to it. This can happen when an agent registered for the first time, or reregistered after a master failover.

Used in: Event

• required Response.GetAgents.Agent agent = 1

Forwarded by the master when an agent is removed. This can happen when the agent is scheduled for maintenance. NOTE: It's possible that an agent might become active once it has been removed, i.e. if the master has gc'ed its list of known "dead" agents. See MESOS-5965 for context.

Used in: Event

• required AgentID agent_id = 1

Forwarded by the master when a framework becomes known to it. This can happen when a new framework registers with the master.

Used in: Event

• required Response.GetFrameworks.Framework framework = 1

Forwarded by the master when a framework is removed. This can happen when a framework is explicitly teardown by the operator or if it fails to reregister with the master within the failover timeout.

Used in: Event

• required FrameworkInfo framework_info = 1

Forwarded by the master when a framework reregisters with the master upon a disconnection (network error) or upon a master failover.

Used in: Event

• required Response.GetFrameworks.Framework framework = 1

First event received when a client subscribes.

Used in: Event

• optional Response.GetState get_state = 1

  Snapshot of the entire cluster state. Further updates to the cluster state are sent as separate events on the stream.

• optional double heartbeat_interval_seconds = 2

  This value will be set if the master is sending heartbeats to subscribers. See the comment above on 'HEARTBEAT' for more details.

Forwarded by the master when a task becomes known to it. This can happen when a new task is launched by the scheduler or when the task becomes known to the master upon an agent (re-)registration after a failover.

Used in: Event

• required Task task = 1

Forwarded by the master when an existing task transitions to a new state.

Used in: Event

• required FrameworkID framework_id = 1

• required TaskStatus status = 2

  This is the status of the task corresponding to the last status update acknowledged by the scheduler.

• required TaskState state = 3

  This is the latest state of the task according to the agent, which can be more recent than `status` above but intermediate state changes may be skipped if they happen faster than the scheduler can acknowledge them.

Used in: Event

• UNKNOWN = 0

• SUBSCRIBED = 1

  See `Subscribed` below.

• TASK_ADDED = 2

  See `TaskAdded` below.

• TASK_UPDATED = 3

  See `TaskUpdated` below.

• AGENT_ADDED = 4

  See `AgentAdded` below.

• AGENT_REMOVED = 5

  See `AgentRemoved` below.

• FRAMEWORK_ADDED = 6

  See `FrameworkAdded` below.

• FRAMEWORK_UPDATED = 7

  See `FrameworkUpdated` below.

• FRAMEWORK_REMOVED = 8

  See `FrameworkRemoved` below.

• HEARTBEAT = 9

  Periodic message sent by the master to the subscriber according to 'Subscribed.heartbeat_interval_seconds'. If the subscriber does not receive any events (including heartbeats) for an extended period of time (e.g., 5 x heartbeat_interval_seconds), it is likely that the connection is lost or there is a network partition. In that case, the subscriber should close the existing subscription connection and resubscribe using a backoff strategy.

* Synchronous responses for all calls (except Call::SUBSCRIBE) made to the v1 master 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.GetAgents get_agents = 10

• optional Response.GetFrameworks get_frameworks = 11

• optional Response.GetExecutors get_executors = 12

• optional Response.GetOperations get_operations = 20

• optional Response.GetTasks get_tasks = 13

• optional Response.GetRoles get_roles = 14

• optional Response.GetWeights get_weights = 15

• optional Response.GetMaster get_master = 16

• optional Response.GetMaintenanceStatus get_maintenance_status = 17

• optional Response.GetMaintenanceSchedule get_maintenance_schedule = 18

• optional Response.GetQuota get_quota = 19

Used in: Response, GetState

• repeated GetAgents.Agent agents = 1

  Registered agents.

• repeated AgentInfo recovered_agents = 2

  Agents which are recovered from registry but not reregistered yet.

Used in: Event.AgentAdded, GetAgents, peloton.private.hostmgr.hostsvc.GetMesosAgentInfoResponse

• required AgentInfo agent_info = 1

• required bool active = 2

• required string version = 3

• optional string pid = 4

• optional TimeInfo registered_time = 5

• optional TimeInfo reregistered_time = 6

• repeated Resource total_resources = 7

  Total resources (including oversubscribed resources) the agent provides.

• repeated Resource allocated_resources = 8

• repeated Resource offered_resources = 9

• repeated AgentInfo.Capability capabilities = 10

• repeated Agent.ResourceProvider resource_providers = 11

Used in: Agent

• required ResourceProviderInfo resource_provider_info = 1

• repeated Resource total_resources = 2

Lists information about all the executors known to the master at the current time. Note that there might be executors unknown to the master running on partitioned or unsubscribed agents.

Used in: Response, GetState

• repeated GetExecutors.Executor executors = 1

• repeated GetExecutors.Executor orphan_executors = 2

  As of Mesos 1.3.0, this field is deprecated and will always be empty. TODO(neilc): Remove this field in Mesos 2.0.

Used in: GetExecutors

• required ExecutorInfo executor_info = 1

• required AgentID agent_id = 2

Contains the flag configuration of the master.

Used in: Response

• repeated Flag flags = 1

Information about all the frameworks known to the master at the current time. Note that there might be frameworks unknown to the master running on partitioned or unsubscribed agents.

Used in: Response, GetState

• repeated GetFrameworks.Framework frameworks = 1

  Frameworks that have subscribed with the master. Note that this includes frameworks that are disconnected and in the process of re-subscribing.

• repeated GetFrameworks.Framework completed_frameworks = 2

  Frameworks that have been teared down.

• repeated FrameworkInfo recovered_frameworks = 3

  This field previously contained frameworks that previously subscribed but haven't yet re-subscribed after a master failover. As of Mesos 1.2, this field will always be empty; recovered frameworks are now reported in the `frameworks` list with the `recovered` field set to true. TODO(neilc): Remove this field in Mesos 2.0.

Used in: Event.FrameworkAdded, Event.FrameworkUpdated, GetFrameworks

• required FrameworkInfo framework_info = 1

• required bool active = 2

• required bool connected = 3

• required bool recovered = 11

  If true, this framework was previously subscribed but hasn't yet re-subscribed after a master failover. Recovered frameworks are only reported if one or more agents running a task or executor for the framework have reregistered after master failover.

• optional TimeInfo registered_time = 4

• optional TimeInfo reregistered_time = 5

• optional TimeInfo unregistered_time = 6

• repeated Offer offers = 7

• repeated InverseOffer inverse_offers = 8

• repeated Resource allocated_resources = 9

• repeated Resource offered_resources = 10

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

Used in: Response

• required bool healthy = 1

Contains the logging level of the master.

Used in: Response

• required uint32 level = 1

Contains the cluster's maintenance schedule.

Used in: Response

• required maintenance.Schedule schedule = 1

Contains the cluster's maintenance status.

Used in: Response

• required maintenance.ClusterStatus status = 1

Contains the master's information.

Used in: Response

• optional MasterInfo master_info = 1

• optional double start_time = 2

• optional double elected_time = 3

Contains a snapshot of the current metrics.

Used in: Response

• repeated Metric metrics = 1

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

Used in: Response

• repeated Operation operations = 1

Contains the cluster's configured quotas.

Used in: Response

• required quota.QuotaStatus status = 1

Provides information about every role that is on the role whitelist (if enabled), has one or more registered frameworks or has a non-default weight or quota.

Used in: Response

• repeated Role roles = 1

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

Used in: Event.Subscribed, Response

• optional GetTasks get_tasks = 1

• optional GetExecutors get_executors = 2

• optional GetFrameworks get_frameworks = 3

• optional GetAgents get_agents = 4

Lists information about all the tasks known to the master at the current time. Note that there might be tasks unknown to the master running on partitioned or unsubscribed agents.

Used in: Response, GetState

• repeated Task pending_tasks = 1

  Tasks that are enqueued on the master waiting (e.g., authorizing) to be launched.

• repeated Task tasks = 2

  Tasks that have been forwarded to the agent for launch. This includes tasks that are staging or running; it also includes tasks that have reached a terminal state but the terminal status update has not yet been acknowledged by the scheduler.

• repeated Task unreachable_tasks = 5

  Tasks that were running on agents that have become partitioned from the master. If/when the agent is no longer partitioned, tasks running on that agent will no longer be unreachable (they will either be running or completed). Note that the master only stores a limited number of unreachable tasks; information about unreachable tasks is also not preserved across master failover.

• repeated Task completed_tasks = 3

  Tasks that have reached terminal state and have all their updates acknowledged by the scheduler.

• repeated Task orphan_tasks = 4

  As of Mesos 1.3.0, this field is deprecated and will always be empty. TODO(neilc): Remove this field in Mesos 2.0.

Contains the version information of the master.

Used in: Response

• required VersionInfo version_info = 1

Provides the weight information about every role.

Used in: Response

• repeated WeightInfo weight_infos = 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_AGENTS = 9

• GET_FRAMEWORKS = 10

• GET_EXECUTORS = 11

  See 'GetExecutors' below.

• GET_OPERATIONS = 19

  See 'GetOperations' below.

• GET_TASKS = 12

  See 'GetTasks' below.

• GET_ROLES = 13

  See 'GetRoles' below.

• GET_WEIGHTS = 14

  See 'GetWeights' below.

• GET_MASTER = 15

  See 'GetMaster' below.

• GET_MAINTENANCE_STATUS = 16

  See 'GetMaintenanceStatus' below.

• GET_MAINTENANCE_SCHEDULE = 17

  See 'GetMaintenanceSchedule' below.

• GET_QUOTA = 18