Post-installation node tasks

After installing OKD, you can further expand and customize your cluster to your requirements through certain node tasks.

Adding FCOS compute machines to an OKD cluster

You can add more Fedora CoreOS (FCOS) compute machines to your OKD cluster on bare metal.

Before you add more compute machines to a cluster that you installed on bare metal infrastructure, you must create FCOS machines for it to use. You can either use an ISO image or network PXE booting to create the machines.

Prerequisites

  • You installed a cluster on bare metal.

  • You have installation media and Fedora CoreOS (FCOS) images that you used to create your cluster. If you do not have these files, you must obtain them by following the instructions in the installation procedure.

Creating more FCOS machines using an ISO image

You can create more Fedora CoreOS (FCOS) compute machines for your bare metal cluster by using an ISO image to create the machines.

Prerequisites

  • Obtain the URL of the Ignition config file for the compute machines for your cluster. You uploaded this file to your HTTP server during installation.

Procedure

  1. Use the ISO file to install FCOS on more compute machines. Use the same method that you used when you created machines before you installed the cluster:

    • Burn the ISO image to a disk and boot it directly.

    • Use ISO redirection with a LOM interface.

  2. After the instance boots, press the TAB or E key to edit the kernel command line.

  3. Add the parameters to the kernel command line:

    1. coreos.inst.install_dev=sda (1)
    2. coreos.inst.ignition_url=http://example.com/worker.ign (2)
    1Specify the block device of the system to install to.
    2Specify the URL of the compute Ignition config file. Only HTTP and HTTPS protocols are supported.

  4. Press Enter to complete the installation. After FCOS installs, the system reboots. After the system reboots, it applies the Ignition config file that you specified.

  5. Continue to create more compute machines for your cluster.

Creating more FCOS machines by PXE or iPXE booting

You can create more Fedora CoreOS (FCOS) compute machines for your bare metal cluster by using PXE or iPXE booting.

Prerequisites

  • Obtain the URL of the Ignition config file for the compute machines for your cluster. You uploaded this file to your HTTP server during installation.

  • Obtain the URLs of the FCOS ISO image, compressed metal BIOS, kernel, and initramfs files that you uploaded to your HTTP server during cluster installation.

  • You have access to the PXE booting infrastructure that you used to create the machines for your OKD cluster during installation. The machines must boot from their local disks after FCOS is installed on them.

  • If you use UEFI, you have access to the grub.conf file that you modified during OKD installation.

Procedure

  1. Confirm that your PXE or iPXE installation for the FCOS images is correct.

    • For PXE:

      1. DEFAULT pxeboot
      2. TIMEOUT 20
      3. PROMPT 0
      4. LABEL pxeboot
      5.     KERNEL http://<HTTP_server>/rhcos-<version>-live-kernel-<architecture> (1)
      6.     APPEND initrd=http://<HTTP_server>/rhcos-<version>-live-initramfs.<architecture>.img coreos.inst.install_dev=/dev/sda coreos.inst.ignition_url=http://<HTTP_server>/worker.ign coreos.live.rootfs_url=http://<HTTP_server>/rhcos-<version>-live-rootfs.<architecture>.img (2)
      1Specify the location of the live kernel file that you uploaded to your HTTP server.
      2Specify locations of the FCOS files that you uploaded to your HTTP server. The initrd parameter value is the location of the live initramfs file, the coreos.inst.ignition_url parameter value is the location of the worker Ignition config file, and the coreos.live.rootfs_url parameter value is the location of the live rootfs file. The coreos.inst.ignition_url and coreos.live.rootfs_url parameters only support HTTP and HTTPS.

This configuration does not enable serial console access on machines with a graphical console. To configure a different console, add one or more console= arguments to the APPEND line. For example, add console=tty0 console=ttyS0 to set the first PC serial port as the primary console and the graphical console as a secondary console. For more information, see How does one set up a serial terminal and/or console in Red Hat Enterprise Linux?.

  • For iPXE:

    1. kernel http://<HTTP_server>/rhcos-<version>-live-kernel-<architecture> initrd=main coreos.inst.install_dev=/dev/sda coreos.inst.ignition_url=http://<HTTP_server>/worker.ign coreos.live.rootfs_url=http://<HTTP_server>/rhcos-<version>-live-rootfs.<architecture>.img (1)
    2. initrd --name main http://<HTTP_server>/rhcos-<version>-live-initramfs.<architecture>.img (2)
    1Specify locations of the FCOS files that you uploaded to your HTTP server. The kernel parameter value is the location of the kernel file, the initrd=main argument is needed for booting on UEFI systems, the coreos.inst.ignition_url parameter value is the location of the worker Ignition config file, and the coreos.live.rootfs_url parameter value is the location of the live rootfs file. The coreos.inst.ignition_url and coreos.live.rootfs_url parameters only support HTTP and HTTPS.
    2Specify the location of the initramfs file that you uploaded to your HTTP server.

This configuration does not enable serial console access on machines with a graphical console. To configure a different console, add one or more console= arguments to the kernel line. For example, add console=tty0 console=ttyS0 to set the first PC serial port as the primary console and the graphical console as a secondary console. For more information, see How does one set up a serial terminal and/or console in Red Hat Enterprise Linux?.

  1. Use the PXE or iPXE infrastructure to create the required compute machines for your cluster.

Approving the certificate signing requests for your machines

When you add machines to a cluster, two pending certificate signing requests (CSRs) are generated for each machine that you added. You must confirm that these CSRs are approved or, if necessary, approve them yourself. The client requests must be approved first, followed by the server requests.

Prerequisites

  • You added machines to your cluster.

Procedure

  1. Confirm that the cluster recognizes the machines:

    1. $ oc get nodes

    Example output

    1. NAME      STATUS    ROLES   AGE  VERSION
    2. master-0  Ready     master  63m  v1.20.0
    3. master-1  Ready     master  63m  v1.20.0
    4. master-2  Ready     master  64m  v1.20.0
    5. worker-0  NotReady  worker  76s  v1.20.0
    6. worker-1  NotReady  worker  70s  v1.20.0

    The output lists all of the machines that you created.

    The preceding output might not include the compute nodes, also known as worker nodes, until some CSRs are approved.

  2. Review the pending CSRs and ensure that you see the client requests with the Pending or Approved status for each machine that you added to the cluster:

    1. $ oc get csr

    Example output

    1. NAME        AGE     REQUESTOR                                                                   CONDITION
    2. csr-8b2br   15m     system:serviceaccount:openshift-machine-config-operator:node-bootstrapper   Pending
    3. csr-8vnps   15m     system:serviceaccount:openshift-machine-config-operator:node-bootstrapper   Pending
    4. ...

    In this example, two machines are joining the cluster. You might see more approved CSRs in the list.

  3. If the CSRs were not approved, after all of the pending CSRs for the machines you added are in Pending status, approve the CSRs for your cluster machines:

    Because the CSRs rotate automatically, approve your CSRs within an hour of adding the machines to the cluster. If you do not approve them within an hour, the certificates will rotate, and more than two certificates will be present for each node. You must approve all of these certificates. Once the client CSR is approved, the Kubelet creates a secondary CSR for the serving certificate, which requires manual approval. Then, subsequent serving certificate renewal requests are automatically approved by the machine-approver if the Kubelet requests a new certificate with identical parameters.

    For clusters running on platforms that are not machine API enabled, such as bare metal and other user-provisioned infrastructure, you must implement a method of automatically approving the kubelet serving certificate requests (CSRs). If a request is not approved, then the oc exec, oc rsh, and oc logs commands cannot succeed, because a serving certificate is required when the API server connects to the kubelet. Any operation that contacts the Kubelet endpoint requires this certificate approval to be in place. The method must watch for new CSRs, confirm that the CSR was submitted by the node-bootstrapper service account in the system:node or system:admin groups, and confirm the identity of the node.

    • To approve them individually, run the following command for each valid CSR:

      1. $ oc adm certificate approve <csr_name> (1)
      1<csr_name> is the name of a CSR from the list of current CSRs.

    • To approve all pending CSRs, run the following command:

      1. $ oc get csr -o go-template='{{range .items}}{{if not .status}}{{.metadata.name}}{{"\n"}}{{end}}{{end}}' | xargs --no-run-if-empty oc adm certificate approve

      Some Operators might not become available until some CSRs are approved.

  4. Now that your client requests are approved, you must review the server requests for each machine that you added to the cluster:

    1. $ oc get csr

    Example output

    1. NAME        AGE     REQUESTOR                                                                   CONDITION
    2. csr-bfd72   5m26s   system:node:ip-10-0-50-126.us-east-2.compute.internal                       Pending
    3. csr-c57lv   5m26s   system:node:ip-10-0-95-157.us-east-2.compute.internal                       Pending
    4. ...

  5. If the remaining CSRs are not approved, and are in the Pending status, approve the CSRs for your cluster machines:

    • To approve them individually, run the following command for each valid CSR:

      1. $ oc adm certificate approve <csr_name> (1)
      1<csr_name> is the name of a CSR from the list of current CSRs.

    • To approve all pending CSRs, run the following command:

      1. $ oc get csr -o go-template='{{range .items}}{{if not .status}}{{.metadata.name}}{{"\n"}}{{end}}{{end}}' | xargs oc adm certificate approve

  6. After all client and server CSRs have been approved, the machines have the Ready status. Verify this by running the following command:

    1. $ oc get nodes

    Example output

    1. NAME      STATUS    ROLES   AGE  VERSION
    2. master-0  Ready     master  73m  v1.20.0
    3. master-1  Ready     master  73m  v1.20.0
    4. master-2  Ready     master  74m  v1.20.0
    5. worker-0  Ready     worker  11m  v1.20.0
    6. worker-1  Ready     worker  11m  v1.20.0

    It can take a few minutes after approval of the server CSRs for the machines to transition to the Ready status.

Additional information

Deploying machine health checks

Understand and deploy machine health checks.

This process is not applicable for clusters with manually provisioned machines. You can use the advanced machine management and scaling capabilities only in clusters where the Machine API is operational.

About machine health checks

Machine health checks automatically repair unhealthy machines in a particular machine pool.

To monitor machine health, create a resource to define the configuration for a controller. Set a condition to check, such as staying in the NotReady status for five minutes or displaying a permanent condition in the node-problem-detector, and a label for the set of machines to monitor.

You cannot apply a machine health check to a machine with the master role.

The controller that observes a MachineHealthCheck resource checks for the defined condition. If a machine fails the health check, the machine is automatically deleted and one is created to take its place. When a machine is deleted, you see a machine deleted event.

To limit disruptive impact of the machine deletion, the controller drains and deletes only one node at a time. If there are more unhealthy machines than the maxUnhealthy threshold allows for in the targeted pool of machines, remediation stops and therefore enables manual intervention.

Consider the timeouts carefully, accounting for workloads and requirements.

  • Long timeouts can result in long periods of downtime for the workload on the unhealthy machine.

  • Too short timeouts can result in a remediation loop. For example, the timeout for checking the NotReady status must be long enough to allow the machine to complete the startup process.

To stop the check, remove the resource.

Limitations when deploying machine health checks

There are limitations to consider before deploying a machine health check:

  • Only machines owned by a machine set are remediated by a machine health check.

  • Control plane machines are not currently supported and are not remediated if they are unhealthy.

  • If the node for a machine is removed from the cluster, a machine health check considers the machine to be unhealthy and remediates it immediately.

  • If the corresponding node for a machine does not join the cluster after the nodeStartupTimeout, the machine is remediated.

  • A machine is remediated immediately if the Machine resource phase is Failed.

Sample MachineHealthCheck resource

The MachineHealthCheck resource for all cloud-based installation types, and other than bare metal, resembles the following YAML file:

  1. apiVersion: machine.openshift.io/v1beta1
  2. kind: MachineHealthCheck
  3. metadata:
  4.   name: example (1)
  5.   namespace: openshift-machine-api
  6. spec:
  7.   selector:
  8.     matchLabels:
  9.       machine.openshift.io/cluster-api-machine-role: <role> (2)
  10.       machine.openshift.io/cluster-api-machine-type: <role> (2)
  11.       machine.openshift.io/cluster-api-machineset: <cluster_name>-<label>-<zone> (3)
  12.   unhealthyConditions:
  13.   - type:    "Ready"
  14.     timeout: "300s" (4)
  15.     status: "False"
  16.   - type:    "Ready"
  17.     timeout: "300s" (4)
  18.     status: "Unknown"
  19.   maxUnhealthy: "40%" (5)
  20.   nodeStartupTimeout: "10m" (6)
1Specify the name of the machine health check to deploy.
2Specify a label for the machine pool that you want to check.
3Specify the machine set to track in <cluster_name>-<label>-<zone> format. For example, prod-node-us-east-1a.
4Specify the timeout duration for a node condition. If a condition is met for the duration of the timeout, the machine will be remediated. Long timeouts can result in long periods of downtime for a workload on an unhealthy machine.
5Specify the amount of machines allowed to be concurrently remediated in the targeted pool. This can be set as a percentage or an integer. If the number of unhealthy machines exceeds the limit set by maxUnhealthy, remediation is not performed.
6Specify the timeout duration that a machine health check must wait for a node to join the cluster before a machine is determined to be unhealthy.

The matchLabels are examples only; you must map your machine groups based on your specific needs.

Short-circuiting machine health check remediation

Short circuiting ensures that machine health checks remediate machines only when the cluster is healthy. Short-circuiting is configured through the maxUnhealthy field in the MachineHealthCheck resource.

If the user defines a value for the maxUnhealthy field, before remediating any machines, the MachineHealthCheck compares the value of maxUnhealthy with the number of machines within its target pool that it has determined to be unhealthy. Remediation is not performed if the number of unhealthy machines exceeds the maxUnhealthy limit.

If maxUnhealthy is not set, the value defaults to 100% and the machines are remediated regardless of the state of the cluster.

