اجرای آزمایش Gateway API با استفاده از kind

این راهنما گام‌به‌گام به شما نشان می‌دهد چگونه یک محیط آزمایشی محلی با Gateway API راه‌اندازی کنید تا مفاهیم را بدون پیچیدگی‌های production تجربه کنید. 🧪 توجه داشته باشید که این تنظیمات صرفاً برای یادگیری و تست مناسب‌اند و نباید در محیط تولید استفاده شوند.

هدف کلی: با استفاده از kind یک خوشه محلی Kubernetes راه‌اندازی کنید، با اجرای یک کانتینر cloud-provider-kind قابلیت‌های LoadBalancer و Gateway API را شبیه‌سازی کنید، یک Gateway و یک HTTPRoute ایجاد کنید و در نهایت ترافیک را به یک اپلیکیشن ساده echo هدایت و آزمایش کنید. ✅

پیش‌نیازها — قبل از شروع مطمئن شوید روی ماشین محلی نصب شده‌اند: Docker (برای اجرا کردن kind و cloud-provider-kind)، kubectl، kind، و curl. 🛠️

راه‌اندازی یک خوشه kind تک‌نودی (Kubernetes در Docker):

kind create cluster

نصب و اجرای cloud-provider-kind — این کامپوننت دو نقش اصلی دارد: یک کنترل‌کننده LoadBalancer که آدرس IP به سرویس‌های نوع LoadBalancer اختصاص می‌دهد و یک کنترل‌کننده Gateway که مشخصه‌های Gateway API را پیاده‌سازی می‌کند. همچنین CRD های Gateway API را در خوشه نصب می‌کند. برای اجرا:

VERSION="$(basename $(curl -s -L -o /dev/null -w '%{url_effective}' https://github.com/kubernetes-sigs/cloud-provider-kind/releases/latest))"
docker run -d --name cloud-provider-kind --rm --network host -v /var/run/docker.sock:/var/run/docker.sock registry.k8s.io/cloud-provider-kind/cloud-controller-manager:${VERSION}

نکته: در برخی سیستم‌ها ممکن است برای دسترسی به ساکت Docker نیاز به مجوزهای بیشتر باشد. برای اطمینان کانتینر را بررسی کنید:

docker ps --filter name=cloud-provider-kind
docker logs cloud-provider-kind

ایجاد یک GatewayClass/Gateway — cloud-provider-kind به‌طور خودکار یک GatewayClass با نام cloud-provider-kind فراهم می‌کند. مثال مانیفست برای ایجاد یک namespace و یک Gateway که روی پورت 80 گوش می‌دهد و host pattern را “*.exampledomain.example” می‌پذیرد:

---
apiVersion: v1
kind: Namespace
metadata:
  name: gateway-infra
---
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: gateway
  namespace: gateway-infra
spec:
  gatewayClassName: cloud-provider-kind
  listeners:
    - name: default
      hostname: "*.exampledomain.example"
      port: 80
      protocol: HTTP
      allowedRoutes:
        namespaces:
          from: All

پس از اعمال مانیفست، بررسی کنید که Gateway برنامه‌ریزی شده و آدرس به آن تخصیص یافته باشد:

kubectl get gateway -n gateway-infra gateway

ستون PROGRAMMED باید True و فیلد ADDRESS حاوی یک آدرس IP باشد؛ این آدرس آدرس ورودی شما برای تست‌ها خواهد بود. 🔎

راه‌اندازی اپلیکیشن آزمایشی echo — یک اپ ساده که روی پورت 3000 گوش می‌دهد و جزئیات درخواست را بازتاب می‌دهد. آن را در namespace ای به نام demo مستقر می‌کنیم:

apiVersion: v1
kind: Namespace
metadata:
  name: demo
---
apiVersion: v1
kind: Service
metadata:
  labels:
    app.kubernetes.io/name: echo
  name: echo
  namespace: demo
spec:
  ports:
    - name: http
      port: 3000
      protocol: TCP
      targetPort: 3000
  selector:
    app.kubernetes.io/name: echo
  type: ClusterIP
---
apiVersion: apps/v1
kind: Deployment
metadata:
  labels:
    app.kubernetes.io/name: echo
  name: echo
  namespace: demo
spec:
  selector:
    matchLabels:
      app.kubernetes.io/name: echo
  template:
    metadata:
      labels:
        app.kubernetes.io/name: echo
    spec:
      containers:
        - env:
            - name: POD_NAME
              valueFrom:
                fieldRef:
                  apiVersion: v1
                  fieldPath: metadata.name
            - name: NAMESPACE
              valueFrom:
                fieldRef:
                  apiVersion: v1
                  fieldPath: metadata.namespace
          image: registry.k8s.io/gateway-api/echo-basic:v20251204-v1.4.1
          name: echo-basic

