From 883e4860d3b7d0f46a439bd8d8055799e323fd4c Mon Sep 17 00:00:00 2001 From: Aldo Culquicondor Date: Mon, 4 May 2020 16:57:47 -0400 Subject: [PATCH] Clarify usage of MaxSkew and WheUnsatisfiable Signed-off-by: Aldo Culquicondor --- api/openapi-spec/swagger.json | 4 ++-- pkg/apis/core/types.go | 17 +++++++++++------ staging/src/k8s.io/api/core/v1/generated.proto | 17 +++++++++++------ staging/src/k8s.io/api/core/v1/types.go | 17 +++++++++++------ .../api/core/v1/types_swagger_doc_generated.go | 4 ++-- 5 files changed, 37 insertions(+), 22 deletions(-) diff --git a/api/openapi-spec/swagger.json b/api/openapi-spec/swagger.json index 7bd919ede5e..427e713cbe2 100644 --- a/api/openapi-spec/swagger.json +++ b/api/openapi-spec/swagger.json @@ -10178,7 +10178,7 @@ "description": "LabelSelector is used to find matching pods. Pods that match this label selector are counted to determine the number of pods in their corresponding topology domain." }, "maxSkew": { - "description": "MaxSkew describes the degree to which pods may be unevenly distributed. It's the maximum permitted difference between the number of matching pods in any two topology domains of a given topology type. For example, in a 3-zone cluster, MaxSkew is set to 1, and pods with the same labelSelector spread as 1/1/0: | zone1 | zone2 | zone3 | | P | P | | - if MaxSkew is 1, incoming pod can only be scheduled to zone3 to become 1/1/1; scheduling it onto zone1(zone2) would make the ActualSkew(2-0) on zone1(zone2) violate MaxSkew(1). - if MaxSkew is 2, incoming pod can be scheduled onto any zone. It's a required field. Default value is 1 and 0 is not allowed.", + "description": "MaxSkew describes the degree to which pods may be unevenly distributed. When `whenUnsatisfiable=DoNotSchedule`, it is the maximum permitted difference between the number of matching pods in the target topology and the global minimum. For example, in a 3-zone cluster, MaxSkew is set to 1, and pods with the same labelSelector spread as 1/1/0: | zone1 | zone2 | zone3 | | P | P | | - if MaxSkew is 1, incoming pod can only be scheduled to zone3 to become 1/1/1; scheduling it onto zone1(zone2) would make the ActualSkew(2-0) on zone1(zone2) violate MaxSkew(1). - if MaxSkew is 2, incoming pod can be scheduled onto any zone. When `whenUnsatisfiable=ScheduleAnyway`, it is used to give higher precedence to topologies that satisfy it. It's a required field. Default value is 1 and 0 is not allowed.", "format": "int32", "type": "integer" }, @@ -10187,7 +10187,7 @@ "type": "string" }, "whenUnsatisfiable": { - "description": "WhenUnsatisfiable indicates how to deal with a pod if it doesn't satisfy the spread constraint. - DoNotSchedule (default) tells the scheduler not to schedule it - ScheduleAnyway tells the scheduler to still schedule it It's considered as \"Unsatisfiable\" if and only if placing incoming pod on any topology violates \"MaxSkew\". For example, in a 3-zone cluster, MaxSkew is set to 1, and pods with the same labelSelector spread as 3/1/1: | zone1 | zone2 | zone3 | | P P P | P | P | If WhenUnsatisfiable is set to DoNotSchedule, incoming pod can only be scheduled to zone2(zone3) to become 3/2/1(3/1/2) as ActualSkew(2-1) on zone2(zone3) satisfies MaxSkew(1). In other words, the cluster can still be imbalanced, but scheduler won't make it *more* imbalanced. It's a required field.", + "description": "WhenUnsatisfiable indicates how to deal with a pod if it doesn't satisfy the spread constraint. - DoNotSchedule (default) tells the scheduler not to schedule it. - ScheduleAnyway tells the scheduler to schedule the pod in any location,\n but giving higher precedence to topologies that would help reduce the\n skew.\nA constraint is considered \"Unsatisfiable\" for an incoming pod if and only if every possible node assigment for that pod would violate \"MaxSkew\" on some topology. For example, in a 3-zone cluster, MaxSkew is set to 1, and pods with the same labelSelector spread as 3/1/1: | zone1 | zone2 | zone3 | | P P P | P | P | If WhenUnsatisfiable is set to DoNotSchedule, incoming pod can only be scheduled to zone2(zone3) to become 3/2/1(3/1/2) as ActualSkew(2-1) on zone2(zone3) satisfies MaxSkew(1). In other words, the cluster can still be imbalanced, but scheduler won't make it *more* imbalanced. It's a required field.", "type": "string" } }, diff --git a/pkg/apis/core/types.go b/pkg/apis/core/types.go index 2a0d8a3acee..3944d5dcadc 100644 --- a/pkg/apis/core/types.go +++ b/pkg/apis/core/types.go @@ -5176,8 +5176,8 @@ const ( // TopologySpreadConstraint specifies how to spread matching pods among the given topology. type TopologySpreadConstraint struct { // MaxSkew describes the degree to which pods may be unevenly distributed. - // It's the maximum permitted difference between the number of matching pods in - // any two topology domains of a given topology type. + // When `whenUnsatisfiable=DoNotSchedule`, it is the maximum permitted difference + // between the number of matching pods in the target topology and the global minimum. // For example, in a 3-zone cluster, MaxSkew is set to 1, and pods with the same // labelSelector spread as 1/1/0: // +-------+-------+-------+ @@ -5189,6 +5189,8 @@ type TopologySpreadConstraint struct { // scheduling it onto zone1(zone2) would make the ActualSkew(2-0) on zone1(zone2) // violate MaxSkew(1). // - if MaxSkew is 2, incoming pod can be scheduled onto any zone. + // When `whenUnsatisfiable=ScheduleAnyway`, it is used to give higher precedence + // to topologies that satisfy it. // It's a required field. Default value is 1 and 0 is not allowed. MaxSkew int32 // TopologyKey is the key of node labels. Nodes that have a label with this key @@ -5199,10 +5201,13 @@ type TopologySpreadConstraint struct { TopologyKey string // WhenUnsatisfiable indicates how to deal with a pod if it doesn't satisfy // the spread constraint. - // - DoNotSchedule (default) tells the scheduler not to schedule it - // - ScheduleAnyway tells the scheduler to still schedule it - // It's considered as "Unsatisfiable" if and only if placing incoming pod on any - // topology violates "MaxSkew". + // - DoNotSchedule (default) tells the scheduler not to schedule it. + // - ScheduleAnyway tells the scheduler to schedule the pod in any location, + // but giving higher precedence to topologies that would help reduce the + // skew. + // A constraint is considered "Unsatisfiable" for an incoming pod + // if and only if every possible node assigment for that pod would violate + // "MaxSkew" on some topology. // For example, in a 3-zone cluster, MaxSkew is set to 1, and pods with the same // labelSelector spread as 3/1/1: // +-------+-------+-------+ diff --git a/staging/src/k8s.io/api/core/v1/generated.proto b/staging/src/k8s.io/api/core/v1/generated.proto index dbb56094887..b4bb018a89f 100644 --- a/staging/src/k8s.io/api/core/v1/generated.proto +++ b/staging/src/k8s.io/api/core/v1/generated.proto @@ -5004,8 +5004,8 @@ message TopologySelectorTerm { // TopologySpreadConstraint specifies how to spread matching pods among the given topology. message TopologySpreadConstraint { // MaxSkew describes the degree to which pods may be unevenly distributed. - // It's the maximum permitted difference between the number of matching pods in - // any two topology domains of a given topology type. + // When `whenUnsatisfiable=DoNotSchedule`, it is the maximum permitted difference + // between the number of matching pods in the target topology and the global minimum. // For example, in a 3-zone cluster, MaxSkew is set to 1, and pods with the same // labelSelector spread as 1/1/0: // +-------+-------+-------+ @@ -5017,6 +5017,8 @@ message TopologySpreadConstraint { // scheduling it onto zone1(zone2) would make the ActualSkew(2-0) on zone1(zone2) // violate MaxSkew(1). // - if MaxSkew is 2, incoming pod can be scheduled onto any zone. + // When `whenUnsatisfiable=ScheduleAnyway`, it is used to give higher precedence + // to topologies that satisfy it. // It's a required field. Default value is 1 and 0 is not allowed. optional int32 maxSkew = 1; @@ -5029,10 +5031,13 @@ message TopologySpreadConstraint { // WhenUnsatisfiable indicates how to deal with a pod if it doesn't satisfy // the spread constraint. - // - DoNotSchedule (default) tells the scheduler not to schedule it - // - ScheduleAnyway tells the scheduler to still schedule it - // It's considered as "Unsatisfiable" if and only if placing incoming pod on any - // topology violates "MaxSkew". + // - DoNotSchedule (default) tells the scheduler not to schedule it. + // - ScheduleAnyway tells the scheduler to schedule the pod in any location, + // but giving higher precedence to topologies that would help reduce the + // skew. + // A constraint is considered "Unsatisfiable" for an incoming pod + // if and only if every possible node assigment for that pod would violate + // "MaxSkew" on some topology. // For example, in a 3-zone cluster, MaxSkew is set to 1, and pods with the same // labelSelector spread as 3/1/1: // +-------+-------+-------+ diff --git a/staging/src/k8s.io/api/core/v1/types.go b/staging/src/k8s.io/api/core/v1/types.go index 814040564f1..a48528bc75f 100644 --- a/staging/src/k8s.io/api/core/v1/types.go +++ b/staging/src/k8s.io/api/core/v1/types.go @@ -3072,8 +3072,8 @@ const ( // TopologySpreadConstraint specifies how to spread matching pods among the given topology. type TopologySpreadConstraint struct { // MaxSkew describes the degree to which pods may be unevenly distributed. - // It's the maximum permitted difference between the number of matching pods in - // any two topology domains of a given topology type. + // When `whenUnsatisfiable=DoNotSchedule`, it is the maximum permitted difference + // between the number of matching pods in the target topology and the global minimum. // For example, in a 3-zone cluster, MaxSkew is set to 1, and pods with the same // labelSelector spread as 1/1/0: // +-------+-------+-------+ @@ -3085,6 +3085,8 @@ type TopologySpreadConstraint struct { // scheduling it onto zone1(zone2) would make the ActualSkew(2-0) on zone1(zone2) // violate MaxSkew(1). // - if MaxSkew is 2, incoming pod can be scheduled onto any zone. + // When `whenUnsatisfiable=ScheduleAnyway`, it is used to give higher precedence + // to topologies that satisfy it. // It's a required field. Default value is 1 and 0 is not allowed. MaxSkew int32 `json:"maxSkew" protobuf:"varint,1,opt,name=maxSkew"` // TopologyKey is the key of node labels. Nodes that have a label with this key @@ -3095,10 +3097,13 @@ type TopologySpreadConstraint struct { TopologyKey string `json:"topologyKey" protobuf:"bytes,2,opt,name=topologyKey"` // WhenUnsatisfiable indicates how to deal with a pod if it doesn't satisfy // the spread constraint. - // - DoNotSchedule (default) tells the scheduler not to schedule it - // - ScheduleAnyway tells the scheduler to still schedule it - // It's considered as "Unsatisfiable" if and only if placing incoming pod on any - // topology violates "MaxSkew". + // - DoNotSchedule (default) tells the scheduler not to schedule it. + // - ScheduleAnyway tells the scheduler to schedule the pod in any location, + // but giving higher precedence to topologies that would help reduce the + // skew. + // A constraint is considered "Unsatisfiable" for an incoming pod + // if and only if every possible node assigment for that pod would violate + // "MaxSkew" on some topology. // For example, in a 3-zone cluster, MaxSkew is set to 1, and pods with the same // labelSelector spread as 3/1/1: // +-------+-------+-------+ diff --git a/staging/src/k8s.io/api/core/v1/types_swagger_doc_generated.go b/staging/src/k8s.io/api/core/v1/types_swagger_doc_generated.go index bcb9648945f..ce4e7bdac74 100644 --- a/staging/src/k8s.io/api/core/v1/types_swagger_doc_generated.go +++ b/staging/src/k8s.io/api/core/v1/types_swagger_doc_generated.go @@ -2325,9 +2325,9 @@ func (TopologySelectorTerm) SwaggerDoc() map[string]string { var map_TopologySpreadConstraint = map[string]string{ "": "TopologySpreadConstraint specifies how to spread matching pods among the given topology.", - "maxSkew": "MaxSkew describes the degree to which pods may be unevenly distributed. It's the maximum permitted difference between the number of matching pods in any two topology domains of a given topology type. For example, in a 3-zone cluster, MaxSkew is set to 1, and pods with the same labelSelector spread as 1/1/0: ", + "maxSkew": "MaxSkew describes the degree to which pods may be unevenly distributed. When `whenUnsatisfiable=DoNotSchedule`, it is the maximum permitted difference between the number of matching pods in the target topology and the global minimum. For example, in a 3-zone cluster, MaxSkew is set to 1, and pods with the same labelSelector spread as 1/1/0: ", "topologyKey": "TopologyKey is the key of node labels. Nodes that have a label with this key and identical values are considered to be in the same topology. We consider each as a \"bucket\", and try to put balanced number of pods into each bucket. It's a required field.", - "whenUnsatisfiable": "WhenUnsatisfiable indicates how to deal with a pod if it doesn't satisfy the spread constraint. - DoNotSchedule (default) tells the scheduler not to schedule it - ScheduleAnyway tells the scheduler to still schedule it It's considered as \"Unsatisfiable\" if and only if placing incoming pod on any topology violates \"MaxSkew\". For example, in a 3-zone cluster, MaxSkew is set to 1, and pods with the same labelSelector spread as 3/1/1: ", + "whenUnsatisfiable": "WhenUnsatisfiable indicates how to deal with a pod if it doesn't satisfy the spread constraint. - DoNotSchedule (default) tells the scheduler not to schedule it. - ScheduleAnyway tells the scheduler to schedule the pod in any location,\n but giving higher precedence to topologies that would help reduce the\n skew.\nA constraint is considered \"Unsatisfiable\" for an incoming pod if and only if every possible node assigment for that pod would violate \"MaxSkew\" on some topology. For example, in a 3-zone cluster, MaxSkew is set to 1, and pods with the same labelSelector spread as 3/1/1: ", "labelSelector": "LabelSelector is used to find matching pods. Pods that match this label selector are counted to determine the number of pods in their corresponding topology domain.", }