Pre-upgrade checks

Where the checks run

• On a reviewed plan. Once a plan is validated, the planning page runs the checks for that plan. This is the report you override failures in — see Deal with the pre-upgrade checks.
• When a rollout starts. Executing runs every check again and decides on that run.
• On the Components tab, Run checks runs them without a plan. The checks that are about a plan's components, images or charts are then Skipped, and the badge Upgrade readiness shows the overall result.
• On a rollout's page, the checks are shown as they stood when the rollout started.

Results

Result	Meaning
Pass	Nothing to do.
Warn	Worth reading; never stops a rollout. A check that errors, or takes longer than five seconds, reports Warn too: it then says nothing about the platform, so verify that part by hand.
Fail	Stops the rollout unless you override it. The override and the check's id are recorded on the rollout.
Fail, marked Cannot be overridden	Stops the rollout until the cause is fixed.
Skipped	Does not apply to this plan or this platform, and says why.

The overall result is the worst one; Skipped counts as a pass. A check marked release was declared by the release being rolled out rather than built into the platform.

release.prerequisites can never be overridden. A release can mark more of its checks as impossible to override; platform.drift is never among them.

Platform and plan checks

Check	What it looks at	Warns or fails when
Platform components are healthy platform.health	Every platform component that runs, except an optional module that is not installed, and whether a rollout is executing	Fail: a component is not Healthy — bring it back first, because a rollout replaces images and does not repair anything — or a rollout is already executing or paused
Platform database accepts connections database.connection	That the Lifecycle module can connect to the platform database	Fail: it cannot. A rollout records its state after every batch
Release feed is reachable releasefeed.reachable	That the feed URL answers. Skipped without a feed	Fail: it does not. The CRD bundle is fetched during the rollout
Identity provider answers discovery identity.oidc-discovery	The identity provider's OpenID discovery document, and that it names the issuer the platform expects	Fail: it does not answer, or names another issuer — align the platform's identity settings with the issuer the provider advertises
Control plane can reach its dependencies network.kernel-egress	That the Lifecycle module can reach the platform API, the identity provider and the release feed	Fail: one is unreachable — check egress network policies and DNS in stackship-system
Health gates answer on the running versions platform.gates-reachable	Each planned component's health check, against the version that runs now	Fail: a check does not answer. The rollout would pause on the same check
Plan images are servable by their registries registry.pull	That every image in the plan can be pulled	Fail: an image is missing or the registry refuses the platform's pull credentials
Release configuration renders for every planned component release.config-render	That the configuration the release gives each planned component can be written on this platform	Fail: a value it needs is missing — re-run the installer so the platform configuration carries it, or roll a newer Lifecycle module first. Warn: the plan also upgrades the Lifecycle module, and the new version renders these components
Clusters are reachable with the platform's own identity platform.cluster-api-url	Whether the platform can act on every registered cluster with its own identity	Fail: the only registered cluster has an API URL; Warn: one of several has. The cluster the platform runs in must be registered without an API URL — see Connect a cluster — and the platform API (stackship-api) restarted after the change, since it caches cluster connections
Clusters hold the permission ceiling this release needs platform.iam-projector-ceiling	For a plan that moves the rbac or kernel component: whether every cluster already holds the Kubernetes rules the release's permission ceiling adds	Warn only: a cluster lacks rules. The row lists them with the commands a cluster administrator runs once; the upgrade itself is safe either way — see After upgrading
Modules that write Secrets have the grants that let them leave the shared account platform.module-secret-grants	Whether the Kubernetes grants that let those modules run under their own accounts are on the cluster. Runs with or without a plan	Warn only: grants are missing, so those modules keep running under the shared module account. A cluster administrator applies them once, as the check describes
The operator may turn policies into admission control operator.admission-policy-grant	For a plan that moves the policies module: whether the operator's ClusterRole stackship-operator-role may manage validating admission policies and their bindings	Fail: it may not, so a policy would be saved and listed but never enforced. The check shows the command a cluster administrator runs

Checks for plans that upgrade a third-party chart or run a platform step

Check	What it looks at	Warns or fails when
The cluster carries the platform admin bundle this release needs release.prerequisites	Every object in the release's platform admin bundle — see The platform admin bundle	Fail, cannot be overridden: objects are missing, changed by hand or unreadable. The row lists each object and the command a cluster administrator runs. Warn: the bundle could not be compared, or is published for another namespace. A release without a bundle is judged on the dependency upgrader's account alone
The pre-rollout snapshot has a backup destination backup.destination	For a plan that upgrades a chart: that Velero's default backup location is Available, and, for a chart whose undo is a database restore, that the platform database has a backup method	Fail: no destination. Override it and a failed snapshot is recorded and the rollout continues — except for a chart whose undo is a database restore, where the snapshot is required. Warn: the target is a service inside this cluster, or the daily platform backup is missing or paused — see Platform backups
The pre-rollout snapshot completed rollout.snapshot	Always Skipped in the report, because the snapshot is taken after it, before batch 1. The rollout's page shows the result	—

Checks the release declares

A release can require things of the cluster. These checks carry the release mark.

Check	Warns or fails when
Kubernetes version is in the release's supported range release.kubernetes	Fail: the cluster's Kubernetes version is outside the range
Operator meets the release's version floor release.operator	Fail: the operator is older — include it in the rollout, in a batch before the components that need it. Warn: its version is not known
Required third-party APIs are served release.required-apis	Fail: the cluster does not serve an API the release uses
Required configuration keys are present release.config-contract	Fail: a component's configuration lacks a key the release reads — re-run the installer, or repair the component, first. Warn: the configuration could not be read
Infrastructure versions match the release's tested set release.tested-with	Warn only: a dependency runs a version the release was not tested with, or its version is not known
Release declares requirements this version cannot check release.unknown-requirements	Warn only: the running Lifecycle module is older than the release's requirements — upgrade it first, or verify them by hand

Checks the operator runs

The operator adds checks it can only make from inside the cluster.

Check	Warns or fails when
operator.preflight	Warn: the operator did not answer within 20 seconds, so its checks are missing
platform.drift	For a plan with a platform step: the installer's dry run found platform settings changed by hand. Fail, which you may override: the rollout then pauses at the platform step, where you choose what happens to them — see Settings changed by hand. Warn: the dry run had not finished two minutes after the other checks, so it says nothing yet
dependency.<chart>.dry-run	For each chart the plan upgrades: the dry run of its upgrade — the values that change, the CRDs, or why it refused. Shown on the plan under Dependencies