انتقال features به Stable

خبر خوب برای تیم‌های DevOps/SRE: Gateway API نسخه v1.5 منتشر شد! 🎉 این نسخه که در 14 مارس 2026 عرضه شده، بزرگ‌ترین به‌روزرسانی تاکنون است و بیشترین تمرکزش روی ارتقاء قابلیت‌های Experimental به کانال Standard (Stable) بوده است.

نسخه پچ Gateway API v1.5.1 هم در دسترس قرار گرفته است. 🔧

در v1.5 شش قابلیت پرتقاضا به کانال Standard منتقل شده‌اند: ListenerSet، TLSRoute (promoted to Stable)، HTTPRoute CORS filter، Client Certificate Validation (mTLS)، Certificate Selection for Gateway TLS Origination و ReferenceGrant. سپاس ویژه از همه مشارکت‌کنندگان Gateway API بابت تلاش‌ها و مشارکت‌هایشان 🙏

روند انتشار جدید

از این نسخه به بعد، پروژه به مدل release train منتقل شده است: در تاریخ freeze هر release، هر ویژگی‌ای که آماده باشد در آن ریلیز بسته می‌شود. این قاعده هم روی قابلیت‌های Experimental و هم Standard اعمال می‌شود و مستندات هم جزئی از این قاعده‌اند — اگر مستندات آماده نباشند، آن قابلیت آماده ارسال نیست. هدف این تغییر داشتن یک cadence انتشار قابل‌اعتمادتر است؛ در همین راستا نقش‌های Release Manager و Release Shadow هم به تیم افزوده شده‌اند. قدردانی از Flynn (Buoyant) و Beka Modebadze (Google) که در هماهنگی و پالایش فرایند انتشار کمک کردند — آن‌ها در ریلیز بعدی هم در این نقش ادامه خواهند داد.

قابلیت‌های جدید در کانال Standard

ListenerSet — Leads: Dave Protasowski, David Jumani — GEP-1713

چرا ListenerSet؟

قبل از ListenerSet، همه listenerها باید مستقیماً روی شی Gateway تعریف می‌شدند. این روش برای سناریوهای ساده خوب بود اما در محیط‌های پیچیده یا multi-tenant مشکلاتی ایجاد می‌کرد: تیم‌های پلتفرم و اپلیکیشن مجبور بودند روی یک Gateway هماهنگ باشند، تفویض ایمن مالکیت listenerها سخت بود و توسعه یا گسترش Gateway نیازمند تغییر مستقیم در منبع اولیه بود. ListenerSet این محدودیت‌ها را رفع می‌کند؛ با ListenerSet می‌توانید listenerها را به‌صورت مستقل تعریف کنید و سپس آن‌ها را روی یک Gateway هدف merge کنید. همچنین ListenerSet اجازه می‌دهد بیش از 64 listener به یک Gateway مشترک متصل شوند که برای استقرارهای بزرگ و سناریوهایی با چند hostname برای هر listener حیاتی است. توجه کنید که همچنان فیلد listener در Gateway اجباری است و Gateway باید حداقل یک listener معتبر داشته باشد.

چطور کار می‌کند

یک ListenerSet به یک Gateway attach می‌شود و یک یا چند listener به آن اضافه می‌کند. کنترلر Gateway وظیفه دارد listenerهای تعریف‌شده در خود Gateway و هر ListenerSet متصل را merge کند. در مثال زیر، تیم زیرساخت یک Gateway با یک listener پیش‌فرض HTTP تعریف کرده و دو تیم اپلیکیشن هرکدام در namespace جداگانه یک ListenerSet دارند که به همان Gateway متصل شده و listenerهای HTTPS اضافی ارائه می‌دهند:

---
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: example-gateway
  namespace: infra
spec:
  gatewayClassName: example-gateway-class
  allowedListeners:
    namespaces:
      from: All # A selector lets you fine tune this
  listeners:
  - name: http
    protocol: HTTP
    port: 80
---
apiVersion: gateway.networking.k8s.io/v1
kind: ListenerSet
metadata:
  name: team-a-listeners
  namespace: team-a
spec:
  parentRef:
    name: example-gateway
    namespace: infra
  listeners:
  - name: https-a
    protocol: HTTPS
    port: 443
    hostname: a.example.com
    tls:
      certificateRefs:
      - name: a-cert
