- URL:
- https://<root>/system/upgrades/config/update
- Methods:
POST
- Required Capability:
- Access allowed with either "Security and infrastructure" or "Servers" privileges
- Version Introduced:
- 11.2
Description
The update
operation allows administrators to set or modify the node affinity and tolerations for the pods used during upgrades or updates. Once a placement policy has been created, it will be applied whenever an upgrade job is created.
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 node
and tolerations
properties, see the Node affinity and Tolerations sections below.
Node affinity
Before establishing node affinity, a label must be placed on the node. A label is comprised of key-value pairs (key=value
) that are used to attract pods to be scheduled on that node. This is done by configuring the node
for the pods used during an upgrade to use the same label key and values information as the node. Below is the general JSON syntax for node
:
"nodeAffinity": {
"<requiredDuringSchedulingIgnoredDuringExecution | preferredDuringSchedulingIgnoredDuringExecution>": {
"nodeSelectorTerms": [
{
"matchExpressions": [
{
"key": "<label key>",
"operator": "<In | NotIn | Exists | DoesNotExist>",
"values": [
"<label value>"
]
}
]
}
]
}
}
They key
and values
information, along with an operator
value that specifies the relationship between the node
properties and the node's labels, are evaluated along with whether the matching values are required or preferred during scheduling to determine when the upgrade job's pods will be scheduled.
For example, a node receives the following label:
kubectl label nodes exampleNode sampleLabel=sampleValue
and an administrator wants to require that the key (sample
) and value (sample
) information is applied to the the pods so they can be scheduled to the specific node. To achieve that outcome, the node
property would need to be configured with the exact key and value information applied to the node, as well as setting the required
property:
"nodeAffinity": {
"requiredDuringSchedulingIgnoredDuringExecution": {
"nodeSelectorTerms": [
{
"matchExpressions": [
{
"key": "sampleLabel",
"operator": "In",
"values": [
"sampleValue"
]
}
]
}
]
}
}
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 label nodes. Node affinity 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 designated for the upgrade job 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 |
---|---|
| Possible value for the |
| Possible value for the |
| Possible value for the |
| Possible value for the |
| Possible value for the |
To demonstrate how taints and tolerations interact, consider an administrator that wants to taint a node so that only tolerant pods will be scheduled 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:NoSchedule
The exact values of the key
(sample
), value
(sample
), and effect
(No
) 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 the upgrade job'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 requirements can run on standard nodes.
Request parameters
Parameter | Details |
---|---|
| Returns the current Example
|
| The response format. The default format is Values: |
Example usage
The following is a sample POST request for the update
operation:
POST /context/admin/system/upgrades/config/update HTTP/1.1
Host: organization.domain.com
Content-Type: application/x-www-form-urlencoded
Content-Length: []
upgradeConfig={"podPlacementPolicy":{"nodeAffinity": {},"tolerations": [{"effect": "NoSchedule","key": "upgrader","operator": "Equal","value": "true"}]}}&f=pjson&token=aOjrLVEnRpuwfgK-G-PGdyWUQhpJDlGVAt70Z3vrHd1mihME8yx8E1EgRCoIpl3mLm2DSDVjFVbyFeQVD_Sp6DrXAIrwED7NYmMTF_GkLurVWAe-MBROTxqu5781_8qj5S_3tqoINj6OmjG8zfeztCKTUCbV-xrsNp5-50g2-UCX62H_qT0r1fIgqh_KFsFF9f3cC9kzWum47eRH9PmmZHdKGN3XjY3GghswTGCELNJbEQ_q84sz8zYE5q6jx8Cl
JSON Response example
{"status": "success"}