You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@mesos.apache.org by jo...@apache.org on 2015/10/21 20:25:34 UTC
mesos git commit: Documented messages in messages.proto.
Repository: mesos
Updated Branches:
refs/heads/master c08296d93 -> 901b9b8bb
Documented messages in messages.proto.
A brief summary of each message was added.
For messages with an associated Event/Call API object, a reference to
the object was added.
Additionally, there is a great deal of documentation overlap between
these messages and the comments in mesos/scheduler.hpp and
v1/scheduler/scheduler.proto. Where necessary, some notes were added
about the backwards compatibility of messages which are not instantiated
in the code base.
Review: https://reviews.apache.org/r/39457
Project: http://git-wip-us.apache.org/repos/asf/mesos/repo
Commit: http://git-wip-us.apache.org/repos/asf/mesos/commit/901b9b8b
Tree: http://git-wip-us.apache.org/repos/asf/mesos/tree/901b9b8b
Diff: http://git-wip-us.apache.org/repos/asf/mesos/diff/901b9b8b
Branch: refs/heads/master
Commit: 901b9b8bbc0997a2912b82032cc7d25690286e41
Parents: c08296d
Author: Joseph Wu <jo...@mesosphere.io>
Authored: Wed Oct 21 14:06:31 2015 -0400
Committer: Joris Van Remoortere <jo...@gmail.com>
Committed: Wed Oct 21 14:10:03 2015 -0400
----------------------------------------------------------------------
src/messages/messages.proto | 339 ++++++++++++++++++++++++++++++++-------
1 file changed, 284 insertions(+), 55 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/mesos/blob/901b9b8b/src/messages/messages.proto
----------------------------------------------------------------------
diff --git a/src/messages/messages.proto b/src/messages/messages.proto
index ea9a67e..9a1564f 100644
--- a/src/messages/messages.proto
+++ b/src/messages/messages.proto
@@ -20,24 +20,28 @@ import "mesos/mesos.proto";
package mesos.internal;
-// TODO(benh): Provide comments for each of these messages. Also,
-// consider splitting these messages into different "packages" which
-// represent which messages get handled by which components (e.g., the
-// "mesos.executor" package includes messages that the
-// executor handles).
-
-
-// TODO(benh): It would be great if this could just be a
-// TaskInfo wherever it gets used! However, doing so would
-// require adding the framework_id field, the executor_id field, and
-// the state field into TaskInfo though (or send them another
-// way). Also, one performance reason why we don't do that now is
-// because storing whatever data is coupled with a TaskInfo
-// could be large and unnecessary.
+// TODO(benh): Consider splitting these messages into different "packages"
+// which represent which messages get handled by which components (e.g., the
+// "mesos.executor" package includes messages that the executor handles).
+
+
// TODO(bmahler): Add executor_uuid here, and send it to the master. This will
// allow us to expose executor work directories for tasks in the webui when
// looking from the master level. Currently only the slave knows which run the
// task belongs to.
+/**
+ * Describes a task, similar to `TaskInfo`.
+ *
+ * `Task` is used in some of the Mesos messages found below.
+ * `Task` is used instead of `TaskInfo` if:
+ * 1) we need additional IDs, such as a specific
+ * framework, executor, or agent; or
+ * 2) we do not need the additional data, such as the command run by the
+ * task, the specific containerization, or health checks. These
+ * additional fields may be large and unnecessary for some Mesos messages.
+ *
+ * `Task` is generally constructed from a `TaskInfo`. See protobuf::createTask.
+ */
message Task {
required string name = 1;
required TaskID task_id = 2;
@@ -65,6 +69,15 @@ message Task {
// TODO(vinod): Create a new UUID message type.
+/**
+ * Describes a task's status.
+ *
+ * `StatusUpdate` is used in some of the Mesos messages found below.
+ * The master and agent use `StatusUpdate` to wrap a `TaskStatus` when
+ * passing it from the agent to the framework that spawned the task.
+ *
+ * See protobuf::createStatusUpdate.
+ */
message StatusUpdate {
required FrameworkID framework_id = 1;
optional ExecutorID executor_id = 2;
@@ -78,7 +91,7 @@ message StatusUpdate {
optional bytes uuid = 6;
// This corresponds to the latest state of the task according to the
- // slave. Note that this state might be different than the state in
+ // agent. Note that this state might be different than the state in
// 'status' because status update manager queues updates. In other
// words, 'status' corresponds to the update at top of the queue and
// 'latest_state' corresponds to the update at bottom of the queue.
@@ -86,32 +99,48 @@ message StatusUpdate {
}
-// This message encapsulates how we checkpoint a status update to disk.
-// NOTE: If type == UPDATE, the 'update' field is required.
-// NOTE: If type == ACK, the 'uuid' field is required.
+/**
+ * Encapsulates how we checkpoint a `StatusUpdate` to disk.
+ *
+ * See the StatusUpdateManager and slave/state.cpp.
+ */
message StatusUpdateRecord {
enum Type {
UPDATE = 0;
ACK = 1;
}
+
required Type type = 1;
+
+ // Required if type == UPDATE.
optional StatusUpdate update = 2;
+
+ // Required if type == ACK.
optional bytes uuid = 3;
}
+// TODO(josephw): Check if this can be removed. This appears to be
+// for backwards compatibility with very early versions of Mesos.
message SubmitSchedulerRequest
{
required string name = 1;
}
+// TODO(josephw): Remove for the same reason as `SubmitSchedulerRequest`.
message SubmitSchedulerResponse
{
required bool okay = 1;
}
+/**
+ * Sends a free-form message from the executor to the framework.
+ * Mesos forwards the message, if necessary, via the agents and the master.
+ *
+ * See scheduler::Event::Message.
+ */
message ExecutorToFrameworkMessage {
required SlaveID slave_id = 1;
required FrameworkID framework_id = 2;
@@ -120,6 +149,12 @@ message ExecutorToFrameworkMessage {
}
+/**
+ * Sends a free-form message from the framework to the executor.
+ * Mesos forwards the message, if necessary, via the agents and the master.
+ *
+ * See scheduler::Call::Message.
+ */
message FrameworkToExecutorMessage {
required SlaveID slave_id = 1;
required FrameworkID framework_id = 2;
@@ -128,47 +163,99 @@ message FrameworkToExecutorMessage {
}
+/**
+ * Subscribes the framework with the master to receive events.
+ *
+ * Used by the pre-Event/Call Mesos scheduler driver.
+ * See scheduler::Call::Subscribe.
+ */
message RegisterFrameworkMessage {
required FrameworkInfo framework = 1;
}
+/**
+ * Subscribes the framework with the master to receive events.
+ * This is used when the framework has previously registered and
+ * the master changes to a newly elected master.
+ *
+ * Used by the pre-Event/Call Mesos scheduler driver.
+ * See scheduler::Call::Subscribe.
+ */
message ReregisterFrameworkMessage {
required FrameworkInfo framework = 2;
required bool failover = 3;
}
+/**
+ * Notifies the framework that the master has registered it.
+ * The `framework_id` holds a unique ID for distinguishing this framework.
+ *
+ * See scheduler::Event::Subscribed.
+ */
message FrameworkRegisteredMessage {
required FrameworkID framework_id = 1;
required MasterInfo master_info = 2;
}
+
+/**
+ * Notifies the framework that the master has reregistered it.
+ * This message is used in the same conditions as `ReregisterFrameworkMessage`.
+ *
+ * See scheduler::Event::Subscribed.
+ */
message FrameworkReregisteredMessage {
required FrameworkID framework_id = 1;
required MasterInfo master_info = 2;
}
+
+/**
+ * Stops the framework and shuts down all its tasks and executors.
+ *
+ * Used by the pre-Event/Call Mesos scheduler driver.
+ * See scheduler::Call::Teardown.
+ */
message UnregisterFrameworkMessage {
required FrameworkID framework_id = 1;
}
+/**
+ * Aborts the scheduler driver and prevents further callbacks to the driver.
+ *
+ * Used exclusively by the pre-Event/Call Mesos scheduler driver.
+ */
message DeactivateFrameworkMessage {
required FrameworkID framework_id = 1;
}
+/**
+ * Requests specific resources from Mesos's allocator.
+ * If the allocator supports resource requests, any corresponding
+ * resources will be sent like a normal resource offer.
+ *
+ * Used by the pre-Event/Call Mesos scheduler driver.
+ * See scheduler::Call::Request.
+ */
message ResourceRequestMessage {
required FrameworkID framework_id = 1;
repeated Request requests = 2;
}
+/**
+ * Sends resources offers to the scheduler.
+ *
+ * See scheduler::Event::Offers.
+ */
message ResourceOffersMessage {
repeated Offer offers = 1;
repeated string pids = 2;
-
+
// The `inverse_offers` field is added here because we currently use it in
// `master.cpp` when constructing the message to send to schedulers. We use
// the original version of the proto API until we do a full refactor of all
@@ -179,6 +266,12 @@ message ResourceOffersMessage {
}
+/**
+ * Launches tasks using resources from the specified offers.
+ *
+ * Used by the pre-Event/Call Mesos scheduler driver.
+ * See scheduler::Call::Accept and scheduler::Call::Decline.
+ */
message LaunchTasksMessage {
required FrameworkID framework_id = 1;
repeated TaskInfo tasks = 3;
@@ -187,16 +280,35 @@ message LaunchTasksMessage {
}
+/**
+ * Notifies the scheduler that a particular offer is not longer valid.
+ *
+ * See scheduler::Event::Rescind.
+ */
message RescindResourceOfferMessage {
required OfferID offer_id = 1;
}
+/**
+ * Removes all filters previously set by the scheduler.
+ *
+ * Used by the pre-Event/Call Mesos scheduler driver.
+ * See scheduler::Call::Revive.
+ */
message ReviveOffersMessage {
required FrameworkID framework_id = 1;
}
+/**
+ * Depending on the `TaskInfo`, this message either notifies an existing
+ * executor to run the task, or starts a new executor and runs the task.
+ * This message is sent when scheduler::Call::Accept is sent with
+ * Offer::Operation::Launch.
+ *
+ * See executor::Event::Launch.
+ */
message RunTaskMessage {
// TODO(karya): Remove framework_id after MESOS-2559 has shipped.
optional FrameworkID framework_id = 1 [deprecated = true];
@@ -206,29 +318,47 @@ message RunTaskMessage {
// The pid of the framework. This was moved to 'optional' in
// 0.24.0 to support schedulers using the HTTP API. For now, we
// continue to always set pid since it was required in 0.23.x.
- // When 'pid' is unset, or set to empty string, the slave will
+ // When 'pid' is unset, or set to empty string, the agent will
// forward executor messages through the master. For schedulers
// still using the driver, this will remain set.
optional string pid = 3;
}
+/**
+ * Kills a specific task.
+ *
+ * See scheduler::Call::Kill and executor::Event::Kill.
+ */
message KillTaskMessage {
// TODO(bmahler): Include the SlaveID here to improve the Master's
- // ability to respond for non-activated slaves.
+ // ability to respond for non-activated agents.
required FrameworkID framework_id = 1;
required TaskID task_id = 2;
}
-// NOTE: If 'pid' is present, scheduler driver sends an
-// acknowledgement to the pid.
+/**
+ * Sends a task status update to the scheduler.
+ *
+ * See scheduler::Event::Update.
+ */
message StatusUpdateMessage {
required StatusUpdate update = 1;
+
+ // If present, scheduler driver automatically sends an acknowledgement
+ // to the `pid`. This only applies to the pre-Event/Call Mesos
+ // scheduler driver.
optional string pid = 2;
}
+/**
+ * This message is used by the scheduler to acknowledge the receipt of a status
+ * update. Mesos forwards the acknowledgement to the executor running the task.
+ *
+ * See scheduler::Call::Acknowledge and executor::Event::Acknowledged.
+ */
message StatusUpdateAcknowledgementMessage {
required SlaveID slave_id = 1;
required FrameworkID framework_id = 2;
@@ -237,47 +367,73 @@ message StatusUpdateAcknowledgementMessage {
}
+/**
+ * Notifies the scheduler that the agent was lost.
+ *
+ * See scheduler::Event::Failure.
+ */
message LostSlaveMessage {
required SlaveID slave_id = 1;
}
-// Allows the framework to query the status for non-terminal tasks.
-// This causes the master to send back the latest task status for
-// each task in 'statuses', if possible. Tasks that are no longer
-// known will result in a TASK_LOST update. If statuses is empty,
-// then the master will send the latest status for each task
-// currently known.
+/**
+ * Allows the scheduler to query the status for non-terminal tasks.
+ * This causes the master to send back the latest task status for
+ * each task in `statuses`, if possible. Tasks that are no longer
+ * known will result in a `TASK_LOST` update. If `statuses` is empty,
+ * then the master will send the latest status for each task
+ * currently known.
+ */
message ReconcileTasksMessage {
required FrameworkID framework_id = 1;
repeated TaskStatus statuses = 2; // Should be non-terminal only.
}
+/**
+ * Notifies the framework about errors during registration.
+ *
+ * See scheduler::Event::Error.
+ */
message FrameworkErrorMessage {
required string message = 2;
}
+/**
+ * Registers the agent with the master.
+ *
+ * If registration fails, a `ShutdownMessage` is sent to the agent.
+ * Failure conditions are documented inline in Master::registerSlave.
+ */
message RegisterSlaveMessage {
required SlaveInfo slave = 1;
- // Resources that are checkpointed by the slave (e.g., persistent
+ // Resources that are checkpointed by the agent (e.g., persistent
// volume or dynamic reservation). Frameworks need to release
// checkpointed resources explicitly.
repeated Resource checkpointed_resources = 3;
- // NOTE: This is a hack for the master to detect the slave's
- // version. If unset the slave is < 0.21.0.
+ // NOTE: This is a hack for the master to detect the agent's
+ // version. If unset the agent is < 0.21.0.
// TODO(bmahler): Do proper versioning: MESOS-986.
optional string version = 2;
}
+/**
+ * Registers the agent with the master.
+ * This is used when the agent has previously registered and
+ * the master changes to a newly elected master.
+ *
+ * If registration fails, a `ShutdownMessage` is sent to the agent.
+ * Failure conditions are documented inline in Master::reregisterSlave.
+ */
message ReregisterSlaveMessage {
required SlaveInfo slave = 2;
- // Resources that are checkpointed by the slave (e.g., persistent
+ // Resources that are checkpointed by the agent (e.g., persistent
// volume or dynamic reservation). Frameworks need to release
// checkpointed resources explicitly.
repeated Resource checkpointed_resources = 7;
@@ -286,68 +442,98 @@ message ReregisterSlaveMessage {
repeated Task tasks = 3;
repeated Archive.Framework completed_frameworks = 5;
- // NOTE: This is a hack for the master to detect the slave's
- // version. If unset the slave is < 0.21.0.
+ // NOTE: This is a hack for the master to detect the agent's
+ // version. If unset the agent is < 0.21.0.
// TODO(bmahler): Do proper versioning: MESOS-986.
optional string version = 6;
}
+/**
+ * Notifies the agent that the master has registered it.
+ * The `slave_id` holds a unique ID for distinguishing this agent.
+ */
message SlaveRegisteredMessage {
required SlaveID slave_id = 1;
optional MasterSlaveConnection connection = 2;
}
+/**
+ * Notifies the agent that the master has reregistered it.
+ * This message is used in the same conditions as `ReregisterSlaveMessage`.
+ */
message SlaveReregisteredMessage {
required SlaveID slave_id = 1;
+ // Contains a list of non-terminal tasks that the master believes to
+ // be running on the agent. The agent should respond `TASK_LOST` to
+ // any tasks that are unknown, so the master knows to remove those.
repeated ReconcileTasksMessage reconciliations = 2;
+
optional MasterSlaveConnection connection = 3;
}
+/**
+ * This message is sent by the agent to the master during agent shutdown.
+ * The master updates its state to reflect the removed agent.
+ */
message UnregisterSlaveMessage {
required SlaveID slave_id = 1;
}
+/**
+ * Describes the connection between the master and agent.
+ */
message MasterSlaveConnection {
// Product of max_slave_ping_timeouts * slave_ping_timeout.
// If no pings are received within the total timeout,
- // the master will remove the slave.
+ // the master will remove the agent.
optional double total_ping_timeout_seconds = 1;
}
-// This message is periodically sent by the master to the slave.
-// If the slave is connected to the master, "connected" is true.
+/**
+ * This message is periodically sent by the master to the agent.
+ * If the agent is connected to the master, "connected" is true.
+ */
message PingSlaveMessage {
required bool connected = 1;
}
-// This message is sent by the slave to the master in response to the
-// PingSlaveMessage.
+/**
+ * This message is sent by the agent to the master in response to the
+ * `PingSlaveMessage`.
+ */
message PongSlaveMessage {}
-// Tells a slave to shut down all executors of the given framework.
+/**
+ * Tells an agent to shut down all executors of the given framework.
+ */
message ShutdownFrameworkMessage {
required FrameworkID framework_id = 1;
}
-// Tells a slave (and consequently executor) to shutdown an executor.
+/**
+ * Tells an agent (and consequently the executor) to shutdown an executor.
+ */
message ShutdownExecutorMessage {
// TODO(vinod): Make these fields required. These are made optional
- // for backwards compatibility between 0.23.0 slave and pre 0.23.0
+ // for backwards compatibility between 0.23.0 agent and pre 0.23.0
// executor driver.
optional ExecutorID executor_id = 1;
optional FrameworkID framework_id = 2;
}
+/**
+ * Broadcasts updated framework information from master to all agents.
+ */
message UpdateFrameworkMessage {
required FrameworkID framework_id = 1;
@@ -356,29 +542,43 @@ message UpdateFrameworkMessage {
}
-// This message is sent to the slave whenever there is an update of
-// the resources that need to be checkpointed (e.g., persistent volume
-// or dynamic reservation).
+/**
+ * This message is sent to the agent whenever there is an update of
+ * the resources that need to be checkpointed (e.g., persistent volume
+ * or dynamic reservation).
+ */
message CheckpointResourcesMessage {
repeated Resource resources = 1;
}
-// This message is sent by the slave to the master to inform the
-// master about the total amount of oversubscribed (allocated and
-// allocatable) resources.
+/**
+ * This message is sent by the agent to the master to inform the
+ * master about the total amount of oversubscribed (allocated and
+ * allocatable) resources.
+ */
message UpdateSlaveMessage {
required SlaveID slave_id = 1;
repeated Resource oversubscribed_resources = 2;
}
+/**
+ * Subscribes the executor with the agent to receive events.
+ *
+ * See executor::Call::Subscribe.
+ */
message RegisterExecutorMessage {
required FrameworkID framework_id = 1;
required ExecutorID executor_id = 2;
}
+/**
+ * Notifies the executor that the agent has registered it.
+ *
+ * See executor::Event::Subscribed.
+ */
message ExecutorRegisteredMessage {
required ExecutorInfo executor_info = 2;
required FrameworkID framework_id = 3;
@@ -388,12 +588,22 @@ message ExecutorRegisteredMessage {
}
+/**
+ * Notifies the executor that the agent has reregistered it.
+ *
+ * See executor::Event::Subscribed.
+ */
message ExecutorReregisteredMessage {
required SlaveID slave_id = 1;
required SlaveInfo slave_info = 2;
}
+/**
+ * Notifies the scheduler about terminated executors.
+ *
+ * See scheduler::Event::Failure.
+ */
message ExitedExecutorMessage {
required SlaveID slave_id = 1;
required FrameworkID framework_id = 2;
@@ -402,11 +612,22 @@ message ExitedExecutorMessage {
}
+/**
+ * Reestablishes the connection between executor and agent after agent failover.
+ * This message originates from the agent.
+ */
message ReconnectExecutorMessage {
required SlaveID slave_id = 1;
}
+/**
+ * Subscribes the executor with the agent to receive events.
+ * This is used after a disconnection. The executor must include
+ * any unacknowledged tasks or updates.
+ *
+ * See executor::Call::Subscribe.
+ */
message ReregisterExecutorMessage {
required ExecutorID executor_id = 1;
required FrameworkID framework_id = 2;
@@ -415,6 +636,11 @@ message ReregisterExecutorMessage {
}
+/**
+ * Sends a free-form message from the master to an agent.
+ * The agent should gracefully terminate in response, which includes
+ * shutting down all executors and tasks on the agent.
+ */
message ShutdownMessage {
optional string message = 1;
}
@@ -433,12 +659,15 @@ message Archive {
repeated Framework frameworks = 1;
}
-// Message describing task current health status that is sent by
-// the task health checker to the command executor.
-// The command executor reports the task status back to the
-// on each receive. If the health checker configured faiure
-// condition meets, then kill_task flag will be set to true which
-// the executor on message receive will kill the task.
+
+/**
+ * Message describing task current health status that is sent by
+ * the task health checker to the command executor.
+ * The command executor reports the task status back to the
+ * on each receive. If the health checker configured failure
+ * condition meets, then `kill_task` flag will be set to true which
+ * the executor on message receive will kill the task.
+ */
message TaskHealthStatus {
required TaskID task_id = 1;