src/messages/messages.proto

// 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.

syntax = "proto2";

import "mesos/mesos.proto";
import "mesos/resource_provider/resource_provider.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.
 *
 * A task status update may be used for guaranteed delivery of some
 * task-related information, e.g., task's health update. Such information
 * may be shadowed by subsequent task status updates, that do not preserve
 * fields of the previously sent message.
 */
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 filters for the specified role. If a role is not provided, then
 * this is equivalent to passing all of the framework's subscribed roles.
 *
 * Used by the pre-Event/Call Mesos scheduler driver.
 * See scheduler::Call::Revive.
 *
 * NOTE: There is no `roles` field in V0 API as we will
 * eventually move to V1 API.
 */
message ReviveOffersMessage {
  required FrameworkID framework_id = 1;
  repeated string roles = 2;
}


/**
 * 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;
}


/**
 * This message either notifies an existing executor to run a task
 * group, or starts a new executor and runs the task group. This
 * message is sent when scheduler::Call::Accept is sent with
 * Offer::Operation::LaunchGroup.
 *
 * See executor::Event::LaunchGroup.
 */
message RunTaskGroupMessage {
  required FrameworkInfo framework = 1;
  required ExecutorInfo executor = 2;
  required TaskGroupInfo task_group = 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;
}


/**
 * This message is used in two situations:
 *
 *   (a) schedulers can query masters about the master's view of the
 *       state of one or more tasks. If the `statuses` field is empty
 *       ("implicit reconciliation"), the master will respond with
 *       status updates for all of the non-terminal tasks it knows
 *       about.
 *
 *   (b) the master can query an agent about the agent's view of the
 *       state of one or more tasks.
 *
 * In both cases, the response to this message is returned via zero or
 * more status update messages with the `reason` field set to
 * `REASON_RECONCILIATION`.
 */
message ReconcileTasksMessage {
  required FrameworkID framework_id = 1;
  repeated TaskStatus statuses = 2; // Should be non-terminal only.

  // Should only be set for reconciliation requests sent to agents by
  // the master (case (b) above). This is necessary because the agent
  // might not know anything about the framework, and the correct
  // response to the reconciliation request might depend on the
  // framework's capabilities (e.g., PARTITION_AWARE).
  optional FrameworkInfo framework = 3;
}


/**
 * 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 {
  // NOTE: The `Resources` in `SlaveInfo` cannot contain reservation
  // refinements. Therefore, `slave.resources` will always use the
  // "pre-reservation-refinement" format.
  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. If any of the checkpointed
  // resources use reservation refinements, every resource in this field
  // will be represented using the "post-reservation-refinement" format;
  // otherwise, this field will be in "pre-reservation-refinement" format.
  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;

  // This field allows an agent to advertise its set of
  // capabilities (e.g., ability to launch tasks of 'multi-role'
  // frameworks).
  repeated SlaveInfo.Capability agent_capabilities = 4;
}


/**
 * Reregisters the agent with the master.
 *
 * This is used when the agent has previously registered and the agent
 * has reason to suspect that it should re-establish its connection
 * (e.g., a new master is elected or the agent hasn't seen a ping from
 * the master for a long period of time).
 *
 * If registration fails, a `ShutdownMessage` is sent to the agent.
 * Failure conditions are documented inline in Master::reregisterSlave.
 */
message ReregisterSlaveMessage {
  // NOTE: The `Resources` in `SlaveInfo` cannot contain reservation
  // refinements. Therefore, `slave.resources` will always use the
  // "pre-reservation-refinement" format.
  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. If any of the checkpointed
  // resources use reservation refinements, every resource in this field
  // will be represented using the "post-reservation-refinement" format;
  // otherwise, this field will be in "pre-reservation-refinement" format.
  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;

  // This field allows an agent to advertise its set of
  // capabilities (e.g., ability to launch tasks of 'multi-role'
  // frameworks).
  repeated SlaveInfo.Capability agent_capabilities = 9;
}


/**
 * 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 are
  // running on the agent.  The agent should respond `TASK_DROPPED` to any
  // tasks that are unknown, so the master knows to remove them.
  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;

  // Updated framework info.
  optional FrameworkInfo framework_info = 3;
}


/**
 * 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), or total resources.
 */
message UpdateSlaveMessage {
  required SlaveID slave_id = 1;

  // This message can contain one of `oversubscribed_resources` or
  // `total_resources`. Callers are expected to set the `type` field
  // to denote which field should be examined. For backwards
  // compatibility we interpret an unset `type` field as if it was
  // `OVERSUBSCRIBED`.
  //
  // It is suggested that callers use the `total_resources` field
  // exclusively as the `oversubscribed_resources` field might be
  // removed in the future.
  enum Type {
    UNKNOWN = 0;
    OVERSUBSCRIBED = 1;
    TOTAL = 2;
  }

  optional Type type = 3;

  repeated Resource oversubscribed_resources = 2;
  repeated Resource total_resources = 4;
}


/**
 * A wrapper message that is sent for a local resource provider Call
 * by the agent to the master. The agent serves as a proxy between the
 * local resource provider and the master.
 */
message ResourceProviderCallMessage {
  required resource_provider.Call call = 1;

  // This field will be set for the initial 'Subscribe' Call where the
  // resource provider ID hasn't been assigned yet. This 'uuid' will
  // be echoed back in the corresponding 'Subscribed' Event, allowing
  // the agent to tell which resource provider the Event is for.
  optional bytes uuid = 2;
}


/**
 * A wrapper message that is sent for a local resource provider Event
 * by the master to the agent. The agent serves as a proxy between the
 * local resource provider and the master.
 */
message ResourceProviderEventMessage {
  required ResourceProviderID resource_provider_id = 1;
  required resource_provider.Event event = 2;

  // See the comments in 'ResourceProviderCallMessage'.
  optional bytes uuid = 3;
}


/**
 * 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 library or program to the executor.
 *
 * The `kill_task` flag is set to true when the health check library or
 * program deems the task to be irrevocably unhealthy, for example, if
 * the number of consecutive failed health checks meets the configured
 * `consecutive_failure` value. If this flag is set, executor should
 * consider killing the associated task.
 */
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;
}