The appropriate maxUnhealthy value depends on the scale of the cluster you deploy and how many machines the MachineHealthCheck covers. For example, you can use the maxUnhealthy value to cover multiple machine sets across multiple availability zones so that if you lose an entire zone, your maxUnhealthy setting prevents further remediation within the cluster.

The maxUnhealthy field can be set as either an integer or percentage. There are different remediation implementations depending on the maxUnhealthy value.

Setting maxUnhealthy by using an absolute value

If maxUnhealthy is set to 2:

  • Remediation will be performed if 2 or fewer nodes are unhealthy

  • Remediation will not be performed if 3 or more nodes are unhealthy

These values are independent of how many machines are being checked by the machine health check.

Setting maxUnhealthy by using percentages

If maxUnhealthy is set to 40% and there are 25 machines being checked:

  • Remediation will be performed if 10 or fewer nodes are unhealthy

  • Remediation will not be performed if 11 or more nodes are unhealthy

If maxUnhealthy is set to 40% and there are 6 machines being checked:

  • Remediation will be performed if 2 or fewer nodes are unhealthy

  • Remediation will not be performed if 3 or more nodes are unhealthy

The allowed number of machines is rounded down when the percentage of maxUnhealthy machines that are checked is not a whole number.

Creating a MachineHealthCheck resource

You can create a MachineHealthCheck resource for all MachineSets in your cluster. You should not create a MachineHealthCheck resource that targets control plane machines.

Prerequisites

  • Install the oc command line interface.

Procedure

  1. Create a healthcheck.yml file that contains the definition of your machine health check.

  2. Apply the healthcheck.yml file to your cluster:

    1. $ oc apply -f healthcheck.yml

Scaling a machine set manually

To add or remove an instance of a machine in a machine set, you can manually scale the machine set.

This guidance is relevant to fully automated, installer-provisioned infrastructure installations. Customized, user-provisioned infrastructure installations do not have machine sets.

Prerequisites

  • Install an OKD cluster and the oc command line.

  • Log in to oc as a user with cluster-admin permission.

Procedure

  1. View the machine sets that are in the cluster:

    1. $ oc get machinesets -n openshift-machine-api

    The machine sets are listed in the form of <clusterid>-worker-<aws-region-az>.

  2. Scale the machine set:

    1. $ oc scale --replicas=2 machineset <machineset> -n openshift-machine-api

    Or:

    1. $ oc edit machineset <machineset> -n openshift-machine-api

    You can scale the machine set up or down. It takes several minutes for the new machines to be available.

Understanding the difference between machine sets and the machine config pool

MachineSet objects describe OKD nodes with respect to the cloud or machine provider.

The MachineConfigPool object allows MachineConfigController components to define and provide the status of machines in the context of upgrades.

The MachineConfigPool object allows users to configure how upgrades are rolled out to the OKD nodes in the machine config pool.

The NodeSelector object can be replaced with a reference to the MachineSet object.

The OKD node configuration file contains important options. For example, two parameters control the maximum number of pods that can be scheduled to a node: podsPerCore and maxPods.

When both options are in use, the lower of the two values limits the number of pods on a node. Exceeding these values can result in:

  • Increased CPU utilization.

  • Slow pod scheduling.

  • Potential out-of-memory scenarios, depending on the amount of memory in the node.

  • Exhausting the pool of IP addresses.

  • Resource overcommitting, leading to poor user application performance.

In Kubernetes, a pod that is holding a single container actually uses two containers. The second container is used to set up networking prior to the actual container starting. Therefore, a system running 10 pods will actually have 20 containers running.

Disk IOPS throttling from the cloud provider might have an impact on CRI-O and kubelet. They might get overloaded when there are large number of I/O intensive pods running on the nodes. It is recommended that you monitor the disk I/O on the nodes and use volumes with sufficient throughput for the workload.

podsPerCore sets the number of pods the node can run based on the number of processor cores on the node. For example, if podsPerCore is set to 10 on a node with 4 processor cores, the maximum number of pods allowed on the node will be 40.

  1. kubeletConfig:
  2.   podsPerCore: 10

Setting podsPerCore to 0 disables this limit. The default is 0. podsPerCore cannot exceed maxPods.

maxPods sets the number of pods the node can run to a fixed value, regardless of the properties of the node.

  1.  kubeletConfig:
  2.     maxPods: 250

Creating a KubeletConfig CRD to edit kubelet parameters

The kubelet configuration is currently serialized as an Ignition configuration, so it can be directly edited. However, there is also a new kubelet-config-controller added to the Machine Config Controller (MCC). This lets you use a KubeletConfig custom resource (CR) to edit the kubelet parameters.

As the fields in the kubeletConfig object are passed directly to the kubelet from upstream Kubernetes, the kubelet validates those values directly. Invalid values in the kubeletConfig object might cause cluster nodes to become unavailable. For valid values, see the Kubernetes documentation.

Consider the following guidance:

  • Create one KubeletConfig CR for each machine config pool with all the config changes you want for that pool. If you are applying the same content to all of the pools, you need only one KubeletConfig CR for all of the pools.

  • Edit an existing KubeletConfig CR to modify existing settings or add new settings, instead of creating a CR for each change. It is recommended that you create a CR only to modify a different machine config pool, or for changes that are intended to be temporary, so that you can revert the changes.

  • As needed, create multiple KubeletConfig CRs with a limit of 10 per cluster. For the first KubeletConfig CR, the Machine Config Operator (MCO) creates a machine config appended with kubelet. With each subsequent CR, the controller creates another kubelet machine config with a numeric suffix. For example, if you have a kubelet machine config with a -2 suffix, the next kubelet machine config is appended with -3.

If you want to delete the machine configs, delete them in reverse order to avoid exceeding the limit. For example, you delete the kubelet-3 machine config before deleting the kubelet-2 machine config.

If you have a machine config with a kubelet-9 suffix, and you create another KubeletConfig CR, a new machine config is not created, even if there are fewer than 10 kubelet machine configs.

Example KubeletConfig CR

  1. $ oc get kubeletconfig
  1. NAME                AGE
  2. set-max-pods        15m

Example showing a KubeletConfig machine config

  1. $ oc get mc | grep kubelet
  1. ...
  2. 99-worker-generated-kubelet-1                  b5c5119de007945b6fe6fb215db3b8e2ceb12511   3.2.0             26m
  3. ...

The following procedure is an example to show how to configure the maximum number of pods per node on the worker nodes.

Prerequisites

  1. Obtain the label associated with the static MachineConfigPool CR for the type of node you want to configure. Perform one of the following steps:

    1. View the machine config pool:

      1. $ oc describe machineconfigpool <name>

      For example:

      1. $ oc describe machineconfigpool worker

      Example output

      1. apiVersion: machineconfiguration.openshift.io/v1
      2. kind: MachineConfigPool
      3. metadata:
      4.   creationTimestamp: 2019-02-08T14:52:39Z
      5.   generation: 1
      6.   labels:
      7.     custom-kubelet: set-max-pods (1)
      1If a label has been added it appears under labels.

    2. If the label is not present, add a key/value pair:

      1. $ oc label machineconfigpool worker custom-kubelet=set-max-pods

Procedure

  1. View the available machine configuration objects that you can select:

    1. $ oc get machineconfig

    By default, the two kubelet-related configs are 01-master-kubelet and 01-worker-kubelet.

  2. Check the current value for the maximum pods per node:

    1. $ oc describe node <node_name>

    For example:

    1. $ oc describe node ci-ln-5grqprb-f76d1-ncnqq-worker-a-mdv94

    Look for value: pods: <value> in the Allocatable stanza:

    Example output

    1. Allocatable:
    2.  attachable-volumes-aws-ebs:  25
    3.  cpu:                         3500m
    4.  hugepages-1Gi:               0
    5.  hugepages-2Mi:               0
    6.  memory:                      15341844Ki
    7.  pods:                        250

  3. Set the maximum pods per node on the worker nodes by creating a custom resource file that contains the kubelet configuration:

    1. apiVersion: machineconfiguration.openshift.io/v1
    2. kind: KubeletConfig
    3. metadata:
    4.   name: set-max-pods
    5. spec:
    6.   machineConfigPoolSelector:
    7.     matchLabels:
    8.       custom-kubelet: set-max-pods (1)
    9.   kubeletConfig:
    10.     maxPods: 500 (2)
    1Enter the label from the machine config pool.
    2Add the kubelet configuration. In this example, use maxPods to set the maximum pods per node.

    The rate at which the kubelet talks to the API server depends on queries per second (QPS) and burst values. The default values, 50 for kubeAPIQPS and 100 for kubeAPIBurst, are sufficient if there are limited pods running on each node. It is recommended to update the kubelet QPS and burst rates if there are enough CPU and memory resources on the node.

    1. apiVersion: machineconfiguration.openshift.io/v1
    2. kind: KubeletConfig
    3. metadata:
    4.   name: set-max-pods
    5. spec:
    6.   machineConfigPoolSelector:
    7.     matchLabels:
    8.       custom-kubelet: set-max-pods
    9.   kubeletConfig:
    10.     maxPods: <pod_count>
    11.     kubeAPIBurst: <burst_rate>
    12.     kubeAPIQPS: <QPS>

    1. Update the machine config pool for workers with the label:

      1. $ oc label machineconfigpool worker custom-kubelet=large-pods

    2. Create the KubeletConfig object:

      1. $ oc create -f change-maxPods-cr.yaml

    3. Verify that the KubeletConfig object is created:

      1. $ oc get kubeletconfig

      Example output

      1. NAME                AGE
      2. set-max-pods        15m

      Depending on the number of worker nodes in the cluster, wait for the worker nodes to be rebooted one by one. For a cluster with 3 worker nodes, this could take about 10 to 15 minutes.

  4. Verify that the changes are applied to the node:

    1. Check on a worker node that the maxPods value changed:

      1. $ oc describe node <node_name>

    2. Locate the Allocatable stanza:

      1.  ...
      2. Allocatable:
      3.   attachable-volumes-gce-pd:  127
      4.   cpu:                        3500m
      5.   ephemeral-storage:          123201474766
      6.   hugepages-1Gi:              0
      7.   hugepages-2Mi:              0
      8.   memory:                     14225400Ki
      9.   pods:                       500 (1)
      10.  ...
      1In this example, the pods parameter should report the value you set in the KubeletConfig object.

  5. Verify the change in the KubeletConfig object:

    1. $ oc get kubeletconfigs set-max-pods -o yaml

    This should show a status: "True" and type:Success:

    1. spec:
    2.   kubeletConfig:
    3.     maxPods: 500
    4.   machineConfigPoolSelector:
    5.     matchLabels:
    6.       custom-kubelet: set-max-pods
    7. status:
    8.   conditions:
    9.   - lastTransitionTime: "2021-06-30T17:04:07Z"
    10.     message: Success
    11.     status: "True"
    12.     type: Success

Modifying the number of unavailable worker nodes

By default, only one machine is allowed to be unavailable when applying the kubelet-related configuration to the available worker nodes. For a large cluster, it can take a long time for the configuration change to be reflected. At any time, you can adjust the number of machines that are updating to speed up the process.

Procedure

  1. Edit the worker machine config pool:

    1. $ oc edit machineconfigpool worker

  2. Set maxUnavailable to the value that you want:

    1. spec:
    2.   maxUnavailable: <node_count>

    When setting the value, consider the number of worker nodes that can be unavailable without affecting the applications running on the cluster.

Control plane node sizing

The control plane node resource requirements depend on the number of nodes in the cluster. The following control plane node size recommendations are based on the results of control plane density focused testing. The control plane tests create the following objects across the cluster in each of the namespaces depending on the node counts:

  • 12 image streams

  • 3 build configurations

  • 6 builds

  • 1 deployment with 2 pod replicas mounting two secrets each

  • 2 deployments with 1 pod replica mounting two secrets

  • 3 services pointing to the previous deployments

  • 3 routes pointing to the previous deployments

  • 10 secrets, 2 of which are mounted by the previous deployments

  • 10 config maps, 2 of which are mounted by the previous deployments

Number of worker nodesCluster load (namespaces)CPU coresMemory (GB)

25

500

4

16

100

1000

8

32

250

4000

16

96

On a large and dense cluster with three masters or control plane nodes, the CPU and memory usage will spike up when one of the nodes is stopped, rebooted or fails. The failures can be due to unexpected issues with power, network or underlying infrastructure in addition to intentional cases where the cluster is restarted after shutting it down to save costs. The remaining two control plane (also known as master) nodes must handle the load in order to be highly available which leads to increase in the resource usage. This is also expected during upgrades because the masters are cordoned, drained, and rebooted serially to apply the operating system updates, as well as the control plane Operators update. To avoid cascading failures, keep the overall resource usage on the control plane nodes (also known as the master nodes) to at most half of all available capacity to handle the resource usage spikes. Increase the CPU and memory on the control plane nodes accordingly to avoid potential downtime due to lack of resources.

The node sizing varies depending on the number of nodes and object counts in the cluster. It also depends on whether the objects are actively being created on the cluster. During object creation, the control plane is more active in terms of resource usage compared to when the objects are in the running phase.

If you used an installer-provisioned infrastructure installation method, you cannot modify the control plane node size in a running OKD 4.7 cluster. Instead, you must estimate your total node count and use the suggested control plane node size during installation.

The recommendations are based on the data points captured on OKD clusters with OpenShiftSDN as the network plug-in.

In OKD 4.7, half of a CPU core (500 millicore) is now reserved by the system by default compared to OKD 3.11 and previous versions. The sizes are determined taking that into consideration.

Setting up CPU Manager

