agentgateway 사용하기

agentgateway 사용하기 (Use agentgateway)

agentgateway는 Envoy의 대안으로 사용할 수 있는 데이터 플레인 프록시예요. AI 에이전트와 Model Context Protocol (MCP) 트래픽을 위해 특별히 제작되었으면서도, 일반 목적의 Layer 7 라우팅도 지원해요. agentgateway가 활성화되면 Istio가 앰비언트 메시의 두 역할에서 Envoy 대신 그것을 프로그래밍할 수 있어요:

출처: Istio 문서

본문

• 인그레스 게이트웨이로서, 메시로 들어오는 노스-사우스 트래픽을 처리하고,
• 웨이포인트 프록시로서, 워크로드 집합에 대한 이스트-웨스트 Layer 7 처리를 처리해요.

이 가이드는 통합이 어떻게 동작하는지, 어떤 API가 지원되는지, 그리고 각 역할에 대해 Istio를 설치하고 agentgateway를 구성하는 방법을 설명해요.

통합이 어떻게 동작하는지 (How the integration works)

Istiod는 agentgateway를 오직 쿠버네티스 Gateway API 리소스를 통해서만 구성하며, 그것을 xDS를 통해 프록시에 전달해요. 이 프록시는 Envoy와는 구별되는 데이터 플레인 구현이에요. Gateway가 agentgateway GatewayClass를 선택하면, Istiod는 Istio의 Envoy 기반 게이트웨이를 관리하는 것과 같은 방식으로 agentgateway Deployment와 Service를 프로비저닝하고 관리해요.

agentgateway를 활성화하면 두 개의 GatewayClass 리소스가 등록돼요:

GatewayClass	컨트롤러	역할
istio-agentgateway	istio.io/agentgateway-controller	인그레스 게이트웨이
istio-agentgateway-waypoint	istio.io/agentgateway-waypoint-controller	웨이포인트 프록시

데이터 플레인은 gatewayClassName 필드를 통해 Gateway별로 선택되므로, agentgateway와 Istio의 기본 Envoy 기반 게이트웨이 및 웨이포인트가 같은 클러스터에서 공존할 수 있어요. 특정 게이트웨이 또는 웨이포인트에 대해 위 클래스 중 하나를 참조하기만 하면 agentgateway를 선택할 수 있어요.

지원 및 미지원 구성 (Supported and unsupported configuration)

Istio는 다음 Gateway API 리소스를 agentgateway에 대해 지원해요:

• Gateway (istio-agentgateway 또는 istio-agentgateway-waypoint 클래스 사용)
• HTTPRoute, GRPCRoute, TCPRoute, TLSRoute
• AI 추론 워크로드로의 라우팅을 위한 Gateway API Inference Extension의 InferencePool

시작하기 전에 (Before you begin)

쿠버네티스 Gateway API CRD는 대부분의 쿠버네티스 클러스터에 기본으로 설치되어 있지 않다는 점을 명심하세요. Gateway API를 사용하기 전에 설치되어 있는지 확인하세요:

$ kubectl get crd gateways.gateway.networking.k8s.io &> /dev/null || \
  kubectl apply --server-side -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.6.0/experimental-install.yaml

agentgateway가 활성화된 Istio 설치하기 (Install Istio with agentgateway enabled)

agentgateway 지원은 istiod의 PILOT_ENABLE_AGENTGATEWAY 기능 플래그 뒤에 있으며, 기본적으로 비활성화돼 있어요. 플래그를 활성화한 채 ambient 프로파일로 Istio를 설치하세요. 웨이포인트 GatewayClass도 등록되도록 ambient 프로파일이 필요해요:

$ istioctl install --set profile=ambient --set values.pilot.env.PILOT_ENABLE_AGENTGATEWAY=true -y

두 agentgateway GatewayClass 리소스가 등록되었는지 확인하세요:

$ kubectl get gatewayclass istio-agentgateway istio-agentgateway-waypoint
NAME                          CONTROLLER                                  ACCEPTED   AGE
istio-agentgateway            istio.io/agentgateway-controller            True       30s
istio-agentgateway-waypoint   istio.io/agentgateway-waypoint-controller   True       30s

샘플 애플리케이션 배포하기 (Deploy a sample application)

이 가이드의 예제에서 사용되는 Bookinfo 샘플 애플리케이션을 배포하세요:

$ kubectl apply -f @samples/bookinfo/platform/kube/bookinfo.yaml@

agentgateway를 인그레스 게이트웨이로 구성하기 (Configure agentgateway as an ingress gateway)

agentgateway를 인그레스 게이트웨이로 사용하려면 istio-agentgateway 클래스를 참조하는 Gateway를 생성하세요. Istiod가 해당 agentgateway 배포를 자동으로 프로비저닝하고 관리해요.

$ kubectl apply -f - <<EOF
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: bookinfo-gateway
  annotations:
    networking.istio.io/service-type: ClusterIP
spec:
  gatewayClassName: istio-agentgateway
  listeners:
  - name: http
    port: 80
    protocol: HTTP
    allowedRoutes:
      namespaces:
        from: Same
EOF