---
apiVersion: gateway.networking.k8s.io/v1
kind: ListenerSet
metadata:
  name: team-b-listeners
  namespace: team-b
spec:
  parentRef:
    name: example-gateway
    namespace: infra
  listeners:
  - name: https-b
    protocol: HTTPS
    port: 443
    hostname: b.example.com
    tls:
      certificateRefs:
      - name: b-cert
---

Tوضیح عملی: این مدل به شما اجازه می‌دهد مالکیت listenerها را به صورت امن بین تیم‌ها تفکیک کنید، بدون نیاز به تغییر مستقیم منبع Gateway توسط هر تیم. کنترلر merge را انجام می‌دهد و در صورت تداخل نام‌ها یا تنظیمات ناسازگار باید سیاست‌های conflict resolution را در نظر بگیرید.

TLSRoute — Leads: Rostislav Bobrovsky, Ricardo Pchevuzinske Katz — GEP-2643

TLSRoute این امکان را می‌دهد که درخواست‌ها بر اساس Server Name Indication (SNI) در TLS handshake مسیردهی شوند و استریم TLS را به backend مناسب هدایت کنند. وقتی از TLSRoute استفاده می‌کنید، listener TLS روی Gateway می‌تواند در یکی از دو حالت Passthrough یا Terminate پیکربندی شود.

نکتهٔ مهاجرت: اگر Gateway API v1.5 Standard را بر روی نسخه‌های قبلی Experimental (v1.4 یا قدیمی‌تر) نصب کنید، TLSRouteهای Experimental که دارید ممکن است قابل استفاده نباشند، چون آن‌ها در نسخه‌های v1alpha2 یا v1alpha3 ذخیره شده‌اند و در YAMLهای Standard v1.5 گنجانده نشده‌اند. در این حالت دو گزینه دارید: یا از کانال Experimental برای v1.5.1 و بعد از آن استفاده کنید یا TLSRouteهای خود را دانلود و مهاجرت داده و به نسخه v1 منتقل کنید که در YAMLهای Standard موجود است.

Passthrough mode

Passthrough برای نیازهای امنیتی سختگیرانه طراحی شده است؛ جایی که ترافیک باید end-to-end رمزنگاری شده باقی بماند تا به backend برسد، یا وقتی که نمی‌خواهید/نمی‌توانید گواهی‌ها را روی Gateway ذخیره کنید. در این حالت، جریان بایت رمزنگاری‌شده مستقیماً به backend پروکسی می‌شود و Gateway به کلید خصوصی یا داده‌های غیررمز شده دسترسی ندارد. مثال زیر یک Gateway با listener در حالت Passthrough و یک TLSRoute مرتبط را نشان می‌دهد که بر اساس SNI با foo.example.com تطابق می‌دهد:

---
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: example-gateway
spec:
  gatewayClassName: example-gateway-class
  listeners:
  - name: tls-passthrough
    protocol: TLS
    port: 8443
    tls:
      mode: Passthrough
---
apiVersion: gateway.networking.k8s.io/v1
kind: TLSRoute
metadata:
  name: foo-route
spec:
  parentRefs:
  - name: example-gateway
  sectionName: tls-passthrough
  hostnames:
  - "foo.example.com"
  rules:
  - backendRefs:
    - name: foo-svc
      port: 8443
---

Terminate mode

Terminate mode اجازهٔ مدیریت متمرکز گواهی‌ها روی Gateway را می‌دهد. در این حالت، TLS در Gateway terminate می‌شود و payload رمزگشایی‌شده به صورت TCP/plaintext به backend هدایت می‌شود. مثال زیر یک Gateway و TLSRoute برای حالت Terminate را نشان می‌دهد که SNI با bar.example.com تطابق دارد:

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: example-gateway
spec:
  gatewayClassName: example-gateway-class
  listeners:
  - name: tls-terminate
    protocol: TLS
    port: 443
    tls:
      mode: Terminate
      certificateRefs:
      - name: tls-terminate-certificate
---
apiVersion: gateway.networking.k8s.io/v1
kind: TLSRoute
metadata:
  name: bar-route
spec:
  parentRefs:
  - name: example-gateway
  sectionName: tls-terminate
  hostnames:
  - "bar.example.com"
  rules:
  - backendRefs:
    - name: bar-svc
      port: 8080
