ListenerSet 지원

ListenerSet 지원 (ListenerSet Support)

ListenerSet는 ListenerSet 리소스에 정의된 추가 리스너 그룹이 단일 Gateway에 붙을 수 있게 해줘요. 인프라 소유자는 Gateway를 관리하면서, 애플리케이션 소유자는 별도 네임스페이스에서 리스너와 TLS 인증서를 관리할 수 있어요.

출처: ListenerSet Support

본문

ListenerSet는 ListenerSet 리소스에 정의된 추가 리스너 그룹이 단일 Gateway에 붙을 수 있게 해줘요. 이를 통해 인프라 소유자는 Gateway를 관리하면서, 애플리케이션 소유자는 별도 네임스페이스에서 리스너와 TLS 인증서를 관리할 수 있어요. 붙은 모든 리스너는 부모 Gateway의 주소와 인프라를 사용해요.

Cilium은 표준 ListenerSet API를 지원해요. 이 기능은 별도의 Cilium 기능 플래그가 필요하지 않아요. Cilium operator를 시작하기 전에 ListenerSet CRD를 설치해서 시작 시 ListenerSet 지원이 감지되도록 해주세요 (사전 요구사항 참고). 기존 설치에 CRD를 추가한 경우, 그 후 Cilium operator를 재시작해서 새 리소스를 감지하고 ListenerSet 지원을 활성화하게 해주세요.

참고

기본적으로 Gateway 리소스는 ListenerSet을 수락하지 않아요. Gateway에 대한 ListenerSet 부착을 활성화하려면 spec.allowedListeners로 ListenerSet이 붙을 수 있는 네임스페이스를 선택해주세요.

리스너 위임하기 (Delegate a listener)

다음 예제는 default 네임스페이스에 Gateway를 만들고, gateway-access: "true" 레이블이 있는 네임스페이스의 ListenerSet을 허용해요. ListenerSet과 HTTPRoute는 이 레이블이 있는 listenerset-demo 네임스페이스에 만들어져요.

---
apiVersion: v1
kind: Namespace
metadata:
  name: listenerset-demo
  labels:
    gateway-access: "true"
---
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: shared-gateway
  namespace: default
spec:
  gatewayClassName: cilium
  allowedListeners:
    namespaces:
      from: Selector
      selector:
        matchLabels:
          gateway-access: "true"
  listeners:
  - name: base-http
    protocol: HTTP
    port: 8081
---
apiVersion: gateway.networking.k8s.io/v1
kind: ListenerSet
metadata:
  name: delegated-listeners
  namespace: listenerset-demo
spec:
  parentRef:
    name: shared-gateway
    namespace: default
  listeners:
  - name: echo
    hostname: echo.example.com
    protocol: HTTP
    port: 80
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: echo
  namespace: listenerset-demo
spec:
  parentRefs:
  - group: gateway.networking.k8s.io
    kind: ListenerSet
    name: delegated-listeners
    sectionName: echo
  hostnames:
  - echo.example.com
  rules:
  - backendRefs:
    - name: echo-1
      port: 8080

구성을 적용하고 위임된 네임스페이스에 echo 애플리케이션을 배포해볼게요:

$ kubectl apply -f https://raw.githubusercontent.com/cilium/cilium/1.20.2/examples/kubernetes/gateway/listenerset.yaml
$ kubectl -n listenerset-demo apply -f https://raw.githubusercontent.com/cilium/cilium/1.20.2/examples/kubernetes/gateway/echo-basic.yaml

라우트는 리스너를 정의하는 리소스에 직접 붙어요. HTTPRoute는 kind: ListenerSet를 지정하고 echo 리스너를 선택해요. Gateway만 참조하는 Route는 어떤 ListenerSet 리스너에도 붙지 않아요.

ListenerSet 확인하기 (Verify the ListenerSet)

부모 Gateway와 ListenerSet을 모두 확인해볼게요:

$ kubectl get gateway shared-gateway
NAME             CLASS    ADDRESS          PROGRAMMED   AGE
shared-gateway   cilium   192.0.2.100      True         1m

$ kubectl get listenerset -n listenerset-demo delegated-listeners
NAME                  ACCEPTED   PROGRAMMED   AGE
delegated-listeners   True       True         1m

리스너에 요청을 보내볼게요:

$ GATEWAY=$(kubectl get gateway shared-gateway -o jsonpath='{.status.addresses[0].value}')
$ curl --fail --header 'Host: echo.example.com' http://$GATEWAY/

Gateway는 유효한 리스너를 하나 이상 포함하는 붙은 ListenerSet의 수를 status.attachedListenerSets에 보고해요. 위임된 리스너에 대한 상세 상태는 ListenerSet의 status.listeners 필드에 나타나요. 문제 해결 시 각 리스너의 Accepted, Programmed, ResolvedRefs, Conflicted 조건을 검사하세요. 또한 부모 Gateway가 프로그래밍됐고 주소가 있는지도 확인하세요.

$ kubectl describe gateways -n default shared-gateway | grep Attached
  Attached Listener Sets:  1
    Attached Routes:  0

$ kubectl describe listenerset -n listenerset-demo delegated-listeners | grep Attached
    Attached Routes:  1

운영 고려사항 (Operational considerations)

  • Gateway는 allowedListeners로 어떤 ListenerSet 네임스페이스가 수락되는지 제어해요. 기본적으로는 어떤 ListenerSet도 허용되지 않아요.
  • 각 ListenerSet 리스너는 allowedRoutes로 Route 부착을 독립적으로 제어해요. 이 필드를 생략하면 ListenerSet의 네임스페이스의 Route가 허용돼요.
  • Route 부모 참조는 반드시 명시적으로 kind: ListenerSet를 설정해야 해요. kind를 생략하면 Gateway로 기본 설정돼요.
  • HTTPRoute, GRPCRoute, TLSRoute와 선택적 TCPRoute, UDPRoute API는 ListenerSet의 호환 리스너를 대상으로 할 수 있어요.
  • Gateway에 직접 정의된 리스너는 충돌하는 ListenerSet 리스너보다 우선해요. ListenerSet들 사이에서는 더 오래된 ListenerSet이 우선해요. 충돌은 더 낮은 우선순위의 리스너에 보고돼요.
  • 유효한 리스너와 유효하지 않은 리스너가 섞인 ListenerSet도 수락될 수 있어요. ListenerSet의 최상위 조건만 믿지 말고 각 리스너의 상태를 확인하세요.
  • 인증서 참조는 ListenerSet의 네임스페이스에서 평가돼요. 크로스 네임스페이스 Secret에는 ListenerSet용 ReferenceGrant가 필요해요. 부모 Gateway에 부여된 Grant는 상속되지 않아요.
  • 부모 Gateway는 자신만의 유효한 리스너를 하나 이상 유지해야 해요. 유효한 ListenerSet이 있다고 해서 그 외에는 유효하지 않은 Gateway가 수락되지는 않아요.

완전한 부착, 충돌, 상태 의미론은 업스트림 ListenerSet 문서를 참고해주세요.

더 알아보기 (Learn more)