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.

import "mesos/interface/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(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;
  required FrameworkID framework_id = 3;
  optional ExecutorID executor_id = 4;
  required SlaveID slave_id = 5;
  required TaskState state = 6; // Latest state of the task.
  repeated Resource resources = 7;
  repeated TaskStatus statuses = 8;

  // These fields correspond to the state and uuid of the latest
  // status update forwarded to the master.
  // NOTE: Either both the fields must be set or both must be unset.
  optional TaskState status_update_state = 9;
  optional bytes status_update_uuid = 10;

  optional Labels labels = 11;

  // Service discovery information for the task. It is not interpreted
  // or acted upon by Mesos. It is up to a service discovery system
  // to use this information as needed and to handle tasks without
  // service discovery information.
  optional DiscoveryInfo discovery = 12;
}


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

  // 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
  // the messages being sent.
  // It is not fully implemented in the old scheduler; only the V1 scheduler
  // currently implements inverse offers.
  repeated InverseOffer inverse_offers = 3;
}


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


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


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