> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-trino-dialect.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Run Preflight Checks

To ensure the readiness of your environment or do pre-upgrade validation, we provide preflight checks. The Preflight checks levarage [Troubleshoot](https://troubleshoot.sh/), 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

```console theme={null}
kubectl krew install preflight
```

Or refer to the [Troubleshoot documentation](https://troubleshoot.sh/docs/) for other installation options.

## Copy the Preflight Helm Chart

Add the preflight chart to your ECR copy step:

```bash theme={null}
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`:

```bash theme={null}
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:

```bash theme={null}
    --set preflight.cloud=gcp   # for GCP
    --set preflight.cloud=azure # for Azure
```

To validate against a custom StorageClass:

```bash theme={null}
    --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):

```bash theme={null}
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:

| Scope                                                                                                   | Resources                                                                                 |
| ------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| Cluster-wide                                                                                            | `nodes`, `namespaces`, `persistentvolumes`, `storageclasses`, `customresourcedefinitions` |
| Operator namespace (`clickhouse-operator-system`)                                                       | `deployments`, `replicasets`, `pods`, `services`, `configmaps`, `events`                  |
| ClickHouse cluster namespace (`ns-<cluster-name>` by default, or `preflight.namespace` when overridden) | `statefulsets`, `pods`, `persistentvolumeclaims`, `services`, `configmaps`, `events`      |

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