Deploying machine health checks

You can configure and deploy a machine health check to automatically repair damaged machines in a machine pool.

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

You can define conditions under which machines in a cluster are considered unhealthy by using a MachineHealthCheck resource. Machines matching the conditions are automatically remediated.

To monitor machine health, create a MachineHealthCheck custom resource (CR) that includes a label for the set of machines to monitor and a condition to check, such as staying in the NotReady status for 15 minutes or displaying a permanent condition in the node-problem-detector.

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

For machines with the master role, the machine health check reports the number of unhealthy nodes, but the machine is not deleted. For example:

Example output
  1. $ oc get machinehealthcheck example -n openshift-machine-api
  1. NAME      MAXUNHEALTHY   EXPECTEDMACHINES   CURRENTHEALTHY
  2. example   40%            3                  1

To limit the disruptive impact of machine deletions, 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, the controller stops deleting machines and you must manually intervene.

To stop the check, remove the custom resource.

MachineHealthChecks on Bare Metal

Machine deletion on bare metal cluster triggers reprovisioning of a bare metal host. Usually bare metal reprovisioning is a lengthy process, during which the cluster is missing compute resources and applications might be interrupted. To change the default remediation process from machine deletion to host power-cycle, annotate the MachineHealthCheck resource with the machine.openshift.io/remediation-strategy: external-baremetal annotation.

After you set the annotation, unhealthy machines are power-cycled by using BMC credentials.

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.

Additional resources

Sample MachineHealthCheck resource

The MachineHealthCheck resource resembles one of the following YAML files:

MachineHealthCheck for bare metal

  1. apiVersion: machine.openshift.io/v1beta1
  2. kind: MachineHealthCheck
  3. metadata:
  4.   name: example (1)
  5.   namespace: openshift-machine-api
  6.   annotations:
  7.     machine.openshift.io/remediation-strategy: external-baremetal (2)
  8. spec:
  9.   selector:
  10.     matchLabels:
  11.       machine.openshift.io/cluster-api-machine-role: <role> (3)
  12.       machine.openshift.io/cluster-api-machine-type: <role> (3)
  13.       machine.openshift.io/cluster-api-machineset: <cluster_name>-<label>-<zone> (4)
  14.   unhealthyConditions:
  15.   - type:    "Ready"
  16.     timeout: "300s" (5)
  17.     status: "False"
  18.   - type:    "Ready"
  19.     timeout: "300s" (5)
  20.     status: "Unknown"
  21.   maxUnhealthy: "40%" (6)
  22.   nodeStartupTimeout: "10m" (7)
1Specify the name of the machine health check to deploy.
2For bare metal clusters, you must include the machine.openshift.io/remediation-strategy: external-baremetal annotation in the annotations section to enable power-cycle remediation. With this remediation strategy, unhealthy hosts are rebooted instead of removed from the cluster.
3Specify a label for the machine pool that you want to check.
4Specify the machine set to track in <cluster_name>-<label>-<zone> format. For example, prod-node-us-east-1a.
5Specify 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.
6Specify 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.
7Specify 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.

MachineHealthCheck for all other installation types

  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

Additional resources

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