improve-network-info.patch

diff --git a/include/mesos/mesos.proto b/include/mesos/mesos.proto
index 4a16be1..8181f3c 100644
--- a/include/mesos/mesos.proto
+++ b/include/mesos/mesos.proto
@@ -1351,13 +1351,17 @@ 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).
+ * A framework may request the network isolator on the Agent to isolate the
+ * container in a network namespace and create a virtual network interface.
+ * The `NetworkInfo` message describes the properties of that virtual
+ * interface, including the IP addresses and network isolation policy
+ * (network group membership).
+ *
+ * The NetworkInfo message is not interpreted by the Master or Agent and is
+ * intended to be used 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
@@ -1369,23 +1373,56 @@ message NetworkInfo {
     IPv6 = 2;
   }
 
+  // Specifies either a request for an IP address, or the actual assigned
+  // IP address.
+  //
+  // On a request (included in ContainerInfo) specifying neither `protocol`
+  // nor `ip_address` means that the isolator is free to assign any available
+  // address.
+  message IpAddress {
+    // 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.
+    //
+    // If an explicit address is requested but is unavailable, the network
+    // isolator should fail the task.
+    optional string ip_address = 2;
+  }
+
+  // When included in a ContainerInfo, each of these represent a
+  // request for an IP address. Each request can specify an explicit address
+  // or the IP protocol to use.
+  //
+  // When included in a TaskStatus message, these inform the framework
+  // scheduler about the IP addresses that are bound to the container
+  // interface. When there are no custom network isolator modules installed,
+  // this field is filled in automatically with the Agent IP address.
+  repeated IpAddress ip_addresses = 5;
+
   // 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;
+  optional Protocol protocol = 1 [deprecated = true]; // Since 0.25.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;
+  optional string ip_address = 2 [deprecated = true]; // Since 0.25.1
 
-  // 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.
+  // A group is the name given to a set of logically-related interfaces that
+  // are allowed to communicate among themselves. Network traffic is allowed
+  // between two container interfaces that share at least one network group.
+  // 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.