- URL:https://<root>/services/<serviceName.serviceType>/placementPolicy/edit(POST only)
- Required Capability:Default administrator role | Security and infrastructure
- Version Introduced:11.2
Description
The edit operation allows administrators to set or modify the node affinity and tolerations for a GIS service's pods. Node affinity allows for pods to be scheduled to nodes that have matching label key-value pairs, whereas tolerations allow for pods to be scheduled on tainted nodes that would otherwise repel them if not for matching toleration and taint key-value pairs. For more information on configuring the nodeAffinity and tolerations properties, see the Node affinity and Tolerations sections below.
Note:
The following sections outline some of the configurable properties for the nodeAffinity and tolerations JSON objects. However, both nodeAffinity and tolerations are open to support other properties that are unspecified in this documentation. Prior to setting node affinity or tolerations for a GIS service, reference the Kubernetes Node affinity or Tolerations documentation for more detailed information, additional properties or values, and any potential updates made to those areas.
Node affinity
Before establishing node affinity, a label must be placed on an individual node or added to node pools so that newly created or recycled nodes inherit the same label. A label is comprised of key-value pairs (key=value) that are to attract specific pods to be scheduled on that node. This is done by configuring a GIS service's pods nodeAffinity property to use the same label key and value information as the node. Below is the general JSON syntax for nodeAffinity:
"nodeAffinity": {
"<requiredDuringSchedulingIgnoredDuringExecution | preferredDuringSchedulingIgnoredDuringExecution>": {
"nodeSelectorTerms": [
{
"matchExpressions": [
{
"key": "<label key>",
"operator": "<In | NotIn | Exists | DoesNotExist>",
"values": [
"<label value>"
]
}
]
}
]
}
}The key and values information, along with an operator value that specifies the relationship between nodeAffinity properties and the node's labels, are evaluated along with whether the matching values are required or preferred during scheduling in order to determine where the service's pods are scheduled.
For example, a node receives the following label:
kubectl label nodes exampleNode sampleLabel=sampleValueand an administrator wants to require that the key (sampleLabel) and value (sampleValue) information is present on a GIS service's pods in order for them to be scheduled to a specific node. To achieve that outcome, the nodeAffinity property would need to be configured with the exact key and value information applied to the node, as well as setting the requiredDuringSchedulingIgnoredDuringExecution property:
"nodeAffinity": {
"requiredDuringSchedulingIgnoredDuringExecution": {
"nodeSelectorTerms": [
{
"matchExpressions": [
{
"key": "sampleLabel",
"operator": "In",
"values": [
"sampleValue"
]
}
]
}
]
}
}Note:
When requiredDuringSchedulingIgnoredDuringExecution is specified, the scheduler will not schedule the pod if the nodeAffinity key and values properties do not match any node's label key-value pairs. When preferredDuringSchedulingIgnoredDuringExecution is specified, the scheduler will attempt to schedule the pod to a matching node. However, if no node's label matches the pod's nodeAffinity key and values properties, the pod will still be scheduled to any available node (excluding tainted nodes that repel intolerant pods).
Node affinity ensures that the scheduler will attempt to schedule pods with their matching nodes. However, it may not prevent other pods, that do not have matching key-value pairs, from being scheduled to labeled nodes. It will also not remove preexisting pods that have been scheduled to the node before the label was added. Administrators wanting to repel all pods that are not for a specific service may also want to taint the node.
Tolerations
Similarly to node affinity, tainting a node requires a key-value pair, as well as an effect, to be applied to a node. Applying a taint to a node ensures that all pods that do not tolerate the node are repelled from it and are scheduled to other available nodes instead. For a pod to tolerate a tainted node, the key, values, and effect properties under tolerations must either match the tainted values exactly or have just the key value be present in the tolerations property. Below is the general JSON syntax for tolerations:
"tolerations": [
{
"effect": "<NoExecute | NoSchedule | PreferNoSchedule>",
"key": "<taint key>",
"operator": "<Exists | Equal>",
"value": "<taint value>"
}
]The table below defines the different values that can be assigned to the effect and operator properties:
| Value | Details |
|---|---|
| NoExecute | Possible value for the effect property. If set, the scheduler will immediately remove intolerant pods from the node that may have been schedule to the node prior to its tainting. |
| NoSchedule | Possible value for the effect property. If set, the scheduler will not schedule any new pods to the node that do not tolerate the taint, but any pods currently present on the node (regardless of tolerations) will remain in the node. |
| PreferNoSchedule | Possible value for the effect property. The scheduler will attempt to place pods that do not tolerate the node to different nodes. However, non-tolerant pods may still be scheduled to the tainted node. |
| Exists | Possible value for the operator property. If set, the scheduler checks if just the key exists and matches the taint key. The values property is not required. |
| Equal | Possible value for the operator property. If set, the scheduler is checking if both the key and values properties match the taint key-value pair. |
To demonstrate how taints and tolerations interact, consider an administrator that wants to taint a node so that only tolerant pods will be schedule to the node, and that all preexisting pods on the node are expelled if they are not tolerant. To achieve this, a taint must first be applied to the node:
kubectl label nodes exampleNode sampleKey=sampleValue:NoScheduleThe exact values of the key (sampleKey), value (sampleValue), and effect (NoSchedule) values used to taint the node would need to used to configure the toleration property:
"tolerations": [
{
"effect": "NoSchedule",
"key": "sampleKey",
"operator": "Equal",
"value": "sampleValue"
}
]Tainting a node and assigning tolerations to a service's pods ensures that the node is reserved for the pods that need the node's specialized resources, and that other pods that do not need certain resources can run on standard nodes.
Request parameters
| Parameter | Details |
|---|---|
| servicePlacementPolicy | Returns the current placementPolicy JSON object. The nodeAffinity and tolerations properties can be modified to reflect the label or taint values that has been applied to a node or group of nodes. The deploymentType and deploymentID values are provided automatically and should not be modified. Syntax Example |
| async | Specifies if the operation should be performed asynchronously. The default value is false. Values: true | false |
| f | The response format. The default format is html. Values: html | json | pjson |
Example usage
The following is a sample POST request for the edit operation that demonstrates configuring tolerations for a feature service's pods:
POST /context/admin/services/CommercialDamageAssessment.FeatureServer/placementPolicy/edit HTTP/1.1
Host: organization.domain.com
Content-Type: application/x-www-form-urlencoded
Content-Length: []
servicePlacementPolicy={"placementPolicy": [{"deploymentId": "kfnxectieft8iaxn3qka9","deploymentType": "FeatureServer","podPlacementPolicy":{"nodeAffinity":{},"tolerations": [{"effect": "NoSchedule","key": "label1","operator": "Equal","value": "test1"}]}}]}&f=pjson&token=Mb0ORrkLObNO2Q8FZoUCHHzSMzZi0CbhLHNRYMqqa6URG_ojQJF3rNsJAfRB23MyCrLwSmuaHPUo4AEIrUuoH1-4Ot5xh4565FtlQahXAhK2C7Sy0oydZhBwD8KdFSnVlnLr-e9uI5ovSWZ2lGNn9SwoV2MPMzeAh_5r-q-wgwF8DTT_nhuCXJGkMRy-48jjGS2aN5FI18STHZ8RAuKxGasH90SI3C7njZzlGCUrY5m6BDhCMsdpZA14GwNX8CisJSON Response
{"status": "success"}