gatewayClassName: istio-agentgateway 필드가 Envoy가 아닌 agentgateway 데이터 플레인을 선택해요. 기본적으로 Istio는 게이트웨이에 대해 LoadBalancer 서비스를 만들어요. networking.istio.io/service-type: ClusterIP 어노테이션은 대신 ClusterIP 서비스를 요청해서, 이 가이드에서 kubectl port-forward로 게이트웨이에 도달할 수 있게 해요.

productpage 서비스를 게이트웨이를 통해 노출하도록 HTTPRoute를 연결하세요:

$ kubectl apply -f - <<EOF
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: bookinfo
spec:
  parentRefs:
  - name: bookinfo-gateway
  rules:
  - matches:
    - path:
        type: Exact
        value: /productpage
    - path:
        type: PathPrefix
        value: /static
    - path:
        type: Exact
        value: /login
    - path:
        type: PathPrefix
        value: /api/v1/products
    backendRefs:
    - name: productpage
      port: 9080
EOF

게이트웨이가 프로비저닝되고 프로그래밍되었는지 확인하세요. CLASS 열이 agentgateway 클래스를 보여줘요:

$ kubectl get gateway bookinfo-gateway
NAME               CLASS                ADDRESS                                      PROGRAMMED   AGE
bookinfo-gateway   istio-agentgateway   bookinfo-gateway.default.svc.cluster.local   True         30s

이제 agentgateway 인그레스 게이트웨이를 통해 애플리케이션에 접근할 수 있어요. 로컬 포트를 게이트웨이 서비스로 포워딩하고 브라우저에서 http://localhost:8080/productpage를 여세요:

$ kubectl port-forward svc/bookinfo-gateway 8080:80

agentgateway를 웨이포인트로 구성하기 (Configure agentgateway as a waypoint)

웨이포인트 프록시는 앰비언트 메시의 워크로드 집합에 Layer 7 처리를 추가해요. 이 역할에 agentgateway를 사용하려면 istio-agentgateway-waypoint 클래스를 참조하는 Gateway를 배포하세요.

먼저 네임스페이스가 앰비언트 데이터 플레인에 등록되었는지 확인하세요:

$ kubectl label namespace default istio.io/dataplane-mode=ambient
namespace/default labeled

웨이포인트를 배포하세요. 모든 웨이포인트처럼, HBONE 프로토콜을 사용해 포트 15008에서 mesh라는 단일 리스너를 정의해야 해요. Envoy 웨이포인트와의 유일한 차이는 gatewayClassName이에요:

$ kubectl apply -f - <<EOF
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: agentgateway-waypoint
  labels:
    istio.io/waypoint-for: service
spec:
  gatewayClassName: istio-agentgateway-waypoint
  listeners:
  - name: mesh
    port: 15008
    protocol: HBONE
EOF

웨이포인트가 프로그래밍되었는지 확인하세요:

$ kubectl get gateway agentgateway-waypoint
NAME                    CLASS                         ADDRESS        PROGRAMMED   AGE
agentgateway-waypoint   istio-agentgateway-waypoint   10.96.15.112   True         30s

웨이포인트의 이름을 값으로 하는 istio.io/use-waypoint 레이블을 추가해 서비스를 웨이포인트를 사용하도록 등록하세요. 예를 들어, reviews 서비스로 향하는 트래픽을 agentgateway 웨이포인트를 통해 보내려면:

$ kubectl label service reviews istio.io/use-waypoint=agentgateway-waypoint
service/reviews labeled

이제 앰비언트 메시의 워크로드에서 reviews 서비스로의 요청이 Layer 7 처리를 위해 agentgateway 웨이포인트를 통해 라우팅돼요. 네임스페이스, 서비스, 파드를 등록하는 방법과 웨이포인트가 서로 다른 트래픽 유형을 처리하는 방법에 대해 더 알아보려면 웨이포인트 프록시 구성을 참조하세요.

웨이포인트에서 Layer 7 라우팅 정책을 적용하려면, kind가 Service인 parentRef를 사용해 Gateway API 라우트를 Service에 연결하세요. 예를 들어 다음 HTTPRoute는 reviews 서비스 트래픽의 90%를 reviews-v1로, 10%를 reviews-v2로 보내요:

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: reviews
spec:
  parentRefs:
  - group: ""
    kind: Service
    name: reviews
    port: 9080
  rules:
  - backendRefs:
    - name: reviews-v1
      port: 9080
      weight: 90
    - name: reviews-v2
      port: 9080
      weight: 10

정리 (Cleanup)

인그레스 게이트웨이와 그 라우트를 제거하세요:

$ kubectl delete httproute bookinfo
$ kubectl delete gateway bookinfo-gateway

웨이포인트를 제거하고 reviews 서비스의 등록을 해제하세요:

$ kubectl label service reviews istio.io/use-waypoint-
$ kubectl delete gateway agentgateway-waypoint

샘플 애플리케이션과 앰비언트 레이블을 제거하세요:

$ kubectl delete -f @samples/bookinfo/platform/kube/bookinfo.yaml@
$ kubectl label namespace default istio.io/dataplane-mode-

Istio를 제거하세요:

$ istioctl uninstall --purge -y
$ kubectl delete namespace istio-system

쿠버네티스 Gateway API CRD를 제거하세요:

$ kubectl delete -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.6.0/experimental-install.yaml

더 알아보기 (Learn more)

• Configure waypoint proxies
• agentgateway