1. Documentation
×

Preflight validation for Kernel Module Management (KMM) Modules

Before performing an upgrade on the cluster with applied KMM modules, you must verify that kernel modules installed using KMM are able to be installed on the nodes after the cluster upgrade and possible kernel upgrade. Preflight attempts to validate every Module loaded in the cluster, in parallel. Preflight does not wait for validation of one Module to complete before starting validation of another Module.

Validation kickoff

Preflight validation is triggered by creating a PreflightValidationOCP resource in the cluster. This spec contains two fields:

releaseImage

Mandatory field that provides the name of the release image for the OKD version the cluster is upgraded to.

pushBuiltImage

If true, then the images created during the Build and Sign validation are pushed to their repositories. This field is false by default.

Validation lifecycle

Preflight validation attempts to validate every module loaded in the cluster. Preflight stops running validation on a Module resource after the validation is successful. If module validation fails, you can change the module definitions and Preflight tries to validate the module again in the next loop.

If you want to run Preflight validation for an additional kernel, then you should create another PreflightValidationOCP resource for that kernel. After all the modules have been validated, it is recommended to delete the PreflightValidationOCP resource.

Validation status

A PreflightValidationOCP resource reports the status and progress of each module in the cluster that it attempts or has attempted to validate in its .status.modules list. Elements of that list contain the following fields:

lastTransitionTime

The last time the Module resource status transitioned from one status to another. This should be when the underlying status has changed. If that is not known, then using the time when the API field changed is acceptable.

name

The name of the Module resource.

namespace

The namespace of the Module resource.

statusReason

Verbal explanation regarding the status.

verificationStage

Describes the validation stage being executed:

  • image: Image existence verification

  • build: Build process verification

  • sign: Sign process verification

verificationStatus

The status of the Module verification:

  • true: Verified

  • false: Verification failed

  • error: Error during the verification process

  • unknown: Verification has not started

Preflight validation stages per Module

Preflight runs the following validations on every KMM Module present in the cluster:

  1. Image validation stage

  2. Build validation stage

  3. Sign validation stage

Image validation stage

Image validation is always the first stage of the preflight validation to be executed. If image validation is successful, no other validations are run on that specific module.

Image validation consists of two stages:

  1. Image existence and accessibility. The code tries to access the image defined for the upgraded kernel in the module and get its manifests.

  2. Verify the presence of the kernel module defined in the Module in the correct path for future modprobe execution. If this validation is successful, it probably means that the kernel module was compiled with the correct Linux headers. The correct path is <dirname>/lib/modules/<upgraded_kernel>/.

Build validation stage

Build validation is executed only when image validation has failed and there is a build section in the Module that is relevant for the upgraded kernel. Build validation attempts to run the build job and validate that it finishes successfully.

You must specify the kernel version when running depmod, as shown here:

$ RUN depmod -b /opt ${KERNEL_VERSION}

If the PushBuiltImage flag is defined in the PreflightValidationOCP custom resource (CR), it also tries to push the resulting image into its repository. The resulting image name is taken from the definition of the containerImage field of the Module CR.

If the sign section is defined for the upgraded kernel, then the resulting image will not be the containerImage field of the Module CR, but a temporary image name, because the resulting image should be the product of Sign flow.

Sign validation stage

Sign validation is executed only when image validation has failed. There is a sign section in the Module resource that is relevant for the upgrade kernel, and build validation finishes successfully in case there was a build section in the Module relevant for the upgraded kernel. Sign validation attempts to run the sign job and validate that it finishes successfully.

If the PushBuiltImage flag is defined in the PreflightValidationOCP CR, sign validation also tries to push the resulting image to its registry. The resulting image is always the image defined in the ContainerImage field of the Module. The input image is either the output of the Build stage, or an image defined in the UnsignedImage field.

If a build section exists, the sign section input image is the build section’s output image. Therefore, in order for the input image to be available for the sign section, the PushBuiltImage flag must be defined in the PreflightValidationOCP CR.

Example PreflightValidationOCP resource

This section shows an example of the PreflightValidationOCP resource in the YAML format.

The example verifies all of the currently present modules against the upcoming kernel version included in the OKD release 4.11.18, which the following release image points to:

quay.io/openshift-release-dev/ocp-release@sha256:22e149142517dfccb47be828f012659b1ccf71d26620e6f62468c264a7ce7863

Because .spec.pushBuiltImage is set to true, KMM pushes the resulting images of Build/Sign in to the defined repositories.

apiVersion: kmm.sigs.x-k8s.io/v1beta2
kind: PreflightValidationOCP
metadata:
  name: preflight
spec:
  releaseImage: quay.io/openshift-release-dev/ocp-release@sha256:22e149142517dfccb47be828f012659b1ccf71d26620e6f62468c264a7ce7863
  pushBuiltImage: true