Migrate Manifests Off Removed Kubernetes APIs

Original Prepium guide · Written for Kubernetes v1.35 and checked against the official documentation on 6 October 2026. Use a disposable practice cluster.

Migrate manifests off removed API versions without changing what they do

Kubernetes retires beta API versions on a published schedule. Objects already stored in the cluster survive, because the API server can serve them through the newer version, but a YAML file that still names a removed version is rejected by kubectl apply. Migration is therefore two jobs: change apiVersion, then rewrite any fields whose names or shape changed in the newer version.

old file (removed version) ──→ apply rejected
        │ 1. new apiVersion   2. renamed / restructured fields
        └──→ new file ──→ server dry-run ──→ apply

1. Ask the cluster what it serves

kubectl api-versions | grep -E 'batch|autoscaling|networking'
kubectl api-resources --api-group=networking.k8s.io
kubectl explain ingress --api-version=networking.k8s.io/v1

Trust the cluster over memory. api-versions lists every group/version the server offers, and kubectl explain documents the fields of the version you name, which is exactly what you need when a field has moved. Both answer from the live cluster, so you do not have to hunt through the docs for a field path during the exam.

2. Know the removals that matter for application manifests

• CronJob: batch/v1beta1 stopped being served in v1.25. Use batch/v1; the deprecation guide lists no notable field changes.
• HorizontalPodAutoscaler: autoscaling/v2beta1 went in v1.25 and autoscaling/v2beta2 in v1.26. Use autoscaling/v2. A metric's targetAverageUtilization becomes a target block with type: Utilization and averageUtilization.
• Ingress: extensions/v1beta1 and networking.k8s.io/v1beta1 went in v1.22. Use networking.k8s.io/v1, where several fields were renamed (next step).

3. Rewrite an Ingress backend by hand

Here is an old-style rule of our own, routing /catalog on shop.example.test to a Service port that is referenced by name:

# networking.k8s.io/v1beta1 (no longer served)
- path: /catalog
  backend:
    serviceName: catalog-svc
    servicePort: http

In networking.k8s.io/v1 the backend becomes a nested service object, a string port goes under port.name (a numeric one would go under port.number), and every path must declare a pathType:

# networking.k8s.io/v1
- path: /catalog
  pathType: Prefix
  backend:
    service:
      name: catalog-svc
      port:
        name: http

Choose pathType deliberately. Exact matches only the literal path, Prefix matches by path elements split on /, and ImplementationSpecific leaves matching to the Ingress class. The guide suggests ImplementationSpecific when you need the undefined old behaviour; when you know the intended matching, state it. A top-level spec.backend is now spec.defaultBackend.

4. Validate before you apply

Assume the migrated file is shop-ingress.yaml and defines an Ingress named shop in prepium-tutorial.

kubectl apply --dry-run=server -f shop-ingress.yaml
kubectl apply -f shop-ingress.yaml
kubectl -n prepium-tutorial get ingress shop -o jsonpath='{.spec.rules[0].http.paths[0].backend.service}'

A server-side dry run submits the request to the API server without persisting it, so the server's schema checks run and leftover old fields or a missing pathType surface before anything changes. kubectl apply validates strictly by default, failing on unknown fields instead of dropping them. Then compare the stored object with the old file field by field: the goal is the same routing, schedule or scaling target, only expressed in the new schema.

The kubectl convert plugin can rewrite a file to another version, but it is not part of kubectl by default (it was removed from the built-in commands and is now installed separately), and the documentation warns that it may fill in non-ideal defaults. Review its output as carefully as a hand edit.

Common mistakes

• Changing only apiVersion on an Ingress: the request fails because serviceName and servicePort are not part of the v1 schema and pathType is missing.
• Putting a named port under port.number. Name and number are mutually exclusive, and number must be an integer.
• Moving an HPA to autoscaling/v2 but keeping targetAverageUtilization: strict validation rejects the unknown field.
• Silently changing behaviour while migrating, for example a different schedule, host or path type than the original file intended.

Cleanup: delete anything you created in prepium-tutorial with kubectl delete namespace prepium-tutorial. References: Deprecated API Migration Guide, Ingress, Install the kubectl convert plugin. Next, try Ingress configuration or CronJobs.