Procedure

  1. Optional: Label a node:

    1. # oc label node perf-node.example.com cpumanager=true

  2. Edit the MachineConfigPool of the nodes where CPU Manager should be enabled. In this example, all workers have CPU Manager enabled:

    1. # oc edit machineconfigpool worker

  3. Add a label to the worker machine config pool:

    1. metadata:
    2.   creationTimestamp: 2020-xx-xxx
    3.   generation: 3
    4.   labels:
    5.     custom-kubelet: cpumanager-enabled

  4. Create a KubeletConfig, cpumanager-kubeletconfig.yaml, custom resource (CR). Refer to the label created in the previous step to have the correct nodes updated with the new kubelet config. See the machineConfigPoolSelector section:

    1. apiVersion: machineconfiguration.openshift.io/v1
    2. kind: KubeletConfig
    3. metadata:
    4.   name: cpumanager-enabled
    5. spec:
    6.   machineConfigPoolSelector:
    7.     matchLabels:
    8.       custom-kubelet: cpumanager-enabled
    9.   kubeletConfig:
    10.      cpuManagerPolicy: static (1)
    11.      cpuManagerReconcilePeriod: 5s (2)
    1Specify a policy:

    • none. This policy explicitly enables the existing default CPU affinity scheme, providing no affinity beyond what the scheduler does automatically.

    • static. This policy allows pods with certain resource characteristics to be granted increased CPU affinity and exclusivity on the node.

    2Optional. Specify the CPU Manager reconcile frequency. The default is 5s.

  5. Create the dynamic kubelet config:

    1. # oc create -f cpumanager-kubeletconfig.yaml

    This adds the CPU Manager feature to the kubelet config and, if needed, the Machine Config Operator (MCO) reboots the node. To enable CPU Manager, a reboot is not needed.

  6. Check for the merged kubelet config:

    1. # oc get machineconfig 99-worker-XXXXXX-XXXXX-XXXX-XXXXX-kubelet -o json | grep ownerReference -A7

    Example output

    1.        "ownerReferences": [
    2.             {
    3.                 "apiVersion": "machineconfiguration.openshift.io/v1",
    4.                 "kind": "KubeletConfig",
    5.                 "name": "cpumanager-enabled",
    6.                 "uid": "7ed5616d-6b72-11e9-aae1-021e1ce18878"
    7.             }
    8.         ]

  7. Check the worker for the updated kubelet.conf:

    1. # oc debug node/perf-node.example.com
    2. sh-4.2# cat /host/etc/kubernetes/kubelet.conf | grep cpuManager

    Example output

    1. cpuManagerPolicy: static        (1)
    2. cpuManagerReconcilePeriod: 5s   (1)
    1These settings were defined when you created the KubeletConfig CR.

  8. Create a pod that requests a core or multiple cores. Both limits and requests must have their CPU value set to a whole integer. That is the number of cores that will be dedicated to this pod:

    1. # cat cpumanager-pod.yaml

    Example output

    1. apiVersion: v1
    2. kind: Pod
    3. metadata:
    4.   generateName: cpumanager-
    5. spec:
    6.   containers:
    7.   - name: cpumanager
    8.     image: gcr.io/google_containers/pause-amd64:3.0
    9.     resources:
    10.       requests:
    11.         cpu: 1
    12.         memory: "1G"
    13.       limits:
    14.         cpu: 1
    15.         memory: "1G"
    16.   nodeSelector:
    17.     cpumanager: "true"

  9. Create the pod:

    1. # oc create -f cpumanager-pod.yaml

  10. Verify that the pod is scheduled to the node that you labeled:

    1. # oc describe pod cpumanager

    Example output

    1. Name:               cpumanager-6cqz7
    2. Namespace:          default
    3. Priority:           0
    4. PriorityClassName:  <none>
    5. Node:  perf-node.example.com/xxx.xx.xx.xxx
    6. ...
    7. Limits:
    8.      cpu:     1
    9.      memory:  1G
    10.    Requests:
    11.      cpu:        1
    12.      memory:     1G
    13. ...
    14. QoS Class:       Guaranteed
    15. Node-Selectors:  cpumanager=true

  11. Verify that the cgroups are set up correctly. Get the process ID (PID) of the pause process:

    1. # ├─init.scope
    2. │ └─1 /usr/lib/systemd/systemd --switched-root --system --deserialize 17
    3. └─kubepods.slice
    4.  ├─kubepods-pod69c01f8e_6b74_11e9_ac0f_0a2b62178a22.slice
    5.  │ ├─crio-b5437308f1a574c542bdf08563b865c0345c8f8c0b0a655612c.scope
    6.  │ └─32706 /pause

    Pods of quality of service (QoS) tier Guaranteed are placed within the kubepods.slice. Pods of other QoS tiers end up in child cgroups of kubepods:

    1. # cd /sys/fs/cgroup/cpuset/kubepods.slice/kubepods-pod69c01f8e_6b74_11e9_ac0f_0a2b62178a22.slice/crio-b5437308f1ad1a7db0574c542bdf08563b865c0345c86e9585f8c0b0a655612c.scope
    2. # for i in `ls cpuset.cpus tasks` ; do echo -n "$i "; cat $i ; done

    Example output

    1. cpuset.cpus 1
    2. tasks 32706

  12. Check the allowed CPU list for the task:

    1. # grep ^Cpus_allowed_list /proc/32706/status

    Example output

    1. Cpus_allowed_list:    1

  13. Verify that another pod (in this case, the pod in the burstable QoS tier) on the system cannot run on the core allocated for the Guaranteed pod:

    1. # cat /sys/fs/cgroup/cpuset/kubepods.slice/kubepods-besteffort.slice/kubepods-besteffort-podc494a073_6b77_11e9_98c0_06bba5c387ea.slice/crio-c56982f57b75a2420947f0afc6cafe7534c5734efc34157525fa9abbf99e3849.scope/cpuset.cpus
    2. 0
    3. # oc describe node perf-node.example.com

    Example output

    1. ...
    2. Capacity:
    3. attachable-volumes-aws-ebs:  39
    4. cpu:                         2
    5. ephemeral-storage:           124768236Ki
    6. hugepages-1Gi:               0
    7. hugepages-2Mi:               0
    8. memory:                      8162900Ki
    9. pods:                        250
    10. Allocatable:
    11. attachable-volumes-aws-ebs:  39
    12. cpu:                         1500m
    13. ephemeral-storage:           124768236Ki
    14. hugepages-1Gi:               0
    15. hugepages-2Mi:               0
    16. memory:                      7548500Ki
    17. pods:                        250
    18. -------                               ----                           ------------  ----------  ---------------  -------------  ---
    19.  default                                 cpumanager-6cqz7               1 (66%)       1 (66%)     1G (12%)         1G (12%)       29m
    21. Allocated resources:
    22.  (Total limits may be over 100 percent, i.e., overcommitted.)
    23.  Resource                    Requests          Limits
    24.  --------                    --------          ------
    25.  cpu                         1440m (96%)       1 (66%)

    This VM has two CPU cores. The system-reserved setting reserves 500 millicores, meaning that half of one core is subtracted from the total capacity of the node to arrive at the Node Allocatable amount. You can see that Allocatable CPU is 1500 millicores. This means you can run one of the CPU Manager pods since each will take one whole core. A whole core is equivalent to 1000 millicores. If you try to schedule a second pod, the system will accept the pod, but it will never be scheduled:

    1. NAME                    READY   STATUS    RESTARTS   AGE
    2. cpumanager-6cqz7        1/1     Running   0          33m
    3. cpumanager-7qc2t        0/1     Pending   0          11s

Huge pages

Understand and configure huge pages.

What huge pages do

Memory is managed in blocks known as pages. On most systems, a page is 4Ki. 1Mi of memory is equal to 256 pages; 1Gi of memory is 256,000 pages, and so on. CPUs have a built-in memory management unit that manages a list of these pages in hardware. The Translation Lookaside Buffer (TLB) is a small hardware cache of virtual-to-physical page mappings. If the virtual address passed in a hardware instruction can be found in the TLB, the mapping can be determined quickly. If not, a TLB miss occurs, and the system falls back to slower, software-based address translation, resulting in performance issues. Since the size of the TLB is fixed, the only way to reduce the chance of a TLB miss is to increase the page size.

A huge page is a memory page that is larger than 4Ki. On x86_64 architectures, there are two common huge page sizes: 2Mi and 1Gi. Sizes vary on other architectures. To use huge pages, code must be written so that applications are aware of them. Transparent Huge Pages (THP) attempt to automate the management of huge pages without application knowledge, but they have limitations. In particular, they are limited to 2Mi page sizes. THP can lead to performance degradation on nodes with high memory utilization or fragmentation due to defragmenting efforts of THP, which can lock memory pages. For this reason, some applications may be designed to (or recommend) usage of pre-allocated huge pages instead of THP.

How huge pages are consumed by apps

Nodes must pre-allocate huge pages in order for the node to report its huge page capacity. A node can only pre-allocate huge pages for a single size.

Huge pages can be consumed through container-level resource requirements using the resource name hugepages-<size>, where size is the most compact binary notation using integer values supported on a particular node. For example, if a node supports 2048KiB page sizes, it exposes a schedulable resource hugepages-2Mi. Unlike CPU or memory, huge pages do not support over-commitment.

  1. apiVersion: v1
  2. kind: Pod
  3. metadata:
  4.   generateName: hugepages-volume-
  5. spec:
  6.   containers:
  7.   - securityContext:
  8.       privileged: true
  9.     image: rhel7:latest
  10.     command:
  11.     - sleep
  12.     - inf
  13.     name: example
  14.     volumeMounts:
  15.     - mountPath: /dev/hugepages
  16.       name: hugepage
  17.     resources:
  18.       limits:
  19.         hugepages-2Mi: 100Mi (1)
  20.         memory: "1Gi"
  21.         cpu: "1"
  22.   volumes:
  23.   - name: hugepage
  24.     emptyDir:
  25.       medium: HugePages
1Specify the amount of memory for hugepages as the exact amount to be allocated. Do not specify this value as the amount of memory for hugepages multiplied by the size of the page. For example, given a huge page size of 2MB, if you want to use 100MB of huge-page-backed RAM for your application, then you would allocate 50 huge pages. OKD handles the math for you. As in the above example, you can specify 100MB directly.

Allocating huge pages of a specific size

Some platforms support multiple huge page sizes. To allocate huge pages of a specific size, precede the huge pages boot command parameters with a huge page size selection parameter hugepagesz=<size>. The <size> value must be specified in bytes with an optional scale suffix [kKmMgG]. The default huge page size can be defined with the default_hugepagesz=<size> boot parameter.

Huge page requirements

  • Huge page requests must equal the limits. This is the default if limits are specified, but requests are not.

  • Huge pages are isolated at a pod scope. Container isolation is planned in a future iteration.

  • EmptyDir volumes backed by huge pages must not consume more huge page memory than the pod request.

  • Applications that consume huge pages via shmget() with SHM_HUGETLB must run with a supplemental group that matches proc/sys/vm/hugetlb_shm_group.

Additional resources

Configuring huge pages

Nodes must pre-allocate huge pages used in an OKD cluster. There are two ways of reserving huge pages: at boot time and at run time. Reserving at boot time increases the possibility of success because the memory has not yet been significantly fragmented. The Node Tuning Operator currently supports boot time allocation of huge pages on specific nodes.

At boot time

Procedure

To minimize node reboots, the order of the steps below needs to be followed:

  1. Label all nodes that need the same huge pages setting by a label.

    1. $ oc label node <node_using_hugepages> node-role.kubernetes.io/worker-hp=

  2. Create a file with the following content and name it hugepages-tuned-boottime.yaml:

    1. apiVersion: tuned.openshift.io/v1
    2. kind: Tuned
    3. metadata:
    4.   name: hugepages (1)
    5.   namespace: openshift-cluster-node-tuning-operator
    6. spec:
    7.   profile: (2)
    8.   - data: |
    9.       [main]
    10.       summary=Boot time configuration for hugepages
    11.       include=openshift-node
    12.       [bootloader]
    13.       cmdline_openshift_node_hugepages=hugepagesz=2M hugepages=50 (3)
    14.     name: openshift-node-hugepages
    16.   recommend:
    17.   - machineConfigLabels: (4)
    18.       machineconfiguration.openshift.io/role: "worker-hp"
    19.     priority: 30
    20.     profile: openshift-node-hugepages
    1Set the name of the Tuned resource to hugepages.
    2Set the profile section to allocate huge pages.
    3Note the order of parameters is important as some platforms support huge pages of various sizes.
    4Enable machine config pool based matching.

  3. Create the Tuned hugepages profile

    1. $ oc create -f hugepages-tuned-boottime.yaml

  4. Create a file with the following content and name it hugepages-mcp.yaml:

    1. apiVersion: machineconfiguration.openshift.io/v1
    2. kind: MachineConfigPool
    3. metadata:
    4.   name: worker-hp
    5.   labels:
    6.     worker-hp: ""
    7. spec:
    8.   machineConfigSelector:
    9.     matchExpressions:
    10.       - {key: machineconfiguration.openshift.io/role, operator: In, values: [worker,worker-hp]}
    11.   nodeSelector:
    12.     matchLabels:
    13.       node-role.kubernetes.io/worker-hp: ""

  5. Create the machine config pool:

    1. $ oc create -f hugepages-mcp.yaml

Given enough non-fragmented memory, all the nodes in the worker-hp machine config pool should now have 50 2Mi huge pages allocated.

  1. $ oc get node <node_using_hugepages> -o jsonpath="{.status.allocatable.hugepages-2Mi}"
  2. 100Mi

This functionality is currently only supported on Fedora CoreOS (FCOS) 8.x worker nodes. On Fedora 7.x worker nodes the Tuned [bootloader] plug-in is currently not supported.

Understanding device plug-ins

The device plug-in provides a consistent and portable solution to consume hardware devices across clusters. The device plug-in provides support for these devices through an extension mechanism, which makes these devices available to Containers, provides health checks of these devices, and securely shares them.