تعریف یک HTTPRoute که درخواست‌های host = some.exampledomain.example را به سرویس echo هدایت کند و به Gateway در namespace gateway-infra متصل شود:

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: echo
  namespace: demo
spec:
  parentRefs:
    - name: gateway
      namespace: gateway-infra
  hostnames: ["some.exampledomain.example"]
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /
      backendRefs:
        - name: echo
          port: 3000

تست مسیر با curl — ابتدا آدرس IP اختصاص‌یافته به Gateway را پیدا کرده و سپس با host header مناسب درخواست بفرستید:

GW_ADDR=$(kubectl get gateway -n gateway-infra gateway -o jsonpath='{.status.addresses[0].value}')
curl --resolve some.exampledomain.example:80:${GW_ADDR} http://some.exampledomain.example

اگر همه‌چیز درست باشد، باید یک پاسخ JSON دریافت کنید که مسیر، host، method، headers و اطلاعات پاد/namespace را نشان می‌دهد؛ مشابه این خروجی:

{
  "path": "/",
  "host": "some.exampledomain.example",
  "method": "GET",
  "proto": "HTTP/1.1",
  "headers": {
    "accept": ["*/*"],
    "user-agent": ["curl/8.15.0"]
  },
  "Namespace": "demo",
  "pod": "echo-..."
}

اگر این پاسخ را دریافت کردید، تبریک 🎉 راه‌اندازی Gateway API محلی شما عملکرد صحیح دارد.

عیب‌یابی — مراحل و معیارهایی که معمولاً کمک می‌کنند:

1) وضعیت Gateway را بررسی کنید:

kubectl get gateway -n gateway-infra gateway -o yaml

در بخش status باید ببینید که Gateway Accepted: True و Programmed: True و آدرس در .status.addresses پر شده است.

2) وضعیت HTTPRoute را بررسی کنید:

kubectl get httproute -n demo echo -o yaml

در بخش status.parents شرایط را ببینید. موارد رایج:

– اگر ResolvedRefs با دلیل BackendNotFound روی False است، یعنی سرویس یا نام backend اشتباه است.

– اگر Accepted روی False است، مسیر نتوانسته به Gateway متصل شود — مجوزهای namespace یا تطابق host را بررسی کنید.

مثال خطا وقتی Backend پیدا نشد (نمونه در بخش status):

status:
  parents:
    - conditions:
        - lastTransitionTime: "2026-01-19T17:13:35Z"
          message: backend not found
          observedGeneration: 2
          reason: BackendNotFound
          status: "False"
          type: ResolvedRefs
  controllerName: kind.sigs.k8s.io/gateway-controller

3) لاگ‌های کنترلر cloud-provider-kind را بررسی کنید تا خطاها یا جزئیات بیشتر را ببینید:

docker logs -f cloud-provider-kind

پاکسازی منابع پس از آزمایش:

kubectl delete namespace gateway-infra
kubectl delete namespace demo
docker stop cloud-provider-kind
kind delete cluster

گام‌های بعدی و نکات حرفه‌ای برای SRE/DevOps:

– برای استقرار production، کنترل‌رهای Gateway API مختلف را مرور کنید و یکی را انتخاب کنید که نیازهای شما (TLS، scalability، observability، integration با cloud provider واقعی) را برآورده کند. 🔍

– مستندات Gateway API را برای قابلیت‌های پیشرفته مثل TLS termination، traffic splitting، header manipulation و مسیریابی پیچیده بررسی کنید.

– در محیط‌های واقعی از محدودیت attach به namespace (Same یا Selector) برای allowedRoutes استفاده کنید تا امنیت و جداسازی را تضمین کنید؛ اجازه All صرفاً برای آزمایش مناسب است.

یادآوری نهایی: این تنظیمات شبیه‌سازی محیط ابری برای توسعه و یادگیری است — برای بارهای واقعی از راهکارهای آزموده و مناسب production استفاده کنید. ⚠️

اگر خواستید، می‌توانم کمک کنم همین مانیفست‌ها را برای یک پیاده‌سازی production-ready یا برای اضافه کردن TLS و observability (metrics/logs) بهبود بدهم. 🙂

اجرای آزمایش Gateway API با استفاده از kind

لغو پاسخ