Documented task, executor, and volume IDs reuse is discouraged.

This is generally a bad idea for (at least) two reasons:

(1) Determining when the previous entity with the ID has terminated
    can be non-trivial. Several frameworks have done this incorrectly
    in the past.

(2) When reusing IDs, logs can be more difficult to read because the
    same ID can refer to different entities at different times.

Review: https://reviews.apache.org/r/44834/

include/mesos/mesos.proto

@@ -60,28 +60,29 @@ message SlaveID {
 
 
 /**
- * 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.).
+ * A framework-generated ID to distinguish a task. The ID must remain
+ * unique while the task is active. A framework can reuse an ID _only_
+ * if the previous task with the same ID has reached a terminal state
+ * (e.g., TASK_FINISHED, TASK_LOST, TASK_KILLED, etc.). However,
+ * reusing task IDs is strongly discouraged (MESOS-2198).
  */
 message TaskID {
   required string value = 1;
 }
 
 
 /**
- * A framework generated ID to distinguish an executor. Only one
+ * 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.
+ * time. However, reusing executor IDs is discouraged.
  */
 message ExecutorID {
   required string value = 1;
 }
 
 
 /**
- * A slave generated ID to distinguish a container. The ID must be unique
+ * A slave-generated ID to distinguish a container. The ID must be unique
  * between any active or completed containers on the slave. In particular,
  * containers for different runs of the same (framework, executor) pair must be
  * unique.
@@ -670,19 +671,19 @@ message Resource {
 
   message DiskInfo {
     // Describes a persistent disk volume.
+    //
     // A persistent disk volume will not be automatically garbage
-    // collected if the task/executor/slave terminates, but is
+    // collected if the task/executor/slave terminates, but will be
     // re-offered to the framework(s) belonging to the 'role'.
-    // A framework can set the ID (if it is not set yet) to express
-    // the intention to create a new persistent disk volume from a
-    // regular disk resource. To reuse a previously created volume, a
-    // framework can launch a task/executor when it receives an offer
-    // with a persistent volume, i.e., ID is set.
-    // NOTE: Currently, we do not allow a persistent disk volume
-    // without a reservation (i.e., 'role' should not be '*').
+    //
+    // NOTE: Currently, we do not allow persistent disk volumes
+    // without a reservation (i.e., 'role' cannot be '*').
     message Persistence {
-      // A unique ID for the persistent disk volume.
-      // NOTE: The ID needs to be unique per role on each slave.
+      // A unique ID for the persistent disk volume. This ID must be
+      // unique per role on each slave. Although it is possible to use
+      // the same ID on different slaves in the cluster and to reuse
+      // IDs after a volume with that ID has been destroyed, both
+      // practices are discouraged.
       required string id = 1;
 
       // This field indicates the principal of the operator or

include/mesos/v1/mesos.proto

@@ -60,28 +60,29 @@ message AgentID {
 
 
 /**
- * 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.).
+ * A framework-generated ID to distinguish a task. The ID must remain
+ * unique while the task is active. A framework can reuse an ID _only_
+ * if the previous task with the same ID has reached a terminal state
+ * (e.g., TASK_FINISHED, TASK_LOST, TASK_KILLED, etc.). However,
+ * reusing task IDs is strongly discouraged (MESOS-2198).
  */
 message TaskID {
   required string value = 1;
 }
 
 
 /**
- * A framework generated ID to distinguish an executor. Only one
+ * A framework-generated ID to distinguish an executor. Only one
  * executor with the same ID can be active on the same agent at a
- * time.
+ * time. However, reusing executor IDs is discouraged.
  */
 message ExecutorID {
   required string value = 1;
 }
 
 
 /**
- * An agent generated ID to distinguish a container. The ID must be
+ * An agent-generated ID to distinguish a container. The ID must be
  * unique between any active or completed containers on the agent. In
  * particular, containers for different runs of the same (framework,
  * executor) pair must be unique.
@@ -664,19 +665,19 @@ message Resource {
 
   message DiskInfo {
     // Describes a persistent disk volume.
+    //
     // A persistent disk volume will not be automatically garbage
-    // collected if the task/executor/agent terminates, but is
+    // collected if the task/executor/agent terminates, but will be
     // re-offered to the framework(s) belonging to the 'role'.
-    // A framework can set the ID (if it is not set yet) to express
-    // the intention to create a new persistent disk volume from a
-    // regular disk resource. To reuse a previously created volume, a
-    // framework can launch a task/executor when it receives an offer
-    // with a persistent volume, i.e., ID is set.
-    // NOTE: Currently, we do not allow a persistent disk volume
-    // without a reservation (i.e., 'role' should not be '*').
+    //
+    // NOTE: Currently, we do not allow persistent disk volumes
+    // without a reservation (i.e., 'role' cannot be '*').
     message Persistence {
-      // A unique ID for the persistent disk volume.
-      // NOTE: The ID needs to be unique per role on each agent.
+      // A unique ID for the persistent disk volume. This ID must be
+      // unique per role on each agent. Although it is possible to use
+      // the same ID on different agents in the cluster and to reuse
+      // IDs after a volume with that ID has been destroyed, both
+      // practices are discouraged.
       required string id = 1;
 
       // This field indicates the principal of the operator or