OKD supports the device plug-in API, but the device plug-in Containers are supported by individual vendors.

A device plug-in is a gRPC service running on the nodes (external to the kubelet) that is responsible for managing specific hardware resources. Any device plug-in must support following remote procedure calls (RPCs):

  1. service DevicePlugin {
  2.       // GetDevicePluginOptions returns options to be communicated with Device
  3.       // Manager
  4.       rpc GetDevicePluginOptions(Empty) returns (DevicePluginOptions) {}
  6.       // ListAndWatch returns a stream of List of Devices
  7.       // Whenever a Device state change or a Device disappears, ListAndWatch
  8.       // returns the new list
  9.       rpc ListAndWatch(Empty) returns (stream ListAndWatchResponse) {}
  11.       // Allocate is called during container creation so that the Device
  12.       // Plug-in can run device specific operations and instruct Kubelet
  13.       // of the steps to make the Device available in the container
  14.       rpc Allocate(AllocateRequest) returns (AllocateResponse) {}
  16.       // PreStartcontainer is called, if indicated by Device Plug-in during
  17.       // registration phase, before each container start. Device plug-in
  18.       // can run device specific operations such as reseting the device
  19.       // before making devices available to the container
  20.       rpc PreStartcontainer(PreStartcontainerRequest) returns (PreStartcontainerResponse) {}
  21. }

Example device plug-ins

For easy device plug-in reference implementation, there is a stub device plug-in in the Device Manager code: vendor/k8s.io/kubernetes/pkg/kubelet/cm/deviceplugin/device_plugin_stub.go.

Methods for deploying a device plug-in

  • Daemon sets are the recommended approach for device plug-in deployments.

  • Upon start, the device plug-in will try to create a UNIX domain socket at /var/lib/kubelet/device-plugin/ on the node to serve RPCs from Device Manager.

  • Since device plug-ins must manage hardware resources, access to the host file system, as well as socket creation, they must be run in a privileged security context.

  • More specific details regarding deployment steps can be found with each device plug-in implementation.

Understanding the Device Manager

Device Manager provides a mechanism for advertising specialized node hardware resources with the help of plug-ins known as device plug-ins.

You can advertise specialized hardware without requiring any upstream code changes.

OKD supports the device plug-in API, but the device plug-in Containers are supported by individual vendors.

Device Manager advertises devices as Extended Resources. User pods can consume devices, advertised by Device Manager, using the same Limit/Request mechanism, which is used for requesting any other Extended Resource.

Upon start, the device plug-in registers itself with Device Manager invoking Register on the /var/lib/kubelet/device-plugins/kubelet.sock and starts a gRPC service at /var/lib/kubelet/device-plugins/<plugin>.sock for serving Device Manager requests.

Device Manager, while processing a new registration request, invokes ListAndWatch remote procedure call (RPC) at the device plug-in service. In response, Device Manager gets a list of Device objects from the plug-in over a gRPC stream. Device Manager will keep watching on the stream for new updates from the plug-in. On the plug-in side, the plug-in will also keep the stream open and whenever there is a change in the state of any of the devices, a new device list is sent to the Device Manager over the same streaming connection.

While handling a new pod admission request, Kubelet passes requested Extended Resources to the Device Manager for device allocation. Device Manager checks in its database to verify if a corresponding plug-in exists or not. If the plug-in exists and there are free allocatable devices as well as per local cache, Allocate RPC is invoked at that particular device plug-in.

Additionally, device plug-ins can also perform several other device-specific operations, such as driver installation, device initialization, and device resets. These functionalities vary from implementation to implementation.

Enabling Device Manager

Enable Device Manager to implement a device plug-in to advertise specialized hardware without any upstream code changes.

Device Manager provides a mechanism for advertising specialized node hardware resources with the help of plug-ins known as device plug-ins.

  1. Obtain the label associated with the static MachineConfigPool CRD for the type of node you want to configure. Perform one of the following steps:

    1. View the machine config:

      1. # oc describe machineconfig <name>

      For example:

      1. # oc describe machineconfig 00-worker

      Example output

      1. Name:         00-worker
      2. Namespace:
      3. Labels:       machineconfiguration.openshift.io/role=worker (1)
      1Label required for the Device Manager.

