Skip to content

Upgrade Blocked by Deprecated API

Symptom

The upgrade target is rejected or flagged because the cluster recently used a Kubernetes API that is deprecated or removed in the target version.

Possible Causes

  • Manifests still use deprecated API versions.
  • CRDs or admission webhooks are pinned to removed APIs.
  • Operators or add-ons were not upgraded before the cluster version move.

Diagnosis Steps

flowchart TD
    A[Target version is blocked] --> B[Identify removed API versions for target]
    B --> C[Find workloads controllers or CRDs still using them]
    C --> D[Update manifests and controllers]

  1. Confirm the cluster version and allowed targets.

    az aks get-upgrades \
    --resource-group "$RG" \
    --name "$CLUSTER_NAME" \
    --output table
    Command Purpose
    az aks get-upgrades List available Kubernetes upgrade versions for the cluster.
    --resource-group Resource group that contains the AKS cluster.
    --name Name of the AKS cluster.
    --output Output format for the result.

  2. Review Kubernetes resources and controller inventory.

    kubectl api-resources
kubectl get crd
kubectl get deploy --all-namespaces

  3. Compare the target version against the manifests and controllers that still depend on removed APIs.

Resolution

  • Update manifests to supported API versions.
  • Upgrade or replace controllers, webhooks, and operators that still depend on removed APIs.
  • Re-validate in non-production before retrying production.

Prevention

  • Treat API deprecation review as part of every minor-version planning cycle.
  • Do not wait for the oldest supported minor version before cleaning up deprecated objects.
  • Keep cluster lifecycle tracking tied to application-controller lifecycle, not just control-plane schedule.

See Also

Sources