[MESOS-4421] Document that /reserve, /create-volumes endpoints can return misleading "success"

• Type: Task
• Status: Resolved
• Priority: Major
• Resolution: Fixed
• Fix Version/s: 0.28.0
• Component/s: documentation, master
• Labels: documentation endpoint mesosphere persistent-volumes reservations
• Sprint: Mesosphere Sprint 27, Mesosphere Sprint 28
• Story Points: 3
• Assignee: Neil Conway
• Reporter: Neil Conway
• Shepherd: Jie Yu
• Created: 18/Jan/16 22:34
• Updated: 26/Nov/18 12:20
• Resolved: 26/Nov/18 12:20

Description

The docs for the /reserve endpoint say:

200 OK: Success (the requested resources have been reserved).

This is not true: the master returns 200 when the request has been validated and a CheckpointResourcesMessage has been sent to the agent, but the master does not attempt to verify that the message has been received or that the agent successfully checkpointed. Same behavior applies to /unreserve, /create-volumes, and /destroy-volumes.

We should either:

1. Accurately document what 200 return code means.
2. Change the implementation to wait for the agent's next checkpoint to succeed (and to include the effect of the operation) before returning success to the HTTP client.

Issue Links

• relates to: MESOS-4580 Consider returning `202` (Accepted) for /reserve and related endpoints