Procedure

  1. Create a custom resource (CR) for your configuration change.

    Sample configuration for a Device Manager CR

    1. apiVersion: machineconfiguration.openshift.io/v1
    2. kind: KubeletConfig
    3. metadata:
    4.   name: devicemgr (1)
    5. spec:
    6.   machineConfigPoolSelector:
    7.     matchLabels:
    8.        machineconfiguration.openshift.io: devicemgr (2)
    9.   kubeletConfig:
    10.     feature-gates:
    11.       - DevicePlugins=true (3)
    1Assign a name to CR.
    2Enter the label from the Machine Config Pool.
    3Set DevicePlugins to ‘true`.

  2. Create the Device Manager:

    1. $ oc create -f devicemgr.yaml

    Example output

    1. kubeletconfig.machineconfiguration.openshift.io/devicemgr created

  3. Ensure that Device Manager was actually enabled by confirming that /var/lib/kubelet/device-plugins/kubelet.sock is created on the node. This is the UNIX domain socket on which the Device Manager gRPC server listens for new plug-in registrations. This sock file is created when the Kubelet is started only if Device Manager is enabled.

Taints and tolerations

Understand and work with taints and tolerations.

Understanding taints and tolerations

A taint allows a node to refuse a pod to be scheduled unless that pod has a matching toleration.

You apply taints to a node through the Node specification (NodeSpec) and apply tolerations to a pod through the Pod specification (PodSpec). When you apply a taint a node, the scheduler cannot place a pod on that node unless the pod can tolerate the taint.

Example taint in a node specification

  1. spec:
  2. ....
  3.   template:
  4. ....
  5.     spec:
  6.       taints:
  7.       - effect: NoExecute
  8.         key: key1
  9.         value: value1
  10. ....

Example toleration in a Pod spec

  1. spec:
  2. ....
  3.   template:
  4. ....
  5.     spec:
  6.       tolerations:
  7.       - key: "key1"
  8.         operator: "Equal"
  9.         value: "value1"
  10.         effect: "NoExecute"
  11.         tolerationSeconds: 3600
  12. ....

Taints and tolerations consist of a key, value, and effect.

Table 1. Taint and toleration components
ParameterDescription

key

The key is any string, up to 253 characters. The key must begin with a letter or number, and may contain letters, numbers, hyphens, dots, and underscores.

value

The value is any string, up to 63 characters. The value must begin with a letter or number, and may contain letters, numbers, hyphens, dots, and underscores.

effect

The effect is one of the following:

NoSchedule [1]

  • New pods that do not match the taint are not scheduled onto that node.

  • Existing pods on the node remain.

PreferNoSchedule

  • New pods that do not match the taint might be scheduled onto that node, but the scheduler tries not to.

  • Existing pods on the node remain.

NoExecute

  • New pods that do not match the taint cannot be scheduled onto that node.

  • Existing pods on the node that do not have a matching toleration are removed.

operator

Equal

The key/value/effect parameters must match. This is the default.

Exists

The key/effect parameters must match. You must leave a blank value parameter, which matches any.

  1. If you add a NoSchedule taint to a control plane node (also known as the master node) the node must have the node-role.kubernetes.io/master=:NoSchedule taint, which is added by default.

    For example:

    1. apiVersion: v1
    2. kind: Node
    3. metadata:
    4.   annotations:
    5.     machine.openshift.io/machine: openshift-machine-api/ci-ln-62s7gtb-f76d1-v8jxv-master-0
    6.     machineconfiguration.openshift.io/currentConfig: rendered-master-cdc1ab7da414629332cc4c3926e6e59c
    7. ...
    8. spec:
    9.   taints:
    10.   - effect: NoSchedule
    11.     key: node-role.kubernetes.io/master
    12. ...

A toleration matches a taint:

  • If the operator parameter is set to Equal:

    • the key parameters are the same;

    • the value parameters are the same;

    • the effect parameters are the same.

  • If the operator parameter is set to Exists:

    • the key parameters are the same;

    • the effect parameters are the same.

The following taints are built into OKD:

  • node.kubernetes.io/not-ready: The node is not ready. This corresponds to the node condition Ready=False.

  • node.kubernetes.io/unreachable: The node is unreachable from the node controller. This corresponds to the node condition Ready=Unknown.

  • node.kubernetes.io/out-of-disk: The node has insufficient free space on the node for adding new pods. This corresponds to the node condition OutOfDisk=True.

  • node.kubernetes.io/memory-pressure: The node has memory pressure issues. This corresponds to the node condition MemoryPressure=True.

  • node.kubernetes.io/disk-pressure: The node has disk pressure issues. This corresponds to the node condition DiskPressure=True.

  • node.kubernetes.io/network-unavailable: The node network is unavailable.

  • node.kubernetes.io/unschedulable: The node is unschedulable.

  • node.cloudprovider.kubernetes.io/uninitialized: When the node controller is started with an external cloud provider, this taint is set on a node to mark it as unusable. After a controller from the cloud-controller-manager initializes this node, the kubelet removes this taint.

Understanding how to use toleration seconds to delay pod evictions

You can specify how long a pod can remain bound to a node before being evicted by specifying the tolerationSeconds parameter in the Pod specification or MachineSet object. If a taint with the NoExecute effect is added to a node, a pod that does tolerate the taint, which has the tolerationSeconds parameter, the pod is not evicted until that time period expires.

Example output

  1. spec:
  2. ....
  3.   template:
  4. ....
  5.     spec:
  6.       tolerations:
  7.       - key: "key1"
  8.         operator: "Equal"
  9.         value: "value1"
  10.         effect: "NoExecute"
  11.         tolerationSeconds: 3600

Here, if this pod is running but does not have a matching toleration, the pod stays bound to the node for 3,600 seconds and then be evicted. If the taint is removed before that time, the pod is not evicted.

Understanding how to use multiple taints

You can put multiple taints on the same node and multiple tolerations on the same pod. OKD processes multiple taints and tolerations as follows:

  1. Process the taints for which the pod has a matching toleration.

  2. The remaining unmatched taints have the indicated effects on the pod:

    • If there is at least one unmatched taint with effect NoSchedule, OKD cannot schedule a pod onto that node.

    • If there is no unmatched taint with effect NoSchedule but there is at least one unmatched taint with effect PreferNoSchedule, OKD tries to not schedule the pod onto the node.

    • If there is at least one unmatched taint with effect NoExecute, OKD evicts the pod from the node if it is already running on the node, or the pod is not scheduled onto the node if it is not yet running on the node.

      • Pods that do not tolerate the taint are evicted immediately.

      • Pods that tolerate the taint without specifying tolerationSeconds in their Pod specification remain bound forever.

      • Pods that tolerate the taint with a specified tolerationSeconds remain bound for the specified amount of time.

For example:

  • Add the following taints to the node:

    1. $ oc adm taint nodes node1 key1=value1:NoSchedule
    1. $ oc adm taint nodes node1 key1=value1:NoExecute
    1. $ oc adm taint nodes node1 key2=value2:NoSchedule

  • The pod has the following tolerations:

    1. spec:
    2. ....
    3.   template:
    4. ....
    5.     spec:
    6.       tolerations:
    7.       - key: "key1"
    8.         operator: "Equal"
    9.         value: "value1"
    10.         effect: "NoSchedule"
    11.       - key: "key1"
    12.         operator: "Equal"
    13.         value: "value1"
    14.         effect: "NoExecute"

In this case, the pod cannot be scheduled onto the node, because there is no toleration matching the third taint. The pod continues running if it is already running on the node when the taint is added, because the third taint is the only one of the three that is not tolerated by the pod.

Understanding pod scheduling and node conditions (taint node by condition)

The Taint Nodes By Condition feature, which is enabled by default, automatically taints nodes that report conditions such as memory pressure and disk pressure. If a node reports a condition, a taint is added until the condition clears. The taints have the NoSchedule effect, which means no pod can be scheduled on the node unless the pod has a matching toleration.

The scheduler checks for these taints on nodes before scheduling pods. If the taint is present, the pod is scheduled on a different node. Because the scheduler checks for taints and not the actual node conditions, you configure the scheduler to ignore some of these node conditions by adding appropriate pod tolerations.

To ensure backward compatibility, the daemon set controller automatically adds the following tolerations to all daemons:

  • node.kubernetes.io/memory-pressure

  • node.kubernetes.io/disk-pressure

  • node.kubernetes.io/out-of-disk (only for critical pods)

  • node.kubernetes.io/unschedulable (1.10 or later)

  • node.kubernetes.io/network-unavailable (host network only)

You can also add arbitrary tolerations to daemon sets.

Understanding evicting pods by condition (taint-based evictions)

The Taint-Based Evictions feature, which is enabled by default, evicts pods from a node that experiences specific conditions, such as not-ready and unreachable. When a node experiences one of these conditions, OKD automatically adds taints to the node, and starts evicting and rescheduling the pods on different nodes.

Taint Based Evictions have a NoExecute effect, where any pod that does not tolerate the taint is evicted immediately and any pod that does tolerate the taint will never be evicted, unless the pod uses the tolerationSeconds parameter.

The tolerationSeconds parameter allows you to specify how long a pod stays bound to a node that has a node condition. If the condition still exists after the tolerationSeconds period, the taint remains on the node and the pods with a matching toleration are evicted. If the condition clears before the tolerationSeconds period, pods with matching tolerations are not removed.

If you use the tolerationSeconds parameter with no value, pods are never evicted because of the not ready and unreachable node conditions.

OKD evicts pods in a rate-limited way to prevent massive pod evictions in scenarios such as the master becoming partitioned from the nodes.

OKD automatically adds a toleration for node.kubernetes.io/not-ready and node.kubernetes.io/unreachable with tolerationSeconds=300, unless the Pod configuration specifies either toleration.

  1. spec:
  2. ....
  3.   template:
  4. ....
  5.     spec:
  6.       tolerations:
  7.       - key: node.kubernetes.io/not-ready
  8.         operator: Exists
  9.         effect: NoExecute
  10.         tolerationSeconds: 300 (1)
  11.       - key: node.kubernetes.io/unreachable
  12.         operator: Exists
  13.         effect: NoExecute
  14.         tolerationSeconds: 300
1These tolerations ensure that the default pod behavior is to remain bound for five minutes after one of these node conditions problems is detected.

You can configure these tolerations as needed. For example, if you have an application with a lot of local state, you might want to keep the pods bound to node for a longer time in the event of network partition, allowing for the partition to recover and avoiding pod eviction.

Pods spawned by a daemon set are created with NoExecute tolerations for the following taints with no tolerationSeconds:

  • node.kubernetes.io/unreachable

  • node.kubernetes.io/not-ready

As a result, daemon set pods are never evicted because of these node conditions.

Tolerating all taints

You can configure a pod to tolerate all taints by adding an operator: "Exists" toleration with no key and value parameters. Pods with this toleration are not removed from a node that has taints.

Pod spec for tolerating all taints

  1. spec:
  2. ....
  3.   template:
  4. ....
  5.     spec:
  6.       tolerations:
  7.       - operator: "Exists"

Adding taints and tolerations

You add tolerations to pods and taints to nodes to allow the node to control which pods should or should not be scheduled on them. For existing pods and nodes, you should add the toleration to the pod first, then add the taint to the node to avoid pods being removed from the node before you can add the toleration.

Procedure

  1. Add a toleration to a pod by editing the Pod spec to include a tolerations stanza:

    Sample pod configuration file with an Equal operator

    1. spec:
    2. ....
    3.   template:
    4. ....
    5.     spec:
    6.       tolerations:
    7.       - key: "key1" (1)
    8.         value: "value1"
    9.         operator: "Equal"
    10.         effect: "NoExecute"
    11.         tolerationSeconds: 3600 (2)
    1The toleration parameters, as described in the Taint and toleration components table.
    2The tolerationSeconds parameter specifies how long a pod can remain bound to a node before being evicted.

    For example:

    Sample pod configuration file with an Exists operator

    1. spec:
    2. ....
    3.   template:
    4. ....
    5.     spec:
    6.       tolerations:
    7.       - key: "key1"
    8.         operator: "Exists" (1)
    9.         effect: "NoExecute"
    10.         tolerationSeconds: 3600
    1The Exists operator does not take a value.

    This example places a taint on node1 that has key key1, value value1, and taint effect NoExecute.

  2. Add a taint to a node by using the following command with the parameters described in the Taint and toleration components table:

    1. $ oc adm taint nodes <node_name> <key>=<value>:<effect>

    For example:

    1. $ oc adm taint nodes node1 key1=value1:NoExecute

    This command places a taint on node1 that has key key1, value value1, and effect NoExecute.

    If you add a NoSchedule taint to a control plane node (also known as the master node) the node must have the node-role.kubernetes.io/master=:NoSchedule taint, which is added by default.

    For example:

    1. apiVersion: v1
    2. kind: Node
    3. metadata:
    4.   annotations:
    5.     machine.openshift.io/machine: openshift-machine-api/ci-ln-62s7gtb-f76d1-v8jxv-master-0
    6.     machineconfiguration.openshift.io/currentConfig: rendered-master-cdc1ab7da414629332cc4c3926e6e59c
    7. …
    8. spec:
    9.   taints:
    10.   - effect: NoSchedule
    11.     key: node-role.kubernetes.io/master
    12. …

    The tolerations on the Pod match the taint on the node. A pod with either toleration can be scheduled onto node1.

Adding taints and tolerations using a machine set

You can add taints to nodes using a machine set. All nodes associated with the MachineSet object are updated with the taint. Tolerations respond to taints added by a machine set in the same manner as taints added directly to the nodes.

Procedure

  1. Add a toleration to a pod by editing the Pod spec to include a tolerations stanza:

    Sample pod configuration file with Equal operator

    1. spec:
    2. ....
    3.   template:
    4. ....
    5.     spec:
    6.       tolerations:
    7.       - key: "key1" (1)
    8.         value: "value1"
    9.         operator: "Equal"
    10.         effect: "NoExecute"
    11.         tolerationSeconds: 3600 (2)
    1The toleration parameters, as described in the Taint and toleration components table.
    2The tolerationSeconds parameter specifies how long a pod is bound to a node before being evicted.

    For example:

    Sample pod configuration file with Exists operator

    1. spec:
    2. ....
    3.   template:
    4. ....
    5.     spec:
    6.       tolerations:
    7.       - key: "key1"
    8.         operator: "Exists"
    9.         effect: "NoExecute"
    10.         tolerationSeconds: 3600

  2. Add the taint to the MachineSet object:

    1. Edit the MachineSet YAML for the nodes you want to taint or you can create a new MachineSet object:

      1. $ oc edit machineset <machineset>

    2. Add the taint to the spec.template.spec section:

      Example taint in a node specification

      1. spec:
      2. ....
      3.   template:
      4. ....
      5.     spec:
      6.       taints:
      7.       - effect: NoExecute
      8.         key: key1
      9.         value: value1
      10. ....

      This example places a taint that has the key key1, value value1, and taint effect NoExecute on the nodes.

    3. Scale down the machine set to 0:

      1. $ oc scale --replicas=0 machineset <machineset> -n openshift-machine-api

      Wait for the machines to be removed.

    4. Scale up the machine set as needed:

      1. $ oc scale --replicas=2 machineset <machineset> -n openshift-machine-api

      Wait for the machines to start. The taint is added to the nodes associated with the MachineSet object.

Binding a user to a node using taints and tolerations

If you want to dedicate a set of nodes for exclusive use by a particular set of users, add a toleration to their pods. Then, add a corresponding taint to those nodes. The pods with the tolerations are allowed to use the tainted nodes, or any other nodes in the cluster.

If you want ensure the pods are scheduled to only those tainted nodes, also add a label to the same set of nodes and add a node affinity to the pods so that the pods can only be scheduled onto nodes with that label.

Procedure

To configure a node so that users can use only that node:

  1. Add a corresponding taint to those nodes:

    For example:

    1. $ oc adm taint nodes node1 dedicated=groupName:NoSchedule

  2. Add a toleration to the pods by writing a custom admission controller.

Controlling nodes with special hardware using taints and tolerations

In a cluster where a small subset of nodes have specialized hardware, you can use taints and tolerations to keep pods that do not need the specialized hardware off of those nodes, leaving the nodes for pods that do need the specialized hardware. You can also require pods that need specialized hardware to use specific nodes.

You can achieve this by adding a toleration to pods that need the special hardware and tainting the nodes that have the specialized hardware.

Procedure

To ensure nodes with specialized hardware are reserved for specific pods:

  1. Add a toleration to pods that need the special hardware.

    For example:

    1. spec:
    2. ....
    3.   template:
    4. ....
    5.     spec:
    6.       tolerations:
    7.       - key: "disktype"
    8.         value: "ssd"
    9.         operator: "Equal"
    10.         effect: "NoSchedule"
    11.         tolerationSeconds: 3600

  2. Taint the nodes that have the specialized hardware using one of the following commands:

    1. $ oc adm taint nodes <node-name> disktype=ssd:NoSchedule

    Or:

    1. $ oc adm taint nodes <node-name> disktype=ssd:PreferNoSchedule

Removing taints and tolerations

You can remove taints from nodes and tolerations from pods as needed. You should add the toleration to the pod first, then add the taint to the node to avoid pods being removed from the node before you can add the toleration.

Procedure

To remove taints and tolerations:

  1. To remove a taint from a node:

    1. $ oc adm taint nodes <node-name> <key>-

    For example:

    1. $ oc adm taint nodes ip-10-0-132-248.ec2.internal key1-

    Example output

    1. node/ip-10-0-132-248.ec2.internal untainted

  2. To remove a toleration from a pod, edit the Pod spec to remove the toleration:

    1. spec:
    2. ....
    3.   template:
    4. ....
    5.     spec:
    6.       tolerations:
    7.       - key: "key2"
    8.         operator: "Exists"
    9.         effect: "NoExecute"
    10.         tolerationSeconds: 3600

Topology Manager

Understand and work with Topology Manager.

Topology Manager policies

Topology Manager aligns Pod resources of all Quality of Service (QoS) classes by collecting topology hints from Hint Providers, such as CPU Manager and Device Manager, and using the collected hints to align the Pod resources.

To align CPU resources with other requested resources in a Pod spec, the CPU Manager must be enabled with the static CPU Manager policy.

Topology Manager supports four allocation policies, which you assign in the cpumanager-enabled custom resource (CR):

none policy

This is the default policy and does not perform any topology alignment.

best-effort policy

For each container in a pod with the best-effort topology management policy, kubelet calls each Hint Provider to discover their resource availability. Using this information, the Topology Manager stores the preferred NUMA Node affinity for that container. If the affinity is not preferred, Topology Manager stores this and admits the pod to the node.

restricted policy

For each container in a pod with the restricted topology management policy, kubelet calls each Hint Provider to discover their resource availability. Using this information, the Topology Manager stores the preferred NUMA Node affinity for that container. If the affinity is not preferred, Topology Manager rejects this pod from the node, resulting in a pod in a Terminated state with a pod admission failure.

single-numa-node policy

For each container in a pod with the single-numa-node topology management policy, kubelet calls each Hint Provider to discover their resource availability. Using this information, the Topology Manager determines if a single NUMA Node affinity is possible. If it is, the pod is admitted to the node. If a single NUMA Node affinity is not possible, the Topology Manager rejects the pod from the node. This results in a pod in a Terminated state with a pod admission failure.

Setting up Topology Manager

To use Topology Manager, you must configure an allocation policy in the cpumanager-enabled custom resource (CR). This file might exist if you have set up CPU Manager. If the file does not exist, you can create the file.

Prequisites

  • Configure the CPU Manager policy to be static. Refer to Using CPU Manager in the Scalability and Performance section.

Procedure

To activate Topololgy Manager:

  1. Configure the Topology Manager allocation policy in the cpumanager-enabled custom resource (CR).

    1. $ oc edit KubeletConfig cpumanager-enabled
    1. apiVersion: machineconfiguration.openshift.io/v1
    2. kind: KubeletConfig
    3. metadata:
    4.   name: cpumanager-enabled
    5. spec:
    6.   machineConfigPoolSelector:
    7.     matchLabels:
    8.       custom-kubelet: cpumanager-enabled
    9.   kubeletConfig:
    10.      cpuManagerPolicy: static (1)
    11.      cpuManagerReconcilePeriod: 5s
    12.      topologyManagerPolicy: single-numa-node (2)
    1This parameter must be static.
    2Specify your selected Topology Manager allocation policy. Here, the policy is single-numa-node. Acceptable values are: default, best-effort, restricted, single-numa-node.

Pod interactions with Topology Manager policies

The example Pod specs below help illustrate pod interactions with Topology Manager.

The following pod runs in the BestEffort QoS class because no resource requests or limits are specified.

  1. spec:
  2.   containers:
  3.   - name: nginx
  4.     image: nginx

The next pod runs in the Burstable QoS class because requests are less than limits.

  1. spec:
  2.   containers:
  3.   - name: nginx
  4.     image: nginx
  5.     resources:
  6.       limits:
  7.         memory: "200Mi"
  8.       requests:
  9.         memory: "100Mi"

If the selected policy is anything other than none, Topology Manager would not consider either of these Pod specifications.

The last example pod below runs in the Guaranteed QoS class because requests are equal to limits.

  1. spec:
  2.   containers:
  3.   - name: nginx
  4.     image: nginx
  5.     resources:
  6.       limits:
  7.         memory: "200Mi"
  8.         cpu: "2"
  9.         example.com/device: "1"
  10.       requests:
  11.         memory: "200Mi"
  12.         cpu: "2"
  13.         example.com/device: "1"

Topology Manager would consider this pod. The Topology Manager consults the CPU Manager static policy, which returns the topology of available CPUs. Topology Manager also consults Device Manager to discover the topology of available devices for example.com/device.

Topology Manager will use this information to store the best Topology for this container. In the case of this pod, CPU Manager and Device Manager will use this stored information at the resource allocation stage.

Resource requests and overcommitment

For each compute resource, a container may specify a resource request and limit. Scheduling decisions are made based on the request to ensure that a node has enough capacity available to meet the requested value. If a container specifies limits, but omits requests, the requests are defaulted to the limits. A container is not able to exceed the specified limit on the node.

The enforcement of limits is dependent upon the compute resource type. If a container makes no request or limit, the container is scheduled to a node with no resource guarantees. In practice, the container is able to consume as much of the specified resource as is available with the lowest local priority. In low resource situations, containers that specify no resource requests are given the lowest quality of service.

Scheduling is based on resources requested, while quota and hard limits refer to resource limits, which can be set higher than requested resources. The difference between request and limit determines the level of overcommit; for instance, if a container is given a memory request of 1Gi and a memory limit of 2Gi, it is scheduled based on the 1Gi request being available on the node, but could use up to 2Gi; so it is 200% overcommitted.

Cluster-level overcommit using the Cluster Resource Override Operator

The Cluster Resource Override Operator is an admission webhook that allows you to control the level of overcommit and manage container density across all the nodes in your cluster. The Operator controls how nodes in specific projects can exceed defined memory and CPU limits.

You must install the Cluster Resource Override Operator using the OKD console or CLI as shown in the following sections. During the installation, you create a ClusterResourceOverride custom resource (CR), where you set the level of overcommit, as shown in the following example:

  1. apiVersion: operator.autoscaling.openshift.io/v1
  2. kind: ClusterResourceOverride
  3. metadata:
  4. -   name: cluster (1)
  5. spec:
  6.    memoryRequestToLimitPercent: 50 (2)
  7.    cpuRequestToLimitPercent: 25 (3)
  8.    limitCPUToMemoryPercent: 200 (4)
1The name must be cluster.
2Optional. If a container memory limit has been specified or defaulted, the memory request is overridden to this percentage of the limit, between 1-100. The default is 50.
3Optional. If a container CPU limit has been specified or defaulted, the CPU request is overridden to this percentage of the limit, between 1-100. The default is 25.
4Optional. If a container memory limit has been specified or defaulted, the CPU limit is overridden to a percentage of the memory limit, if specified. Scaling 1Gi of RAM at 100 percent is equal to 1 CPU core. This is processed prior to overriding the CPU request (if configured). The default is 200.

The Cluster Resource Override Operator overrides have no effect if limits have not been set on containers. Create a LimitRange object with default limits per individual project or configure limits in Pod specs for the overrides to apply.

When configured, overrides can be enabled per-project by applying the following label to the Namespace object for each project:

  1. apiVersion: v1
  2. kind: Namespace
  3. metadata:
  5. ....
  7.   labels:
  8.     clusterresourceoverrides.admission.autoscaling.openshift.io/enabled: "true"
  10. ....

The Operator watches for the ClusterResourceOverride CR and ensures that the ClusterResourceOverride admission webhook is installed into the same namespace as the operator.

Installing the Cluster Resource Override Operator using the web console

You can use the OKD web console to install the Cluster Resource Override Operator to help control overcommit in your cluster.

Prerequisites

  • The Cluster Resource Override Operator has no effect if limits have not been set on containers. You must specify default limits for a project using a LimitRange object or configure limits in Pod specs for the overrides to apply.

Procedure

To install the Cluster Resource Override Operator using the OKD web console:

  1. In the OKD web console, navigate to Home → Projects

    1. Click Create Project.

    2. Specify clusterresourceoverride-operator as the name of the project.

    3. Click Create.

  2. Navigate to Operators → OperatorHub.

    1. Choose ClusterResourceOverride Operator from the list of available Operators and click Install.

    2. On the Install Operator page, make sure A specific Namespace on the cluster is selected for Installation Mode.

    3. Make sure clusterresourceoverride-operator is selected for Installed Namespace.

    4. Select an Update Channel and Approval Strategy.

    5. Click Install.

  3. On the Installed Operators page, click ClusterResourceOverride.

    1. On the ClusterResourceOverride Operator details page, click Create Instance.

    2. On the Create ClusterResourceOverride page, edit the YAML template to set the overcommit values as needed:

      1. apiVersion: operator.autoscaling.openshift.io/v1
      2. kind: ClusterResourceOverride
      3. metadata:
      4.   name: cluster (1)
      5. spec:
      6.   podResourceOverride:
      7.     spec:
      8.       memoryRequestToLimitPercent: 50 (2)
      9.       cpuRequestToLimitPercent: 25 (3)
      10.       limitCPUToMemoryPercent: 200 (4)
      1The name must be cluster.
      2Optional. Specify the percentage to override the container memory limit, if used, between 1-100. The default is 50.
      3Optional. Specify the percentage to override the container CPU limit, if used, between 1-100. The default is 25.
      4Optional. Specify the percentage to override the container memory limit, if used. Scaling 1Gi of RAM at 100 percent is equal to 1 CPU core. This is processed prior to overriding the CPU request, if configured. The default is 200.

    3. Click Create.

  4. Check the current state of the admission webhook by checking the status of the cluster custom resource:

    1. On the ClusterResourceOverride Operator page, click cluster.

    2. On the ClusterResourceOverride Details age, click YAML. The mutatingWebhookConfigurationRef section appears when the webhook is called.

      1. apiVersion: operator.autoscaling.openshift.io/v1
      2. kind: ClusterResourceOverride
      3. metadata:
      4.   annotations:
      5.     kubectl.kubernetes.io/last-applied-configuration: |
      6.       {"apiVersion":"operator.autoscaling.openshift.io/v1","kind":"ClusterResourceOverride","metadata":{"annotations":{},"name":"cluster"},"spec":{"podResourceOverride":{"spec":{"cpuRequestToLimitPercent":25,"limitCPUToMemoryPercent":200,"memoryRequestToLimitPercent":50}}}}
      7.   creationTimestamp: "2019-12-18T22:35:02Z"
      8.   generation: 1
      9.   name: cluster
      10.   resourceVersion: "127622"
      11.   selfLink: /apis/operator.autoscaling.openshift.io/v1/clusterresourceoverrides/cluster
      12.   uid: 978fc959-1717-4bd1-97d0-ae00ee111e8d
      13. spec:
      14.   podResourceOverride:
      15.     spec:
      16.       cpuRequestToLimitPercent: 25
      17.       limitCPUToMemoryPercent: 200
      18.       memoryRequestToLimitPercent: 50
      19. status:
      21. ....
      23.     mutatingWebhookConfigurationRef: (1)
      24.       apiVersion: admissionregistration.k8s.io/v1beta1
      25.       kind: MutatingWebhookConfiguration
      26.       name: clusterresourceoverrides.admission.autoscaling.openshift.io
      27.       resourceVersion: "127621"
      28.       uid: 98b3b8ae-d5ce-462b-8ab5-a729ea8f38f3
      30. ....
      1Reference to the ClusterResourceOverride admission webhook.

Installing the Cluster Resource Override Operator using the CLI

You can use the OKD CLI to install the Cluster Resource Override Operator to help control overcommit in your cluster.

Prerequisites

  • The Cluster Resource Override Operator has no effect if limits have not been set on containers. You must specify default limits for a project using a LimitRange object or configure limits in Pod specs for the overrides to apply.

Procedure

To install the Cluster Resource Override Operator using the CLI:

  1. Create a namespace for the Cluster Resource Override Operator:

    1. Create a Namespace object YAML file (for example, cro-namespace.yaml) for the Cluster Resource Override Operator:

      1. apiVersion: v1
      2. kind: Namespace
      3. metadata:
      4.   name: clusterresourceoverride-operator

    2. Create the namespace:

      1. $ oc create -f <file-name>.yaml

      For example:

      1. $ oc create -f cro-namespace.yaml

  2. Create an Operator group:

    1. Create an OperatorGroup object YAML file (for example, cro-og.yaml) for the Cluster Resource Override Operator:

      1. apiVersion: operators.coreos.com/v1
      2. kind: OperatorGroup
      3. metadata:
      4.   name: clusterresourceoverride-operator
      5.   namespace: clusterresourceoverride-operator
      6. spec:
      7.   targetNamespaces:
      8.     - clusterresourceoverride-operator

    2. Create the Operator Group:

      1. $ oc create -f <file-name>.yaml

      For example:

      1. $ oc create -f cro-og.yaml

  3. Create a subscription:

    1. Create a Subscription object YAML file (for example, cro-sub.yaml) for the Cluster Resource Override Operator:

      1. apiVersion: operators.coreos.com/v1alpha1
      2. kind: Subscription
      3. metadata:
      4.   name: clusterresourceoverride
      5.   namespace: clusterresourceoverride-operator
      6. spec:
      7.   channel: "4.7"
      8.   name: clusterresourceoverride
      9.   source: redhat-operators
      10.   sourceNamespace: openshift-marketplace

    2. Create the subscription:

      1. $ oc create -f <file-name>.yaml

      For example:

      1. $ oc create -f cro-sub.yaml

  4. Create a ClusterResourceOverride custom resource (CR) object in the clusterresourceoverride-operator namespace:

    1. Change to the clusterresourceoverride-operator namespace.

      1. $ oc project clusterresourceoverride-operator

    2. Create a ClusterResourceOverride object YAML file (for example, cro-cr.yaml) for the Cluster Resource Override Operator:

      1. apiVersion: operator.autoscaling.openshift.io/v1
      2. kind: ClusterResourceOverride
      3. metadata:
      4.     name: cluster (1)
      5. spec:
      6.   podResourceOverride:
      7.     spec:
      8.       memoryRequestToLimitPercent: 50 (2)
      9.       cpuRequestToLimitPercent: 25 (3)
      10.       limitCPUToMemoryPercent: 200 (4)
      1The name must be cluster.
      2Optional. Specify the percentage to override the container memory limit, if used, between 1-100. The default is 50.
      3Optional. Specify the percentage to override the container CPU limit, if used, between 1-100. The default is 25.
      4Optional. Specify the percentage to override the container memory limit, if used. Scaling 1Gi of RAM at 100 percent is equal to 1 CPU core. This is processed prior to overriding the CPU request, if configured. The default is 200.

    3. Create the ClusterResourceOverride object:

      1. $ oc create -f <file-name>.yaml

      For example:

      1. $ oc create -f cro-cr.yaml

  5. Verify the current state of the admission webhook by checking the status of the cluster custom resource.

    1. $ oc get clusterresourceoverride cluster -n clusterresourceoverride-operator -o yaml

    The mutatingWebhookConfigurationRef section appears when the webhook is called.

    Example output

    1. apiVersion: operator.autoscaling.openshift.io/v1
    2. kind: ClusterResourceOverride
    3. metadata:
    4.   annotations:
    5.     kubectl.kubernetes.io/last-applied-configuration: |
    6.       {"apiVersion":"operator.autoscaling.openshift.io/v1","kind":"ClusterResourceOverride","metadata":{"annotations":{},"name":"cluster"},"spec":{"podResourceOverride":{"spec":{"cpuRequestToLimitPercent":25,"limitCPUToMemoryPercent":200,"memoryRequestToLimitPercent":50}}}}
    7.   creationTimestamp: "2019-12-18T22:35:02Z"
    8.   generation: 1
    9.   name: cluster
    10.   resourceVersion: "127622"
    11.   selfLink: /apis/operator.autoscaling.openshift.io/v1/clusterresourceoverrides/cluster
    12.   uid: 978fc959-1717-4bd1-97d0-ae00ee111e8d
    13. spec:
    14.   podResourceOverride:
    15.     spec:
    16.       cpuRequestToLimitPercent: 25
    17.       limitCPUToMemoryPercent: 200
    18.       memoryRequestToLimitPercent: 50
    19. status:
    21. ....
    23.     mutatingWebhookConfigurationRef: (1)
    24.       apiVersion: admissionregistration.k8s.io/v1beta1
    25.       kind: MutatingWebhookConfiguration
    26.       name: clusterresourceoverrides.admission.autoscaling.openshift.io
    27.       resourceVersion: "127621"
    28.       uid: 98b3b8ae-d5ce-462b-8ab5-a729ea8f38f3
    30. ....
    1Reference to the ClusterResourceOverride admission webhook.

Configuring cluster-level overcommit

The Cluster Resource Override Operator requires a ClusterResourceOverride custom resource (CR) and a label for each project where you want the Operator to control overcommit.

Prerequisites

  • The Cluster Resource Override Operator has no effect if limits have not been set on containers. You must specify default limits for a project using a LimitRange object or configure limits in Pod specs for the overrides to apply.

Procedure

To modify cluster-level overcommit:

  1. Edit the ClusterResourceOverride CR:

    1. apiVersion: operator.autoscaling.openshift.io/v1
    2. kind: ClusterResourceOverride
    3. metadata:
    4. -   name: cluster
    5. spec:
    6.    memoryRequestToLimitPercent: 50 (1)
    7.    cpuRequestToLimitPercent: 25 (2)
    8.    limitCPUToMemoryPercent: 200 (3)
    1Optional. Specify the percentage to override the container memory limit, if used, between 1-100. The default is 50.
    2Optional. Specify the percentage to override the container CPU limit, if used, between 1-100. The default is 25.
    3Optional. Specify the percentage to override the container memory limit, if used. Scaling 1Gi of RAM at 100 percent is equal to 1 CPU core. This is processed prior to overriding the CPU request, if configured. The default is 200.

  2. Ensure the following label has been added to the Namespace object for each project where you want the Cluster Resource Override Operator to control overcommit:

    1. apiVersion: v1
    2. kind: Namespace
    3. metadata:
    5. ....
    7.   labels:
    8.     clusterresourceoverrides.admission.autoscaling.openshift.io/enabled: "true" (1)
    10. ....
    1Add this label to each project.

Node-level overcommit

You can use various ways to control overcommit on specific nodes, such as quality of service (QOS) guarantees, CPU limits, or reserve resources. You can also disable overcommit for specific nodes and specific projects.

Understanding compute resources and containers

The node-enforced behavior for compute resources is specific to the resource type.

Understanding container CPU requests

A container is guaranteed the amount of CPU it requests and is additionally able to consume excess CPU available on the node, up to any limit specified by the container. If multiple containers are attempting to use excess CPU, CPU time is distributed based on the amount of CPU requested by each container.

For example, if one container requested 500m of CPU time and another container requested 250m of CPU time, then any extra CPU time available on the node is distributed among the containers in a 2:1 ratio. If a container specified a limit, it will be throttled not to use more CPU than the specified limit. CPU requests are enforced using the CFS shares support in the Linux kernel. By default, CPU limits are enforced using the CFS quota support in the Linux kernel over a 100ms measuring interval, though this can be disabled.

Understanding container memory requests

A container is guaranteed the amount of memory it requests. A container can use more memory than requested, but once it exceeds its requested amount, it could be terminated in a low memory situation on the node. If a container uses less memory than requested, it will not be terminated unless system tasks or daemons need more memory than was accounted for in the node’s resource reservation. If a container specifies a limit on memory, it is immediately terminated if it exceeds the limit amount.

Understanding overcomitment and quality of service classes

A node is overcommitted when it has a pod scheduled that makes no request, or when the sum of limits across all pods on that node exceeds available machine capacity.

In an overcommitted environment, it is possible that the pods on the node will attempt to use more compute resource than is available at any given point in time. When this occurs, the node must give priority to one pod over another. The facility used to make this decision is referred to as a Quality of Service (QoS) Class.

For each compute resource, a container is divided into one of three QoS classes with decreasing order of priority:

Table 2. Quality of Service Classes
PriorityClass NameDescription

1 (highest)

Guaranteed

If limits and optionally requests are set (not equal to 0) for all resources and they are equal, then the container is classified as Guaranteed.

2

Burstable

If requests and optionally limits are set (not equal to 0) for all resources, and they are not equal, then the container is classified as Burstable.

3 (lowest)

BestEffort

If requests and limits are not set for any of the resources, then the container is classified as BestEffort.

Memory is an incompressible resource, so in low memory situations, containers that have the lowest priority are terminated first:

  • Guaranteed containers are considered top priority, and are guaranteed to only be terminated if they exceed their limits, or if the system is under memory pressure and there are no lower priority containers that can be evicted.

  • Burstable containers under system memory pressure are more likely to be terminated once they exceed their requests and no other BestEffort containers exist.

  • BestEffort containers are treated with the lowest priority. Processes in these containers are first to be terminated if the system runs out of memory.

Understanding how to reserve memory across quality of service tiers

You can use the qos-reserved parameter to specify a percentage of memory to be reserved by a pod in a particular QoS level. This feature attempts to reserve requested resources to exclude pods from lower OoS classes from using resources requested by pods in higher QoS classes.

OKD uses the qos-reserved parameter as follows:

  • A value of qos-reserved=memory=100% will prevent the Burstable and BestEffort QOS classes from consuming memory that was requested by a higher QoS class. This increases the risk of inducing OOM on BestEffort and Burstable workloads in favor of increasing memory resource guarantees for Guaranteed and Burstable workloads.

  • A value of qos-reserved=memory=50% will allow the Burstable and BestEffort QOS classes to consume half of the memory requested by a higher QoS class.

  • A value of qos-reserved=memory=0% will allow a Burstable and BestEffort QoS classes to consume up to the full node allocatable amount if available, but increases the risk that a Guaranteed workload will not have access to requested memory. This condition effectively disables this feature.

Understanding swap memory and QOS

You can disable swap by default on your nodes to preserve quality of service (QOS) guarantees. Otherwise, physical resources on a node can oversubscribe, affecting the resource guarantees the Kubernetes scheduler makes during pod placement.

For example, if two guaranteed pods have reached their memory limit, each container could start using swap memory. Eventually, if there is not enough swap space, processes in the pods can be terminated due to the system being oversubscribed.

Failing to disable swap results in nodes not recognizing that they are experiencing MemoryPressure, resulting in pods not receiving the memory they made in their scheduling request. As a result, additional pods are placed on the node to further increase memory pressure, ultimately increasing your risk of experiencing a system out of memory (OOM) event.

If swap is enabled, any out-of-resource handling eviction thresholds for available memory will not work as expected. Take advantage of out-of-resource handling to allow pods to be evicted from a node when it is under memory pressure, and rescheduled on an alternative node that has no such pressure.

Understanding nodes overcommitment

In an overcommitted environment, it is important to properly configure your node to provide best system behavior.

When the node starts, it ensures that the kernel tunable flags for memory management are set properly. The kernel should never fail memory allocations unless it runs out of physical memory.

To ensure this behavior, OKD configures the kernel to always overcommit memory by setting the vm.overcommit_memory parameter to 1, overriding the default operating system setting.

OKD also configures the kernel not to panic when it runs out of memory by setting the vm.panic_on_oom parameter to 0. A setting of 0 instructs the kernel to call oom_killer in an Out of Memory (OOM) condition, which kills processes based on priority

You can view the current setting by running the following commands on your nodes:

  1. $ sysctl -a |grep commit

Example output

  1. vm.overcommit_memory = 1
  1. $ sysctl -a |grep panic

Example output

  1. vm.panic_on_oom = 0

The above flags should already be set on nodes, and no further action is required.

You can also perform the following configurations for each node:

  • Disable or enforce CPU limits using CPU CFS quotas

  • Reserve resources for system processes

  • Reserve memory across quality of service tiers

Disabling or enforcing CPU limits using CPU CFS quotas

Nodes by default enforce specified CPU limits using the Completely Fair Scheduler (CFS) quota support in the Linux kernel.

If you disable CPU limit enforcement, it is important to understand the impact on your node:

  • If a container has a CPU request, the request continues to be enforced by CFS shares in the Linux kernel.

  • If a container does not have a CPU request, but does have a CPU limit, the CPU request defaults to the specified CPU limit, and is enforced by CFS shares in the Linux kernel.

  • If a container has both a CPU request and limit, the CPU request is enforced by CFS shares in the Linux kernel, and the CPU limit has no impact on the node.

Prerequisites

  1. Obtain the label associated with the static MachineConfigPool CRD for the type of node you want to configure. Perform one of the following steps:

    1. View the machine config pool:

      1. $ oc describe machineconfigpool <name>

      For example:

      1. $ oc describe machineconfigpool worker

      Example output

      1. apiVersion: machineconfiguration.openshift.io/v1
      2. kind: MachineConfigPool
      3. metadata:
      4.   creationTimestamp: 2019-02-08T14:52:39Z
      5.   generation: 1
      6.   labels:
      7.     custom-kubelet: small-pods (1)
      1If a label has been added it appears under labels.

    2. If the label is not present, add a key/value pair:

      1. $ oc label machineconfigpool worker custom-kubelet=small-pods

Procedure

  1. Create a custom resource (CR) for your configuration change.

    Sample configuration for a disabling CPU limits

    1. apiVersion: machineconfiguration.openshift.io/v1
    2. kind: KubeletConfig
    3. metadata:
    4.   name: disable-cpu-units (1)
    5. spec:
    6.   machineConfigPoolSelector:
    7.     matchLabels:
    8.       custom-kubelet: small-pods (2)
    9.   kubeletConfig:
    10.     cpuCfsQuota: (3)
    11.       - "false"
    1Assign a name to CR.
    2Specify the label to apply the configuration change.
    3Set the cpuCfsQuota parameter to false.

Reserving resources for system processes

To provide more reliable scheduling and minimize node resource overcommitment, each node can reserve a portion of its resources for use by system daemons that are required to run on your node for your cluster to function. In particular, it is recommended that you reserve resources for incompressible resources such as memory.

Procedure

To explicitly reserve resources for non-pod processes, allocate node resources by specifying resources available for scheduling. For more details, see Allocating Resources for Nodes.

Disabling overcommitment for a node

When enabled, overcommitment can be disabled on each node.

Procedure

To disable overcommitment in a node run the following command on that node:

  1. $ sysctl -w vm.overcommit_memory=0

Project-level limits

To help control overcommit, you can set per-project resource limit ranges, specifying memory and CPU limits and defaults for a project that overcommit cannot exceed.

For information on project-level resource limits, see Additional Resources.

Alternatively, you can disable overcommitment for specific projects.

Disabling overcommitment for a project

When enabled, overcommitment can be disabled per-project. For example, you can allow infrastructure components to be configured independently of overcommitment.

Procedure

To disable overcommitment in a project:

  1. Edit the project object file

  2. Add the following annotation:

    1. quota.openshift.io/cluster-resource-override-enabled: "false"

  3. Create the project object:

    1. $ oc create -f <file-name>.yaml

Freeing node resources using garbage collection

Understand and use garbage collection.

Understanding how terminated containers are removed though garbage collection

Container garbage collection can be performed using eviction thresholds.

When eviction thresholds are set for garbage collection, the node tries to keep any container for any pod accessible from the API. If the pod has been deleted, the containers will be as well. Containers are preserved as long the pod is not deleted and the eviction threshold is not reached. If the node is under disk pressure, it will remove containers and their logs will no longer be accessible using oc logs.

  • eviction-soft - A soft eviction threshold pairs an eviction threshold with a required administrator-specified grace period.

  • eviction-hard - A hard eviction threshold has no grace period, and if observed, OKD takes immediate action.

If a node is oscillating above and below a soft eviction threshold, but not exceeding its associated grace period, the corresponding node would constantly oscillate between true and false. As a consequence, the scheduler could make poor scheduling decisions.

To protect against this oscillation, use the eviction-pressure-transition-period flag to control how long OKD must wait before transitioning out of a pressure condition. OKD will not set an eviction threshold as being met for the specified pressure condition for the period specified before toggling the condition back to false.

Understanding how images are removed though garbage collection

Image garbage collection relies on disk usage as reported by cAdvisor on the node to decide which images to remove from the node.

The policy for image garbage collection is based on two conditions:

  • The percent of disk usage (expressed as an integer) which triggers image garbage collection. The default is 85.

  • The percent of disk usage (expressed as an integer) to which image garbage collection attempts to free. Default is 80.

For image garbage collection, you can modify any of the following variables using a custom resource.

Table 3. Variables for configuring image garbage collection
SettingDescription

imageMinimumGCAge

The minimum age for an unused image before the image is removed by garbage collection. The default is 2m.

imageGCHighThresholdPercent

The percent of disk usage, expressed as an integer, which triggers image garbage collection. The default is 85.

imageGCLowThresholdPercent

The percent of disk usage, expressed as an integer, to which image garbage collection attempts to free. The default is 80.

Two lists of images are retrieved in each garbage collector run:

  1. A list of images currently running in at least one pod.

  2. A list of images available on a host.

As new containers are run, new images appear. All images are marked with a time stamp. If the image is running (the first list above) or is newly detected (the second list above), it is marked with the current time. The remaining images are already marked from the previous spins. All images are then sorted by the time stamp.

Once the collection starts, the oldest images get deleted first until the stopping criterion is met.

Configuring garbage collection for containers and images

As an administrator, you can configure how OKD performs garbage collection by creating a kubeletConfig object for each machine config pool.

OKD supports only one kubeletConfig object for each machine config pool.

You can configure any combination of the following:

  • soft eviction for containers

  • hard eviction for containers

  • eviction for images

For soft container eviction you can also configure a grace period before eviction.

Prerequisites

  1. Obtain the label associated with the static MachineConfigPool CRD for the type of node you want to configure. Perform one of the following steps:

    1. View the machine config pool:

      1. $ oc describe machineconfigpool <name>

      For example:

      1. $ oc describe machineconfigpool worker

      Example output

      1. Name:         worker
      2. Namespace:
      3. Labels:       custom-kubelet=small-pods (1)
      1If a label has been added it appears under Labels.

    2. If the label is not present, add a key/value pair:

      1. $ oc label machineconfigpool worker custom-kubelet=small-pods

Procedure

  1. Create a custom resource (CR) for your configuration change.

    Sample configuration for a container garbage collection CR:

    1. apiVersion: machineconfiguration.openshift.io/v1
    2. kind: KubeletConfig
    3. metadata:
    4.   name: worker-kubeconfig (1)
    5. spec:
    6.   machineConfigPoolSelector:
    7.     matchLabels:
    8.       custom-kubelet: small-pods (2)
    9.   kubeletConfig:
    10.     evictionSoft: (3)
    11.       memory.available: "500Mi" (4)
    12.       nodefs.available: "10%"
    13.       nodefs.inodesFree: "5%"
    14.       imagefs.available: "15%"
    15.       imagefs.inodesFree: "10%"
    16.     evictionSoftGracePeriod:  (5)
    17.       memory.available: "1m30s"
    18.       nodefs.available: "1m30s"
    19.       nodefs.inodesFree: "1m30s"
    20.       imagefs.available: "1m30s"
    21.       imagefs.inodesFree: "1m30s"
    22.     evictionHard:
    23.       memory.available: "200Mi"
    24.       nodefs.available: "5%"
    25.       nodefs.inodesFree: "4%"
    26.       imagefs.available: "10%"
    27.       imagefs.inodesFree: "5%"
    28.     evictionPressureTransitionPeriod: 0s (6)
    29.     imageMinimumGCAge: 5m (7)
    30.     imageGCHighThresholdPercent: 80 (8)
    31.     imageGCLowThresholdPercent: 75 (9)
    1Name for the object.
    2Selector label.
    3Type of eviction: EvictionSoft and EvictionHard.
    4Eviction thresholds based on a specific eviction trigger signal.
    5Grace periods for the soft eviction. This parameter does not apply to eviction-hard.
    6The duration to wait before transitioning out of an eviction pressure condition
    7The minimum age for an unused image before the image is removed by garbage collection.
    8The percent of disk usage (expressed as an integer) which triggers image garbage collection.
    9The percent of disk usage (expressed as an integer) to which image garbage collection attempts to free.

  2. Create the object:

    1. $ oc create -f <file-name>.yaml

    For example:

    1. $ oc create -f gc-container.yaml

    Example output

    1. kubeletconfig.machineconfiguration.openshift.io/gc-container created

  3. Verify that garbage collection is active. The Machine Config Pool you specified in the custom resource appears with UPDATING as ‘true` until the change is fully implemented:

    1. $ oc get machineconfigpool

    Example output

    1. NAME     CONFIG                                   UPDATED   UPDATING
    2. master   rendered-master-546383f80705bd5aeaba93   True      False
    3. worker   rendered-worker-b4c51bb33ccaae6fc4a6a5   False     True

