diff --git a/proto/mesos.proto b/proto/mesos.proto index 33e1b28..4a16be1 100644 --- a/proto/mesos.proto +++ b/proto/mesos.proto @@ -93,6 +93,24 @@ message ContainerID { } +/** + * Represents time since the epoch, in nanoseconds. + */ +message TimeInfo { + required int64 nanoseconds = 1; + + // TODO(josephw): Add time zone information, if necessary. +} + + +/** + * Represents duration in nanoseconds. + */ +message DurationInfo { + required int64 nanoseconds = 1; +} + + /** * A network address. * @@ -119,6 +137,71 @@ message URL { } +/** + * Represents an interval, from a given start time over a given duration. + * This interval pertains to an unavailability event, such as maintenance, + * and is not a generic interval. + */ +message Unavailability { + required TimeInfo start = 1; + + // When added to `start`, this represents the end of the interval. + // If unspecified, the duration is assumed to be infinite. + optional DurationInfo duration = 2; + + // TODO(josephw): Add additional fields for expressing the purpose and + // urgency of the unavailability event. +} + + +/** + * Represents a single machine, which may hold one or more slaves. + * + * NOTE: In order to match a slave to a machine, both the `hostname` and + * `ip` must match the values advertised by the slave to the master. + * Hostname is not case-sensitive. + */ +message MachineID { + optional string hostname = 1; + optional string ip = 2; +} + + +/** + * Holds information about a single machine, its `mode`, and any other + * relevant information which may affect the behavior of the machine. + */ +message MachineInfo { + // Describes the several states that a machine can be in. A `Mode` + // applies to a machine and to all associated slaves on the machine. + enum Mode { + // In this mode, a machine is behaving normally; + // offering resources, executing tasks, etc. + UP = 1; + + // In this mode, all slaves on the machine are expected to cooperate with + // frameworks to drain resources. In general, draining is done ahead of + // a pending `unavailability`. The resources should be drained so as to + // maximize utilization prior to the maintenance but without knowingly + // violating the frameworks' requirements. + DRAINING = 2; + + // In this mode, a machine is not running any tasks and will not offer + // any of its resources. Slaves on the machine will not be allowed to + // register with the master. + DOWN = 3; + } + + required MachineID id = 1; + optional Mode mode = 2; + + // Signifies that the machine may be unavailable during the given interval. + // See comments in `Unavailability` and for the `unavailability` fields + // in `Offer` and `InverseOffer` for more information. + optional Unavailability unavailability = 3; +} + + /** * Describes a framework. */ @@ -722,6 +805,9 @@ message ResourceUsage { // Current resource usage. If absent, the containerizer // cannot provide resource usage. optional ResourceStatistics statistics = 3; + + // The container id for the executor specified in the executor_info field. + required ContainerID container_id = 4; } repeated Executor executors = 1; @@ -836,6 +922,18 @@ message Offer { repeated Attribute attributes = 7; repeated ExecutorID executor_ids = 6; + // Signifies that the resources in this Offer may be unavailable during + // the given interval. Any tasks launched using these resources may be + // killed when the interval arrives. For example, these resources may be + // part of a planned maintenance schedule. + // + // This field only provides information about a planned unavailability. + // The unavailability interval may not necessarily start at exactly this + // interval, nor last for exactly the duration of this interval. + // The unavailability may also be forever! See comments in + // `Unavailability` for more details. + optional Unavailability unavailability = 9; + // Defines an operation that can be performed against offers. message Operation { enum Type { @@ -876,6 +974,57 @@ message Offer { } +/** + * A request to return some resources occupied by a framework. + */ +message InverseOffer { + // This is the same OfferID as found in normal offers, which allows + // re-use of some of the OfferID-only messages. + required OfferID id = 1; + + // URL for reaching the slave running on the host. This enables some + // optimizations as described in MESOS-3012, such as allowing the + // scheduler driver to bypass the master and talk directly with a slave. + optional URL url = 2; + + // The framework that should release its resources. + // If no specifics are provided (i.e. which slave), all the framework's + // resources are requested back. + required FrameworkID framework_id = 3; + + // Specified if the resources need to be released from a particular slave. + // All the framework's resources on this slave are requested back, + // unless further qualified by the `resources` field. + optional SlaveID slave_id = 4; + + // This InverseOffer represents a planned unavailability event in the + // specified interval. Any tasks running on the given framework or slave + // may be killed when the interval arrives. Therefore, frameworks should + // aim to gracefully terminate tasks prior to the arrival of the interval. + // + // For reserved resources, the resources are expected to be returned to the + // framework after the unavailability interval. This is an expectation, + // not a guarantee. For example, if the unavailiability duration is not set, + // the resources may be removed permenantly. + // + // For other resources, there is no guarantee that requested resources will + // be returned after the unavailiability interval. The allocator has no + // obligation to re-offer these resources to the prior framework after + // the unavailability. + required Unavailability unavailability = 5; + + // A list of resources being requested back from the framework, + // on the slave identified by `slave_id`. If no resources are specified + // then all resources are being requested back. For the purpose of + // maintenance, this field is always empty (maintenance always requests + // all resources back). + repeated Resource resources = 6; + + // TODO(josephw): Add additional options for narrowing down the resources + // being requested back. Such as specific executors, tasks, etc. +} + + /** * Describes a task. Passed from the scheduler all the way to an * executor (see SchedulerDriver::launchTasks and @@ -1002,6 +1151,10 @@ message TaskStatus { // labels should be used to tag TaskStatus message with light-weight // meta-data. optional Labels labels = 12; + + // Container related information that is resolved dynamically such as + // network address. + optional ContainerStatus container_status = 13; } @@ -1135,7 +1288,7 @@ message Image { // Protobuf for specifying an Appc container image. See: // https://github.com/appc/spec/blob/master/spec/aci.md - message AppC { + message Appc { // The name of the image. required string name = 1; @@ -1158,7 +1311,7 @@ message Image { // Only one of the following image messages should be set to match // the type. - optional AppC appc = 2; + optional Appc appc = 2; optional Docker docker = 3; } @@ -1194,6 +1347,52 @@ message Volume { } +/** + * Describes a network request by framework as well as network resolution + * provided by the the executor or Agent. + * + * A framework may request the network isolator on the Agent to assign an IP + * address to the container being launched. Alternatively, it can provide a + * specific IP address to be assigned to the container. The NetworkInfo message + * is not interpreted by the Master or Agent and is intended to be use by Agent + * modules implementing network isolation. If the modules are missing, the + * message is simply ignored. In future, the task launch will fail if there is + * no module providing the network isolation capabilities (MESOS-3390). + * + * An executor, Agent, or an Agent module may append NetworkInfos inside + * TaskStatus::container_status to provide information such as the container IP + * address and isolation groups. + */ +message NetworkInfo { + enum Protocol { + IPv4 = 1; + IPv6 = 2; + } + + // Specify IP address requirement. Set protocol to the desired value to + // request the network isolator on the Agent to assign an IP address to the + // container being launched. If a specific IP address is specified in + // ip_address, this field should not be set. + optional Protocol protocol = 1; + + // Statically assigned IP provided by the Framework. This IP will be assigned + // to the container by the network isolator module on the Agent. This field + // should not be used with the protocol field above. + // NOTE: It is up to the networking 'provider' (IPAM/Isolator) to interpret + // this either as a hint of as a requirement for assigning the IP. + optional string ip_address = 2; + + // A group is the name given to a set of logically-related IPs that are + // allowed to communicate within themselves. For example, one might want + // to create separate groups for isolating dev, testing, qa and prod + // deployment environments. + repeated string groups = 3; + + // To tag certain metadata to be used by Isolator/IPAM, e.g., rack, etc. + optional Labels labels = 4; +}; + + /** * Describes a container configuration and allows extensible * configurations for different container implementations. @@ -1253,6 +1452,20 @@ message ContainerInfo { // the type. optional DockerInfo docker = 3; optional MesosInfo mesos = 5; + + // A list of network requests. A framework can request multiple IP addresses + // for the container. + repeated NetworkInfo network_infos = 7; +} + + +/** + * Container related information that is resolved during container setup. The + * information is sent back to the framework as part of the TaskStatus message. + */ +message ContainerStatus { + // This field can be reliably used to identify the container IP address. + repeated NetworkInfo network_infos = 1; } diff --git a/readme.md b/readme.md index 2d36501..24f1d94 100644 --- a/readme.md +++ b/readme.md @@ -2,7 +2,7 @@ erlang-mesos ------------ An erlang binding for [mesos](http://mesos.apache.org/). -Currently supports the 0.24.1 version - see [releases](https://github.com/mdevilliers/erlang-mesos/releases) for previous releases. +Currently supports the 0.25.0 version - see [releases](https://github.com/mdevilliers/erlang-mesos/releases) for previous releases. [![Build Status](https://travis-ci.org/mdevilliers/erlang-mesos.svg?branch=master)](https://travis-ci.org/mdevilliers/erlang-mesos) diff --git a/src/erlang_mesos.app.src b/src/erlang_mesos.app.src index aa58214..a80e93f 100644 --- a/src/erlang_mesos.app.src +++ b/src/erlang_mesos.app.src @@ -1,7 +1,7 @@ {application, erlang_mesos, [ {description, ""}, - {vsn, "0.24.1"}, + {vsn, "0.25.0"}, {registered, []}, {applications, [kernel,stdlib]} ]}.