Kubernetes package repository move to pkgs.k8s.io

A node's package repository points at one minor line, so moving a node to the next minor version starts with changing the repository entry, before any package upgrade runs. The legacy apt.kubernetes.io and yum.kubernetes.io repositories are frozen, which means a node still pointed there cannot receive packages for newer minor releases, whatever its package manager reports. Each per-minor-version repository on pkgs.k8s.io carries packages for a single minor line, so the repository entry itself defines what a node can install. Confirm the exact repository path format, package names and signing key location for your operating system against the current Kubernetes installation documentation before editing any node.

The version skew policy sets the order in which that change can happen. The kube-apiserver is upgraded first, one minor version at a time, before kube-controller-manager, kube-scheduler and kubelets. Kubelets may be up to three minor versions older than kube-apiserver, which gives node groups a window to finish, but it does not permit skipping steps in the sequence. Control plane and node packages must follow the same order, so the repository change for a node belongs in that node's stage of the plan, after the control plane has reached the target minor. Write the sequence as a checklist per node group so each repository change is tied to a verified control plane version.

Pinning matters because the repository is per minor line. When kubelet, kubeadm and kubectl packages are held to their current minor during routine patching, a standard security update cannot pull in a newer minor by accident. Patch windows are where cross-minor upgrades most often happen unintentionally, because a generic upgrade command treats every available newer version as eligible. Confirm how your package manager holds packages on your operating system, and run a listing before patching to check that only patch releases within the current minor line would be installed. Record which hold is set on each node so the upgrade plan starts from a known state.

Plan for the change to be recorded and reversible. A node stage should include the repository entry change, the package versions it will install, and the previous entry needed to roll back. Confirm that each node can reach the new repository, or an internal mirror if the cluster runs without internet access, and ask who maintains that mirror and how often it is synchronized. Kubeadm can pull control plane images from a private registry, but package mirrors need their own owner and process. Keep an inventory that states the minor version and repository each node uses, since mixed entries are the first thing to check when a node will not upgrade.

Rollback is realistic at the package layer and limited at the cluster layer, so decide where your safe points are before the first node changes. Restoring a repository entry is simple: point the node back to the previous source file and confirm that the older kubelet and kubectl packages are still installable from your mirror. Once kubeadm has run on the control plane, however, reverting binaries does not revert the cluster state already written to etcd. For that you need an etcd snapshot taken with etcdctl snapshot save before the first change, and a restore procedure using etcdutl that your team has rehearsed in a non-production cluster. Confirm the exact rollback commands for your kubeadm version in the official upgrade documentation before the maintenance window, not during it.

After each node, run the same short set of checks and record the results before moving on. First, confirm the node reports Ready in the output of kubectl get nodes. Second, confirm that the VERSION column shows the kubelet version you expect, which proves the node has reported its new version to the API server and is not still running the old binary. Third, check workload health: pods drained from the node should be running on other nodes, no pods should be in crash loops, and disruption budgets should have held. Fourth, run the smoke test agreed with application owners, such as a request through the ingress to a service that touches a dependency. A check that is not written down in advance tends to be skipped under time pressure.

The version skew policy sets how far a node may lag behind the control plane during the rollout. The kube-apiserver must be upgraded one minor version at a time and before the controller manager, scheduler and kubelets, and a kubelet may be up to three minor versions older than the kube-apiserver. That gives a node some room, but it is a hard boundary, not a holding area. A node that stays on an old package because its repository move failed can drift toward the edge of the allowed window, and a fleet split across several versions makes every later step harder to reason about. Plan the number of nodes you can leave behind, and treat any node that cannot reach the target version within your change window as a finding, not a reason to extend the window indefinitely.

A failed node should stop the rollout before the next node is touched. The problem may come from the node, but it may also come from something shared, such as the new repository configuration, a package dependency, a container runtime change or a control plane fault that only appears once a kubelet reconnects. Draining the next node would move more workload onto fewer healthy nodes while the cause is still unknown. Define stop criteria in advance: the node is not Ready, reports the wrong version, shows failing workloads, or fails the smoke test. When a stop criteria is met, hold the rollout, decide whether to roll that node back or fix it forward, and resume only after the cause is recorded.