Preflight checks

What are preflight checks? Copied

Preflight checks are automated validation tests that run before installing or upgrading ITRS Analytics. They examine your Kubernetes cluster environment to identify potential issues that could affect deployment success, system stability, or performance.

• Storage configuration and performance
• Cluster resource availability
• Backup and snapshot support
• Service mesh compatibility
• Network and security settings

Each check evaluates specific conditions and reports results as pass, warning, or error. Some checks are informational and allow you to proceed with caution, while others are strict (blocking) and must be resolved before installation can continue.

When to use preflight checks Copied

Preflight checks run automatically in the following scenarios:

• Before deploying ITRS Analytics for the first time
• When updating to a new version of ITRS Analytics
• After modifying settings in the KOTS Admin Console

Although preflight checks run automatically during installation and upgrade, you can also run them manually before installation to validate your environment in advance.

To do this, use the Troubleshoot preflight tooling. In summary, you must:

1. Download the preflight binary, or install it as a kubectl plugin by using Krew.
2. Run the preflight application manually by using curl or Krew.

This approach is useful when you want to identify and address environment issues before starting the actual ITRS Analytics installation. Preflight checks help you avoid problems by catching issues early.

• Identify insufficient resources or incompatible configurations before they cause installation to fail.
• Detect storage latency, throughput, or stability issues that could degrade system performance.
• Verify backup and snapshot capabilities are properly configured to safeguard your data.
• Catch problems in minutes rather than discovering them hours into a deployment.

By addressing preflight check findings before proceeding, you ensure a smoother deployment experience and a more stable, reliable ITRS Analytics environment.

How preflight checks work in ITRS Analytics Copied

When you initiate an installation or upgrade through the KOTS Admin Console, preflight checks execute automatically in the background. Here’s what happens:

1. Each check runs against your Kubernetes cluster, testing specific requirements.
2. Results are displayed in the Admin Console with clear pass/warning/error indicators.
3. Failed checks include detailed error messages and recommended actions.
4. Depending on the severity, you can either proceed (for warnings) or must resolve issues (for blocking errors).

Warning

Please do not skip or intentionally ignore blocking preflight errors unless you fully understand the impact or are acting under direct guidance from ITRS. The bypass option in the KOTS Admin Console and CLI is intended only for exceptional cases, such as a known preflight defect or a supervised deployment. Ignoring blocking errors can cause the ITRS Analytics installation or upgrade to fail.

Some preflight checks, such as the Disk I/O performance check, take a long time to complete. They can be skipped by toggling the checkboxes Advanced Settings > Preflight and Support Bundle Settings in the Admin Console.

You can skip this check if alternative performance testing tools are available, or if ITRS Analytics is being reconfigured incrementally over short periods (within minutes or hours), where significant disk degradation is not expected. ITRS Analytics requires highly performant disks to operate well.

Preflight check types Copied

The following sections describe the specific preflight checks that ITRS Analytics performs and how to interpret and address their results.

Preflight checks for Trident-based storage Copied

This ensures that the assigned storage class meets best practices and avoids potential issues that could impact stability and performance.

• Check the storage class associated with each workload. If the provisioner is csi.trident.netapp.io, validate the parameters for the presence of any of the identified issues.

• The backendType is set to ontap-nas-economy. According to Trident documentation, ontap-nas-economy is not recommended for production.

• The provisioningType is set to thin. When configured as thin, there is no strict guarantee that the requested storage will always be available.

• The snapshots parameter must be set to false. If set to true, this setting can lead to rapid disk utilization increases, potentially reaching 100% due to snapshot storage.

• Recommended actions:

  • If any of these issues are detected, update the storage class parameters accordingly.
  • Consult Trident documentation for best practices on configuring backend storage.
  • Monitor storage utilization closely, especially when enabling snapshots.

Preflight checks for Disk I/O performance Copied

The preflight Disk I/O performance check is designed to validate the performance of all configured storage classes using the fio (Flexible I/O Tester) benchmarking tool. The objective is to identify latency, throughput, or stability issues before they impact application workloads.

Note

This preflight test uses fio to measure disk sync latency and IOPS (Input/Output Operations Per Second) by creating short-lived PVCs for each configured storage class. Enabling the Disk I/O Performance test can considerably extend the overall runtime of the preflight checks.

For each storage class, the test suite runs four predefined fio profiles, designed to simulate a broad range of I/O workloads:

• Random reads
• Random writes
• Single-path access patterns
• Multi-path access patterns

Each fio profile is configured to run for 60 seconds, resulting in a minimum test duration of 4 minutes per storage class (for example, 4 tests x 60 seconds x the number of storage classes). The total runtime of the preflight check scales linearly with the number of configured storage classes in the environment.

Each storage class is evaluated against the following key Disk I/O performance metrics, along with their associated thresholds and severity levels.

Expand table

Non-strict preflight mode Copied

Preflight checks for both Warning and Error levels are currently configured in a non-strict mode. This means they will not block the installation process, allowing for greater flexibility during deployment.

Managing settings for preflight and support bundle Copied

The Disk I/O performance check is enabled by default for both preflight checks and support bundles. The configuration options for both features are available in the KOTS Admin Console under Advanced Settings > Preflight and Support Bundle Settings.

Preflight checks Copied

During system reconfiguration, the check is automatically skipped if an existing installation is detected, unless it has been explicitly enabled through configuration.

To disable this, clear the selection for the Run Disk I/O Performance Test checkbox.

Support bundle Copied

This check is managed independently using the Include Disk I/O Test for Support Bundle option. When enabled, it adds the disk performance test to the support bundle, helping capture disk latency and throughput.

It operates independently of the preflight check configuration and remains enabled by default unless explicitly disabled. To modify this setting, simply select or clear the corresponding checkbox.

Preflight checks for CSI VolumeSnapshot support in StorageClass Copied

Ensure that a given StorageClass in a Kubernetes cluster supports CSI VolumeSnapshots, which are essential for consistent backups. This check must be performed prior to initiating any backup operations to ensure support and backup consistency.

Note

Support for backup and restore in ITRS Analytics is disabled by default. You can modify the Enable IAX backup and restore setting located under Advanced Settings > Backup and Restore in the KOTS Admin Console. For more information, see Backup and restore documentation.

Strict preflight check for CSI VolumeSnapshot support Copied

Beginning with ITRS Analytics version 2.12.6, the preflight check for CSI VolumeSnapshotClass support has been made strict (blocking) to ensure consistent and reliable backup and restore functionality. To prevent potential data loss and restore failures, this preflight check blocks installation if no supported VolumeSnapshotClass is detected.

If a compatible VolumeSnapshotClass is not found, the installation will be blocked unless you resolve the issue or explicitly disable backups in the KOTS Admin Console under Advanced Settings > Backup and Restore.

Conceptual flow and example Copied

1. Retrieve the provisioner or driver for the selected StorageClass (for example, ebs-sc).

   kubectl get storageclasses.storage.k8s.io ebs-sc -o jsonpath='{.provisioner}' 
   

2. Check for matching VolumeSnapshotClass.

   kubectl get volumesnapshotclass -o json | jq '.items[] | select(.driver == "<provisioner>") | .metadata.name'
   

If no VolumeSnapshotClass is found that matches the provisioner of the specified StorageClass, the following error is displayed:

Error

The following StorageClasses do not support CSI VolumeSnapshots: <SC Name (provisioner: <provisioner>)>. Without CSI VolumeSnapshot support, consistent backups cannot be guaranteed and are not supported. To proceed with the installation, you must resolve this issue or disable the backup option in Advanced Settings under Backup and Restore.