Using the Node Tuning Operator

Understand and use the Node Tuning Operator.

The Node Tuning Operator helps you manage node-level tuning by orchestrating the Tuned daemon. The majority of high-performance applications require some level of kernel tuning. The Node Tuning Operator provides a unified management interface to users of node-level sysctls and more flexibility to add custom tuning specified by user needs.

The Operator manages the containerized Tuned daemon for OKD as a Kubernetes daemon set. It ensures the custom tuning specification is passed to all containerized Tuned daemons running in the cluster in the format that the daemons understand. The daemons run on all nodes in the cluster, one per node.

Node-level settings applied by the containerized Tuned daemon are rolled back on an event that triggers a profile change or when the containerized Tuned daemon is terminated gracefully by receiving and handling a termination signal.

The Node Tuning Operator is part of a standard OKD installation in version 4.1 and later.

Accessing an example Node Tuning Operator specification

Use this process to access an example Node Tuning Operator specification.

Procedure

  1. Run:

    1. $ oc get Tuned/default -o yaml -n openshift-cluster-node-tuning-operator

The default CR is meant for delivering standard node-level tuning for the OKD platform and it can only be modified to set the Operator Management state. Any other custom changes to the default CR will be overwritten by the Operator. For custom tuning, create your own Tuned CRs. Newly created CRs will be combined with the default CR and custom tuning applied to OKD nodes based on node or pod labels and profile priorities.

