You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@mesos.apache.org by as...@apache.org on 2020/05/06 15:16:48 UTC
[mesos] branch 1.9.x updated: Added docs for UPDATE_FRAMEWORK call.
This is an automated email from the ASF dual-hosted git repository.
asekretenko pushed a commit to branch 1.9.x
in repository https://gitbox.apache.org/repos/asf/mesos.git
The following commit(s) were added to refs/heads/1.9.x by this push:
new 2474583 Added docs for UPDATE_FRAMEWORK call.
2474583 is described below
commit 247458311cab68b6108bd5cf0723cbfad904f856
Author: Andrei Sekretenko <as...@apache.org>
AuthorDate: Wed Mar 25 12:15:50 2020 +0100
Added docs for UPDATE_FRAMEWORK call.
Review: https://reviews.apache.org/r/72267
---
docs/scheduler-http-api.md | 111 +++++++++++++++++++++++++++++++++++++++++++--
1 file changed, 108 insertions(+), 3 deletions(-)
diff --git a/docs/scheduler-http-api.md b/docs/scheduler-http-api.md
index 9831d52..a77a9df 100644
--- a/docs/scheduler-http-api.md
+++ b/docs/scheduler-http-api.md
@@ -55,7 +55,7 @@ The response returned from the `SUBSCRIBE` call (see [below](#subscribe)) is enc
This is the first step in the communication process between the scheduler and the master. This is also to be considered as subscription to the "/scheduler" event stream.
-To subscribe with the master, the scheduler sends an HTTP POST with a `SUBSCRIBE` message including the required FrameworkInfo. Note that if "subscribe.framework_info.id" and "FrameworkID" are not set, the master considers the scheduler as a new one and subscribes it by assigning it a FrameworkID. The HTTP response is a stream in RecordIO format; the event stream begins with either a `SUBSCRIBED` event or an `ERROR` event (see details in **Events** section). The response also includes th [...]
+To subscribe with the master, the scheduler sends an HTTP POST with a `SUBSCRIBE` message including the required FrameworkInfo and the list of initially suppressed roles (which must be a subset of roles in FrameworkInfo, see the section for `SUPPRESS` call). Note that if "subscribe.framework_info.id" and "FrameworkID" are not set, the master considers the scheduler as a new one and subscribes it by assigning it a FrameworkID. The HTTP response is a stream in RecordIO format; the event st [...]
```
SUBSCRIBE Request (JSON):
@@ -73,9 +73,10 @@ Connection: close
"framework_info" : {
"user" : "foo",
"name" : "Example HTTP Framework",
- "roles": ["test"],
+ "roles": ["test1", "test2"],
"capabilities" : [{"type": "MULTI_ROLE"}]
- }
+ },
+ "suppressed_roles" : ["test2"]
}
}
@@ -102,6 +103,11 @@ with a `SUBSCRIBED` event. For further details, see the **Disconnections** secti
NOTE: In the old version of the API, (re-)registered callbacks also included MasterInfo, which contained information about the master the driver currently connected to. With the new API, since schedulers explicitly subscribe with the leading master (see details below in **Master Detection** section), it's not relevant anymore.
+NOTE: By providing a different FrameworkInfo and/or set of suppressed roles,
+re-subscribing scheduler can change some of the fields of FrameworkInfo and the
+set of suppressed roles. Allowed changes and their effects are consistent with
+those that can be performed via `UPDATE_FRAMEWORK` call (see below).
+
If subscription fails for whatever reason (e.g., invalid request), an HTTP 4xx response is returned with the error message as part of the body and the connection is closed.
A scheduler can make additional HTTP requests to the "/scheduler" endpoint only after it has opened a persistent connection to it by sending a `SUBSCRIBE` request and received a `SUBSCRIBED` response. Calls made without subscription will result in "403 Forbidden" instead of a "202 Accepted" response. A scheduler might also receive a "400 Bad Request" response if the HTTP request is malformed (e.g., malformed HTTP headers).
@@ -494,6 +500,105 @@ HTTP/1.1 202 Accepted
```
+### UPDATE_FRAMEWORK
+
+Sent by the scheduler to change fields of its `FrameworkInfo` and/or the set of
+suppressed roles. Allowed changes and their effects are consistent with changing
+FrameworkInfo and/or set of suppressed roles when re-subscribing.
+
+#### Disallowed updates
+Updating the following `FrameworkInfo` fields is not allowed:
+ * `principal` (mainly because "changing a principal" effectively means
+ a transfer of a framework by an original principal to the new one; secure
+ mechanism for such transfer is yet to be developed)
+ * `user`
+ * `checkpoint`
+
+`UPDATE_FRAMEWORK` call trying to update any of these fields is not valid,
+unlike an attempt to change `user`/`checkpoint` when resubscribing, in which
+case the new value is ignored.
+
+#### Updating framework roles
+Updating `framework_info.roles` and `suppressed_roles` is supported.
+In a valid `UPDATE_FRAMEWORK` call, new suppressed roles must be a (potentially
+empty) subset of new framework roles.
+
+Updating roles has the following effects:
+ * After the call is processed, master will be sending offers to all
+ non-suppressed roles of the framework.
+ * Offers to old framework roles removed by this call will be rescinded.
+ * Offers to roles from suppressed set will NOT be rescinded.
+ * For roles that were transitioned out of suppressed, offer filters (set by
+ ACCEPT/DECLINE) will be cleared.
+ will be cleared.
+ * Other framework objects that use roles removed by this call (for example,
+ tasks) are not affected.
+
+#### Updating other fields
+ * Updating `name`, `hostname`, `webui_url` and `labels` is fully supported
+ by Mesos; these updates are simply propagated to Mesos API endpoints.
+ * Updating `failover_timeout` and `offer_filters` is supported. Note that
+ there is no way to guarantee that offers issued when the old `offer_filters`
+ were in place will not be received by the framework after the master applies
+ the update.
+ * Schedulers can add capabilities via updating `capabilities` field. The call
+ attempting to remove a capability is not considered invalid; however, there
+ is no guarantee that it is safe for the framework to remove the capability.
+ If you really need your framewok to be able to remove a capability, please
+ reach out to the Mesos dev/user list (dev@mesos.apache.org or
+ user@mesos.apache.org).
+ In future, to prevent accidental unsafe downgrade of frameworks, Mesos will
+ need to implement minimum capabilities for schedulers (similarly to minimum
+ master/agent capabilities, see
+ [MESOS-8878](https://issues.apache.org/jira/browse/MESOS-8878)).
+
+
+```
+
+UPDATE_FRAMEWORK Request (JSON):
+
+POST /api/v1/scheduler HTTP/1.1
+
+Host: masterhost:5050
+Content-Type: application/json
+Accept: application/json
+Connection: close
+
+{
+ "type" : "UPDATE_FRAMEWORK",
+ "update_framework" : {
+ "framework_info" : {
+ "user" : "foo",
+ "name" : "Example HTTP Framework",
+ "roles": ["test1", "test2"],
+ "capabilities" : [{"type": "MULTI_ROLE"}]
+ },
+ "suppressed_roles" : ["test2"]
+ }
+}
+
+UPDATE_FRAMEWORK Response:
+HTTP/1.1 200 OK
+```
+
+Response codes:
+ * "200 OK" after the update has been successfully applied by the master and
+ sent to the agents.
+ * "400 Bad request" if the call was not valid or authorizing the call failed.
+ * "403 Forbidden" if the principal was declined authorization to use the
+ provided FrameworkInfo. (Typical authorizer implementations will check
+ authorization to use specified roles.)
+
+No partial updates occur in error cases: either all fields are updated or none
+of them.
+
+NOTE: In Mesos 1.9, effects of changing roles or suppressed roles set via
+UPDATE_FRAMEWORK could be potentially reordered with related effects of
+`ACCEPT`/`DECLINE`/`SUPPRESS`/`REVIVE` or another `UPDATE_FRAMEWORK`;
+to avoid such reordering, it was necessary to wait for UPDATE_FRAMEWORK response
+before issuing the next call. This issue has been fixed in Mesos 1.10.0 (see
+[MESOS-10056](https://issues.apache.org/jira/browse/MESOS-10056)).
+
## Events
Schedulers are expected to keep a **persistent** connection to the "/scheduler" endpoint (even after getting a `SUBSCRIBED` HTTP Response event). This is indicated by the "Connection: keep-alive" and "Transfer-Encoding: chunked" headers with *no* "Content-Length" header set. All subsequent events that are relevant to this framework generated by Mesos are streamed on this connection. The master encodes each Event in RecordIO format, i.e., string representation of the length of the event i [...]