blob: ce724c098a7731490a206c19b542161d3730665f [file] [log] [blame]
// 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";
package mesos.executor;
option java_package = "org.apache.mesos.executor";
option java_outer_classname = "Protos";
/**
* Executor event API.
*
* An event is described using the standard protocol buffer "union"
* trick, see https://developers.google.com/protocol-buffers/docs/techniques#union.
*/
message Event {
// Possible event types, followed by message definitions if
// applicable.
enum Type {
// This must be the first enum value in this list, to
// ensure that if 'type' is not set, the default value
// is UNKNOWN. This enables enum values to be added
// in a backwards-compatible way. See: MESOS-4997.
UNKNOWN = 0;
SUBSCRIBED = 1; // See 'Subscribed' below.
LAUNCH = 2; // See 'Launch' below.
LAUNCH_GROUP = 8; // See 'LaunchGroup' below.
KILL = 3; // See 'Kill' below.
ACKNOWLEDGED = 4; // See 'Acknowledged' below.
MESSAGE = 5; // See 'Message' below.
ERROR = 6; // See 'Error' below.
// Received when the agent asks the executor to shutdown/kill itself.
// The executor is then required to kill all its active tasks, send
// `TASK_KILLED` status updates and gracefully exit. The executor
// should terminate within a `MESOS_EXECUTOR_SHUTDOWN_GRACE_PERIOD`
// (an environment variable set by the agent upon executor startup);
// it can be configured via `ExecutorInfo.shutdown_grace_period`. If
// the executor fails to do so, the agent will forcefully destroy the
// container where the executor is running. The agent would then send
// `TASK_LOST` updates for any remaining active tasks of this executor.
//
// NOTE: The executor must not assume that it will always be allotted
// the full grace period, as the agent may decide to allot a shorter
// period and failures / forcible terminations may occur.
//
// TODO(alexr): Consider adding a duration field into the `Shutdown`
// message so that the agent can communicate when a shorter period
// has been allotted.
SHUTDOWN = 7;
// Received periodically to make sure the connection is alive and to
// prevent any possible network intermediaries from marking the
// connection as stale (when there are no other messages being sent).
HEARTBEAT = 9;
}
// First event received when the executor subscribes.
// The 'id' field in the 'framework_info' will be set.
message Subscribed {
required ExecutorInfo executor_info = 1;
required FrameworkInfo framework_info = 2;
required SlaveInfo slave_info = 3;
// Uniquely identifies the container of an executor run.
optional ContainerID container_id = 4;
}
// Received when the framework attempts to launch a task. Once
// the task is successfuly launched, the executor must respond with
// a TASK_RUNNING update (See TaskState in mesos.proto).
message Launch {
required TaskInfo task = 1;
}
// Received when the framework attempts to launch a group of tasks atomically.
// Similar to `Launch` above the executor must send TASK_RUNNING updates for
// tasks that are successfully launched.
message LaunchGroup {
required TaskGroupInfo task_group = 1;
}
// Received when the scheduler wants to kill a specific task. Once
// the task is terminated, the executor should send a TASK_KILLED
// (or TASK_FAILED) update. The terminal update is necessary so
// Mesos can release the resources associated with the task.
message Kill {
required TaskID task_id = 1;
// If set, overrides any previously specified kill policy for this task.
// This includes 'TaskInfo.kill_policy' and 'Executor.kill.kill_policy'.
optional KillPolicy kill_policy = 2;
}
// Received when the slave acknowledges the receipt of status
// update. Schedulers are responsible for explicitly acknowledging
// the receipt of status updates that have 'update.status().uuid()'
// field set. Unacknowledged updates can be retried by the executor.
// They should also be sent by the executor whenever it
// re-subscribes.
message Acknowledged {
required TaskID task_id = 1;
required bytes uuid = 2;
}
// Received when a custom message generated by the scheduler is
// forwarded by the slave. Note that this message is not
// interpreted by Mesos and is only forwarded (without reliability
// guarantees) to the executor. It is up to the scheduler to retry
// if the message is dropped for any reason.
message Message {
required bytes data = 1;
}
// Received in case the executor sends invalid calls (e.g.,
// required values not set).
// TODO(arojas): Remove this once the old executor driver is no
// longer supported. With HTTP API all errors will be signaled via
// HTTP response codes.
message Error {
required string message = 1;
}
// Type of the event, indicates which optional field below should be
// present if that type has a nested message definition.
// Enum fields should be optional, see: MESOS-4997.
optional Type type = 1;
optional Subscribed subscribed = 2;
optional Acknowledged acknowledged = 3;
optional Launch launch = 4;
optional LaunchGroup launch_group = 8;
optional Kill kill = 5;
optional Message message = 6;
optional Error error = 7;
}
/**
* Executor call API.
*
* Like Event, a Call is described using the standard protocol buffer
* "union" trick (see above).
*/
message Call {
// Possible call types, followed by message definitions if
// applicable.
enum Type {
// See comments above on `Event::Type` for more details on this enum value.
UNKNOWN = 0;
SUBSCRIBE = 1; // See 'Subscribe' below.
UPDATE = 2; // See 'Update' below.
MESSAGE = 3; // See 'Message' below.
// Optional message that can be used to make sure the executor's
// connection is still alive and to prevent any possible network
// intermediaries from marking the connection as stale (when there
// are no other messages being sent). Heartbeats are only necessary
// if the executor uses a persistent connection to send calls.
HEARTBEAT = 4;
}
// Request to subscribe with the slave. If subscribing after a disconnection,
// it must include a list of all the tasks and updates which haven't been
// acknowledged by the scheduler.
message Subscribe {
repeated TaskInfo unacknowledged_tasks = 1;
repeated Update unacknowledged_updates = 2;
}
// Notifies the scheduler that a task has transitioned from one
// state to another. Status updates should be used by executors
// to reliably communicate the status of the tasks that they
// manage. It is crucial that a terminal update (see TaskState
// in mesos.proto) is sent to the scheduler as soon as the task
// terminates, in order for Mesos to release the resources allocated
// to the task. It is the responsibility of the scheduler to
// explicitly acknowledge the receipt of a status update. See
// 'Acknowledged' in the 'Events' section above for the semantics.
message Update {
required TaskStatus status = 1;
}
// Sends arbitrary binary data to the scheduler. Note that Mesos
// neither interprets this data nor makes any guarantees about the
// delivery of this message to the scheduler.
// See 'Message' in the 'Events' section.
message Message {
required bytes data = 2;
}
// Identifies the executor which generated this call.
required ExecutorID executor_id = 1;
required FrameworkID framework_id = 2;
// Type of the call, indicates which optional field below should be
// present if that type has a nested message definition.
// In case type is SUBSCRIBED, no message needs to be set.
// See comments on `Event::Type` above on the reasoning behind this field being optional.
optional Type type = 3;
optional Subscribe subscribe = 4;
optional Update update = 5;
optional Message message = 6;
}