Sửa lỗi Kubernetes: no matches for kind "Ingress" in version "extensions/v1beta1"

Lỗi gặp phải

error: unable to recognize "deploy.yaml": no matches for kind "Ingress" in version "extensions/v1beta1"

Bạn chạy kubectl apply -f lên một cluster Kubernetes 1.22+ và gặp lỗi ngay — dù file YAML trông hoàn toàn bình thường. Vấn đề không phải do cú pháp. Mà là phiên bản API trong file đó đã không còn tồn tại trên cluster nữa.

Nguyên nhân gốc rễ

Kubernetes 1.22 đã xóa hoàn toàn nhóm API extensions/v1beta1. Không phải deprecated — mà là xóa hẳn. API server không còn biết Ingress thuộc nhóm đó là gì, đó chính xác là lý do thông báo "no matches for kind" xuất hiện.

API Ingress đã trải qua ba thế hệ trước khi điều này xảy ra:

• ≤ 1.13: Chỉ có extensions/v1beta1
• 1.14: Ra mắt networking.k8s.io/v1beta1; extensions/v1beta1 bị đánh dấu deprecated
• 1.19: networking.k8s.io/v1 được nâng lên stable
• 1.22: Cả hai phiên bản beta bị loại bỏ — đây là lúc lỗi bắt đầu xuất hiện

Đáng lưu ý: Deployment, DaemonSet và ReplicaSet thuộc extensions/v1beta1 đã bị cắt từ phiên bản 1.16. Nếu nhiều loại resource cùng lỗi một lúc, khả năng cao manifest của bạn được tạo từ Kubernetes 1.14 hoặc cũ hơn.

Cách sửa: Cập nhật manifest

Chỉ đổi dòng apiVersion thôi là chưa đủ. Spec Ingress trong networking.k8s.io/v1 đã cấu trúc lại trường backend và bắt buộc phải có pathType. Có ba điểm cần thay đổi.

Cũ (extensions/v1beta1 — lỗi trên 1.22+)

apiVersion: extensions/v1beta1
kind: Ingress
metadata:
  name: my-ingress
  annotations:
    kubernetes.io/ingress.class: nginx
spec:
  rules:
  - host: example.com
    http:
      paths:
      - path: /
        backend:
          serviceName: my-service
          servicePort: 80

Mới (networking.k8s.io/v1 — hoạt động từ 1.19+)

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: my-ingress
  annotations:
    kubernetes.io/ingress.class: nginx
spec:
  rules:
  - host: example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: my-service
            port:
              number: 80

Cụ thể những gì đã thay đổi:

• backend.serviceName → backend.service.name
• backend.servicePort → backend.service.port.number (hoặc .name cho named port)
• pathType hiện là bắt buộc — dùng Prefix, Exact, hoặc ImplementationSpecific

Migrate hàng loạt với kubectl-convert

Có hàng chục manifest cần cập nhật? Plugin kubectl-convert xử lý việc chuyển đổi tự động thay vì bắt bạn sửa từng file một:

# Cài plugin (Linux)
curl -LO "https://dl.k8s.io/release/$(kubectl version --client -o json | jq -r .clientVersion.gitVersion)/bin/linux/amd64/kubectl-convert"
chmod +x kubectl-convert
sudo mv kubectl-convert /usr/local/bin/

# Xem trước kết quả sau khi chuyển đổi
kubectl convert -f old-ingress.yaml --output-version networking.k8s.io/v1

# Lưu ra file mới
kubectl convert -f old-ingress.yaml --output-version networking.k8s.io/v1 > new-ingress.yaml

Trước khi nâng cấp cluster, chạy pluto để quét toàn bộ repository tìm các API version đã deprecated chỉ trong một lần:

# Cài pluto (macOS)
brew install FairwindsOps/tap/pluto

# Quét tất cả file YAML trong thư mục
pluto detect-files -d ./k8s/

# Kiểm tra những gì đang chạy trên cluster thực tế
pluto detect-all-in-cluster

Kiểm tra sau khi sửa

Trước tiên, xác nhận cluster của bạn có hỗ trợ API target không:

kubectl api-versions | grep networking
# Kết quả cần có: networking.k8s.io/v1

Apply manifest đã cập nhật và kiểm tra kết quả:

kubectl apply -f deploy.yaml
# Kết quả mong đợi: ingress.networking.k8s.io/my-ingress created

kubectl get ingress my-ingress
kubectl describe ingress my-ingress

Lưu ý một trường hợp: nếu Ingress này đã được deploy trước đó với API cũ, cluster có thể vẫn còn giữ object cũ. Hãy xóa đi trước rồi mới apply lại:

kubectl delete ingress my-ingress
kubectl apply -f deploy.yaml

Phòng tránh về sau

• Thêm pluto detect-files -d ./k8s/ vào CI pipeline — công cụ này sẽ cảnh báo API version deprecated trước khi chúng được đưa lên cluster.
• Trước khi nâng cấp, đọc hướng dẫn deprecation API của Kubernetes cho phiên bản đích. Mọi thứ bị xóa đều được liệt kê rõ ràng ở đó.
• Khi chỉnh sửa YAML thủ công, dán vào YAML ↔ JSON Converter của ToolCraft để phát hiện lỗi cấu trúc sớm. Công cụ chạy hoàn toàn trên trình duyệt — không có dữ liệu nào rời khỏi máy bạn — điều này quan trọng khi manifest chứa thông tin xác thực cluster hoặc hostname nội bộ.
• Với bất kỳ cluster lạ nào, hãy chạy kubectl api-resources | grep ingress trước khi deploy để biết chính xác những gì đang có sẵn.