| // Licensed to the Apache Software Foundation (ASF) under one |
| // or more contributor license agreements. See the NOTICE file |
| // distributed with this work for additional information |
| // regarding copyright ownership. The ASF licenses this file |
| // to you under the Apache License, Version 2.0 (the |
| // "License"); you may not use this file except in compliance |
| // with the License. You may obtain a copy of the License at |
| // |
| // http://www.apache.org/licenses/LICENSE-2.0 |
| // |
| // Unless required by applicable law or agreed to in writing, software |
| // distributed under the License is distributed on an "AS IS" BASIS, |
| // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| // See the License for the specific language governing permissions and |
| // limitations under the License. |
| |
| import "mesos/mesos.proto"; |
| |
| package mesos.internal; |
| |
| // 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(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; |
| optional SlaveID slave_id = 3; |
| |
| // Since 0.23.0 we set 'status.uuid' in the executor |
| // driver for all retryable status updates. |
| required TaskStatus status = 4; |
| |
| required double timestamp = 5; |
| |
| // Since 0.26.0 this is deprecated in favor of 'status.uuid'. |
| optional bytes uuid = 6; |
| |
| // This corresponds to the latest state of the task according to the |
| // 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. |
| optional TaskState latest_state = 7; |
| } |
| |
| |
| /** |
| * 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; |
| required ExecutorID executor_id = 3; |
| required bytes data = 4; |
| } |
| |
| |
| /** |
| * 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; |
| required ExecutorID executor_id = 3; |
| required bytes data = 4; |
| } |
| |
| |
| /** |
| * 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; |
| } |
| |
| |
| /** |
| * Sends inverse offers to the scheduler. |
| * NOTE: This message is only sent through the V1 HTTP API. Driver |
| * based schedulers will not receive it. |
| * |
| * See scheduler::Event::InverseOffers. |
| */ |
| message InverseOffersMessage { |
| repeated InverseOffer inverse_offers = 1; |
| repeated string pids = 2; |
| } |
| |
| |
| /** |
| * 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; |
| required Filters filters = 5; |
| repeated OfferID offer_ids = 6; |
| } |
| |
| |
| /** |
| * Notifies the scheduler that a particular offer is not longer valid. |
| * |
| * See scheduler::Event::Rescind. |
| */ |
| message RescindResourceOfferMessage { |
| required OfferID offer_id = 1; |
| } |
| |
| |
| /** |
| * Notifies the scheduler that a particular inverse offer is not longer |
| * valid. |
| * NOTE: This message is only sent through the V1 HTTP API. Driver |
| * based schedulers will not receive it. |
| * |
| * See scheduler::Event::RescindInverseOffer. |
| */ |
| message RescindInverseOfferMessage { |
| required OfferID inverse_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]; |
| required FrameworkInfo framework = 2; |
| required TaskInfo task = 4; |
| |
| // 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 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 agents. |
| required FrameworkID framework_id = 1; |
| required TaskID task_id = 2; |
| |
| // If set, overrides the `KillPolicy` specified when the task was launched. |
| optional KillPolicy kill_policy = 3; |
| } |
| |
| |
| /** |
| * 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; |
| required TaskID task_id = 3; |
| required bytes uuid = 4; |
| } |
| |
| |
| /** |
| * Notifies the scheduler that the agent was lost. |
| * |
| * See scheduler::Event::Failure. |
| */ |
| message LostSlaveMessage { |
| required SlaveID slave_id = 1; |
| } |
| |
| |
| /** |
| * 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 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 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 agent (e.g., persistent |
| // volume or dynamic reservation). Frameworks need to release |
| // checkpointed resources explicitly. |
| repeated Resource checkpointed_resources = 7; |
| |
| repeated ExecutorInfo executor_infos = 4; |
| repeated Task tasks = 3; |
| repeated FrameworkInfo frameworks = 8; |
| repeated Archive.Framework completed_frameworks = 5; |
| |
| // 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_agent_ping_timeouts * agent_ping_timeout. |
| // If no pings are received within the total timeout, |
| // the master will remove the agent. |
| optional double total_ping_timeout_seconds = 1; |
| } |
| |
| |
| /** |
| * 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 agent to the master in response to the |
| * `PingSlaveMessage`. |
| */ |
| message PongSlaveMessage {} |
| |
| |
| /** |
| * Tells an agent to shut down all executors of the given framework. |
| */ |
| message ShutdownFrameworkMessage { |
| required FrameworkID framework_id = 1; |
| } |
| |
| |
| /** |
| * 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 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; |
| |
| // See the comment on RunTaskMessage.pid. |
| optional string pid = 2; |
| } |
| |
| |
| /** |
| * 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 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; |
| required FrameworkInfo framework_info = 4; |
| required SlaveID slave_id = 5; |
| required SlaveInfo slave_info = 6; |
| } |
| |
| |
| /** |
| * 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; |
| required ExecutorID executor_id = 3; |
| required int32 status = 4; |
| } |
| |
| |
| /** |
| * 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; |
| repeated TaskInfo tasks = 3; |
| repeated StatusUpdate updates = 4; |
| } |
| |
| |
| /** |
| * 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; |
| } |
| |
| |
| // TODO(adam-mesos): Move this to an 'archive' package. |
| /** |
| * Describes Completed Frameworks, etc. for archival. |
| */ |
| message Archive { |
| message Framework { |
| required FrameworkInfo framework_info = 1; |
| optional string pid = 2; |
| repeated Task tasks = 3; |
| } |
| repeated Framework frameworks = 1; |
| } |
| |
| |
| /** |
| * Message describing a task's current health status, which is sent by |
| * the health check program to the executor. |
| * On each receive, if the number of consecutive failed health checks |
| * meets the `consecutive_failure` configuration, then `kill_task` |
| * flag will be set to true. |
| */ |
| message TaskHealthStatus { |
| required TaskID task_id = 1; |
| |
| required bool healthy = 2; |
| |
| // Flag to initiate task kill. |
| optional bool kill_task = 3 [default = false]; |
| |
| // Number of consecutive failures observed by the health check program. |
| // This will not be populated if task is healthy. |
| optional int32 consecutive_failures = 4; |
| } |
| |
| |
| /** |
| * Message to signal completion of an event within a module. |
| */ |
| message HookExecuted { |
| optional string module = 1; |
| } |