---

HTTPRoute CORS filter — Leads: Damian Sawicki, Ricardo Pchevuzinske Katz, Norwin Schnyder, Huabing (Robin) Zhao, LiangLliu — GEP-1767

HTTPRoute حالا می‌تواند تنظیمات CORS را مدیریت کند. CORS مکانیزمی مبتنی بر هدرهای HTTP است که مشخص می‌کند آیا یک صفحه وب می‌تواند از منبعی با origin متفاوت به منابع سرور دسترسی داشته باشد یا خیر. با فیلتر CORS در HTTPRoute می‌توانید originهای مجاز، متدها، هدرها، headerهای قابل مشاهده، زمان نگهداری preflight و این‌که آیا credentials (مثل کوکی‌ها) مجاز هستند را تنظیم کنید.

نمونه ساده‌ای که درخواست‌ها را از https://app.example مجاز می‌کند:

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: cors
spec:
  parentRefs:
  - name: same-namespace
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /cors-behavior-creds-false
    backendRefs:
    - name: infra-backend-v1
      port: 8080
    filters:
    - cors:
        allowOrigins:
        - https://app.example
      type: CORS
---

به‌جای لیست originهای مشخص می‌توانید از wildcard “*” استفاده کنید تا هر origin مجاز شود، یا از semi-specified origins مثل https://*.bar.com هم پشتیبانی می‌شود. مثال جامع‌تری که اجازهٔ credentials را هم می‌دهد:

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: cors-allow-credentials
spec:
  parentRefs:
  - name: same-namespace
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /cors-behavior-creds-true
    backendRefs:
    - name: infra-backend-v1
      port: 8080
    filters:
    - cors:
        allowOrigins:
        - "https://www.foo.example.com"
        - "https://*.bar.example.com"
        allowMethods:
        - GET
        - OPTIONS
        allowHeaders:
        - "*"
        exposeHeaders:
        - "x-header-3"
        - "x-header-4"
        allowCredentials: true
        maxAge: 3600
      type: CORS
---

گزینه‌های مهم در فیلتر CORS:

allowCredentials — مشخص می‌کند آیا مرورگر مجاز است credentials (مثل کوکی‌ها یا HTTP auth) را در درخواست CORS ارسال کند یا نه.
allowMethods — متدهای HTTP مجاز برای درخواست‌های CORS.
allowHeaders — هدرهای HTTP مجاز در درخواست CORS.
exposeHeaders — هدرهایی که به کلاینت در دسترس قرار می‌گیرند.
maxAge — حداکثر زمان (ثانیه) که مرورگر نتیجهٔ preflight را کش می‌کند.

Gateway client certificate validation (mTLS) — Leads: Arko Dasgupta, Katarzyna Łach, Norwin Schnyder — GEP-91

Client certificate validation یا mTLS مکانیزمی است که در آن کلاینت هم گواهی ارائه می‌دهد تا هویت خود را به سرور ثابت کند، برخلاف TLS معمولی که فقط سرور گواهی ارائه می‌دهد. در زمینه‌ی Gateway API، این قابلیت به شما اجازه می‌دهد سیاست‌های اعتبارسنجی گواهی کلاینت‌ها را در سطوح listener یا route تعریف کنید تا ارتباطات سمت مشتری از نظر هویت‌سنجی تقویت شوند. این برای سرویس‌هایی که نیاز به احراز هویت دوطرفه یا نیازهای امنیتی قوی دارند، بسیار مفید است.

جمع‌بندی و نکات عملی

v1.5 تمرکز قابل‌توجهی روی پایداری و ارتقاء قابلیت‌هایی دارد که برای استقرارهای تولیدی بزرگ حیاتی‌اند: تفکیک listenerها با ListenerSet، مسیریابی و مدیریت TLS انعطاف‌پذیر با TLSRoute (Passthrough و Terminate)، مدیریت CORS در HTTPRoute، و پشتیبانی از mTLS و انتخاب گواهی برای TLS Origination. اگر دارید از نسخه‌های Experimental استفاده می‌کنید، در مورد مهاجرت منابع (به‌خصوص TLSRoute) دقت کنید و قبل از آپگرید روی سناریوهای production خود تست انجام دهید. 🚀