include/mesos/mesos.proto - mesos - Git at Google

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

 package mesos;

 option java_package = "org.apache.mesos";
 option java_outer_classname = "Protos";


 /**
  * Status is used to indicate the state of the scheduler and executor
  * driver after function calls.
  */
 enum Status {
   DRIVER_NOT_STARTED = 1;
   DRIVER_RUNNING = 2;
   DRIVER_ABORTED = 3;
   DRIVER_STOPPED = 4;
 }


 /**
  * A unique ID assigned to a framework. A framework can reuse this ID
  * in order to do failover (see MesosSchedulerDriver).
  */
 message FrameworkID {
   required string value = 1;
 }


 /**
  * A unique ID assigned to an offer.
  */
 message OfferID {
   required string value = 1;
 }


 /**
  * A unique ID assigned to a slave. Currently, a slave gets a new ID
  * whenever it (re)registers with Mesos. Framework writers shouldn't
  * assume any binding between a slave ID and and a hostname.
  */
 message SlaveID {
   required string value = 1;
 }


 /**
  * A framework generated ID to distinguish a task. The ID must remain
  * unique while the task is active. However, a framework can reuse an
  * ID _only_ if a previous task with the same ID has reached a
  * terminal state (e.g., TASK_FINISHED, TASK_LOST, TASK_KILLED, etc.).
  */
 message TaskID {
   required string value = 1;
 }


 /**
  * A framework generated ID to distinguish an executor. Only one
  * executor with the same ID can be active on the same slave at a
  * time.
  */
 message ExecutorID {
   required string value = 1;
 }


 /**
  * Describes a framework. If the user field is set to an empty string
  * Mesos will automagically set it to the current user. Note that the
  * ID is only available after a framework has registered, however, it
  * is included here in order to facilitate scheduler failover (i.e.,
  * if it is set then the MesosSchedulerDriver expects the scheduler is
  * performing failover). The amount of time that the master will wait
  * for the scheduler to failover before removing the framework is
  * specified by failover_timeout.
  * If checkpoint is set, framework pid, executor pids and status updates
  * are checkpointed to disk.
  * Checkpointing allows a restarted slave to reconnect with old executors
  * and recover status updates, at the cost of disk I/O.
  * The role field is used to group frameworks for allocation decisions,
  * depending on the allocation policy being used.
  */
 message FrameworkInfo {
   required string user = 1;
   required string name = 2;
   optional FrameworkID id = 3;
   optional double failover_timeout = 4 [default = 0.0];
   optional bool checkpoint = 5 [default = false];
   optional string role = 6 [default = "*"];
 }


 /**
  * Describes a command, executed via: '/bin/sh -c value'. Any uri's
  * specified are fetched before executing the command.
  * If executable field for an uri is set, executable file permission
  * is set on the downloaded file. Also, if the downloaded file has ".tgz"
  * extension it is extracted into the executor's working directory.
  * In addition, any environment variables are set before executing
  * the command (so they can be used to "parameterize" your command).
  */
 message CommandInfo {
   message URI {
     required string value = 1;
     optional bool executable = 2;
   }

   repeated URI uris = 1;
   optional Environment environment = 2;
   required string value = 3;
 }


 /**
  * Describes information about an executor. The 'data' field can be
  * used to pass arbitrary bytes to an executor.
  */
 message ExecutorInfo {
   required ExecutorID executor_id = 1;
   optional FrameworkID framework_id = 8; // TODO(benh): Make this required.
   required CommandInfo command = 7;
   repeated Resource resources = 5;
   optional string name = 9;

   // Source is an identifier style string used by frameworks to track
   // the source of an executor. This is useful when it's possible for
   // different executor ids to be related semantically.
   // NOTE: Source is exposed alongside the resource usage of the
   // executor via JSON on the slave. This allows users to import
   // usage information into a time series database for monitoring.
   optional string source = 10;
   optional bytes data = 4;
 }


 /**
  * Describes a master. This will probably have more fields in the
  * future which might be used, for example, to link a framework webui
  * to a master webui.
  */
 message MasterInfo {
   required string id = 1;
   required uint32 ip = 2;
   required uint32 port = 3 [default = 5050];
 }


 /**
  * Describes a slave. The 'webui_hostname' and 'webui_port' are
  * provided in the event a host has different private and public
  * hostnames (e.g., Amazon EC2). Note that the 'id' field is only
  * available after a slave is registered with the master, and is made
  * available here to facilitate re-registration.
  * If checkpoint is set, the slave is checkpointing its own
  * information and potentially frameworks' information (if a
  * framework has checkpointing enabled).
  */
 message SlaveInfo {
   required string hostname = 1;
   optional int32 port = 8 [default = 5051];
   required string webui_hostname = 2;             // Deprecated!
   optional int32 webui_port = 4 [default = 8081]; // Deprecated!
   repeated Resource resources = 3;
   repeated Attribute attributes = 5;
   optional SlaveID id = 6;
   optional bool checkpoint = 7 [default = false];
 }


 /**
  * Describes an Attribute or Resource "value". A value is described
  * using the standard protocol buffer "union" trick.
  */
 message Value {
   enum Type {
     SCALAR = 0;
     RANGES = 1;
     SET = 2;
     TEXT = 3;
   }

   message Scalar {
     required double value = 1;
   }

   message Range {
     required uint64 begin = 1;
     required uint64 end = 2;
   }

   message Ranges {
     repeated Range range = 1;
   }

   message Set {
     repeated string item = 1;
   }

   message Text {
     required string value = 1;
   }

   required Type type = 1;
   optional Scalar scalar = 2;
   optional Ranges ranges = 3;
   optional Set set = 4;
   optional Text text = 5;
 }


 /**
  * Describes an attribute that can be set on a machine. For now,
  * attributes and resources share the same "value" type, but this may
  * change in the future and attributes may only be string based.
  */
 message Attribute {
   required string name = 1;
   required Value.Type type = 2;
   optional Value.Scalar scalar = 3;
   optional Value.Ranges ranges = 4;
   optional Value.Set set = 6;
   optional Value.Text text = 5;
 }


 /**
  * Describes a resource on a machine. A resource can take on one of
  * three types: scalar (double), a list of finite and discrete ranges
  * (e.g., [1-10, 20-30]), or a set of items. A resource is described
  * using the standard protocol buffer "union" trick.
  *
  * TODO(benh): Add better support for "expected" resources (e.g.,
  * cpus, memory, disk, network).
  */
 message Resource {
   required string name = 1;
   required Value.Type type = 2;
   optional Value.Scalar scalar = 3;
   optional Value.Ranges ranges = 4;
   optional Value.Set set = 5;
   optional string role = 6 [default = "*"];
 }


 /*
  * A snapshot of resource usage statistics.
  */
 message ResourceStatistics {
   required double timestamp = 1; // Snapshot time, in seconds since the Epoch.

   // CPU Usage Information:
   // Total CPU time spent in user mode, and kernel mode.
   optional double cpus_user_time_secs = 2;
   optional double cpus_system_time_secs = 3;

   // Number of CPUs allocated.
   required double cpus_limit = 4;

   // cpu.stat on process throttling (for contention issues).
   optional uint32 cpus_nr_periods = 7;
   optional uint32 cpus_nr_throttled = 8;
   optional double cpus_throttled_time_secs = 9;

   // Memory Usage Information:
   optional uint64 mem_rss_bytes = 5; // Resident Set Size.

   // Amount of memory resources allocated.
   optional uint64 mem_limit_bytes = 6;

   // TODO(bmahler): Add disk usage.
   // TODO(bmahler): Add network usage?
 }


 /**
  * Describes a snapshot of the resource usage for an executor.
  *
  * TODO(bmahler): Note that we want to be sending this information
  * to the master, and subsequently to the relevant scheduler. So
  * this proto is designed to be easy for the scheduler to use, this
  * is why we provide the slave id, executor info / task info.
  */
 message ResourceUsage {
   required SlaveID slave_id = 1;
   required FrameworkID framework_id = 2;

   // Resource usage is for an executor. For tasks launched with
   // an explicit executor, the executor id is provided. For tasks
   // launched without an executor, our internal executor will be
   // used. In this case, we provide the task id here instead, in
   // order to make this message easier for schedulers to work with.

   optional ExecutorID executor_id = 3; // If present, this executor was
   optional string executor_name = 4;   // explicitly specified.

   optional TaskID task_id = 5; // If present, the task did not have an executor.

   // If missing, the isolation module cannot provide resource usage.
   optional ResourceStatistics statistics = 6;
 }


 /**
  * Describes a request for resources that can be used by a framework
  * to proactively influence the allocator.  If 'slave_id' is provided
  * then this request is assumed to only apply to resources on that
  * slave.
  */
 message Request {
   optional SlaveID slave_id = 1;
   repeated Resource resources = 2;
 }


 /**
  * Describes some resources available on a slave. An offer only
  * contains resources from a single slave.
  */
 message Offer {
   required OfferID id = 1;
   required FrameworkID framework_id = 2;
   required SlaveID slave_id = 3;
   required string hostname = 4;
   repeated Resource resources = 5;
   repeated Attribute attributes = 7;
   repeated ExecutorID executor_ids = 6;
 }


 /**
  * Describes a task. Passed from the scheduler all the way to an
  * executor (see SchedulerDriver::launchTasks and
  * Executor::launchTask). Either ExecutorInfo or CommandInfo should be set.
  * A different executor can be used to launch this task, and subsequent tasks
  * meant for the same executor can reuse the same ExecutorInfo struct.
  */
 message TaskInfo {
   required string name = 1;
   required TaskID task_id = 2;
   required SlaveID slave_id = 3;
   repeated Resource resources = 4;
   optional ExecutorInfo executor = 5;
   optional CommandInfo command = 7;
   optional bytes data = 6;
 }


 /**
  * Describes possible task states. IMPORTANT: Mesos assumes tasks that
  * enter terminal states (see below) imply the task is no longer
  * running and thus clean up any thing associated with the task
  * (ultimately offering any resources being consumed by that task to
  * another task).
  */
 enum TaskState {
   TASK_STAGING = 6;  // Initial state. Framework status updates should not use.
   TASK_STARTING = 0;
   TASK_RUNNING = 1;
   TASK_FINISHED = 2; // TERMINAL.
   TASK_FAILED = 3;   // TERMINAL.
   TASK_KILLED = 4;   // TERMINAL.
   TASK_LOST = 5;     // TERMINAL.
 }


 /**
  * Describes the current status of a task.
  */
 message TaskStatus {
   required TaskID task_id = 1;
   required TaskState state = 2;
   optional string message = 4; // Possible message explaining state.
   optional bytes data = 3;
 }


 /**
  * Describes possible filters that can be applied to unused resources
  * (see SchedulerDriver::launchTasks) to influence the allocator.
  */
 message Filters {
   // Time to consider unused resources refused. Note that all unused
   // resources will be considered refused and use the default value
   // (below) regardless of whether Filters was passed to
   // SchedulerDriver::launchTasks. You MUST pass Filters with this
   // field set to change this behavior (i.e., get another offer which
   // includes unused resources sooner or later than the default).
   optional double refuse_seconds = 1 [default = 5.0];
 }


 /**
 * Describes a collection of environment variables. This is used with
 * CommandInfo in order to set environment variables before running a
 * command.
 */
 message Environment {
   message Variable {
     required string name = 1;
     required string value = 2;
   }

   repeated Variable variables = 1;
 }


 /**
  * A generic (key, value) pair used in various places for parameters.
  */
 message Parameter {
   required string key = 1;
   required string value = 2;
 }


 /**
  * Collection of Parameter.
  */
 message Parameters {
   repeated Parameter parameter = 1;
 }
	/**
	* 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.
	*/

	package mesos;

	option java_package = "org.apache.mesos";
	option java_outer_classname = "Protos";


	/**
	* Status is used to indicate the state of the scheduler and executor
	* driver after function calls.
	*/
	enum Status {
	DRIVER_NOT_STARTED = 1;
	DRIVER_RUNNING = 2;
	DRIVER_ABORTED = 3;
	DRIVER_STOPPED = 4;
	}


	/**
	* A unique ID assigned to a framework. A framework can reuse this ID
	* in order to do failover (see MesosSchedulerDriver).
	*/
	message FrameworkID {
	required string value = 1;
	}


	/**
	* A unique ID assigned to an offer.
	*/
	message OfferID {
	required string value = 1;
	}


	/**
	* A unique ID assigned to a slave. Currently, a slave gets a new ID
	* whenever it (re)registers with Mesos. Framework writers shouldn't
	* assume any binding between a slave ID and and a hostname.
	*/
	message SlaveID {
	required string value = 1;
	}


	/**
	* A framework generated ID to distinguish a task. The ID must remain
	* unique while the task is active. However, a framework can reuse an
	* ID _only_ if a previous task with the same ID has reached a
	* terminal state (e.g., TASK_FINISHED, TASK_LOST, TASK_KILLED, etc.).
	*/
	message TaskID {
	required string value = 1;
	}


	/**
	* A framework generated ID to distinguish an executor. Only one
	* executor with the same ID can be active on the same slave at a
	* time.
	*/
	message ExecutorID {
	required string value = 1;
	}


	/**
	* Describes a framework. If the user field is set to an empty string
	* Mesos will automagically set it to the current user. Note that the
	* ID is only available after a framework has registered, however, it
	* is included here in order to facilitate scheduler failover (i.e.,
	* if it is set then the MesosSchedulerDriver expects the scheduler is
	* performing failover). The amount of time that the master will wait
	* for the scheduler to failover before removing the framework is
	* specified by failover_timeout.
	* If checkpoint is set, framework pid, executor pids and status updates
	* are checkpointed to disk.
	* Checkpointing allows a restarted slave to reconnect with old executors
	* and recover status updates, at the cost of disk I/O.
	* The role field is used to group frameworks for allocation decisions,
	* depending on the allocation policy being used.
	*/
	message FrameworkInfo {
	required string user = 1;
	required string name = 2;
	optional FrameworkID id = 3;
	optional double failover_timeout = 4 [default = 0.0];
	optional bool checkpoint = 5 [default = false];
	optional string role = 6 [default = "*"];
	}


	/**
	* Describes a command, executed via: '/bin/sh -c value'. Any uri's
	* specified are fetched before executing the command.
	* If executable field for an uri is set, executable file permission
	* is set on the downloaded file. Also, if the downloaded file has ".tgz"
	* extension it is extracted into the executor's working directory.
	* In addition, any environment variables are set before executing
	* the command (so they can be used to "parameterize" your command).
	*/
	message CommandInfo {
	message URI {
	required string value = 1;
	optional bool executable = 2;
	}

	repeated URI uris = 1;
	optional Environment environment = 2;
	required string value = 3;
	}


	/**
	* Describes information about an executor. The 'data' field can be
	* used to pass arbitrary bytes to an executor.
	*/
	message ExecutorInfo {
	required ExecutorID executor_id = 1;
	optional FrameworkID framework_id = 8; // TODO(benh): Make this required.
	required CommandInfo command = 7;
	repeated Resource resources = 5;
	optional string name = 9;

	// Source is an identifier style string used by frameworks to track
	// the source of an executor. This is useful when it's possible for
	// different executor ids to be related semantically.
	// NOTE: Source is exposed alongside the resource usage of the
	// executor via JSON on the slave. This allows users to import
	// usage information into a time series database for monitoring.
	optional string source = 10;
	optional bytes data = 4;
	}


	/**
	* Describes a master. This will probably have more fields in the
	* future which might be used, for example, to link a framework webui
	* to a master webui.
	*/
	message MasterInfo {
	required string id = 1;
	required uint32 ip = 2;
	required uint32 port = 3 [default = 5050];
	}


	/**
	* Describes a slave. The 'webui_hostname' and 'webui_port' are
	* provided in the event a host has different private and public
	* hostnames (e.g., Amazon EC2). Note that the 'id' field is only
	* available after a slave is registered with the master, and is made
	* available here to facilitate re-registration.
	* If checkpoint is set, the slave is checkpointing its own
	* information and potentially frameworks' information (if a
	* framework has checkpointing enabled).
	*/
	message SlaveInfo {
	required string hostname = 1;
	optional int32 port = 8 [default = 5051];
	required string webui_hostname = 2; // Deprecated!
	optional int32 webui_port = 4 [default = 8081]; // Deprecated!
	repeated Resource resources = 3;
	repeated Attribute attributes = 5;
	optional SlaveID id = 6;
	optional bool checkpoint = 7 [default = false];
	}


	/**
	* Describes an Attribute or Resource "value". A value is described
	* using the standard protocol buffer "union" trick.
	*/
	message Value {
	enum Type {
	SCALAR = 0;
	RANGES = 1;
	SET = 2;
	TEXT = 3;
	}

	message Scalar {
	required double value = 1;
	}

	message Range {
	required uint64 begin = 1;
	required uint64 end = 2;
	}

	message Ranges {
	repeated Range range = 1;
	}

	message Set {
	repeated string item = 1;
	}

	message Text {
	required string value = 1;
	}

	required Type type = 1;
	optional Scalar scalar = 2;
	optional Ranges ranges = 3;
	optional Set set = 4;
	optional Text text = 5;
	}


	/**
	* Describes an attribute that can be set on a machine. For now,
	* attributes and resources share the same "value" type, but this may
	* change in the future and attributes may only be string based.
	*/
	message Attribute {
	required string name = 1;
	required Value.Type type = 2;
	optional Value.Scalar scalar = 3;
	optional Value.Ranges ranges = 4;
	optional Value.Set set = 6;
	optional Value.Text text = 5;
	}


	/**
	* Describes a resource on a machine. A resource can take on one of
	* three types: scalar (double), a list of finite and discrete ranges
	* (e.g., [1-10, 20-30]), or a set of items. A resource is described
	* using the standard protocol buffer "union" trick.
	*
	* TODO(benh): Add better support for "expected" resources (e.g.,
	* cpus, memory, disk, network).
	*/
	message Resource {
	required string name = 1;
	required Value.Type type = 2;
	optional Value.Scalar scalar = 3;
	optional Value.Ranges ranges = 4;
	optional Value.Set set = 5;
	optional string role = 6 [default = "*"];
	}


	/*
	* A snapshot of resource usage statistics.
	*/
	message ResourceStatistics {
	required double timestamp = 1; // Snapshot time, in seconds since the Epoch.

	// CPU Usage Information:
	// Total CPU time spent in user mode, and kernel mode.
	optional double cpus_user_time_secs = 2;
	optional double cpus_system_time_secs = 3;

	// Number of CPUs allocated.
	required double cpus_limit = 4;

	// cpu.stat on process throttling (for contention issues).
	optional uint32 cpus_nr_periods = 7;
	optional uint32 cpus_nr_throttled = 8;
	optional double cpus_throttled_time_secs = 9;

	// Memory Usage Information:
	optional uint64 mem_rss_bytes = 5; // Resident Set Size.

	// Amount of memory resources allocated.
	optional uint64 mem_limit_bytes = 6;

	// TODO(bmahler): Add disk usage.
	// TODO(bmahler): Add network usage?
	}


	/**
	* Describes a snapshot of the resource usage for an executor.
	*
	* TODO(bmahler): Note that we want to be sending this information
	* to the master, and subsequently to the relevant scheduler. So
	* this proto is designed to be easy for the scheduler to use, this
	* is why we provide the slave id, executor info / task info.
	*/
	message ResourceUsage {
	required SlaveID slave_id = 1;
	required FrameworkID framework_id = 2;

	// Resource usage is for an executor. For tasks launched with
	// an explicit executor, the executor id is provided. For tasks
	// launched without an executor, our internal executor will be
	// used. In this case, we provide the task id here instead, in
	// order to make this message easier for schedulers to work with.

	optional ExecutorID executor_id = 3; // If present, this executor was
	optional string executor_name = 4; // explicitly specified.

	optional TaskID task_id = 5; // If present, the task did not have an executor.

	// If missing, the isolation module cannot provide resource usage.
	optional ResourceStatistics statistics = 6;
	}


	/**
	* Describes a request for resources that can be used by a framework
	* to proactively influence the allocator. If 'slave_id' is provided
	* then this request is assumed to only apply to resources on that
	* slave.
	*/
	message Request {
	optional SlaveID slave_id = 1;
	repeated Resource resources = 2;
	}


	/**
	* Describes some resources available on a slave. An offer only
	* contains resources from a single slave.
	*/
	message Offer {
	required OfferID id = 1;
	required FrameworkID framework_id = 2;
	required SlaveID slave_id = 3;
	required string hostname = 4;
	repeated Resource resources = 5;
	repeated Attribute attributes = 7;
	repeated ExecutorID executor_ids = 6;
	}


	/**
	* Describes a task. Passed from the scheduler all the way to an
	* executor (see SchedulerDriver::launchTasks and
	* Executor::launchTask). Either ExecutorInfo or CommandInfo should be set.
	* A different executor can be used to launch this task, and subsequent tasks
	* meant for the same executor can reuse the same ExecutorInfo struct.
	*/
	message TaskInfo {
	required string name = 1;
	required TaskID task_id = 2;
	required SlaveID slave_id = 3;
	repeated Resource resources = 4;
	optional ExecutorInfo executor = 5;
	optional CommandInfo command = 7;
	optional bytes data = 6;
	}


	/**
	* Describes possible task states. IMPORTANT: Mesos assumes tasks that
	* enter terminal states (see below) imply the task is no longer
	* running and thus clean up any thing associated with the task
	* (ultimately offering any resources being consumed by that task to
	* another task).
	*/
	enum TaskState {
	TASK_STAGING = 6; // Initial state. Framework status updates should not use.
	TASK_STARTING = 0;
	TASK_RUNNING = 1;
	TASK_FINISHED = 2; // TERMINAL.
	TASK_FAILED = 3; // TERMINAL.
	TASK_KILLED = 4; // TERMINAL.
	TASK_LOST = 5; // TERMINAL.
	}


	/**
	* Describes the current status of a task.
	*/
	message TaskStatus {
	required TaskID task_id = 1;
	required TaskState state = 2;
	optional string message = 4; // Possible message explaining state.
	optional bytes data = 3;
	}


	/**
	* Describes possible filters that can be applied to unused resources
	* (see SchedulerDriver::launchTasks) to influence the allocator.
	*/
	message Filters {
	// Time to consider unused resources refused. Note that all unused
	// resources will be considered refused and use the default value
	// (below) regardless of whether Filters was passed to
	// SchedulerDriver::launchTasks. You MUST pass Filters with this
	// field set to change this behavior (i.e., get another offer which
	// includes unused resources sooner or later than the default).
	optional double refuse_seconds = 1 [default = 5.0];
	}


	/**
	* Describes a collection of environment variables. This is used with
	* CommandInfo in order to set environment variables before running a
	* command.
	*/
	message Environment {
	message Variable {
	required string name = 1;
	required string value = 2;
	}

	repeated Variable variables = 1;
	}


	/**
	* A generic (key, value) pair used in various places for parameters.
	*/
	message Parameter {
	required string key = 1;
	required string value = 2;
	}


	/**
	* Collection of Parameter.
	*/
	message Parameters {
	repeated Parameter parameter = 1;
	}