مهاجرت از NGINX Ingress Controller به Kubernetes Gateway API

چیزی که باید بدونیم اینه که NGINX Ingress Controller داره تا مارس ۲۰۲۶ از رده خارج میشه. بعد از اون تاریخ دیگه آپدیت، فیکس یا حتی پچ امنیتی دریافت نمی‌کنه و به نوعی باید برای راه‌حل جدید آماده باشیم، مخصوصاً اگر توی پروداکشن ازش استفاده می‌کنیم.

یک گزینه‌ی بی‌دردسر و قابل اتکا برای جابجایی، Gateway API هست. این ابزار جدیدتر، ساختارمندتر و انعطاف‌پذیرتر از Ingress قدیمی‌ست و داره به استاندارد اصلی Kubernetes تبدیل میشه.

چرا باید از Ingress به Gateway API مهاجرت کنیم؟

خیلی خلاصه:

• پیچیدگی‌های Ingress با انبوه annotation ها و محدودیت‌ها بزرگ شده؛ مخصوصا وقتی بخوای مسیرهای پیشرفته، traffic splitting یا قاعده‌های پیچیده بسازی.
• Gateway API ساختار نقش‌محور داره، بهتر قابل توسعه‌ست و امکانات بیشتری مثل routing‌های پیچیده، پشتیبانی از چند پروتکل، policy‌های دقیق و … رو استاندارد خودش کرده.
• جامعه Kubernetes به سمت Gateway API رفته و خیلی‌ها معتقدن این راه آینده‌داری برای مسیریابی ترافیک در کل کلاستر هست.

برای مثال این تنظیمات یک Ingress قدیمی است:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: application
  namespace: production
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /
spec:
  ingressClassName: nginx
  rules:
    - host: app.domain.ir
      http:
        paths:
          - path: /api
            pathType: Prefix
            backend:
              service:
                name: application-service
                port:
                  number: 8000

و معادل اون با استفاده از Gateway API

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  annotations:
    gateway.networking.k8s.io/generator: ingress2gateway-0.4.0
  creationTimestamp: null
  name: nginx
  namespace: production
spec:
  gatewayClassName: nginx
  listeners:
  - hostname: app.domain.ir
    name: app-domain-ir-http
    port: 80
    protocol: HTTP
status: {}
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  annotations:
    gateway.networking.k8s.io/generator: ingress2gateway-0.4.0
  creationTimestamp: null
  name: application-app-domain-ir
  namespace: production
spec:
  hostnames:
  - app.domain.ir
  parentRefs:
  - name: nginx
  rules:
  - backendRefs:
    - name: application-service
      port: 8000
    matches:
    - path:
        type: PathPrefix
        value: /api
status:
  parents: []

ابزار ingress2gateway چیه؟

این ابزار یک CLI متن‌باز از پروژه‌های رسمی Kubernetes SIG هست که کمک می‌کنه فایل های YAML قدیمی Ingressت رو تبدیل کنی به منابع Gateway API

به زبان ساده:

1. این ابزار Ingress و annotationهای مرتبط باهاش رو می‌خونه
2. اونها رو به Gateway + HTTPRoute (یا منابع مربوطه دیگه) تبدیل می‌کنه
3. خروجی جدید رو بهت میده تا توی فایل YAML بریزی و apply کنی

⚠️ مهم: این تبدیل کاملاً خودکار نیست. همیشه باید خروجی رو بازبینی کنی، تست کنی و مطمئن بشی با توپولوژی و نیازهای خودت هم‌خوانی داره

روش انجام کار

خلاصه مراحل:

1. Gateway API Controller نصب کن ( یا CRDهای Gateway API را مستقیما نصب کن )
2. ابزار ingress2gateway رو روی سیستمت نصب کن ( مثلا با Go install یا باینری از گیت‌هاب )

go install github.com/kubernetes-sigs/ingress2gateway@latest

3. از Ingress های فعلی خروجی بگیر:

kubectl -n ns get ingress -A -o yaml > old_ingress.yaml

4. سپس ابزار را اجرا می‌کنیم تا فرایند تبدیل را انجام بده

ingress2gateway print -n ns --input-file=old_ingress.yml --providers=ingress-nginx

این کامند، تمامی منابع Gateway API مورد نظر را برای شما چاپ می‌کند مانند:

• Gateway
• HTTPRoute
• ReferenceGrant ( در صورت نیاز )
• TLS configuration ( اگر تعریف شده باشد )

5. در صورت نیاز می‌تونید خروجی رو مستقیم داخل یک فایل هم ذخیره کنید:

ingress2gateway print -n ns --input-file=old_ingress.yaml --providers=ingress-nginx > gateway-api.yaml

6. پس از اینکه خروجی آماده شد، وقتش رسیده اون رو بازبینی کنید. هیچ تضمینی وجود نداره که این ابزار دقیق و کامل کار کنه و با خیال راحت تو محیط پروداکشن ازش استفاده کنید. پس حتما یکبار تمامی موارد رو به صورت دستی چک کنید.
7. منابع جدید که ساخته شده رو اپلای کنید

kubectl -n ns apply -f gateway-api.yaml

دو مورد رو حتما بررسی کنید:

• تمام Gateway ها در حالت READY باشند
• تمام HTTPRoute ها تایید و Attach شده باشند

kubectl get gateways -A
kubectl get httproutes -A

8. پس از اینکه همه چیز رو چک کردید و مشکلی وجود نداشت می‌تونید از Gateway API استفاده کنید:
   1. ترافیک سرویس ها رو به Gateway API منتقل کن
   2. اسکیل NGINX ingress controller رو به ۰ تغییر بده
   3. تمام منابع Ingress قدیمی رو پاک کن
   4. وضعیت کلاستر و لاگ ها رو مانیتور کن
   5. و در نهایت ، NGINX ingress رو کامل پاک کن!!

چنتا نکته مهم قبل از مهاجرت

• Gateway API امکانات بیشتری رو استاندارد کرده که قبلاً با annotations توی Ingress تنظیم می‌کردیم (مثل header matching یا traffic splitting)
• بعضی از ویژگی‌های خیلی خاص Ingress ممکنه بدون extension ها توی Gateway API قابل تبدیل نباشن ، پس همیشه باید چک و تطبیق بدی
• اگر Ingress ت الان فقط HTTP ساده رو هندل می‌کنه، مهاجرتش راحت‌تره. اما هر چی پیکربندی سخت‌تر باشه، بازبینی بیشتری نیاز داره
• در نهایت توجه کنید که این ابزار فقط برای Nginx ساخته نشده و شما می‌تونید انواع مختلف Ingress رو باهاش تبدیل کنید.