Upgrade Preflight Check
Before you upgrade a cluster's Kubernetes version, run the Upgrade Preflight Check — a read-only analysis that runs inside your cluster and reports what could break on the target version. It lets you find and fix upgrade-breaking issues ahead of time, instead of discovering them mid-upgrade.
The check makes no changes to your cluster. Every scanner is read-only (List/Get only), and running the preflight never triggers the upgrade itself.
How It Works
The preflight is executed by the Debug Agent running inside your cluster. When you start a check, Atmosly sends a read-only command to the agent, which scans live cluster state, evaluates it against a curated Kubernetes deprecation/compatibility matrix, and returns a report with a verdict, findings grouped by area, and a remediation plan.
Because the analysis runs in-cluster, it sees the actual resources, add-on versions, node state, and Helm releases in your environment — not just the desired configuration.
Prerequisites
Debug Agent
The preflight requires the Debug Agent to be installed on the cluster. If it isn't, the drawer shows a "Debug agent is not installed" notice and the Run button is disabled. Install the Debug Agent from the cluster first, then return to run the check.
Supported Upgrade Paths
Atmosly upgrades one minor version at a time, so the preflight validates a single-step upgrade (target = source + 1):
| Supported range | |
|---|---|
| Source version | 1.30 – 1.34 |
| Target version | 1.31 – 1.35 |
| Step size | Exactly one minor version (e.g., 1.30 → 1.31) |
If the requested path is outside this window, the drawer shows "Version not supported" or "Support coming soon" and no scan is run.
Navigating to the Preflight Check
There are two entry points, both of which open the Version Upgrade drawer:
-
Cluster Actions dropdown — On the cluster page, open Cluster Actions and select Version Upgrade Check ("Run a read-only pre-flight analysis of what could break when upgrading this cluster's Kubernetes version").
-
Support pill (top bar) — When a cluster is running a version that has left standard support, an Extended support (or Support ended) pill appears next to Cluster Actions. Clicking Upgrade on it opens the same drawer. The pill's tooltip indicates when standard support ended for the current version.
Running a Check
- Open the Version Upgrade drawer using either entry point above.
- Click Run pre-flight analysis. The Debug Agent runs a set of read-only scanners inside the cluster — this takes a short while.
- Review the verdict, the findings grouped by dimension, coverage gaps, and the recommended next steps.
To see the most recent result without re-running the scan, use View last report. Reports are cached briefly, so repeated opens are fast.
What the Preflight Checks
The preflight runs ten independent scanners. Each one runs on its own and a failure in one never aborts the others — an incomplete scanner is instead reported under coverage gaps (see below).
| # | Check | What it verifies |
|---|---|---|
| 1 | Deprecated & removed APIs | Detects workloads and manifests using Kubernetes API versions that are removed between your current and target version. Scans live resources and the last-applied-configuration on Deployments, StatefulSets, DaemonSets, and Ingresses. |
| 2 | Admission webhooks | Flags mutating/validating webhooks that don't advertise the v1 admission review version, and service-backed webhooks whose backing Service or endpoints are missing (weighted by the webhook's failure policy). |
| 3 | Nodes & kubelet skew | Checks kubelet-to-control-plane version skew against the supported policy, warns on deprecated container runtimes (dockershim), and flags cgroup v1 nodes when the target version requires cgroup v2. |
| 4 | Helm releases | Reads your Helm v3 releases (from their release secrets) and inspects the rendered manifests for API versions that are removed in the target version. |
| 5 | Add-ons & controllers | Detects well-known add-ons (CoreDNS, kube-proxy, metrics-server, ingress-nginx, cert-manager, cluster-autoscaler, Calico, AWS EBS CSI, AWS VPC CNI, Karpenter, AWS Load Balancer Controller, Argo CD, and more) and compares their running versions against verified compatibility rules for the target version. |
| 6 | CRDs & conversion webhooks | Flags CustomResourceDefinitions whose conversion webhooks don't support the v1 conversion review, served versions tied to removed APIs, and stale stored versions. |
| 7 | Disruption & drain safety | Surfaces PodDisruptionBudgets that would block node drains (allowing zero disruptions), owner-less "bare" pods, and single-replica workloads that would experience downtime during the rolling node upgrade. |
| 8 | Storage & CSI | Detects StorageClasses still using in-tree provisioners without the matching CSI driver installed, volumes on removed in-tree drivers (e.g., CephFS/RBD), and volume types disabled in newer versions (e.g., gitRepo). |
| 9 | Platform-specific | Runs cloud-specific checks based on the detected platform — for example EKS (Amazon Linux 2 node groups, Fargate kubelet refresh), AKS (deprecated aad-pod-identity), GKE (legacy kube-dns), and self-managed clusters (in-tree cloud provider removal). |
| 10 | Cluster health | A readiness preflight covering NotReady or resource-pressured nodes, crash-looping or heavily restarting kube-system pods, and long-pending pods. These are reported as warnings and never block an upgrade on their own. |
Pre-existing issues are not treated as upgrade blockers. A deprecated or removed API that was already gone before your current version is reported as a warning (something to clean up), not a blocker. Only changes that land between your current and target version are counted as breaking. This keeps the verdict focused on what the upgrade itself will break.
Understanding the Results
Verdict
The report carries one overall recommendation:
| Verdict | Meaning |
|---|---|
| SAFE | No blockers, warnings, or unverified items — the upgrade can proceed. |
| CAUTION | Warnings and/or unverified items are present. No hard blockers, but review them before upgrading. |
| INCOMPLETE — cannot certify | One or more scanners could not complete (for example, due to missing read permissions). Atmosly cannot certify the upgrade as safe until coverage is complete. |
| BLOCKED | At least one breaking issue will fail on the target version. Resolve the blockers before upgrading. |
An incomplete scan can never return SAFE — if Atmosly couldn't verify something, it says so rather than giving false confidence.
Finding Severity
Each individual finding is tagged with a severity, shown in the drawer as:
| Severity | Label | Meaning |
|---|---|---|
| breaking | Must fix / Blocker | Will break on the target version. |
| warning | Warning / Review | Should be reviewed; may cause problems or is deprecated. |
| info | Note | Informational; no action strictly required. |
| unknown | Unverified | Could not be determined — usually because the Debug Agent lacks read access to the relevant resource. |
A risk score (capped at 100) summarizes the findings, weighting breaking issues more heavily than warnings. The drawer presents this as a readiness indicator alongside the counts of blockers, warnings, unverified items, and checks run.
Coverage Gaps & Blind Spots
The report includes a coverage section listing which scanners ran, which were skipped, and which failed (with the impact of each gap). If the Debug Agent doesn't have permission to read a particular resource, the affected findings show as Unverified with guidance to grant the missing access — so you always know what was and wasn't checked.
Remediation Plan
Findings are turned into an ordered remediation plan — blockers first, de-duplicated by root cause. Every step is read-only guidance (e.g., kubectl get / helm get commands) to help you locate and confirm each issue before you fix it.
After the Preflight
The preflight only analyzes — it does not change your cluster or perform the upgrade. Once the report is clean (or the remaining items are acceptable warnings), perform the actual version upgrade from the cluster edit flow. See Update & Upgrade Cluster for the Kubernetes version field and the update process.
Run the preflight again after resolving blockers to confirm the verdict has cleared before you upgrade.