---
title: "Preflight checks"
description: "Ensure a smooth deployment of ITRS Analytics by running essential preflight checks on your Kubernetes cluster. Identify and resolve potential issues before installation."
url: "https://docs.itrsgroup.com/docs/itrs-analytics/platform/2.18.0/prerequisites/preflight-checks/index.html"
---
## What are preflight checks?

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.

![Preflight checks validation](https://docscdn.itrsgroup.com/itrs-analytics-platform/images/iax-preflight-checks-preview.png)

### When to use preflight checks

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](https://troubleshoot.sh/docs/) 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

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

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

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](https://docs.netapp.com/us-en/trident/trident-use/backends.html) for best practices on configuring backend storage.
    - Monitor storage utilization closely, especially when enabling snapshots.

### Preflight checks for Disk I/O performance

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.

| Metric                       | Warning Threshold | Error Threshold | Interpretation                                                       |
|----------------------------------|------------------------|---------------------|------------------------------------------------------------------|
| Data Sync Latency (99th percentile) | > 10 ms               | > 100 ms            | High latency indicates potential queuing or slow disk response   |
| IOPS (Read/Write Average)        | < 3000                | < 2500              | Lower IOPS values suggest inadequate throughput                  |
| Coefficient of Variation (IOPS)  | ≥ 10%                 | ≥ 20%               | High CV suggests unstable or erratic disk performance            |

#### Non-strict preflight mode

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

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 for Disk I/O](https://docscdn.itrsgroup.com/itrs-analytics-platform/images/preflight-checks-disk-io.png)

#### Preflight checks

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

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

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](https://docs.itrsgroup.com/docs/itrs-analytics/platform/2.18.0/backups/backup-and-restore/index.html).



#### Strict preflight check for CSI VolumeSnapshot support

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**.

![Strict preflight check for CSI VolumeSnapshot support](https://docscdn.itrsgroup.com/itrs-analytics-platform/images/iax-preflight-check-csi-strict-blocking.png)

#### Conceptual flow and example

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.



### Preflight check to verify available pod capacity

This preflight check verifies that your Kubernetes cluster has enough available pod slots to successfully deploy ITRS Analytics.

The check ensures that the cluster can accommodate all required IAX components without exceeding its pod capacity or running into scheduling issues. Insufficient pod availability may lead to failed or incomplete deployments.

#### How it works

-  The preflight calculates the number of pods required based on the selected cluster size configuration.

-  It then compares this value against the current available pod capacity in the Kubernetes cluster.

-  If the available capacity is insufficient, the deployment will not proceed until resources are freed or the cluster capacity is increased.


**Note**


This is a strict preflight check. Deployment is blocked if the cluster lacks enough pod slots.
The check prevents resource contention and ensures a stable, fully functional ITRS Analytics deployment.



##### Recommended action

If the check fails:

1. Verify your cluster’s node and pod limits.
2. Scale up your cluster or free up unused resources.
3. Re-run the deployment after ensuring sufficient capacity.

### Preflight check to validate Linkerd compatibility with native sidecars

Beginning with ITRS Analytics 2.16.0, workloads that use native sidecars require a supported version of Linkerd.

The Linkerd native sidecars support preflight check verifies that clusters running Linkerd are compatible with ITRS Analytics workloads that use native sidecars. Running the preflight check confirms that clusters with a pre-installed Linkerd meet these requirements before deployment. This helps prevent deployment issues caused by incompatible service mesh versions.

#### How it validates compatibility

1. Detects Linkerd installation:
   - Searches for the `linkerd-config` ConfigMap in the default `linkerd` namespace.
   - If not found, searches across all namespaces.

2. Validates Linkerd version:
   - If Linkerd is present, its version is parsed and the `proxy.nativeSidecar` flag is checked. Full support requires both version 2.15.0 or later and the flag to be enabled.
   - The version is then compared against the minimum required version (2.15.0).

3. Reports compatibility:
   - If Linkerd is not installed but internal TLS is enabled, or the version is below 2.15.0, the check reports that native sidecar support is unavailable.
   - If Linkerd is version 2.15.0 or later and the `proxy.nativeSidecar` flag is enabled, native sidecar support is considered compatible.

In summary, here's how it works:

| Condition                           | Result                                        |
|-------------------------------------|-----------------------------------------------|
| Linkerd not installed but internal TLS is enabled | Native sidecar support unavailable            |
| Linkerd installed, version < 2.15.0 | Native sidecar support unavailable            |
| Linkerd installed, version ≥ 2.15.0; `nativeSidecar` flag disabled | Native sidecar support unavailable |
| Linkerd installed with version ≥ 2.15.0 and nativeSidecar flag enabled | Native sidecar support available and compatible |

### Preflight check for inotify limits

The Node Sysctl preflight check validates these independent Linux kernel limits on every cluster node:

- `fs.inotify.max_user_instances`, which controls the number of inotify instances that a user can create. The minimum value is `1024`.
- `fs.inotify.max_user_watches`, which controls the number of files and directories that a user can monitor. The minimum value is `65536`.

Insufficient limits can prevent ITRS Analytics workloads from monitoring file system events. A low `fs.inotify.max_user_instances` value can cause `too many open files` errors, while a low `fs.inotify.max_user_watches` value can cause `no space left on device` errors.


**Note**


Beginning with ITRS Analytics 2.18.x, `fs.inotify.max_user_watches` is included as a new check, and both `fs.inotify.max_user_watches` and `fs.inotify.max_user_instances` report a failure instead of a warning when a node is below the minimum value. If you previously saw a warning for these limits during an upgrade, you will now see a failure.



#### How it works

- A single collector runs across all cluster nodes and reads both values from the host `/proc/sys/fs/inotify` directory
- The results show a separate row for each kernel limit, so you can identify which setting needs attention
- Each result covers the entire cluster and reports a failure if any node is below the corresponding minimum. The result identifies each affected node and its current value
- If a value cannot be read, the corresponding result shows a warning

The checks use non-strict mode. A failure appears in the preflight results, but it does not block installation.

Some environments may not allow the collector to complete. Security policies may restrict access to the host `/proc` filesystem, and managed cloud environments may prevent you from changing node kernel parameters. If a check shows a warning, verify both values on each node manually.

If a check fails, see [How to resolve inotify limits during installation?](https://docs.itrsgroup.com/docs/itrs-analytics/latest/faqs/increase-fs-inotify-max-user-instances/index.html).

#### Configuration options

You can control both checks using the **Run Node Sysctl Checks** toggle under **Advanced Settings > Preflight and Support Bundle Settings**. The toggle is enabled by default.

![Preflight checks for inotify limits](https://docscdn.itrsgroup.com/itrs-analytics-platform/images/iax-preflight-check-inotify-limits-2-18-x.png)

When enabled:

- The collector runs automatically during preflight checks
- Separate results for `fs.inotify.max_user_instances` and `fs.inotify.max_user_watches` are included in the preflight results
- The analyzer results are included in support bundles

When disabled:

- The collector and analyzers are excluded from preflight checks and support bundles
- A warning indicates that pods may encounter `too many open files` or `no space left on device` errors if the kernel limits are insufficient


**Note**


Keep **Run Node Sysctl Checks** enabled whenever possible. If your environment prevents the collector from running or prevents you from changing kernel parameters, disable the option and manually verify that both limits meet the minimum values on every node.



### Preflight check for Enforce Zone Spread setting

Beginning with ITRS Analytics 2.17.x, the **Enforce Zone Spread** preflight check validates whether this setting is compatible with the availability zone topology of your Kubernetes cluster.

This check runs automatically before installation or upgrade and is useful when deploying or updating ITRS Analytics in environments where workloads may be distributed across one or more availability zones. It helps detect configuration mismatches early and prevents scheduling issues that could block critical workloads.

#### What it checks

The check reads the `topology.kubernetes.io/zone` label from cluster nodes to determine the cluster's zone topology. It then compares that topology against whether **Enforce Zone Spread** is enabled in your ITRS Analytics configuration.

#### Configuration options

For installations deployed through the KOTS Admin Console, configure **Enforce Zone Spread** on the **Config** page under **Advanced Settings > Preflight and Support Bundle Settings > Zone Spread**. This setting is not enabled by default.

![Preflight checks for Enforce Zone Spread](https://docscdn.itrsgroup.com/itrs-analytics-platform/images/iax-preflight-check-enforce-zone-spread.png)

#### Possible outcomes

| Cluster topology | Enforce Zone Spread | Result | Action required |
|------------------|---------------------|--------|-----------------|
| 3 or more zones detected | Enabled | Pass | No action needed |
| 3 or more zones detected | Disabled | Warning | Consider enabling it for high availability across zones |
| 2 zones detected | Enabled | Fail (blocking) | Disable **Enforce Zone Spread**, or add a third availability zone. Production HA requires at least 3 zones |
| 2 zones detected | Disabled | Pass | No action needed |
| Single zone detected | Enabled | Warning | Consider disabling it because it is unnecessary in single-zone clusters |
| Single zone detected | Disabled | Pass | No action needed |
| No zone labels found | Enabled | Fail (blocking) | Disable **Enforce Zone Spread**, or add `topology.kubernetes.io/zone` labels to cluster nodes |
| No zone labels found | Disabled | Pass | No action needed |

#### Fail condition

The check fails and blocks the installation or upgrade in these situations:

- **Enforce Zone Spread** is enabled but no nodes carry the `topology.kubernetes.io/zone` label. In this state, critical workloads cannot be scheduled because there are no zone labels to spread across.
- **Enforce Zone Spread** is enabled but the cluster has only 2 availability zones. Losing a single zone takes down quorum-based workloads such as ClickHouse Keeper and Kafka. Production HA requires at least 3 zones.

Resolve this before proceeding by doing one of the following:

1. Disable **Enforce Zone Spread** in the ITRS Analytics configuration.
2. Add a third availability zone for a 2-zone cluster, or add `topology.kubernetes.io/zone` labels to cluster nodes if the labels are missing.

The check also fails if node information cannot be retrieved, for example because of RBAC restrictions. If this occurs, verify that the preflight service account has permission to list cluster nodes.


**Note**


This preflight check does not confirm that your cluster has enough availability zones for production high availability. It only validates whether **Enforce Zone Spread** can be evaluated against the zone labels present on the cluster nodes.

For production deployments that require zone-failure protection, use at least three availability zones and enable **Enforce Zone Spread**. If the cluster spans fewer than three availability zones, leave **Enforce Zone Spread** disabled.



#### Warning conditions

Warnings are non-blocking but indicate a suboptimal configuration.

- If the cluster spans multiple availability zones and **Enforce Zone Spread** is disabled, consider enabling it only when the deployment spans at least three availability zones and requires zone-failure protection.
- If **Enforce Zone Spread** is enabled on a single-zone cluster, it provides no benefit and may cause scheduling issues if nodes are later removed.

### Preflight check for Host Open-Files Ulimit

Beginning with ITRS Analytics 2.18.1, this preflight check validates that every cluster node has a sufficient open-files `ulimit` to run ITRS Analytics safely. The minimum supported limit is 1024. Nodes with insufficient limits may encounter too many open files errors at runtime.

#### How it works

- The check runs as a DaemonSet on all cluster nodes.
- It uses `hostPID: true` to read the kubelet's effective open-files limit on each node.
- It does not require privileged containers.

#### Possible outcomes

This check uses non-strict mode. A failure is reported in the preflight results, but it does not block installation.

| Condition | Result | Action required |
|-----------|--------|-----------------|
| All nodes report a limit of 1024 or higher | Pass | No action needed |
| One or more nodes report a limit below 1024 | Fail | Increase the `ulimit` on the affected nodes |
| One or more nodes cannot be read | Warning | Manually verify the `ulimit` on those nodes |

#### Configuration options

You can control this check using the **Run Host Ulimit Checks** toggle under **Advanced Settings > Preflight and Support Bundle Settings**. This option is enabled by default.


**Note**


If your cluster security policy does not allow `hostPID` pods, disable this check and manually verify that the kubelet open-files limit is at least 1024 on each node.



If the check reports a failure, increase the kubelet open-files limit on the affected nodes and re-run the preflight checks.

### Preflight check for custom TLS certificates and private keys

Beginning with ITRS Analytics 2.18.16, preflight checks verify that a custom TLS certificate and the private key you upload belong together. The KOTS Admin Console saves the files you upload, including a certificate and private key that are not a pair. Use the preflight result to find that mismatch before installation or upgrade, while you can still replace the files.

These checks run only for the custom certificate options you select under **Advanced Settings > TLS Certificates**. If you keep the default self-signed certificates, these checks do not run.

- When you select **ITRS Analytics: custom certificates**, the result is titled **Are the ITRS Analytics custom TLS certificate and private key matching?**
- When you select **Linkerd: custom linkerd certificates**, the result is titled **Are the Linkerd custom TLS certificate and private key matching?** This option is available when Linkerd is enabled.


**Note**


A failure blocks installation and upgrade. The result includes the message **To deploy the application, this check cannot fail.**



#### Prepare the certificate and private key

Upload the certificate file and the private key that were issued together. You can upload the certificate on its own, or a chain file that also contains the issuing certificates supplied with it. In a chain file, put the certificate that matches the private key first, followed by the issuing certificates. Any other order fails in the same way as a private key from a different pair.

An encrypted private key asks for a passphrase when it is used. Remove the passphrase and upload the decrypted key file. An encrypted key fails the check.


**Note**


A pass means the certificate and private key are a pair. Before you deploy, review the certificate file for the following cases, which still pass:

- An expired certificate passes when the private key matches. Check the expiration date in the certificate file.
- A Linkerd certificate passes when the private key matches, including when it is not a certificate authority (CA) certificate. If your Linkerd configuration requires a CA certificate, confirm that property in the certificate file.



#### Possible outcomes

| Condition | Result | Action required |
|-----------|--------|-----------------|
| The certificate and private key match | Pass. The message is **Certificate and private key match.** | No further action is required for the pairing. Check the certificate expiration date. For Linkerd, confirm that the certificate is a CA certificate when your configuration requires one. |
| The files are from different pairs, or the chain file is in the wrong order | Fail (blocking). The message is **Certificate and private key do not match.** | Upload the certificate and private key that were issued together. In a chain file, put the matching certificate first. |
| The private key is encrypted | Fail (blocking). The message is **Private key is encrypted. Decrypt the key before upload.** | Remove the passphrase from the private key, and upload the decrypted key file. |

#### Correct a failed check

1. In the KOTS Admin Console, go to **Advanced Settings > TLS Certificates**.
2. Upload the corrected certificate file and private key for the check that failed.
3. Run the preflight checks again.