While in certain situations the support for pod labels can be a convenient way of automatically delivering required tuning, this practice is discouraged and strongly advised against, especially in large-scale clusters. The default Tuned CR ships without pod label matching. If a custom profile is created with pod label matching, then the functionality will be enabled at that time. The pod label functionality might be deprecated in future versions of the Node Tuning Operator.

Custom tuning specification

The custom resource (CR) for the Operator has two major sections. The first section, profile:, is a list of Tuned profiles and their names. The second, recommend:, defines the profile selection logic.

Multiple custom tuning specifications can co-exist as multiple CRs in the Operator’s namespace. The existence of new CRs or the deletion of old CRs is detected by the Operator. All existing custom tuning specifications are merged and appropriate objects for the containerized Tuned daemons are updated.

Management state

The Operator Management state is set by adjusting the default Tuned CR. By default, the Operator is in the Managed state and the spec.managementState field is not present in the default Tuned CR. Valid values for the Operator Management state are as follows:

  • Managed: the Operator will update its operands as configuration resources are updated

  • Unmanaged: the Operator will ignore changes to the configuration resources

  • Removed: the Operator will remove its operands and resources the Operator provisioned

Profile data

The profile: section lists Tuned profiles and their names.

  1. profile:
  2. - name: tuned_profile_1
  3.   data: |
  4.     # Tuned profile specification
  5.     [main]
  6.     summary=Description of tuned_profile_1 profile
  8.     [sysctl]
  9.     net.ipv4.ip_forward=1
  10.     # ... other sysctl's or other Tuned daemon plugins supported by the containerized Tuned
  12. # ...
  14. - name: tuned_profile_n
  15.   data: |
  16.     # Tuned profile specification
  17.     [main]
  18.     summary=Description of tuned_profile_n profile
  20.     # tuned_profile_n profile settings

