kind를 이용한 게이트웨이 API 실험

이 문서는 kind를 사용하여 로컬 실험 환경을 설정하는 방법을 안내합니다. 이 설정은 학습 및 테스트용으로 설계되었습니다. 이를 통해 복잡한 프로덕션 환경 없이 게이트웨이 API 개념을 이해할 수 있습니다.

개요

• kind(Kubernetes in Docker)를 사용하여 로컬 Kubernetes 클러스터 설정
• LoadBalancer 서비스와 게이트웨이 API 컨트롤러를 모두 제공하는 cloud-provider-kind 배포
• 데모 애플리케이션으로 트래픽을 라우팅하기 위한 게이트웨이 및 HTTPRoute 생성
• 로컬에서 게이트웨이 API 구성 테스트

이 설정은 게이트웨이 API 개념 학습, 개발 및 실험에 이상적입니다.

사전 준비 사항

• Docker - kind 및 cloud-provider-kind를 실행하는 데 필요합니다.
• kubectl - Kubernetes 명령줄 도구
• kind - Kubernetes in Docker
• curl - 라우트를 테스트하는 데 필요합니다.

kind 클러스터 생성

kind create cluster

이렇게 하면 Docker 컨테이너에서 실행되는 단일 노드 Kubernetes 클러스터가 생성됩니다.

cloud-provider-kind 설치

• LoadBalancer 유형 서비스에 주소를 할당하는 LoadBalancer 컨트롤러
• 게이트웨이 API 사양을 구현하는 게이트웨이 API 컨트롤러

또한 클러스터에 게이트웨이 API CRD(Custom Resource Definitions)를 자동으로 설치합니다.

kind 클러스터를 생성한 동일한 호스트에서 cloud-provider-kind를 Docker 컨테이너로 실행합니다:

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

게이트웨이 API 실험하기

cloud-provider-kind는 cloud-provider-kind라는 GatewayClass를 자동으로 프로비저닝합니다. 이 클래스를 사용하여 게이트웨이를 생성할 것입니다.

kind는 클라우드 공급자가 아니지만, 이 프로젝트는 클라우드 지원 환경을 시뮬레이션하는 기능을 제공하므로 cloud-provider-kind라고 명명되었습니다.

게이트웨이 배포

• gateway-infra라는 새 네임스페이스 생성
• 포트 80에서 수신 대기하는 게이트웨이 배포
• *.exampledomain.example 패턴과 일치하는 호스트 이름을 가진 HTTPRoute 허용
• 모든 네임스페이스의 라우트가 게이트웨이에 연결되도록 허용. 참고: 실제 클러스터에서는 allowedRoutes 네임스페이스 선택기 필드에서 Same 또는 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

그런 다음 게이트웨이가 제대로 프로그래밍되고 주소가 할당되었는지 확인하세요:

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 주소가 포함되어야 합니다.

데모 애플리케이션 배포

• 포트 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 생성

• 호스트 이름 some.exampledomain.example에 대한 요청에 응답
• 에코 애플리케이션으로 트래픽 라우팅
• 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

라우트 테스트

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

이 응답을 확인하셨다면 축하합니다! 게이트웨이 API 설정이 올바르게 작동하고 있습니다.

문제 해결

게이트웨이 상태 확인

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

status 섹션에서 조건을 확인하세요. 게이트웨이는 다음을 포함해야 합니다:

• Accepted: True - 게이트웨이가 컨트롤러에 의해 수락됨
• Programmed: True - 게이트웨이가 성공적으로 구성됨
• IP 주소로 채워진 .status.addresses

HTTPRoute 상태 확인

kubectl get httproute -n demo echo -o yaml

status.parents 섹션에서 조건을 확인하세요. 일반적인 문제에는 다음이 포함됩니다:

• BackendNotFound 이유로 ResolvedRefs가 False로 설정된 경우; 이는 백엔드 서비스가 존재하지 않거나 이름이 잘못되었음을 의미합니다.
• Accepted가 False로 설정된 경우; 이는 라우트가 게이트웨이에 연결될 수 없음을 의미합니다 (네임스페이스 권한 또는 호스트 이름 일치 여부 확인).

백엔드를 찾을 수 없을 때의 오류 예시:

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

컨트롤러 로그 확인

docker logs -f cloud-provider-kind

여기에는 LoadBalancer 및 게이트웨이 API 컨트롤러의 자세한 로그가 표시됩니다.

정리

Kubernetes 리소스 제거

kubectl delete namespace gateway-infra
kubectl delete namespace demo

cloud-provider-kind 중지

docker stop cloud-provider-kind

컨테이너가 --rm 플래그로 시작되었으므로 중지될 때 자동으로 제거됩니다.

kind 클러스터 삭제

kind delete cluster

다음 단계

• 프로덕션 배포: 게이트웨이 API 구현체를 검토하여 프로덕션 요구 사항에 맞는 컨트롤러를 찾으세요.
• 더 알아보기: 게이트웨이 API 문서를 탐색하여 TLS, 트래픽 분할, 헤더 조작과 같은 고급 기능을 알아보세요.
• 고급 라우팅: 게이트웨이 API 사용자 가이드를 따라 경로 기반 라우팅, 헤더 일치, 요청 미러링 및 기타 기능을 실험해 보세요.

마지막으로 주의할 점