The Stack Harbor PaaS ships Kubernetes as a managed package — the cluster components (kubelet, kube-proxy, scheduler, controller-manager, etcd, the CNI plugin, the ingress controller, the dashboard, the metrics server) are packaged together, tested as a unit, and installed by the platform. The version you pick at install time fixes that set; an upgrade rolls the whole package forward.
This page explains how versions are managed, how the platform package relates to upstream Kubernetes, and how to choose a version for a new cluster.
How the version is chosen
At cluster install time, the Version dropdown lists the minor versions of Kubernetes that the platform currently supports. The list rotates as new packages are released and old ones reach end-of-support:
- The newest entry in the dropdown is the latest Kubernetes minor that has been packaged, tested, and shipped on the platform.
- Older minor versions remain available for some time after a newer one is added, so existing fleets can keep installing matching versions until they upgrade.
- Versions older than the supported window are removed from the dropdown for new installations but continue to run on already-installed clusters until those clusters upgrade.
The list is the source of truth for what’s currently installable. The dashboard’s version picker reflects it live.
How the package tracks upstream
The platform package wraps upstream Kubernetes — it doesn’t fork it. The version string you see in the dropdown (e.g. 1.31.3) corresponds directly to an upstream patch tag.
Two consequences:
- The package is one or two minor versions behind upstream. Packaging a new minor includes integrating the matching versions of the bundled components, running the platform’s installation and upgrade tests, and validating the health-check suite. That takes time. The lag is normal; it doesn’t indicate a stalled package.
- Patch versions track upstream. When upstream ships a patch on a minor that’s already in the platform package, the next package release picks it up.
You can check the source of the Kubernetes Cluster package on its public GitHub repository for the precise version pinning of each component (ingress controller, dashboard, metrics server, etc.) per release. Stack Harbor support can point you at the current source if you need it.
Choosing a version for a new cluster
The default play is to pick the highest version in the dropdown. That gets you:
- The longest runway before the cluster’s version reaches end-of-support on the platform.
- The most recent bug fixes across both Kubernetes and the bundled components.
Pick an older version only when something forces the choice:
- A managed CRD or operator your team uses isn’t ready for the latest Kubernetes (this is rare with modern projects but happens during major API removals).
- A fleet of clusters you operate already runs an older minor and you want to keep the version uniform until a coordinated upgrade.
- A specific bug you’ve hit in a newer version that’s been fixed only in an older patch series.
Lifecycle and end-of-support
The platform aligns roughly with upstream’s release cadence (a new Kubernetes minor every few months) and its support window (about 14 months upstream). When a Kubernetes minor reaches upstream end-of-life, the platform stops shipping new installations of that version. Existing clusters on that version continue to run but should be upgraded to a still-supported minor on a normal cadence.
Plan one cluster upgrade per quarter as a reasonable rhythm. Upgrading more often is fine; letting a cluster fall multiple minors behind makes the eventual upgrade riskier because each minor-to-minor step has its own deprecations to deal with.
Changelog and per-version detail
For per-version changelogs — which components moved to which versions, which deprecations were absorbed, which platform-package improvements landed — refer to the Release Notes of the Kubernetes Cluster package on the platform’s public GitHub repository. Stack Harbor support can point you at the current source.