Skip to content

Kubernetes Updated 2026-05-27

Kubernetes upgrade

Upgrade an existing Stack Harbor PaaS Kubernetes cluster to the next package version without rebuilding from scratch.

The Stack Harbor PaaS releases new versions of the Kubernetes Cluster package regularly. An existing cluster doesn’t need to be rebuilt to pick up a newer version — a dedicated upgrade add-on rolls the cluster forward in place, advancing both the Kubernetes minor version and the bundled components (ingress controller, dashboard, metrics server, etc.) as a unit.

This page covers how to trigger that upgrade and what to expect.

Trigger the upgrade

  1. Open the environment in the dashboard.
  2. Hover the Master layer and click Add-Ons.
  3. Find the Kubernetes Cluster Configuration add-on panel and click Upgrade.
  4. Confirm the action in the pop-up.

The platform applies the upgrade automatically — drains and replaces master nodes one at a time, rolls workers in turn, validates each step. The exact duration depends on cluster size and topology; a small development cluster upgrades in a few minutes, a production cluster with multiple control-plane and worker nodes takes longer.

If the cluster is already on the latest published package version, the dashboard surfaces a notification to that effect — no action runs.

What the upgrade rolls

A package upgrade advances the cluster’s Kubernetes version one minor at a time (or applies a patch within the current minor, depending on what’s available) and updates the bundled components shipped with the package:

  • The ingress controller.
  • The dashboard.
  • The metrics server.
  • The CNI plugin.
  • Any installed modules (Prometheus, Grafana, Jaeger, cert-manager, etc.).

The add-on doesn’t skip minor versions. To go from 1.28 to 1.30, the upgrade runs twice — first to 1.29, then to 1.30. The dashboard surfaces the next available version each time.

Before the upgrade

Two things worth doing before you click Upgrade:

  • Read the release notes for the package version you’re moving to. Stack Harbor support can point you at the current source. Pay attention to:
    • Removed API versions in the new Kubernetes minor. Workloads using extensions/v1beta1 Ingress or other long-deprecated APIs won’t apply on the new version.
    • Bundled-component changes that might affect ingress annotations, dashboard URLs, or monitoring scrapers.
  • Verify cluster health. Run kubectl get pods --all-namespaces and kubectl get nodes. Don’t start an upgrade with workloads stuck in CrashLoopBackOff or nodes in NotReady — the upgrade will exacerbate the existing problem rather than fix it.

During the upgrade

Kubernetes upgrades are designed to be non-disruptive to running workloads on a properly configured cluster:

  • The control plane upgrades a node at a time. With the production topology (three control-plane nodes behind API load balancers), the API stays available throughout.
  • Workers are drained, upgraded, and uncordoned in turn. Workloads with PodDisruptionBudget set survive cleanly; workloads without one may see brief restarts.
  • Persistent volumes and storage classes are unaffected.

If you’re on the development topology with a single control-plane node, the control-plane upgrade involves a short window of unavailable API. Plan around it.

After the upgrade

When the add-on reports success:

  • Re-run kubectl get pods --all-namespaces to confirm everything is Running.
  • Re-run /var/log/k8s-health-check.log on the master node (cat /var/log/k8s-health-check.log) to confirm the bundled components are healthy at the new version.
  • Smoke-test the cluster’s external surfaces — Ingress, the dashboard, the metrics endpoint.

If any of those fail, see Kubernetes troubleshooting for the diagnostic path.

See also