You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@mesos.apache.org by bm...@apache.org on 2018/10/12 00:51:18 UTC
[mesos] 01/06: Added quota limit to the master API protos.
This is an automated email from the ASF dual-hosted git repository.
bmahler pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/mesos.git
commit e69ffd95d0fc009429b800df4348ea4757e6ba21
Author: Benjamin Mahler <bm...@apache.org>
AuthorDate: Sun Nov 19 15:30:27 2017 -0800
Added quota limit to the master API protos.
This introduces a `limit` in `QuotaInfo` and `QuotaRequest`.
A new `UPDATE_QUOTA` master call is added as a replacement of
`SET_QUOTA` and `REMOVE_QUOTA`, which provides the new semantics
of unset limit meaning "no limit" and unset guarantee meaning
"no guarantee".
The new APIs are marked as experimental for now.
Review: https://reviews.apache.org/r/65334
---
include/mesos/master/master.proto | 32 ++++++++++++-
include/mesos/quota/quota.proto | 32 ++-----------
include/mesos/v1/master/master.proto | 32 ++++++++++++-
include/mesos/v1/quota/quota.proto | 92 +++++++++++++++++++++++++++---------
src/master/http.cpp | 7 +++
src/master/validation.cpp | 7 +++
6 files changed, 148 insertions(+), 54 deletions(-)
diff --git a/include/mesos/master/master.proto b/include/mesos/master/master.proto
index ddb531f..80bd7c4 100644
--- a/include/mesos/master/master.proto
+++ b/include/mesos/master/master.proto
@@ -91,6 +91,16 @@ message Call {
STOP_MAINTENANCE = 27; // See 'StopMaintenance' below.
GET_QUOTA = 28;
+
+ // EXPERIMENTAL DO NOT USE.
+ //
+ // This feature is not implementation complete.
+ //
+ // TODO(bmahler): Remove this when complete and deprecate the
+ // `REMOVE_QUOTA` and `SET_QUOTA` calls in favor of this. Be
+ // sure to document what's different for users.
+ UPDATE_QUOTA = 36; // See 'UpdateQuota' below.
+
SET_QUOTA = 29; // See 'SetQuota' below.
REMOVE_QUOTA = 30; // See 'RemoveQuota' below.
@@ -215,11 +225,24 @@ message Call {
repeated MachineID machines = 1;
}
+ // EXPERIMENTAL DO NOT USE.
+ //
+ // This feature is not implementation complete.
+ //
+ // Updates quota given the provided requests, the requests are
+ // applied in an all-or-nothing manner.
+ message UpdateQuota {
+ repeated quota.QuotaRequest quota_requests = 1;
+ }
+
// Sets the quota for resources to be used by a particular role.
+ //
+ // TODO(bmahler): Deprecate this in favor of `UpdateQuota`.
message SetQuota {
required quota.QuotaRequest quota_request = 1;
}
+ // TODO(bmahler): Deprecate this in favor of `UpdateQuota`.
message RemoveQuota {
required string role = 1;
}
@@ -261,10 +284,15 @@ message Call {
optional UpdateMaintenanceSchedule update_maintenance_schedule = 11;
optional StartMaintenance start_maintenance = 12;
optional StopMaintenance stop_maintenance = 13;
- optional SetQuota set_quota = 14;
- optional RemoveQuota remove_quota = 15;
+ optional UpdateQuota update_quota = 20;
optional Teardown teardown = 16;
optional MarkAgentGone mark_agent_gone = 17;
+
+ // TODO(bmahler): Deprecate in favor of `UPDATE_QUOTA`.
+ optional SetQuota set_quota = 14;
+
+ // TODO(bmahler): Deprecate in favor of `UPDATE_QUOTA`.
+ optional RemoveQuota remove_quota = 15;
}
diff --git a/include/mesos/quota/quota.proto b/include/mesos/quota/quota.proto
index f2ed6f5..3e6b899 100644
--- a/include/mesos/quota/quota.proto
+++ b/include/mesos/quota/quota.proto
@@ -25,52 +25,30 @@ option java_outer_classname = "Protos";
/**
- * `QuotaInfo` describes the guaranteed resource allocation that a role
- * may rely on (i.e. minimum share a role is entitled to receive).
- *
- * As for now, `QuotaInfo` is an internal message used by the master and
- * therefore does not require versioning. However, in the future we may
- * want to expose it in the Framework API, which will render it being
- * external facing.
+ * See v1 `QuotaInfo`.
*/
-// TODO(joerg84): Add limits, i.e. upper bounds of resources that a
-// role is allowed to use.
message QuotaInfo {
- // Quota is granted per role and not per framework, similar to
- // dynamic reservations.
optional string role = 1;
-
- // Principal which set the quota. Currently only operators can set quotas.
optional string principal = 2;
-
- // The guarantee that these resources are allocatable for the above role.
- // NOTE: `guarantee.role` should not specify any role except '*',
- // because quota does not reserve specific resources.
repeated Resource guarantee = 3;
+ repeated Resource limit = 4;
}
/**
- * `QuotaRequest` provides a schema for set quota JSON requests.
+ * See v1 `QuotaRequest`.
*/
message QuotaRequest {
- // Disables the capacity heuristic check if set to `true`.
optional bool force = 1 [default = false];
-
- // The role for which to set quota.
optional string role = 2;
-
- // The requested guarantee that these resources will be allocatable for
- // the above role.
repeated Resource guarantee = 3;
+ repeated Resource limit = 4;
}
/**
- * `QuotaStatus` describes the internal representation for the /quota/status
- * response.
+ * See v1 `QuotaStatus`.
*/
message QuotaStatus {
- // Quotas which are currently set, i.e. known to the master.
repeated QuotaInfo infos = 1;
}
diff --git a/include/mesos/v1/master/master.proto b/include/mesos/v1/master/master.proto
index 1367b48..cd41a7e 100644
--- a/include/mesos/v1/master/master.proto
+++ b/include/mesos/v1/master/master.proto
@@ -89,6 +89,16 @@ message Call {
STOP_MAINTENANCE = 27; // See 'StopMaintenance' below.
GET_QUOTA = 28;
+
+ // EXPERIMENTAL DO NOT USE.
+ //
+ // This feature is not implementation complete.
+ //
+ // TODO(bmahler): Remove this when complete and deprecate the
+ // `REMOVE_QUOTA` and `SET_QUOTA` calls in favor of this. Be
+ // sure to document what's different for users.
+ UPDATE_QUOTA = 36; // See 'UpdateQuota' below.
+
SET_QUOTA = 29; // See 'SetQuota' below.
REMOVE_QUOTA = 30; // See 'RemoveQuota' below.
@@ -213,11 +223,24 @@ message Call {
repeated MachineID machines = 1;
}
+ // EXPERIMENTAL DO NOT USE.
+ //
+ // This feature is not implementation complete.
+ //
+ // Updates quota given the provided requests, the requests are
+ // applied in an all-or-nothing manner.
+ message UpdateQuota {
+ repeated quota.QuotaRequest quota_requests = 1;
+ }
+
// Sets the quota for resources to be used by a particular role.
+ //
+ // TODO(bmahler): Deprecate this in favor of `UpdateQuota`.
message SetQuota {
required quota.QuotaRequest quota_request = 1;
}
+ // TODO(bmahler): Deprecate this in favor of `UpdateQuota`.
message RemoveQuota {
required string role = 1;
}
@@ -259,10 +282,15 @@ message Call {
optional UpdateMaintenanceSchedule update_maintenance_schedule = 11;
optional StartMaintenance start_maintenance = 12;
optional StopMaintenance stop_maintenance = 13;
- optional SetQuota set_quota = 14;
- optional RemoveQuota remove_quota = 15;
+ optional UpdateQuota update_quota = 20;
optional Teardown teardown = 16;
optional MarkAgentGone mark_agent_gone = 17;
+
+ // TODO(bmahler): Deprecate in favor of `UPDATE_QUOTA`.
+ optional SetQuota set_quota = 14;
+
+ // TODO(bmahler): Deprecate in favor of `UPDATE_QUOTA`.
+ optional RemoveQuota remove_quota = 15;
}
diff --git a/include/mesos/v1/quota/quota.proto b/include/mesos/v1/quota/quota.proto
index 5dd772f..44a416d 100644
--- a/include/mesos/v1/quota/quota.proto
+++ b/include/mesos/v1/quota/quota.proto
@@ -25,52 +25,98 @@ option java_outer_classname = "Protos";
/**
- * `QuotaInfo` describes the guaranteed resource allocation that a role
- * may rely on (i.e. minimum share a role is entitled to receive).
- *
- * As for now, `QuotaInfo` is an internal message used by the master and
- * therefore does not require versioning. However, in the future we may
- * want to expose it in the Framework API, which will render it being
- * external facing.
+ * Describes the resource guarantees and limits for a role.
+ * Persisted in the registry.
*/
-// TODO(joerg84): Add limits, i.e. upper bounds of resources that a
-// role is allowed to use.
message QuotaInfo {
- // Quota is granted per role and not per framework, similar to
- // dynamic reservations.
optional string role = 1;
// Principal which set the quota. Currently only operators can set quotas.
optional string principal = 2;
- // The guarantee that these resources are allocatable for the above role.
- // NOTE: `guarantee.role` should not specify any role except '*',
- // because quota does not reserve specific resources.
repeated Resource guarantee = 3;
+ repeated Resource limit = 4;
}
/**
- * `QuotaRequest` provides a schema for set quota JSON requests.
+ * Describes an update to a role's quota. This is a copy of
+ * `QuotaInfo` which omits the principal since it is determined
+ * during authentication. Also allows the user to force the update
+ * in the case of a guarantee overcommit or a limit exceeding the
+ * parent's limit (or overall cluster size if a top level role).
*/
message QuotaRequest {
- // Disables the capacity heuristic check if set to `true`.
- optional bool force = 1 [default = false];
+ // See `guarantee` and `limit` for the behavior of `force`
+ // on these two fields.
+ optional bool force = 1;
- // The role for which to set quota.
optional string role = 2;
- // The requested guarantee that these resources will be allocatable for
- // the above role.
+ // Mesos will try its best to ensure that the role can be
+ // allocated at least as many resources as the guarantee.
+ // Despite this, it's possible for the guarantee to not be
+ // satisfiable, if:
+ // (1) The operator has overcommitted guarantees.
+ // (2) There is a loss of agents that such that the
+ // guarantees overcommit the cluster.
+ // (3) The scheduler is pickier than mesos knows about,
+ // e.g. the scheduler needs resources from agents
+ // with specific attributes.
+ //
+ // The provided guarantee will be validated to ensure it
+ // is not overcommitting the cluster. The operator can
+ // disable this via `QuotaRequest.force`.
+ //
+ // If the guarantee is omitted, there is no guarantee.
+ //
+ // Operators may want to set up alerting to let them know
+ // when a guarantee cannot be satisfied.
+ //
+ // NOTE: The resources must be scalars without additional
+ // metadata like reservations, disk information, etc.
repeated Resource guarantee = 3;
+
+ // EXPERIMENTAL DO NOT USE.
+ //
+ // This feature is not implementation complete.
+ //
+ // Imposes a limit on the amount of resources allocated to the
+ // role. Mesos will try its best to ensure that the role does
+ // not exceed this limit. Despite this, the limit can be exceeded
+ // when:
+ // (1) The limit is lowered below the allocation.
+ // (2) Some agents are partitioned and re-connect with
+ // resources allocated to the role.
+ //
+ // The provided limit will be validated to ensure it does not
+ // exceed the total cluster size. The operator can disable
+ // this check via `QuotaRequest.force`.
+ //
+ // If the limit is omitted, there is no limit.
+ //
+ // Operators may want to set up alerting to let them know
+ // when the limit is exceeded.
+ //
+ // NOTE: The resources must be scalars without additional
+ // metadata like reservations, disk information, etc.
+ //
+ // NOTE: The limit was introduced alongside the v1 `UPDATE_QUOTA`
+ // `master::Call`. Note that the old v0 `POST /quota` endpoint and
+ // the v1 `SetQuota` `master::Call` continue to implicitly set
+ // limit to the guarantee for backwards compatibility. Users
+ // should switch to the v1 `UPDATE_QUOTA` `master::Call` which
+ // does not implicitly set the limit.
+ repeated Resource limit = 4;
}
/**
- * `QuotaStatus` describes the internal representation for the /quota/status
- * response.
+ * `QuotaStatus` describes the internal representation for the
+ * /quota/status response and `GET_QUOTA` `master::Response`.
*/
message QuotaStatus {
- // Quotas which are currently set, i.e. known to the master.
+ // Returns all non-default quotas. Those ommitted from this
+ // list have the default of: no guarantee and no limit.
repeated QuotaInfo infos = 1;
}
diff --git a/src/master/http.cpp b/src/master/http.cpp
index d912789..666097f 100644
--- a/src/master/http.cpp
+++ b/src/master/http.cpp
@@ -366,9 +366,16 @@ Future<Response> Master::Http::api(
case mesos::master::Call::GET_QUOTA:
return quotaHandler.status(call, principal, acceptType);
+ case mesos::master::Call::UPDATE_QUOTA:
+ return NotImplemented();
+
+ // TODO(bmahler): Add this to a deprecated call section
+ // at the bottom once deprecated by `UPDATE_QUOTA`.
case mesos::master::Call::SET_QUOTA:
return quotaHandler.set(call, principal);
+ // TODO(bmahler): Add this to a deprecated call section
+ // at the bottom once deprecated by `UPDATE_QUOTA`.
case mesos::master::Call::REMOVE_QUOTA:
return quotaHandler.remove(call, principal);
diff --git a/src/master/validation.cpp b/src/master/validation.cpp
index c4b8d8c..2950234 100644
--- a/src/master/validation.cpp
+++ b/src/master/validation.cpp
@@ -243,12 +243,19 @@ Option<Error> validate(
case mesos::master::Call::GET_QUOTA:
return None();
+ case mesos::master::Call::UPDATE_QUOTA:
+ return Error("Not implemented");
+
+ // TODO(bmahler): Add this to a deprecated call section
+ // at the bottom once deprecated by `UPDATE_QUOTA`.
case mesos::master::Call::SET_QUOTA:
if (!call.has_set_quota()) {
return Error("Expecting 'set_quota' to be present");
}
return None();
+ // TODO(bmahler): Add this to a deprecated call section
+ // at the bottom once deprecated by `UPDATE_QUOTA`.
case mesos::master::Call::REMOVE_QUOTA:
if (!call.has_remove_quota()) {
return Error("Expecting 'remove_quota' to be present");