Run Preflight Checks

To ensure the readiness of your environment or do pre-upgrade validation, we provide preflight checks. The Preflight checks levarage Troubleshoot, a Kubernetes plugin for cluster diagnostics. No data will be exported during the process.

The following how-to guide explains how to run the preflight checks.

Install the Plugin

kubectl krew install preflight

Or refer to the Troubleshoot documentation for other installation options.

Copy the Preflight Helm Chart

Add the preflight chart to your ECR copy step:

skopeo copy --all docker://$SOURCE_ECR_REPO/helm/preflight-check:1.38.4 docker://$TARGET_ECR_REPO/helm/preflight-check:1.38.4

Run the Checks

Use helm template to render the preflight spec, then pipe it to kubectl preflight:

ECR_HOST=0000000000.dkr.ecr.us-west-2.amazonaws.com
CHART_VERSION=1.38.4
CLUSTER_NAME=default-xx-01

helm template clickhouse-preflight \
    oci://$ECR_HOST/helm/preflight-check \
    --version=$CHART_VERSION \
    --set preflight.clickhouseClusterName=$CLUSTER_NAME | \
kubectl preflight -

This validates node labels, StorageClass configuration, and other requirements. It also checks upgrade readiness of an existing ClickHouse cluster and reports deprecated feature flags or new requirements.

The output shows each check and its status. If a check fails, it includes recommendations on how to fix the issue.

Some defaults differ per cloud provider (AWS, GCP, Azure) so our preflight checks also differ per cloud provider. The preflight checks default to the AWS checks, but this can be changed with:

    --set preflight.cloud=gcp   # for GCP
    --set preflight.cloud=azure # for Azure

To validate against a custom StorageClass:

    --set preflight.checks.prerequisites.storageClassName=<your-storage-class>

Custom Namespaces

By default the analyzed namespace is derived as ns-<clickhouseClusterName>. Clusters that live in a namespace that does not follow this convention must set preflight.namespace to their actual namespace. Otherwise the preflight will analyze the wrong namespace and report all cluster-scoped checks as failing.

For example, for a ClickHouse cluster named clickhouse-cluster-01 that runs in the namespace clickhouse-cluster-01 (no ns- prefix):

helm template clickhouse-preflight \
    oci://$ECR_HOST/helm/preflight-check \
    --version=$CHART_VERSION \
    --set preflight.clickhouseClusterName=clickhouse-cluster-01 \
    --set preflight.namespace=clickhouse-cluster-01 | \
kubectl preflight -

Required Permissions

The user or service account executing kubectl preflight needs read access to the following:

A principal with the built-in view ClusterRole plus view access to the relevant namespaces is sufficient.