{
  "name": "Kubernetes component version skew policy: how far apart component versions can be in a supported cluster",
  "description": "The maximum version difference Kubernetes supports between cluster components, one record per governed component pair (kube-apiserver to kubelet, kube-proxy, kubectl, and the kube-controller-manager/kube-scheduler/cloud-controller-manager group, plus the kube-apiserver-to-kube-apiserver HA rule and the kube-proxy-to-kubelet rule), from the project's own version-skew-policy page. Answers 'how many minor versions behind can my kubelet be', 'can kubectl be newer than kube-apiserver', 'what must already be upgraded before I upgrade this component'. Getting this wrong during a rolling upgrade breaks node registration or blocks the upgrade path, usually discovered mid-rollout. The rule text is stable in structure release to release; the version numbers in the worked examples move with each Kubernetes minor release, so the numeric examples need re-verification on that cadence.",
  "url": "https://referencesource.org/kubernetes-version-skew-policy/",
  "licence": "Source is the Kubernetes project's own documentation (kubernetes.io), a CNCF project. The page footer reads 'Documentation Distributed under CC BY 4.0'. We take the fact plus a short attributed quote linking back.",
  "last_verified": "2026-09-16",
  "stale_after": "2026-12-30",
  "sources": [
    "https://kubernetes.io/releases/version-skew-policy/"
  ],
  "records": [
    {
      "component_pair": "kube-apiserver and kube-apiserver (HA instances)",
      "skew_rule": "the newest and oldest kube-apiserver instances must be within one minor version",
      "max_skew_minor_versions": "1",
      "newer_component_allowed": "symmetric - the page bounds the gap between the newest and oldest instance without naming a governed side",
      "worked_example": "newest kube-apiserver is at 1.37 other kube-apiserver instances are supported at 1.37 and 1.36",
      "current_minor_release": "1.37",
      "upgrade_prerequisite": "In a single-instance cluster, the existing kube-apiserver instance is 1.36 In an HA cluster, all kube-apiserver instances are at 1.36 or 1.37",
      "id": "kube-apiserver-and-kube-apiserver-ha-instances",
      "url": "https://referencesource.org/kubernetes-version-skew-policy/kube-apiserver-and-kube-apiserver-ha-instances/",
      "source": "https://kubernetes.io/releases/version-skew-policy/",
      "source_quote": "the newest and oldest kube-apiserver instances must be within one minor version.",
      "verified_fields": [
        "current_minor_release",
        "skew_rule",
        "upgrade_prerequisite",
        "worked_example"
      ],
      "derived_fields": [
        "component_pair",
        "max_skew_minor_versions",
        "newer_component_allowed"
      ]
    },
    {
      "component_pair": "kube-apiserver and kube-controller-manager, kube-scheduler, or cloud-controller-manager",
      "skew_rule": "They are expected to match the kube-apiserver minor version, but may be up to one minor version older (to allow live upgrades).",
      "max_skew_minor_versions": "1",
      "newer_component_allowed": "no - these components must not be newer than the kube-apiserver instances they communicate with",
      "worked_example": "kube-apiserver is at 1.37 kube-controller-manager, kube-scheduler, and cloud-controller-manager are supported at 1.37 and 1.36",
      "current_minor_release": "1.37",
      "ha_cluster_caveat": "If version skew exists between kube-apiserver instances in an HA cluster, and these components can communicate with any kube-apiserver instance in the cluster (for example, via a load balancer), this narrows the allowed versions of these components.",
      "upgrade_prerequisite": "The kube-apiserver instances these components communicate with are at 1.37",
      "id": "kube-apiserver-and-kube-controller-manager-kube-scheduler-or-cloud-controller-ma",
      "url": "https://referencesource.org/kubernetes-version-skew-policy/kube-apiserver-and-kube-controller-manager-kube-scheduler-or-cloud-controller-ma/",
      "source": "https://kubernetes.io/releases/version-skew-policy/",
      "source_quote": "kube-controller-manager, kube-scheduler, and cloud-controller-manager must not be newer than the kube-apiserver instances they communicate with. They are expected to match the kube-apiserver minor version, but may be up to one minor version older (to allow live upgrades).",
      "verified_fields": [
        "current_minor_release",
        "ha_cluster_caveat",
        "skew_rule",
        "upgrade_prerequisite",
        "worked_example"
      ],
      "derived_fields": [
        "component_pair",
        "max_skew_minor_versions",
        "newer_component_allowed"
      ]
    },
    {
      "component_pair": "kube-apiserver and kube-proxy",
      "skew_rule": "kube-proxy may be up to three minor versions older than kube-apiserver",
      "max_skew_minor_versions": "3",
      "newer_component_allowed": "no - kube-proxy must not be newer than kube-apiserver",
      "legacy_version_exception": "kube-proxy < 1.25 may only be up to two minor versions older than kube-apiserver",
      "worked_example": "kube-apiserver is at 1.37 kube-proxy is supported at 1.37, 1.36, 1.35, and 1.34",
      "current_minor_release": "1.37",
      "ha_cluster_caveat": "If version skew exists between kube-apiserver instances in an HA cluster, this narrows the allowed kube-proxy versions.",
      "upgrade_prerequisite": "The kube-apiserver instances kube-proxy communicates with are at 1.37",
      "id": "kube-apiserver-and-kube-proxy",
      "url": "https://referencesource.org/kubernetes-version-skew-policy/kube-apiserver-and-kube-proxy/",
      "source": "https://kubernetes.io/releases/version-skew-policy/",
      "source_quote": "kube-proxy must not be newer than kube-apiserver. kube-proxy may be up to three minor versions older than kube-apiserver (kube-proxy < 1.25 may only be up to two minor versions older than kube-apiserver).",
      "verified_fields": [
        "current_minor_release",
        "ha_cluster_caveat",
        "legacy_version_exception",
        "skew_rule",
        "upgrade_prerequisite",
        "worked_example"
      ],
      "derived_fields": [
        "component_pair",
        "max_skew_minor_versions",
        "newer_component_allowed"
      ]
    },
    {
      "component_pair": "kube-apiserver and kubectl",
      "skew_rule": "kubectl is supported within one minor version (older or newer) of kube-apiserver.",
      "max_skew_minor_versions": "1",
      "newer_component_allowed": "yes - kubectl is supported one minor version older or newer than kube-apiserver",
      "worked_example": "kube-apiserver is at 1.37 kubectl is supported at 1.38, 1.37, and 1.36",
      "current_minor_release": "1.37",
      "ha_cluster_caveat": "If version skew exists between kube-apiserver instances in an HA cluster, this narrows the supported kubectl versions.",
      "id": "kube-apiserver-and-kubectl",
      "url": "https://referencesource.org/kubernetes-version-skew-policy/kube-apiserver-and-kubectl/",
      "source": "https://kubernetes.io/releases/version-skew-policy/",
      "source_quote": "kubectl is supported within one minor version (older or newer) of kube-apiserver.",
      "verified_fields": [
        "current_minor_release",
        "ha_cluster_caveat",
        "skew_rule",
        "worked_example"
      ],
      "derived_fields": [
        "component_pair",
        "max_skew_minor_versions",
        "newer_component_allowed"
      ]
    },
    {
      "component_pair": "kube-apiserver and kubelet",
      "skew_rule": "kubelet may be up to three minor versions older than kube-apiserver",
      "max_skew_minor_versions": "3",
      "newer_component_allowed": "no - kubelet must not be newer than kube-apiserver",
      "legacy_version_exception": "kubelet < 1.25 may only be up to two minor versions older than kube-apiserver",
      "worked_example": "kube-apiserver is at 1.37 kubelet is supported at 1.37, 1.36, 1.35, and 1.34",
      "current_minor_release": "1.37",
      "ha_cluster_caveat": "If version skew exists between kube-apiserver instances in an HA cluster, this narrows the allowed kubelet versions.",
      "upgrade_prerequisite": "The kube-apiserver instances the kubelet communicates with are at 1.37",
      "id": "kube-apiserver-and-kubelet",
      "url": "https://referencesource.org/kubernetes-version-skew-policy/kube-apiserver-and-kubelet/",
      "source": "https://kubernetes.io/releases/version-skew-policy/",
      "source_quote": "kubelet must not be newer than kube-apiserver. kubelet may be up to three minor versions older than kube-apiserver (kubelet < 1.25 may only be up to two minor versions older than kube-apiserver).",
      "verified_fields": [
        "current_minor_release",
        "ha_cluster_caveat",
        "legacy_version_exception",
        "skew_rule",
        "upgrade_prerequisite",
        "worked_example"
      ],
      "derived_fields": [
        "component_pair",
        "max_skew_minor_versions",
        "newer_component_allowed"
      ]
    },
    {
      "component_pair": "kubelet and kube-proxy",
      "skew_rule": "kube-proxy may be up to three minor versions older or newer than the kubelet instance it runs alongside",
      "max_skew_minor_versions": "3",
      "newer_component_allowed": "yes - kube-proxy may be older or newer than the kubelet instance it runs alongside",
      "legacy_version_exception": "kube-proxy < 1.25 may only be up to two minor versions older or newer than the kubelet instance it runs alongside",
      "current_minor_release": "1.37",
      "id": "kubelet-and-kube-proxy",
      "url": "https://referencesource.org/kubernetes-version-skew-policy/kubelet-and-kube-proxy/",
      "source": "https://kubernetes.io/releases/version-skew-policy/",
      "source_quote": "kube-proxy may be up to three minor versions older or newer than the kubelet instance it runs alongside (kube-proxy < 1.25 may only be up to two minor versions older or newer than the kubelet instance it runs alongside).",
      "verified_fields": [
        "current_minor_release",
        "legacy_version_exception",
        "skew_rule"
      ],
      "derived_fields": [
        "component_pair",
        "max_skew_minor_versions",
        "newer_component_allowed"
      ]
    }
  ]
}