Експерименти з Gateway API за допомогою kind

Цей документ проведе вас через налаштування локального експериментального середовища з Gateway API з використанням kind. Це середовище розроблено для навчання та тестування. Воно допомагає вам зрозуміти концепції Gateway API без складності промислового середовища.

Огляд

У цьому посібнику ви:

• Налаштуєте локальний кластер Kubernetes за допомогою kind (Kubernetes in Docker)
• Розгорнете cloud-provider-kind, який надає як LoadBalancer Services, так і контролер Gateway API
• Створите Gateway і HTTPRoute для маршрутизації трафіку до демо-застосунку
• Протестуєте вашу конфігурацію Gateway API локально

Це середовище ідеально підходить для навчання, розробки та експериментування з концепціями Gateway API.

Передумови

Перед початком переконайтеся, що у вас встановлено наступне на локальному компʼютері:

• Docker — потрібен для запуску kind та cloud-provider-kind
• kubectl — інструмент командного рядка Kubernetes
• kind — Kubernetes in Docker
• curl — потрібен для тестування маршрутів

Створення кластера kind

Створіть новий кластер kind, запустивши:

kind create cluster

Це створить одновузловий кластер Kubernetes, який працює в контейнері Docker.

Встановлення cloud-provider-kind

Далі вам потрібен cloud-provider-kind, який надає два ключові компоненти для цього середовища:

• Контролер LoadBalancer, який призначає адреси Service типу LoadBalancer
• Контролер Gateway API, який реалізує специфікацію Gateway API

Він також автоматично встановлює Custom Resource Definitions (CRDs) Gateway API у вашому кластері.

Запустіть cloud-provider-kind як контейнер Docker на тому ж хості, де ви створили кластер kind:

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.

Перевірте, що cloud-provider-kind запущений:

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

Ви повинні побачити контейнер у списку та в стані виконання. Ви також можете перевірити логи:

docker logs cloud-provider-kind

Експериментування з Gateway API

Тепер, коли ваш кластер налаштований, ви можете почати експериментування з ресурсами Gateway API.

cloud-provider-kind автоматично надає GatewayClass під назвою cloud-provider-kind. Ви будете використовувати цей клас для створення вашого Gateway.

Варто зауважити, що хоча kind не є хмарним провайдером, проєкт названий cloud-provider-kind, оскільки він надає можливості, які імітують хмарне середовище.

Розгортання Gateway

Наведений нижче маніфест:

• Створить новий простір імен gateway-infra
• Розгорне Gateway, який слухає на порту 80
• Прийматиме HTTPRoutes з іменами хостів, які відповідають шаблону *.exampledomain.example
• Дозволить маршрутам з будь-якого простору імен приєднуватися до Gateway. Примітка: У реальних кластерах використовуйте значення Same або Selector у полі allowedRoutes namespace selector, щоб обмежити приєднання.

Застосуйте наступний маніфест:

---
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

Очікуваний результат:

NAME      CLASS                 ADDRESS      PROGRAMMED   AGE
gateway   cloud-provider-kind   172.18.0.3   True         5m6s

Стовпець PROGRAMMED повинен показувати True, а поле ADDRESS повинно містити IP-адресу.

Розгортання демо-застосунку

Далі розгорніть простий echo-застосунок, який допоможе вам протестувати конфігурацію вашого Gateway. Цей застосунок:

• Слухає на порту 3000
• Повертає деталі запиту, включаючи шлях, заголовки та змінні середовища
• Запускається у просторі імен 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

Тепер створіть HTTPRoute для маршрутизації трафіку з вашого Gateway до echo-застосунку. Цей HTTPRoute буде:

• Реагувати на запити для імені хоста some.exampledomain.example
• Маршрутизувати трафік до echo-застосунку
• Приєднуватися до Gateway у просторі імен 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 з іменем хоста some.exampledomain.example. Наступна команда підходить тільки для POSIX shell і може потребувати налаштування для вашого середовища:

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-відповідь подібну до цієї:

{
 "path": "/",
 "host": "some.exampledomain.example",
 "method": "GET",
 "proto": "HTTP/1.1",
 "headers": {
  "Accept": [
   "*/*"
  ],
  "User-Agent": [
   "curl/8.15.0"
  ]
 },
 "namespace": "demo",
 "ingress": "",
 "service": "",
 "pod": "echo-dc48d7cf8-vs2df"
}

Якщо ви бачите цю відповідь, вітаємо! Ваше середовище Gateway API працює правильно.

Усунення несправностей

Якщо щось працює не так, як очікується, ви можете усунути несправності, перевіривши стан ваших ресурсів.

Перевірка стану Gateway

Спочатку перевірте ресурс Gateway:

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

Перевірте стани в розділі status. Ваш Gateway повинен мати:

• Accepted: True - Gateway був прийнятий контролером
• Programmed: True - Gateway був успішно налаштований
• .status.addresses заповнений IP-адресою

Перевірка стану HTTPRoute

Далі перевірте ваш HTTPRoute:

kubectl get httproute -n demo echo -o yaml

Перевірте стани в розділі status.parents. Поширені проблеми включають:

• ResolvedRefs встановлено False з причиною BackendNotFound; це означає, що Service бекенду не існує або має неправильне імʼя
• Accepted встановлено False; це означає, що маршрут не міг приєднатися до Gateway (перевірте дозволи простору імен або відповідність імені хоста)

Приклад помилки, коли бекенд не знайдено:

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

Перевірка логів контролера

Якщо стан ресурсів не допомагає виявити проблему, перевірте логи cloud-provider-kind:

docker logs -f cloud-provider-kind

Це покаже детальні логи як з контролерів LoadBalancer, так і Gateway API.

Очищення

Коли ви закінчите з експериментами, ви можете очистити ресурси:

Видалення ресурсів Kubernetes

Видаліть простори імен (це видалить усі ресурси в них):

kubectl delete namespace gateway-infra
kubectl delete namespace demo

Зупинка cloud-provider-kind

Зупиніть та видаліть контейнер cloud-provider-kind:

docker stop cloud-provider-kind

Оскільки контейнер був запущений з прапорцем --rm, він буде автоматично видалений при зупинці.

Видалення кластера kind

Нарешті, видаліть кластер kind:

kind delete cluster

Наступні кроки

Тепер, коли ви поекспериментували з Gateway API локально, ви готові дослідити готові до промислової експлуатації реалізації:

• Розгортання в промисловій експлуатації: Перегляньте реалізації Gateway API, щоб знайти контролер, який відповідає вашим вимогам до промислового середовища
• Дізнайтеся більше: Ознайомтеся з документацією Gateway API, щоб дізнатися про розширені можливості, такі як TLS, розподіл трафіку та маніпуляція заголовками
• Розширена маршрутизація: Експериментуйте з маршрутизацією на основі шляху, узгодженням заголовків, дзеркальним відображенням запитів та іншими можливостями, дотримуючись посібникам користувача Gateway API

Фінальне попередження

Це середовище kind призначене лише для розробки та навчання. Завжди використовуйте реалізацію Gateway API промислового рівня для реальних робочих навантажень.

• ←Попередня
• Наступна→