Recommended profiles

The profile: selection logic is defined by the recommend: section of the CR. The recommend: section is a list of items to recommend the profiles based on a selection criteria.

  1. recommend:
  2. <recommend-item-1>
  3. # ...
  4. <recommend-item-n>

The individual items of the list:

  1. - machineConfigLabels: (1)
  2.     <mcLabels> (2)
  3.   match: (3)
  4.     <match> (4)
  5.   priority: <priority> (5)
  6.   profile: <tuned_profile_name> (6)
1Optional.
2A dictionary of key/value MachineConfig labels. The keys must be unique.
3If omitted, profile match is assumed unless a profile with a higher priority matches first or machineConfigLabels is set.
4An optional list.
5Profile ordering priority. Lower numbers mean higher priority (0 is the highest priority).
6A Tuned profile to apply on a match. For example tuned_profile_1.

<match> is an optional list recursively defined as follows:

  1. - label: <label_name> (1)
  2.   value: <label_value> (2)
  3.   type: <label_type> (3)
  4.     <match> (4)
1Node or pod label name.
2Optional node or pod label value. If omitted, the presence of <label_name> is enough to match.
3Optional object type (node or pod). If omitted, node is assumed.
4An optional <match> list.

If <match> is not omitted, all nested <match> sections must also evaluate to true. Otherwise, false is assumed and the profile with the respective <match> section will not be applied or recommended. Therefore, the nesting (child <match> sections) works as logical AND operator. Conversely, if any item of the <match> list matches, the entire <match> list evaluates to true. Therefore, the list acts as logical OR operator.

If machineConfigLabels is defined, machine config pool based matching is turned on for the given recommend: list item. <mcLabels> specifies the labels for a machine config. The machine config is created automatically to apply host settings, such as kernel boot parameters, for the profile <tuned_profile_name>. This involves finding all machine config pools with machine config selector matching <mcLabels> and setting the profile <tuned_profile_name> on all nodes that are assigned the found machine config pools. To target nodes that have both master and worker roles, you must use the master role.

The list items match and machineConfigLabels are connected by the logical OR operator. The match item is evaluated first in a short-circuit manner. Therefore, if it evaluates to true, the machineConfigLabels item is not considered.

When using machine config pool based matching, it is advised to group nodes with the same hardware configuration into the same machine config pool. Not following this practice might result in Tuned operands calculating conflicting kernel parameters for two or more nodes sharing the same machine config pool.

Example: node or pod label based matching

  1. - match:
  2.   - label: tuned.openshift.io/elasticsearch
  3.     match:
  4.     - label: node-role.kubernetes.io/master
  5.     - label: node-role.kubernetes.io/infra
  6.     type: pod
  7.   priority: 10
  8.   profile: openshift-control-plane-es
  9. - match:
  10.   - label: node-role.kubernetes.io/master
  11.   - label: node-role.kubernetes.io/infra
  12.   priority: 20
  13.   profile: openshift-control-plane
  14. - priority: 30
  15.   profile: openshift-node

The CR above is translated for the containerized Tuned daemon into its recommend.conf file based on the profile priorities. The profile with the highest priority (10) is openshift-control-plane-es and, therefore, it is considered first. The containerized Tuned daemon running on a given node looks to see if there is a pod running on the same node with the tuned.openshift.io/elasticsearch label set. If not, the entire <match> section evaluates as false. If there is such a pod with the label, in order for the <match> section to evaluate to true, the node label also needs to be node-role.kubernetes.io/master or node-role.kubernetes.io/infra.

If the labels for the profile with priority 10 matched, openshift-control-plane-es profile is applied and no other profile is considered. If the node/pod label combination did not match, the second highest priority profile (openshift-control-plane) is considered. This profile is applied if the containerized Tuned pod runs on a node with labels node-role.kubernetes.io/master or node-role.kubernetes.io/infra.

Finally, the profile openshift-node has the lowest priority of 30. It lacks the <match> section and, therefore, will always match. It acts as a profile catch-all to set openshift-node profile, if no other profile with higher priority matches on a given node.

Decision workflow

Example: machine config pool based matching

  1. apiVersion: tuned.openshift.io/v1
  2. kind: Tuned
  3. metadata:
  4.   name: openshift-node-custom
  5.   namespace: openshift-cluster-node-tuning-operator
  6. spec:
  7.   profile:
  8.   - data: |
  9.       [main]
  10.       summary=Custom OpenShift node profile with an additional kernel parameter
  11.       include=openshift-node
  12.       [bootloader]
  13.       cmdline_openshift_node_custom=+skew_tick=1
  14.     name: openshift-node-custom
  16.   recommend:
  17.   - machineConfigLabels:
  18.       machineconfiguration.openshift.io/role: "worker-custom"
  19.     priority: 20
  20.     profile: openshift-node-custom

To minimize node reboots, label the target nodes with a label the machine config pool’s node selector will match, then create the Tuned CR above and finally create the custom machine config pool itself.

Default profiles set on a cluster

The following are the default profiles set on a cluster.

  1. apiVersion: tuned.openshift.io/v1
  2. kind: Tuned
  3. metadata:
  4.   name: default
  5.   namespace: openshift-cluster-node-tuning-operator
  6. spec:
  7.   profile:
  8.   - name: "openshift"
  9.     data: |
  10.       [main]
  11.       summary=Optimize systems running OpenShift (parent profile)
  12.       include=${f:virt_check:virtual-guest:throughput-performance}
  14.       [selinux]
  15.       avc_cache_threshold=8192
  17.       [net]
  18.       nf_conntrack_hashsize=131072
  20.       [sysctl]
  21.       net.ipv4.ip_forward=1
  22.       kernel.pid_max=>4194304
  23.       net.netfilter.nf_conntrack_max=1048576
  24.       net.ipv4.conf.all.arp_announce=2
  25.       net.ipv4.neigh.default.gc_thresh1=8192
  26.       net.ipv4.neigh.default.gc_thresh2=32768
  27.       net.ipv4.neigh.default.gc_thresh3=65536
  28.       net.ipv6.neigh.default.gc_thresh1=8192
  29.       net.ipv6.neigh.default.gc_thresh2=32768
  30.       net.ipv6.neigh.default.gc_thresh3=65536
  31.       vm.max_map_count=262144
  33.       [sysfs]
  34.       /sys/module/nvme_core/parameters/io_timeout=4294967295
  35.       /sys/module/nvme_core/parameters/max_retries=10
  37.   - name: "openshift-control-plane"
  38.     data: |
  39.       [main]
  40.       summary=Optimize systems running OpenShift control plane
  41.       include=openshift
  43.       [sysctl]
  44.       # ktune sysctl settings, maximizing i/o throughput
  45.       #
  46.       # Minimal preemption granularity for CPU-bound tasks:
  47.       # (default: 1 msec#  (1 + ilog(ncpus)), units: nanoseconds)
  48.       kernel.sched_min_granularity_ns=10000000
  49.       # The total time the scheduler will consider a migrated process
  50.       # "cache hot" and thus less likely to be re-migrated
  51.       # (system default is 500000, i.e. 0.5 ms)
  52.       kernel.sched_migration_cost_ns=5000000
  53.       # SCHED_OTHER wake-up granularity.
  54.       #
  55.       # Preemption granularity when tasks wake up.  Lower the value to
  56.       # improve wake-up latency and throughput for latency critical tasks.
  57.       kernel.sched_wakeup_granularity_ns=4000000
  59.   - name: "openshift-node"
  60.     data: |
  61.       [main]
  62.       summary=Optimize systems running OpenShift nodes
  63.       include=openshift
  65.       [sysctl]
  66.       net.ipv4.tcp_fastopen=3
  67.       fs.inotify.max_user_watches=65536
  68.       fs.inotify.max_user_instances=8192
  70.   recommend:
  71.   - profile: "openshift-control-plane"
  72.     priority: 30
  73.     match:
  74.     - label: "node-role.kubernetes.io/master"
  75.     - label: "node-role.kubernetes.io/infra"
  77.   - profile: "openshift-node"
  78.     priority: 40

Supported Tuned daemon plug-ins

Excluding the [main] section, the following Tuned plug-ins are supported when using custom profiles defined in the profile: section of the Tuned CR:

  • audio

  • cpu

  • disk

  • eeepc_she

  • modules

  • mounts

  • net

  • scheduler

  • scsi_host

  • selinux

  • sysctl

  • sysfs

  • usb

  • video

  • vm

There is some dynamic tuning functionality provided by some of these plug-ins that is not supported. The following Tuned plug-ins are currently not supported:

  • bootloader

  • script

  • systemd

See Available Tuned Plug-ins and Getting Started with Tuned for more information.

Configuring the maximum number of pods per node

Two parameters control the maximum number of pods that can be scheduled to a node: podsPerCore and maxPods. If you use both options, the lower of the two limits the number of pods on a node.

For example, if podsPerCore is set to 10 on a node with 4 processor cores, the maximum number of pods allowed on the node will be 40.

Prerequisites

  1. Obtain the label associated with the static MachineConfigPool CRD for the type of node you want to configure. Perform one of the following steps:

    1. View the machine config pool:

      1. $ oc describe machineconfigpool <name>

      For example:

      1. $ oc describe machineconfigpool worker

      Example output

      1. apiVersion: machineconfiguration.openshift.io/v1
      2. kind: MachineConfigPool
      3. metadata:
      4.   creationTimestamp: 2019-02-08T14:52:39Z
      5.   generation: 1
      6.   labels:
      7.     custom-kubelet: small-pods (1)
      1If a label has been added it appears under labels.

    2. If the label is not present, add a key/value pair:

      1. $ oc label machineconfigpool worker custom-kubelet=small-pods

Procedure

  1. Create a custom resource (CR) for your configuration change.

    Sample configuration for a max-pods CR

    1. apiVersion: machineconfiguration.openshift.io/v1
    2. kind: KubeletConfig
    3. metadata:
    4.   name: set-max-pods (1)
    5. spec:
    6.   machineConfigPoolSelector:
    7.     matchLabels:
    8.       custom-kubelet: small-pods (2)
    9.   kubeletConfig:
    10.     podsPerCore: 10 (3)
    11.     maxPods: 250 (4)
    1Assign a name to CR.
    2Specify the label to apply the configuration change.
    3Specify the number of pods the node can run based on the number of processor cores on the node.
    4Specify the number of pods the node can run to a fixed value, regardless of the properties of the node.

    Setting podsPerCore to 0 disables this limit.

    In the above example, the default value for podsPerCore is 10 and the default value for maxPods is 250. This means that unless the node has 25 cores or more, by default, podsPerCore will be the limiting factor.

  2. List the MachineConfigPool CRDs to see if the change is applied. The UPDATING column reports True if the change is picked up by the Machine Config Controller:

    1. $ oc get machineconfigpools

    Example output

    1. NAME     CONFIG                        UPDATED   UPDATING   DEGRADED
    2. master   master-9cc2c72f205e103bb534   False     False      False
    3. worker   worker-8cecd1236b33ee3f8a5e   False     True       False

    Once the change is complete, the UPDATED column reports True.

    1. $ oc get machineconfigpools

    Example output

    1. NAME     CONFIG                        UPDATED   UPDATING   DEGRADED
    2. master   master-9cc2c72f205e103bb534   False     True       False
    3. worker   worker-8cecd1236b33ee3f8a5e   True      False      False