북극 펭귄

13. [istio-internals] Pilot-agent - 사이드카 컨테이너

cla9 — Tue, 3 Mar 2026 11:51:15 +0900

1. 서론

이번 포스팅에서는 이전 포스팅 내용에 이어서 Sidecar Injector에 의해 주입된 사이드카 컨테이너에 대해서 살펴보겠습니다.

2. 사이드카 컨테이너

이전 포스팅에서 Application Pod에 주입된 init-container에 대해서 살펴봤습니다. init-container는 말 그대로 원래 기동하고자하는 컨테이너 기동 전에 사전 작업 설정을 위해서 잠시 실행되는 임시 컨테이너입니다. 따라서 iptables 등을 조작해서 Application 컨테이너가 기동할 수 있는 환경을 만든 이후 해당 컨테이너는 종료됩니다.

이번에는 본격적으로 주입된 사이드카 컨테이너의 Yaml 내용을 살펴보면서, 어떤 설정이 추가되었는지 살펴보겠습니다.

  - args:
    - proxy
    - sidecar
    - --domain
    - $(POD_NAMESPACE).svc.cluster.local
    - --proxyLogLevel=warning
    - --proxyComponentLogLevel=misc:error
    - --log_output_level=default:info
    - --concurrency
    - "2"
    env:
    - name: JWT_POLICY
      value: third-party-jwt
    - name: PILOT_CERT_PROVIDER
      value: istiod
    - name: CA_ADDR
      value: istiod.istio-system.svc:15012
    - name: POD_NAME
      valueFrom:
        fieldRef:
          fieldPath: metadata.name
    - name: POD_NAMESPACE
      valueFrom:
        fieldRef:
          fieldPath: metadata.namespace
    - name: INSTANCE_IP
      valueFrom:
        fieldRef:
          fieldPath: status.podIP
    - name: SERVICE_ACCOUNT
      valueFrom:
        fieldRef:
          fieldPath: spec.serviceAccountName
    - name: HOST_IP
      valueFrom:
        fieldRef:
          fieldPath: status.hostIP
    - name: PROXY_CONFIG
      value: |
        {}          
    - name: ISTIO_META_POD_PORTS
      value: |-
        [
        ]
    - name: ISTIO_META_APP_CONTAINERS
      value: nginx
    - name: ISTIO_META_CLUSTER_ID
      value: Kubernetes
    - name: ISTIO_META_INTERCEPTION_MODE
      value: REDIRECT
    - name: ISTIO_META_WORKLOAD_NAME
      value: nginx
    - name: ISTIO_META_OWNER
      value: kubernetes://apis/v1/namespaces/default/pods/nginx
    - name: ISTIO_META_MESH_ID
      value: cluster.local
    - name: TRUST_DOMAIN
      value: cluster.local
    image: docker.io/istio/proxyv2:1.14.2
    name: istio-proxy
    ports:
    - containerPort: 15090
      name: http-envoy-prom
      protocol: TCP
    readinessProbe:
      failureThreshold: 30
      httpGet:
        path: /healthz/ready
        port: 15021
      initialDelaySeconds: 1
      periodSeconds: 2
      timeoutSeconds: 3
    resources:
      limits:
        cpu: "2"
        memory: 1Gi
      requests:
        cpu: 10m
        memory: 40Mi
    securityContext:
      allowPrivilegeEscalation: false
      capabilities:
        drop:
        - ALL
      privileged: false
      readOnlyRootFilesystem: true
      runAsGroup: 1337
      runAsNonRoot: true
      runAsUser: 1337

위 코드는 사이드카로 추가된 istio-proxy 부분만 발췌한 코드입니다. 해당 코드에서 중요한 내용만 추려가면서 살펴보겠습니다.

    image: docker.io/istio/proxyv2:1.14.2
    name: istio-proxy

먼저 살펴볼 부분은 해당 컨테이너의 이미지입니다. 이는 이전에 init-container에서 사용했던 이미지와 동일함을 알 수 있습니다. 따라서 기동 시점에 pilot-agent 프로그램이 수행되는 것을 알 수 있습니다.

    securityContext:
      allowPrivilegeEscalation: false
      capabilities:
        drop:
        - ALL
      privileged: false
      readOnlyRootFilesystem: true
      runAsGroup: 1337
      runAsNonRoot: true
      runAsUser: 1337

두 번째로 살펴볼 것은 securityContext입니다.

init-container에는 iptables를 조작해야했기 때문에 root와 NET_ADMIN, NET_RAW와 같은 capability가 필요했는데, 사이드카 컨테이너에서는 이미 iptables 변경이 완료되었기 때문에 더 이상 root로 실행시키지 않으며, capabilities도 모두 삭제하도록 되어있음을 확인할 수 있습니다.

  - args:
    - proxy
    - sidecar
    - --domain
    - $(POD_NAMESPACE).svc.cluster.local
    - --proxyLogLevel=warning
    - --proxyComponentLogLevel=misc:error
    - --log_output_level=default:info
    - --concurrency
    - "2"

세 번째로 살펴볼 것은 argument입니다. 인자를 통해서 해당 프로그램이 proxy로 기동됨을 전달합니다. 여기서 살펴볼 점은 argument를 통해서 sidecar 인자를 넘겨줌에 따라 해당 Container가 sidecar proxy로 기동될 것임을 전달합니다.

두번째 중요한 정보는 --concurrency입니다. 이전에 envoy 아키텍처 포스팅에서 확인하였듯이. conccurency는 Worker 쓰레드의 개수를 의미합니다. 즉 해당 envoy proxy는 Master와 2개의 Worker 쓰레드가 구성되어 동작함을 유추할 수 있습니다.

3. Pilot-Agent 기동 과정

지금까지 YAML 내용을 살펴보면서 sidecar injector에 의해 주입된 사이드카 컨테이너의 주요 설정에 대해서 알아봤습니다. 이번에는 주입된 컨테이너 내부를 살펴보면서 어떻게 동작하는지를 살펴보고자 합니다.

사이드카 컨테이너 내부에는 pilot-agent 프로그램이 존재합니다. 따라서 해당 프로그램이 먼저 기동됩니다. 이때 pilot-agent 내부에는 여러가지 컴포넌트가 존재하는데, 그 중 가장 핵심은 XDS Proxy 입니다.

XDS Proxy는 Envoy Proxy와 istiod의 pilot-discovery의 통신을 중개하는 역할을 담당하는 컴포넌트로써 Envoy에서의 요청사항을 pilot-discovery에 전달하고 pilot-discovery로부터 전달되는 응답값을 Envoy에게 다시 전달하는 역할을 수행합니다. 이때 내부 Envoy와의 통신은 Unix Domain Socket으로 수행하며 pilot-discovery와는 gRPC를 통해 요청을 주고 받는 것이 특징입니다.

Local DNS Server는 istio의 ServiceEntry에서 DNS에 등록되지 않은 host명으로 입력한 경우 올바르게 Resolution되지 않습니다. 이때 내부 Local DNS Server를 둠으로써 Kubernetes 외부에 위치한 Service에 대해서도 DNS 결과를 제공하기 위해 제공되는 서버입니다. 해당 서버는 ISTIO_META_DNS_CAPTURE 환경 변수 여부에 따라 기동 여부가 결정되며, 기본적으로는 false이므로 기동되지 않습니다. 이와 관련한 자세한 내용은 아래 공식문서를 참고하시기 바랍니다.

https://istio.io/latest/docs/ops/configuration/traffic-management/dns-proxy/

DNS Proxying

How to configure DNS proxying.

istio.io

SDS Server는 istio에서 제공하는 mTLS 기능 구현을 위해 CA에게 인증서를 요청하고 제공된 인증서를 관리하기 위한 서버입니다. 해당 컴포넌트에 대해서는 추후 다른 포스팅을 통해 다루어보겠습니다.

Pilot-Agent 내부에 속한 주요 컴포넌트에 대해 간략하게 살펴봤습니다. 지금부터는 envoy와 xds proxy를 중점으로 구동 과정을 살펴보겠습니다.

3-1 Proxy 초기화

pilot-agent가 기동될 때 가장 먼저 수행하는 것은 Proxy 생성을 위한 초기화 작업입니다. 사이드카 컨테이너의 YAML을 살펴보면 위 그림과 같이 Pod의 IP와 이름 그리고 namespace가 환경변수로 주입된 것을 확인할 수 있는데, 해당 값등을 조합하여 Proxy 설정을 진행합니다.

  - args:
    - proxy
    - sidecar
    - --domain
    - $(POD_NAMESPACE).svc.cluster.local
    - --proxyLogLevel=warning
    - --proxyComponentLogLevel=misc:error
    - --log_output_level=default:info
    - --concurrency
    - "2"

Proxy 초기화 과정에서는 입력된 IP와 namespace를 지정하는 것 외에도 ID와 DNS Domain을 수행하는데, ID는 입력된 POD_NAME + "." + POD_NAMESPACE로 지정됩니다. 반면 DNS Domain의 경우 위와 같이 Argument에 --domain 인자로 값이 입력되었으면, 해당 값이 사용되고 입력되지 않았을 경우에는 POD_NAMESPACE + ".svc.cluster.loocal" 이 사용됩니다.

3-2 Proxy Config 설정

Proxy 초기화 이후 수행 작업은 Proxy Config를 설정하는 것입니다. 이때 Proxy Config를 구성하기 위해 세 군데에서 입력되는 정보들을 조합하기 위해 값을 읽어들입니다.

Pod에 입력한 annotation 정보들은 kubernetes의 downwardAPI에 의하여 Pod 내부 /etc/istio/pod/annotations 경로에 Mount 됩니다. 해당 정보는 pilot-agent가 기동하면서 참조할 수 있으며, 이를 통해 annotation 정보를 추출할 수 있습니다. 여기서 annotation 중 proxy.istio.io/config 값은 Pod의 Proxy Config를 설정할 수 있습니다. 따라서 Proxy Config를 구성하는 과정에서 해당 정보를 참고합니다.

두 번째는 Pod 내부에 /etc/istio/config/mesh에 Proxy Config 정보를 위한 파일을 mount 했다면, 해당 정보를 읽어들여서 Proxy Config를 구성합니다.

세 번째는 환경 변수로 입력한 PROXY_CONFIG 정보를 참조하는 것입니다. 해당 정보는 sidecar injector에 의해서 주입된 정보이며, Global Proxy Config 설정을 했다면, sidecar injector가 Pod의 YAML을 조작하는 과정에서 해당 정보가 주입됩니다.

위 세 정보를 추출한 이후에는 Proxy Config를 구성합니다. 이때 pilot-agent 내부에 별도 Default Config가 존재하며, Default Config 외에 입력된 세 가지 Config 정보를 차례 차례로 merge 하여 구성합니다. 이때 위 그림과 같은 순서대로 merge 작업을 수행하며, 같은 값이 존재하는 경우에는 덮어씁니다. 따라서 우선순위 기준으로 보면 Pod에 부착된 어노테이션이 가장 높습니다.

12. [istio-internals] Pilot-agent - init-container

cla9 — Tue, 3 Mar 2026 11:50:59 +0900

1. 서론

이전 포스팅에서는 istiod의 수동 방식과 pilot-discovery Sidecar Injector에 의해 자동 주입된 envoy proxy 과정에 대해서 살펴봤습니다.

Sidecar Injector에 의해 주입된 변경된 Pod를 살펴보면 istio-init이라는 init-container와 istio-proxy라는 사이드카 컨테이너 총 2개가 주입되는 것을 확인할 수 있습니다. 이번 포스팅에서는 그 중 init-container 부분에 대해서 다루어 보고자합니다.

우선 본론에 들어가기 앞서 간단히 해당 컨테이너의 역할에 대해서 살펴보면, envoy가 application과 트래픽을 주고 받고 istio control plane과 통신을 원활하게 수행하기 위한 iptables를 조작합니다.

지금부터 본격적으로 iptables 조작 과정이 어떻게 이루어지는지에 대해서 알아보겠습니다. 다만 필자가 네트워크나 서버 전문가가 아니기 때문에 틀린 부분이 있을 수 있습니다. 틀린 부분이 있다면, 꼭 알려주시기 바랍니다.

2. iptables

Kubernetes에서 네트워크 트래픽을 다루는데 있어 핵심은 iptables와 Netfilter 입니다. 이를 통해서 외부로 트래픽을 전달하기도 하고 내부 컨테이터로 트래픽을 전달합니다. istio 또한 inbound와 outbound 트래픽을 envoy로 전달하고 외부로 보내야하기 때문에 Netfilter에서 제공하는 hook을 사용하여 패킷의 흐름을 변경하며 이를 위해서 사이드카 컨테이너를 주입할 때 iptables 체인을 만들고 라우팅 규칙을 설정하는 작업을 선행합니다.

iptables와 Netfilter에 대해서는 내용이 방대하고 깊으므로 별도 학습을 권장드리며, 본 포스팅에서는 envoy의 설정과 네트워크 조작에 대해 알아보기 이전에 가볍게 iptables에서 사용되는 네트워크 체인에 대해서만 가볍게 다루어보고 넘어가겠습니다.

iptables에는 기본적으로 위와같이 5개의 체인이 등록되어있습니다. 각각의 체인은 역할이 존재하는데, 체인들의 관계와 흐름을 이해하는 것이 중요합니다. 따라서 위 그림을 기반으로 각 체인의 특징에 대해 살펴보겠습니다.

1. PREROUTING

PREROUTING은 Packet이 처음 도달하는 체인으로 패킷 내용을 조사하여 목적지가 로컬 주소인지 아닌지를 판단합니다. 이때 만약 로컬이라면, INPUT 체인으로 전달하고 다른 host로 전달되어야한다면 FORWARDING으로 전달합니다. 그리고 해당 체인을 통해서 목적지의 주소 변경(DNAT)이 가능한 것이 주요 특징 중 하나입니다.

그렇다면 DNAT는 왜 할까요?

가령 Docker를 예로 들자면, 생성한 도커 컨테이너를 외부에서 접속 가능하게 하기 위해 흔히 포트 포워딩을 수행합니다. 이때 위 그림과 같이 특정 서버 포트(8080)에 대해서 컨테이너 내부 포트와 연결시키면, 위와 같이 PREROUTING을 통해 들어온 트래픽은 DOCKER 체인으로 전달되고 그 과정에서 8080 포트로 들어온 연결에 대해서 목적지 주소를 변경하는 작업을 수행해서 이후 컨테이너에 트래픽이 전달됩니다.

2. INPUT

INPUT은 PREROUTING을 통해 전달되는 Packet이 로컬 주소의 목적지를 향할 경우에 해당 체인으로 라우팅됩니다. 만약 해당 체인을 통해 최종 목적지를 지정하면 그쪽으로 트래픽을 전달할 수 있습니다.

3. OUTPUT

OUTPUT은 외부에서 들어오는 패킷이 아니라 서버에서 생성되어 나가는 패킷이 발생될 때 트리거링되는 체인입니다.

4. FORWARDING

FORWARDING은 해당 서버로 보낸 패킷은 아니지만 외부 패킷을 외부로 전달하는 경우 설정 여부에 따라 패킷을 전달할지 여부를 결정합니다. 사례를 통해 조금 더 자세히 살펴보겠습니다.

위와 같이 2개의 서버를 연결하는 라우터로써 사용될 때 중간에 있는 서버는 외부에서 들어온 패킷을 외부로 전달하는 역할을 수행합니다. 이때 패킷을 다른 서버에 전달하기 위해서는 sysctl.conf 파일에서 net.ipv4.ip_forward 값을 1로 설정이 필요합니다. 설정이 완료되면, 해당 체인을 통해서 지정된 Gateway를 통해 목적지로 전달될 것입니다.

두 번째 사례는 위 그림과 같이 단일 서버내라도 Bridge interface로 구성되어있고 하위에 별도 Network namespace와 서로 다른 네트워크 주소로 구성된 환경에서 namespace간 통신을 수행할 때 해당 체인 설정이 필요할 수 있습니다. 가령 FORWARD 체인에 대해서 Policy가 DROP으로 되어있을 경우 출발지 IP에 대해 ACCEPT 하도록 정책을 등록할 수 있습니다.

위 상황에서 같은 서버내 통신인데도 FORWARDING 체인으로 전달되는 이유는 서로 다른 네트워크 주소를 가지고 있기 때문에 host 입장에서는 출발지와 목적지 모두가 외부 패킷이기 때문입니다.

5. POSTROUTING

POSTROUTING은 OUTPUT에서 전달된 패킷이나 FORWARDING을 통해서 전달된 패킷을 통해 네트워크 인터페이스를 통해 나갈 패킷에 대한 처리를 수행할 수 있습니다. 이때 전달된 패킷에 대하여 출발지 주소를 변경(SNAT)할 수 있습니다.

SNAT의 경우는 공인 IP와 사설 IP로 구성되었을 경우 사설 IP 대역에서 외부 인터넷 접속 시 돌아올 목적지를 공인 IP로 지정해야되기 때문에 출발지 주소를 서버의 IP로 변경해서 나갑니다. 따라서 이 경우 해당 체인을 통해 출발지 주소를 변경할 수 있습니다.

3. init conatiner

지금까지 iptables에서 사용되는 체인에 대해서 살펴봤습니다. 지금부터는 이전 포스팅에서 살펴본 istio에 의해서 주입된 사이드카 컨테이너 설정을 차근 차근 살펴보면서 어떤 것이 적용되었는지를 분석해보겠습니다.

  initContainers:
  - args:
    - istio-iptables
    - -p
    - "15001"
    - -z
    - "15006"
    - -u
    - "1337"
    - -m
    - REDIRECT
    - -i
    - '*'
    - -x
    - ""
    - -b
    - '*'
    - -d
    - 15090,15021,15020
    image: docker.io/istio/proxyv2:1.14.2
    name: istio-init
    resources:
      limits:
        cpu: "2"
        memory: 1Gi
      requests:
        cpu: 10m
        memory: 40Mi
    securityContext:
      allowPrivilegeEscalation: false
      capabilities:
        add:
        - NET_ADMIN
        - NET_RAW
        drop:
        - ALL
      privileged: false
      readOnlyRootFilesystem: false
      runAsGroup: 0
      runAsNonRoot: false
      runAsUser: 0

istio에 의해서 변경된 Pod의 yaml을 살펴보면, 위와 같이 istio-init으로 명명된 init container가 포함되었으며 이 단계에서 iptables를 조작한다는 것을 알 수 있습니다.

위 코드 내용을 분할하여 자세히 살펴보겠습니다.

    securityContext:
      allowPrivilegeEscalation: false
      capabilities:
        add:
        - NET_ADMIN
        - NET_RAW
        drop:
        - ALL
      privileged: false
      readOnlyRootFilesystem: false
      runAsGroup: 0
      runAsNonRoot: false
      runAsUser: 0

먼저 iptables를 조작하기 위해서 securityContext에서 NET_ADMIN과 NET_RAW에 대한 capabilites를 추가하고 그 외 나머지는 drop 하도록 하였습니다. 그리고 해당 container를 root 유저로 기동하는 것을 확인할 수 있습니다.

    image: docker.io/istio/proxyv2:1.14.2
    name: istio-init

두번째로 살펴볼 것은 proxyv2 이미지입니다. 해당 컨테이너 이미지명이 proxyv2라고 되어있지만 실제로는 envoy proxy를 기반으로 만들어진 이미지입니다. 해당 이미지에 대한 Dockerfile 명세는 아래 URL을 통해서 확인해볼 수 있습니다.

https://github.com/istio/istio/blob/master/pilot/docker/Dockerfile.proxyv2

GitHub - istio/istio: Connect, secure, control, and observe services.

Connect, secure, control, and observe services. Contribute to istio/istio development by creating an account on GitHub.

github.com

해당 이미지는 pilot-agent를 기동하는데, 이때 argument를 통해서 해당 프로그램이 어떤 동작을 수행하는지를 정의할 수 있습니다.

  - args:
    - istio-iptables
    - -p
    - "15001"
    - -z
    - "15006"
    - -u
    - "1337"
    - -m
    - REDIRECT
    - -i
    - '*'
    - -x
    - ""
    - -b
    - '*'
    - -d
    - 15090,15021,15020

세번째로 살펴볼 것은 argument 입니다. argument로 istio-iptables 옵션을 전달하면 내부에서 istio-iptables.sh을 수행해서 iptables를 조작하는 작업을 수행합니다. 위 코드에서 입력된 옵션에 대해서 살펴보면 다음과 같습니다.

옵션	설명
-p	Traffic을 redirect 받을 envoy의 포트
-z	Inbound TCP traffic에 대해서 redirect 포트
-u	proxy container의 UID
-m	envoy로 redirect되는 Inbound 연결에 사용되는 모드로써 REDIRECT 혹은 TPROXY 중 선택 가능
-i	envoy로 redirect 시킬 CIDR IP Range로 복수개 입력 시 "," 로 구분하여 list 형태로 입력한다. 해당 값이 *일 경우 모두 outbound로 redirect 하며, 값이 없을 경우에는 모든 outbound 트래픽을 disable 한다.
-x	envoy로 redirect 제외 시킬 CIDR IP Range로 복수개 입력 시 "," 로 구분하여 list 형태로 입력함
-b	envoy로 redirect 시킬 Inbound Port를 명시하는 것으로써 복수개 입력 시 "," 로 구분하여 list 형태로 입력함
-d	envoy로 redirect 제외시킬 Inbound Port를 명시하는 것으로써 복수개 입력 시 "," 로 구분하여 list 형태로 입력함

위 예제에서 작성한 옵션을 기반으로 설명하면, 위 args는 다음과 같은 명령을 요구하였음을 알 수 있습니다.

1) Inboud의 경우 15006 그 외는 15001 포트로 전달한다.
2) 해당 proxy를 사용하는 컨테이너의 UID는 1337이다
3) 모든 IP로부터 전달되는 트래픽은 모두 envoy로 redirect한다.
4) envoy redirect 하는데 있어 제외대상 IP는 없다.
5) 15090, 15021, 15020 포트를 제외한 나머지 포트를 통해 들어오는 트래픽은 envoy로 redirect한다.

위 내용에서 15090, 15021, 15020 포트 등은 envoy의 헬스체크와 prometheus 연결 등에 사용하기 위한 포트로 사용되기 때문에 제외하였습니다. 그 밖에도 istio에서 사용하는 여러 포트가 있는데, 해당 내용은 공식문서를 참고하시기 바랍니다.

참고로 위 istio-iptables의 실제 동작 과정이나 위에 설명한 옵션 외에 다른 옵션이 무엇이 있는지 궁금하신 분은 istio github을 참고하시기 바랍니다.

4. iptables 룰 변경 내역 확인

이전 내용들을 토대로 init container 안에서 iptables를 조작함을 확인했습니다. 이번에는 init container를 통해서 변경된 내용을 확인하기 위해 istio-init container의 로그를 확인해보겠습니다.

[cla9@DESKTOP-FBK64T0]$ kubectl logs -c istio-init nginx
2022-08-26T00:34:38.813305Z     info    Istio iptables environment:
ENVOY_PORT=
INBOUND_CAPTURE_PORT=
ISTIO_INBOUND_INTERCEPTION_MODE=
ISTIO_INBOUND_TPROXY_ROUTE_TABLE=
ISTIO_INBOUND_PORTS=
ISTIO_OUTBOUND_PORTS=
ISTIO_LOCAL_EXCLUDE_PORTS=
ISTIO_EXCLUDE_INTERFACES=
ISTIO_SERVICE_CIDR=
ISTIO_SERVICE_EXCLUDE_CIDR=
ISTIO_META_DNS_CAPTURE=
INVALID_DROP=

2022-08-26T00:34:38.813346Z     info    Istio iptables variables:
PROXY_PORT=15001
PROXY_INBOUND_CAPTURE_PORT=15006
PROXY_TUNNEL_PORT=15008
PROXY_UID=1337
PROXY_GID=1337
INBOUND_INTERCEPTION_MODE=REDIRECT
INBOUND_TPROXY_MARK=1337
INBOUND_TPROXY_ROUTE_TABLE=133
INBOUND_PORTS_INCLUDE=*
INBOUND_PORTS_EXCLUDE=15090,15021,15020
OUTBOUND_OWNER_GROUPS_INCLUDE=*
OUTBOUND_OWNER_GROUPS_EXCLUDE=
OUTBOUND_IP_RANGES_INCLUDE=*
OUTBOUND_IP_RANGES_EXCLUDE=
OUTBOUND_PORTS_INCLUDE=
OUTBOUND_PORTS_EXCLUDE=
KUBE_VIRT_INTERFACES=
ENABLE_INBOUND_IPV6=false
DNS_CAPTURE=false
DROP_INVALID=false
CAPTURE_ALL_DNS=false
DNS_SERVERS=[],[]
OUTPUT_PATH=
NETWORK_NAMESPACE=
CNI_MODE=false
EXCLUDE_INTERFACES=

2022-08-26T00:34:38.813822Z     info    Writing following contents to rules file: /tmp/iptables-rules-1661474078813392800.txt3716182416
* nat
-N ISTIO_INBOUND
-N ISTIO_REDIRECT
-N ISTIO_IN_REDIRECT
-N ISTIO_OUTPUT
-A ISTIO_INBOUND -p tcp --dport 15008 -j RETURN
-A ISTIO_REDIRECT -p tcp -j REDIRECT --to-ports 15001
-A ISTIO_IN_REDIRECT -p tcp -j REDIRECT --to-ports 15006
-A PREROUTING -p tcp -j ISTIO_INBOUND
-A ISTIO_INBOUND -p tcp --dport 15090 -j RETURN
-A ISTIO_INBOUND -p tcp --dport 15021 -j RETURN
-A ISTIO_INBOUND -p tcp --dport 15020 -j RETURN
-A ISTIO_INBOUND -p tcp -j ISTIO_IN_REDIRECT
-A OUTPUT -p tcp -j ISTIO_OUTPUT
-A ISTIO_OUTPUT -o lo -s 127.0.0.6/32 -j RETURN
-A ISTIO_OUTPUT -o lo ! -d 127.0.0.1/32 -m owner --uid-owner 1337 -j ISTIO_IN_REDIRECT
-A ISTIO_OUTPUT -o lo -m owner ! --uid-owner 1337 -j RETURN
-A ISTIO_OUTPUT -m owner --uid-owner 1337 -j RETURN
-A ISTIO_OUTPUT -o lo ! -d 127.0.0.1/32 -m owner --gid-owner 1337 -j ISTIO_IN_REDIRECT
-A ISTIO_OUTPUT -o lo -m owner ! --gid-owner 1337 -j RETURN
-A ISTIO_OUTPUT -m owner --gid-owner 1337 -j RETURN
-A ISTIO_OUTPUT -d 127.0.0.1/32 -j RETURN
-A ISTIO_OUTPUT -j ISTIO_REDIRECT
COMMIT

위 코드는 istio-init container의 로그 일부를 발췌하였습니다. 많은 내용이 있지만 이 중에서 유의미한 내용만 추려서 살펴보겠습니다.

PROXY_PORT=15001
PROXY_INBOUND_CAPTURE_PORT=15006
PROXY_UID=1337
PROXY_GID=1337
INBOUND_INTERCEPTION_MODE=REDIRECT
INBOUND_PORTS_INCLUDE=*
INBOUND_PORTS_EXCLUDE=15090,15021,15020
OUTBOUND_OWNER_GROUPS_INCLUDE=*
OUTBOUND_OWNER_GROUPS_EXCLUDE=
OUTBOUND_IP_RANGES_INCLUDE=*
OUTBOUND_IP_RANGES_EXCLUDE=

위 내용들을 살펴보면, 이전에 arg 인자로 전달했던 옵션들이 정상적으로 매칭되었음을 확인할 수 있습니다. 먼저 inbound 트래픽은 15006 포트로 전달되도록 되어있고 outbound의 경우는 15001로 지정되었음을 확인할 수 있습니다.

PROXY의 UID와 GID는 1337로 이 또한 인자로 지정한 값입니다. PORT 전달 대상은 15090, 15021, 15020을 제외한 나머지 PORT를 모두 INBOUND로 전달하도록 되어있습니다.

* nat
-N ISTIO_INBOUND
-N ISTIO_REDIRECT
-N ISTIO_IN_REDIRECT
-N ISTIO_OUTPUT
-A ISTIO_INBOUND -p tcp --dport 15008 -j RETURN
-A ISTIO_REDIRECT -p tcp -j REDIRECT --to-ports 15001
-A ISTIO_IN_REDIRECT -p tcp -j REDIRECT --to-ports 15006
-A PREROUTING -p tcp -j ISTIO_INBOUND
-A ISTIO_INBOUND -p tcp --dport 15090 -j RETURN
-A ISTIO_INBOUND -p tcp --dport 15021 -j RETURN
-A ISTIO_INBOUND -p tcp --dport 15020 -j RETURN
-A ISTIO_INBOUND -p tcp -j ISTIO_IN_REDIRECT
-A OUTPUT -p tcp -j ISTIO_OUTPUT
-A ISTIO_OUTPUT -o lo -s 127.0.0.6/32 -j RETURN
-A ISTIO_OUTPUT -o lo ! -d 127.0.0.1/32 -m owner --uid-owner 1337 -j ISTIO_IN_REDIRECT
-A ISTIO_OUTPUT -o lo -m owner ! --uid-owner 1337 -j RETURN
-A ISTIO_OUTPUT -m owner --uid-owner 1337 -j RETURN
-A ISTIO_OUTPUT -o lo ! -d 127.0.0.1/32 -m owner --gid-owner 1337 -j ISTIO_IN_REDIRECT
-A ISTIO_OUTPUT -o lo -m owner ! --gid-owner 1337 -j RETURN
-A ISTIO_OUTPUT -m owner --gid-owner 1337 -j RETURN
-A ISTIO_OUTPUT -d 127.0.0.1/32 -j RETURN
-A ISTIO_OUTPUT -j ISTIO_REDIRECT

Argument로 전달된 값을 기반으로 생성된 NAT 체인 룰을 보면 위와 같이 지정된 것을 로그를 통해 확인할 수 있습니다. 그렇다면 구체적으로 어떤 값이 어떻게 변경되었을까요? 이에 대해서 조금 자세히 살펴보겠습니다.

로그 내용을 살펴보면 먼저 4개의 체인을 생성한 것을 확인할 수 있습니다. 여기서 각각의 체인은 다음과 같은 역할을 수행합니다.

ISTIO_INBOUND : PREROUTING으로 전달된 트래픽 중 tcp 트래픽 전달받음
ISTIO_REDIRECT : Outbound Traffic을 envoy의 Outbound Handler인 15001 포트로 전달함
ISTIO_IN_REDIRECT : Inbound Traffic을 envoy의 Inbound Handler인 15006 포트로 전달함
ISTIO_OUTPUT : envoy traffic을 결정하는 가장 핵심적인 체인으로 traffic 전달과 관련한 규칙이 정의되어있음.

체인을 생성하고 난 이후에는 체인 호출 및 트래픽 라우팅과 관련된 규칙을 설정하고 있습니다. 위 설정 중에서 가장 중요한 것은 ISTIO_OUTPUT이며, 해당 체인에 적용된 규칙에 의하여 그 다음에 전달할 체인이 결정됩니다.

-A ISTIO_OUTPUT -o lo -s 127.0.0.6/32 -j RETURN
-A ISTIO_OUTPUT -o lo ! -d 127.0.0.1/32 -m owner --uid-owner 1337 -j ISTIO_IN_REDIRECT
-A ISTIO_OUTPUT -o lo -m owner ! --uid-owner 1337 -j RETURN
-A ISTIO_OUTPUT -m owner --uid-owner 1337 -j RETURN
-A ISTIO_OUTPUT -o lo ! -d 127.0.0.1/32 -m owner --gid-owner 1337 -j ISTIO_IN_REDIRECT
-A ISTIO_OUTPUT -o lo -m owner ! --gid-owner 1337 -j RETURN
-A ISTIO_OUTPUT -m owner --gid-owner 1337 -j RETURN
-A ISTIO_OUTPUT -d 127.0.0.1/32 -j RETURN
-A ISTIO_OUTPUT -j ISTIO_REDIRECT

참고로 ISTIO_OUTPUT에 적용된 규칙은 위와 같으며 해당 규칙을 조금 더 풀어서 설명하면 다음과 같습니다.

처리 결과	Out Interface	조건
RETURN	loopback 인터페이스	출발지가 127.0.0.6 일 경우
ISTIO_IN_REDIRECT	loopback 인터페이스	목적지가 localhost(127.0.0.1)가 아니면서 UID가 1337일 경우
RETURN	loopback 인터페이스	UID가 1337가 아닐 경우
RETURN	*	UID가 1337일 경우
ISTIO_IN_REDIRECT	loopback 인터페이스	목적지가 localhost(127.0.0.1)가 아니면서 GID가 1337일 경우
RETURN	loopback 인터페이스	GID가 1337가 아닐 경우
RETURN	*	GID가 1337일 경우
RETURN	*	출발지가 localhost(127.0.0.1)일 경우
ISTIO_REDIRECT	*	*

위 규칙에 따라 외부에서 접속하는 요청을 envoy에 전달하고 다시 envoy inbound handler에서 나온 트래픽을 application에 전달합니다. 그리고 반대로 application에서 나오는 트래픽을 외부로 전달하는 역할을 수행합니다.

체인의 내용만 봐서는 트래픽이 어떤 흐름으로 어떻게 도달되는지 감이 잡히지는 않습니다. 다만 이번 포스팅은 설정과 관련된 내용만을 다루기 때문에 트래픽 전달에 대해서는 추후에 다루어보도록 하고 여기서는 위 설정 관련해서 알아야할 주요 포인트 3가지 (loopback 인터페이스, 127.0.0.6 IP 존재 이유, 1337 UID/GID)에 대해서 알아보겠습니다.

4-1 loopback 인터페이스

일반적으로 쿠버네티스를 통해 1개의 컨테이너가 포함된 POD를 배포하면 왼쪽과 같이 배포된다고 생각하지만, 실제로는 오른쪽과 같이 사용자에게는 보이지 않는 Pause 컨테이너가 포함된 형태로 배포됩니다.

여기서 Pause 컨테이너는 네트워크, IPC namespace를 생성하고 다른 컨테이너와 공유하는 역할을 수행하며, init process의 역할을 수행해서 좀비 프로세스를 방지하는 역할을 수행합니다.

그 결과 POD 내부에 여러개의 컨테이너가 생성되었을 때 내부적으로는 loopback 인터페이스를 통해 컨테이너간에 localhost로 통신이 가능합니다. 따라서 위 ISTIO_OUTPUT 규칙에서 Out Interface가 loopback인 것은 envoy proxy와 Application 통신을 위해 localhost를 사용함을 알 수 있습니다.

4-2 127.0.0.6

해당 IP의 의미에 대해 알기 전에 envoy의 cluster 타입 중 하나인 ORIGINAL_DST와 passthroughcluster에 대한 내용 이해가 필요합니다. 따라서 해당 개념 사전학습 이후에 살펴보겠습니다.

4-2-1 ORIGINAL_DST

ORIGINAL_DST는 envoy의 cluster 타입 중 하나로써, 트래픽이 들어왔을 때 목적지 주소가 envoy에 등록된 Cluster와 Endpoint 중 일치하는 것이 없을 경우에 해당 목적지 주소를 다시 매핑해서 Forwarding할 수 있도록 지원하는 기능입니다.

이를 위해서 envoy 공식 문서에 따르면 2가지 컴포넌트가 상호 작용하는 것을 알 수 있습니다.

1. Original Destination Listener Filter
2. Original Destination Cluster

Original Destination Listener Filter는 envoy 아키텍처 포스팅에서 다룬 내용으로 Listener Filters에 해당합니다. 해당 Filter는 SO_ORIGINAL_DST 소켓 정보를 읽어서 iptables에 의해 목적지 주소가 바뀌기 이전 사용자의 원래 목적지 정보를 읽는 역할을 수행합니다.

iptables를 지나게되면 envoy proxy로 트래픽이 전달되어야 되기 때문에 목적지 주소가 바뀌게 되는데, Original Destination Filter를 통과하면서 redirect된 소켓의 주소 정보를 해당 Filter에서 읽습니다.

이후 해당 정보는 Listener를 지나 Original Destination Cluster에 전해지는데, 이때 해당 트래픽의 목적지 주소를 iptables를 지나기 이전 목적지 주소로 재설정하는데 사용됩니다. 이를 통해 upstream address에 대해서 동적으로 런타임에 주소 변경이 가능한 것이 특징입니다. 그외 Original Destination Cluster에 대한 부가적인 설명은 envoy 공식 문서를 통해 참고 바랍니다.

4-2-2 PassthroughCluster

istio의 Passthrough는 서비스 메시 바깥으로 나가는 egress 트래픽에 대해서 ALLOW_ANY(default)로 지정된 경우 Service Entry로 등록하지 않은 트래픽을 envoy proxy를 통해 외부로 전달하기 위해 사용됩니다. 이를 위해서 PassthroughCluster라는 Virtual Cluster를 envoy 내부에 생성하고 envoy가 보유한 cluster 혹은 endpoint와 매치되지 않는 목적지 트래픽에 대해 해당 Cluster로 트래픽을 전달하고 후속 작업을 처리합니다. 이때 해당 PassthroughCluster의 타입은 이전에 설명한 ORIGINAL_DST로 지정되어 있어 목적지의 IP를 유지한채로 외부에 전달할 수 있습니다.

지금까지 ORIGINAL_DST와 PassthroughCluster에 대해서 설명했습니다. 그렇다면, 이제 127.0.0.6 IP가 왜 등장했는지에 대해서 살펴보겠습니다.

14443 github 이슈를 살펴보면, 이전에는 Service로 등록하지 않은 Pod의 port를 외부에서 호출했을 경우 iptables과 envoy간에 무한 루프로 인하여 트래픽이 정상적으로 전달되지 못하고 계속 반복되는 현상이 있었습니다.

두 번째 문제로는 Pod 내부 호출을 위해서 Wildcard bind 혹은 localhost를 입력하거나 Kubernetes의 downward API를 사용하여 Pod IP만을 지정하게되면, Port가 명시되어있지 않기 때문에 cluster에서 매칭되는 결과를 찾을 수가 없습니다. 따라서 이 경우에는 InboundPassthroughCluster의 경로를 따르게 되는데, 이러한 이유로 Istio가 적용된 클러스터와 그렇지 않은 클러스터에서 Pod간 통신 할 때 제약사항이 존재하게 되었습니다. 여기서 제약사항에 대한 자세한 내용은 Inbound Forwarding 문서를 참고하시기 바랍니다.

따라서, 위 두 가지 문제를 해결하기 위해서 다음과 같은 결정을 하게 됩니다.

출처 : Inbound Forwarding - Google Docs

내용을 살펴보면 Inbound Cluster 타입은 ORIGINAL_DST로 변경했으며, UpstreamBindConfig를 통해 upstream 값을 127.0.0.6으로 지정하여, localhost에 위치한 애플리케이션으로 트래픽을 전달할 수 있도록 하였습니다. 이를 통해 iptables과 envoy간의 무한 루프를 탈피하고자 했습니다.

[cla9@DESKTOP-FBK64T0]$ ip route show table local | grep 127.0.0.0/8
local 127.0.0.0/8 dev lo proto kernel scope host src 127.0.0.1

여기서 127.0.0.6은 127.0.0.0/8 즉 로컬호스트 루프백 주소에 사용하기 위한 수많은 주소 중 하나이며, 컨트리뷰터가 밝힌 수 많은 주소 중 127.0.0.6이 채택된 이유는 envoy의 Inbound 트래픽을 전달받는 포트가 15006 이기 때문입니다.

정리하자면 127.0.0.6는 envoy proxy에 트래픽이 진입한 이후에 바인딩되는 주소로써, envoy 밖으로 나간 이후 Outbound Handler를 우회하여 Pod의 Application으로 전달될 수 있도록 하는 역할을 수행합니다. 이러한 과정이 없다면, envoy에서 upstream으로 전달을 해야하는데, iptables를 지날 때 다시 envoy로 전달될 수 있기 때문에 해당 magic 주소를 임의로 추가하여 iptables에서 envoy가 아닌 application으로 트래픽을 전달하는데 목적이 있습니다. 해당 주소는 istio 코드에 IboundPassthroughClusterIpv4로 하드코딩되어있는 값이며, 자세한 내용은 github 이슈 내용을 참고 바랍니다.

4-3 1337 UID, GID

iptables에서 UID 혹은 GID가 1337로 구분되어 있는 이유는 envoy proxy와 application 트래픽을 구분하기 위한 용도입니다.

5. 마무리

이번 포스팅에서는 사이드카 컨테이너 주입 설정에서 init-container에 주입된 설정에 대해서 살펴봤습니다. init-container에서는 inbound 트래픽을 envoy proxy에게 전달하고 이를 다시 application에게 전달하기 위한 설정과 outbound 트래픽 흐름을 조작하기 위한 iptables 설정에 대해서 살펴봤습니다.

실제 트래픽이 들어왔을 때 어떤 체인을 통해 어떻게 전달되는지에 대해서는 살펴보지 않았기 때문에 해당 iptables 설정이 어떻게 쓰이는지에 대해서는 아직 잘 모를 수 있습니다. 이는 차후에 몇 가지 사례를 통해서 어떤 체인을 통해 전달되는지 살펴보겠습니다.

다음 포스팅에서는 사이드카 컨테이너인 envoy proxy 설정과 내부 구조에 대해서 살펴보겠습니다.

11. [istio-internals] Pilot-discovery 사이드카 컨테이너 주입

cla9 — Tue, 3 Mar 2026 11:50:44 +0900

1. 서론

지금까지 pilot-discovery에 대해서 학습하면서, k8s의 리소스 변화를 감지하고 이를 pilot-agent에게 전달하는 과정에 대해서 살펴봤습니다. 이번에는 애플리케이션 서비스에 pilot-agent를 배포하는 과정을 살펴보며, 이때 pilot-discovery는 어떤 역할을 수행하는지 살펴보겠습니다.

2. pilot-agent 배포

istio를 사용하지 않는 상황에서 단일 서비스에 envoy proxy를 사용한다면, envoy proxy와 service 그리고 proxy와 service 연결을 위한 설정 파일을 한데 묶어 배포하면 되었습니다. 하지만 이러한 방식은 사용자 입장에서 CI/CD 단계에서 service 관리 뿐만 아니라 envoy proxy 설정을 관리해야하는 불편함이 존재했습니다.

더욱이 istio와 같은 control plane이 추가되면, 이제는 control plane과 연결을 위한 속성까지 추가해야하므로 service 관리자의 불편은 더욱 가중됩니다. 만약 배포되는 istio의 설정 정보가 바뀌기라도 한다면, service 관리자는 전체 service에 속한 config 정보를 바꿔야할 지도 모릅니다.

istio에서는 이러한 문제를 해결하고자 사용자는 CI/CD를 위해서 개별 Service 설정에만 집중하도록 하고 pilot-agent 추가와 설정 정보 변경은 istio가 대신 해주기 위한 2가지 방법을 제공합니다.

첫 번째 방법은 수동 방식으로 사용자가 작성한 yaml 파일을 읽어들여 istio 설정이 적용된 형태로 yaml 형태를 변경해주는 스크립트를 제공해주는 방식입니다. 두 번째 방식은 자동으로 Pod 생성 시점에 istio 설정이 적용된 형태로 배포하는 것입니다. 지금부터 이 두 가지 방법에 대해서 살펴보겠습니다.

2-1 수동 배포(istioctl CLI)

첫번째 방법은 istioctl을 통해서 기존에 생성된 pod.yaml을 조작하는 방법입니다.

nginx.yaml

apiVersion: v1
kind: Pod
metadata:
  creationTimestamp: null
  labels:
    run: nginx
  name: nginx
spec:
  containers:
  - image: nginx
    name: nginx
    resources: {}
  dnsPolicy: ClusterFirst
  restartPolicy: Always
status: {}

가령 위와 같은 Pod를 만들기 위한 yaml 파일을 만들었다고 가정해봅시다. 해당 Pod를 배포할 때 envoy proxy를 사이드카로 배포하기 위해서는 istioctl을 통해 yaml 파일을 조작할 수 있습니다.

istioctl kube-inject -f nginx.yaml

istioctl에서 제공하는 kube-inject 명령어를 활용하면, 기존에 생성한 pod의 yaml 파일을 읽어서 envoy proxy를 주입한 yaml 파일을 제공합니다. 제공된 결과를 살펴보면 다음과 같습니다.

apiVersion: v1
kind: Pod
metadata:
  annotations:
    kubectl.kubernetes.io/default-container: nginx
    kubectl.kubernetes.io/default-logs-container: nginx
    prometheus.io/path: /stats/prometheus
    prometheus.io/port: "15020"
    prometheus.io/scrape: "true"
    sidecar.istio.io/status: '{"initContainers":["istio-init"],"containers":["istio-proxy"],"volumes":["workload-socket","workload-certs","istio-envoy","istio-data","istio-podinfo","istio-token","istiod-ca-cert"],"imagePullSecrets":null,"revision":"default"}'
  creationTimestamp: null
  labels:
    run: nginx
    security.istio.io/tlsMode: istio
    service.istio.io/canonical-name: nginx
    service.istio.io/canonical-revision: latest
  name: nginx
spec:
  containers:
  - image: nginx
    name: nginx
    resources: {}
  - args:
    - proxy
    - sidecar
    - --domain
    - $(POD_NAMESPACE).svc.cluster.local
    - --proxyLogLevel=warning
    - --proxyComponentLogLevel=misc:error
    - --log_output_level=default:info
    - --concurrency
    - "2"
    env:
    - name: JWT_POLICY
      value: third-party-jwt
    - name: PILOT_CERT_PROVIDER
      value: istiod
    - name: CA_ADDR
      value: istiod.istio-system.svc:15012
    - name: POD_NAME
      valueFrom:
        fieldRef:
          fieldPath: metadata.name
    - name: POD_NAMESPACE
      valueFrom:
        fieldRef:
          fieldPath: metadata.namespace
    - name: INSTANCE_IP
      valueFrom:
        fieldRef:
          fieldPath: status.podIP
    - name: SERVICE_ACCOUNT
      valueFrom:
        fieldRef:
          fieldPath: spec.serviceAccountName
    - name: HOST_IP
      valueFrom:
        fieldRef:
          fieldPath: status.hostIP
    - name: PROXY_CONFIG
      value: |
        {"envoyAccessLogService":{"address":"skywalking-oap.skywalking:11800"}}
    - name: ISTIO_META_POD_PORTS
      value: |-
        [
        ]
    - name: ISTIO_META_APP_CONTAINERS
      value: nginx
    - name: ISTIO_META_CLUSTER_ID
      value: Kubernetes
    - name: ISTIO_META_INTERCEPTION_MODE
      value: REDIRECT
    - name: ISTIO_META_WORKLOAD_NAME
      value: nginx
    - name: ISTIO_META_OWNER
      value: kubernetes://apis/v1/namespaces/default/pods/nginx
    - name: ISTIO_META_MESH_ID
      value: cluster.local
    - name: TRUST_DOMAIN
      value: cluster.local
    image: docker.io/istio/proxyv2:1.14.2
    name: istio-proxy
    ports:
    - containerPort: 15090
      name: http-envoy-prom
      protocol: TCP
    readinessProbe:
      failureThreshold: 30
      httpGet:
        path: /healthz/ready
        port: 15021
      initialDelaySeconds: 1
      periodSeconds: 2
      timeoutSeconds: 3
    resources:
      limits:
        cpu: "2"
        memory: 1Gi
      requests:
        cpu: 10m
        memory: 40Mi
    securityContext:
      allowPrivilegeEscalation: false
      capabilities:
        drop:
        - ALL
      privileged: false
      readOnlyRootFilesystem: true
      runAsGroup: 1337
      runAsNonRoot: true
      runAsUser: 1337
    volumeMounts:
    - mountPath: /var/run/secrets/workload-spiffe-uds
      name: workload-socket
    - mountPath: /var/run/secrets/workload-spiffe-credentials
      name: workload-certs
    - mountPath: /var/run/secrets/istio
      name: istiod-ca-cert
    - mountPath: /var/lib/istio/data
      name: istio-data
    - mountPath: /etc/istio/proxy
      name: istio-envoy
    - mountPath: /var/run/secrets/tokens
      name: istio-token
    - mountPath: /etc/istio/pod
      name: istio-podinfo
  dnsPolicy: ClusterFirst
  initContainers:
  - args:
    - istio-iptables
    - -p
    - "15001"
    - -z
    - "15006"
    - -u
    - "1337"
    - -m
    - REDIRECT
    - -i
    - '*'
    - -x
    - ""
    - -b
    - '*'
    - -d
    - 15090,15021,15020
    image: docker.io/istio/proxyv2:1.14.2
    name: istio-init
    resources:
      limits:
        cpu: "2"
        memory: 1Gi
      requests:
        cpu: 10m
        memory: 40Mi
    securityContext:
      allowPrivilegeEscalation: false
      capabilities:
        add:
        - NET_ADMIN
        - NET_RAW
        drop:
        - ALL
      privileged: false
      readOnlyRootFilesystem: false
      runAsGroup: 0
      runAsNonRoot: false
      runAsUser: 0
  restartPolicy: Always
  volumes:
  - name: workload-socket
  - name: workload-certs
  - emptyDir:
      medium: Memory
    name: istio-envoy
  - emptyDir: {}
    name: istio-data
  - downwardAPI:
      items:
      - fieldRef:
          fieldPath: metadata.labels
        path: labels
      - fieldRef:
          fieldPath: metadata.annotations
        path: annotations
    name: istio-podinfo
  - name: istio-token
    projected:
      sources:
      - serviceAccountToken:
          audience: istio-ca
          expirationSeconds: 43200
          path: istio-token
  - configMap:
      name: istio-ca-root-cert
    name: istiod-ca-cert
status: {}
---

위 출력 결과물을 보면, 이전에 작성한 Pod.yaml 과 비교해서 꽤나 복잡해진 것을 확인할 수 있습니다. 이는 istiod와 통신을 위한 iptables 변경과 pilot-agent 주입을 위한 기본 설정이 포함되었기 때문입니다. 만약 사용자가 직접 이를 작성해야한다면 꽤나 불편했을텐데, istioctl을 통해서 위와같이 변경된 yaml 파일을 얻을 수 있습니다.

변경된 yaml 파일을 토대로 kubernetes에 배포하면 istio control plane과 통신할 수 있는 envoy proxy가 내장된 Pod를 사용할 수 있습니다.

2-2 자동 배포

이번에는 자동 배포에 대해서 알아보겠습니다. 자동 배포에는 두 가지 방법이 있습니다. 첫번째 방법은 Pod.yaml에 istio에서 요구하는 label을 추가하는 것입니다.

apiVersion: v1
kind: Pod
metadata:
  creationTimestamp: null
  labels:
    run: nginx
    sidecar.istio.io/inject: "true"
  name: nginx
spec:
  containers:
  - image: nginx
    name: nginx
    resources: {}
  dnsPolicy: ClusterFirst
  restartPolicy: Always
status: {}

이전에 살펴본 nginx pod yaml 파일에 sidecar.istio.io/inject: "true" label을 추가하면, Pod 생성 시점에 envoy proxy가 내장된 형태로 Pod yaml이 변경되고 배포가 이루어집니다. 참고로 해당 annotation의 값은 true 이외에도 y, yes, on 중 하나가 입력되면 사이드카 배포가 이루어집니다.

두번째 방법은 배포하려는 namespace에 label을 추가하는 것입니다.

[cla9@DESKTOP-FBK64T0]$ kubectl label ns default istio-injection=enabled
[cla9@DESKTOP-FBK64T0]$ kubectl get ns default -L istio-injection
NAME      STATUS   AGE    ISTIO-INJECTION
default   Active   334d   enabled

위와 같이 Pod를 배포하려는 namespace에 istio-injection=enabled label을 추가하면, 이후 해당 namespace에 배포되는 Pod에는 모두 envoy proxy가 내장된 형태로 배포가 이루어집니다.

지금까지 envoy proxy를 배포하기 위한 수동 배포와 자동 배포에 대해서 살펴봤습니다. 여기서 자동 배포의 경우 Pod 혹은 namespace에 label을 추가하는 것만으로 Pod 생성시에 자동으로 pilot-agent가 배포되는 것을 확인했는데요. 해당 작업은 어떻게 이루어지는 것일까요?

3. Mutation Webhook

사이드카 컨테이너의 자동 주입과정에 대해서 이해하려면, 먼저 kubernetes의 API Server를 활용한 배포 과정에서 어떠한 일이 일어나는지에 대해서 알아야합니다. 따라서 istio의 자동 배포 프로세스 과정을 살펴보기 전에 kubernetes의 Resource 생성 과정에 대해서 살펴보겠습니다.

사용자가 Kubectl을 통해서 Pod를 생성하였을 때, 우리는 일반적으로 위와같이 Kubectl 명령어를 통해서 Kube ApiServer에 전달하면, Pod가 생성된다고 생각합니다.

이때 내부 과정을 조금 더 자세히 살펴보면, 실제로는 위 그림과 같은 단계를 거쳐 Pod가 생성됩니다.

1. kubectl로 명령어를 Kube ApiServer로 전달할 때 명령어를 실행하는 컴퓨터에 존재하는 config파일 정보를 같이 전달합니다. 해당 config 파일에는 인증서 정보와 사용자 정보가 같이 포함되어있습니다.

2. Kube ApiServer는 제일 첫번째로 인증(Authentication) 과정을 수행합니다. 해당 과정은 사용자가 전달한 인증서 정보를 토대로 해당 서버에 접속 가능한 요청인지를 분석하고 승인하는 과정입니다. 마치 ID/Password를 입력했을 때, 유효한 계정인지를 검증하는 것과 같습니다.

3. 두번째로는 인가(Authorization) 과정을 수행합니다. 해당 과정은 접속이 완료된 이후에 해당 사용자가 요청한 작업에 대해서 수행 권한이 있는지를 분석하고 승인하는 과정입니다. 만약 Pod 생성을 요청했는데, 해당 권한이 존재하지 않는다면 이 단계에서 실패합니다.

4. 마지막 단계에서는 Admission Controllers 체인을 거치면서 사용자가 전달한 yaml 파일내에서 validation을 진행하거나 부가적인 내용을 추가하거나 변경하는 등의 기능을 제공합니다.

5. 모든 단계가 완료되면 Pod가 생성됩니다.

여기서 주목할 부분은 Admission Controllers입니다. Admission Controller는 이전에 설명했듯이 인증과 인가외에 검증(Validation)이나 내용을 변경(Mutation)하기 위해 사용됩니다. 또한 Admission Controller는 하나만 존재하는 것이 아니라
여러 Admission Controller가 Chain 형태로 엮여있고 해당 Chain을 순회하면서 validation 혹은 mutation을 진행합니다.

이쯤되면 istio가 어떻게 자동으로 Pod에 사이드카 컨테이너를 주입시킬 수 있는지 눈치를 챌 수 있는데요. Admission controller 중 하나인 MutatingAdmission Webhook을 활용하여 사용자의 요청을 변경시킵니다.

[cla9@DESKTOP-FBK64T0]$ kubectl get mutatingwebhookconfigurations
NAME                         WEBHOOKS   AGE
istio-revision-tag-default   4          2d
istio-sidecar-injector       4          26d

이를 위해서 kubernetes 상에 위와 같이 찾아보면, istio에서 사이드카를 주입하기 위한 MutatingWebhookConfiguration이 존재하는 것을 확인할 수 있습니다.

apiVersion: admissionregistration.k8s.io/v1
kind: MutatingWebhookConfiguration
metadata:
  labels:
    app: sidecar-injector
    install.operator.istio.io/owning-resource: unknown
    install.operator.istio.io/owning-resource-namespace: istio-system
    istio.io/rev: default
    operator.istio.io/component: Pilot
    operator.istio.io/managed: Reconcile
    operator.istio.io/version: 1.12.2
    release: istio
  name: istio-sidecar-injector
webhooks:
- admissionReviewVersions:
  - v1beta1
  - v1
  clientConfig:
    caBundle: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUMvRENDQWVTZ0F3SUJBZ0lRZWhpd2hmTTFLaDNTUGUvVC9qZ29tVEFOQmdrcWhraUc5dzBCQVFzRkFEQVkKTVJZd0ZBWURWUVFLRXcxamJIVnpkR1Z5TG14dlkyRnNNQjRYRFRJeU1Ea3hPREF6TURreE5sb1hEVE15TURreApOVEF6TURreE5sb3dHREVXTUJRR0ExVUVDaE1OWTJ4MWMzUmxjaTVzYjJOaGJEQ0NBU0l3RFFZSktvWklodmNOCkFRRUJCUUFEZ2dFUEFEQ0NBUW9DZ2dFQkFNaXliT3A5SVhpZEpGbU5yUGlVbFVMeVN0RVoyU1BZV3ZVdWlNUWwKRFo2NG44cEI2TmVIL2ZGMFB0eXJneTlxemhtNkZSOCtBTkpFTXBWSDlmTWlHcHpwMVNQeVQ1RXVyaHYwdGVpWQp3ZzRKa2RINEQ2bm03ZUJCTkxkdkszMzFqR0o1RU5WZjlOTVIxR05wdUZZMXgyT045NExkUGxjWHhMOHlFd2NHClVOY2k3aFlyd1JuSHl0VTlFSjVNSGZCKzIydW5KR3ZuVzI1L2RNTllBN0ZMVkd2VHdST0d1RkZzR29UejRQNkMKYUI5bGd1MFZwbkVDb3B1bmJZLys2QW5NMHN5UHJTdjZQVmkvcUVjdzV1cmlYM1BiNFhxSzRkTDI0Vk1aVGNTSgpUQkUwTUpLazEwQjFMNlNqa0JZOGRNeDBCblR5VEJMUnJ6RFNuQlY4cjRiRldsa0NBd0VBQWFOQ01FQXdEZ1lEClZSMFBBUUgvQkFRREFnSUVNQThHQTFVZEV3RUIvd1FGTUFNQkFmOHdIUVlEVlIwT0JCWUVGTDk2eG1pUmRTbGgKVlNFZUtEbXhvdVhYajJnNk1BMEdDU3FHU0liM0RRRUJDd1VBQTRJQkFRQ2pwYTJ5N2U3SkVNQlplVTRxRHFVUwp6aG40cFVpSE1XelJSLzRTU0NwRnZQVzVwRkRLd21ZY2NwUFp2MllCLzg3L2JKU2ZFakk5N0Ewa1NoN2J3aHRPCmNTUm5RdHBmdkp2dlQ2U1BQRGJzWEg1NnVwWXd6Z1dPVElPOEY5b3p1RmpoMHFXQ0VuTFcvcHN5ZHNTbWlyNVMKNHppclVXazVGZjhYTVdMWllYS29wYnpqK0VvNUd2TVVSRDg5cHY3Yng3dE1sOGxGU0MwZkkwVGVLc3d6OUJsbwpPVXExZkp0bStJaDFPdU9aQTFOZGZmYmNzOTZCOGdFSVM2bVFEUjBUVmVEayt4NWk0Zk8xSG56SnZMbEJhVmtpClJneGxiUExFei81VlY1RHBoMzRpTTBPcVZrampiT05RNUlBd211YUZ5RC9jNmJvN2tqcEMyWFpUNndybDI5SXkKLS0tLS1FTkQgQ0VSVElGSUNBVEUtLS0tLQo=
    service:
      name: istiod
      namespace: istio-system
      path: /inject
      port: 443
  failurePolicy: Fail
  matchPolicy: Equivalent
  name: namespace.sidecar-injector.istio.io
  namespaceSelector:
    matchExpressions:
    - key: istio-injection
      operator: In
      values:
      - enabled
  objectSelector:
    matchExpressions:
    - key: sidecar.istio.io/inject
      operator: NotIn
      values:
      - "false"
  reinvocationPolicy: Never
  rules:
  - apiGroups:
    - ""
    apiVersions:
    - v1
    operations:
    - CREATE
    resources:
    - pods
    scope: '*'
  sideEffects: None
  timeoutSeconds: 10

해당 설정을 조금 더 자세히 살펴보겠습니다. 위 코드는 istio-sidecar-injector ConfigMap 일부를 발췌한 부분으로 먼저 살펴볼 지점은 rules 부분에 Pod를 생성할 때 해당 Webhook이 동작하는 것을 확인할 수 있습니다.

또한 namespaceSelector와 objectSelector를 통해서 특정 label의 값이 존재할 경우에만 동작하도록 되어있는 것을 확인할 수 있습니다.

마지막으로 살펴볼 지점은 조건들이 부합되었을 때, istiod의 /inject URL로 요청을 전달하여 후속 작업 처리를 요청한다는 점입니다.

이를 토대로 살펴보면, Kubernetes는 사용자가 요청한 내용을 분석하여 istio를 통한 Mutation 변경이 필요하다고 판단될 때 istiod에게 요청하여 mutation 작업을 수행하도록 요청합니다. 그 이후에는 istiod 내부에서 istio 설정에 맞추어 yaml을 변경한 다음 이를 다시 Kubernetes로 전달하여 후속 작업 진행 후 배포하는 과정을 거쳐 Pod가 생성됩니다.

4. Sidecar Injector

이전 내용을 통해 Pod가 생성되는 시점에 istio pilot-discovery에 요청하여 istio 연결에 필요한 설정이 적용되는 것을 확인할 수 있었습니다. 그렇다면 istio 내부에 어떤 컴포넌트가 어떤 과정을 거쳐 이러한 과정이 수행될까요? pilot-discovery에 위치한 Sidecar Injector 컴포넌트를 살펴보면서, 사이드카 컨테이너를 어떻게 주입하는지 과정을 살펴보겠습니다. 먼저 살펴볼 것은 Sidecar Injector의 기동 과정입니다.

처음에 pilot-discovery가 기동될 당시에 INJECT_ENABLED 환경 변수 값을 확인합니다. 해당 값이 true이면, Sidecar Injector의 초기화 과정을 수행합니다. 참고로 해당 환경 변수의 기본 값은 true입니다.

초기화 과정을 살펴보면 다음과 같습니다.

먼저 pilot-discovery가 실행되는 Pod 내의 /var/lib/istio/inject 하위 디렉토리에 config 파일이 존재하는지를 살펴봅니다. 만약 해당 디렉토리에 config 파일이 위치한다면, config와 values를 FileWatcher에 매핑시킵니다.

만약 해당 디렉토리에 파일이 위치하지 않으면, 그 다음으로 확인하는 것은 k8s의 Configmap을 확인하고 관련 ConfigMapWatcher 컴포넌트를 생성하여 바인딩하는 역할을 수행합니다.

먼저 살펴볼 것은 ConfigMap Watcher 내부입니다. 내부에는 Controller가 존재하고 ConfigMap 이벤트를 전달받기 위해서 informer를 등록하고 변경 사항을 전달 받습니다. 이때 ConfigMap Watcher가 감시하는 대상은 istio-system 네임스페이스에 존재하는 istio-sidecar-injector입니다. 참고로 해당 ConfigMap은 istio 설치 시에 자동 등록되는 리소스로 내부에는 config와 values 두 Key에 해당하는 데이터가 존재합니다.

informer에 등록된 이후 해당 Configmap에 변경이 발생하면, 다음과 같은 과정을 거칩니다.

1. informer에서 queue에 이벤트 정보를 전달합니다.
2. queue에는 등록된 callback을 호출합니다.
3. Controller에 등록된 callback의 역할은 Configmap 정보를 읽고 거기에서 등록된 config 데이터와 values 두 개의 데이터를 읽어들이는 작업을 수행하고, ConfigMap Watcher에 등록된 handler에 전달하여 후속 작업을 위임합니다.
4. handler의 역할은 Webhook 구조체에 위치한 updateConfig 메소드를 호출하는 것입니다.
5. updateConfig 메소드의 역할은 ConfigMap을 읽어들여 Webhook 구조체 멤버에 저장합니다. 이때 config의 경우는 configMap의 config key의 값을 그대로 저장하지만, values의 경우는 해당 데이터를 map으로 변환 후 ValuesConfig 구조체로 감싸서 Webhook의 valuesconfig에 저장하는 차이점이 있습니다.

위 내용을 보면, istio-sidecar-injector ConfigMap의 values 데이터를 Map 형태로 Parsing하여 저장하는 것을 확인할 수 있습니다.

5번 단계까지 진행되면, pilot-discovery 내부에 사이드카 주입을 위한 템플릿 정보를 취득할 수 있으며, ConfigMap 변경에 따라서 이를 감지하고 반영할 수 있게 되었습니다. 이후 진행되는 6번 단계에서는 외부에서 /inject 혹은 /inject/ URI를 통해서 접근할 경우 요청을 처리하기 위한 handler 메소드를 등록하는데, 이때 담당을 webhook에 위치한 serverInject 메소드가 담당합니다. 즉 사이드카 컨테이너 주입 역할은 serverInject 메소드에 있습니다. 지금부터 해당 메소드에서 수행되는 주요 과정에 대해서 살펴보겠습니다.

4-1 사이드카 주입 가능 여부 확인

serveInject 메소드내에서 가장 먼저 수행하는 작업은 위 그림과 같습니다. 먼저 Client의 요청 타입은 JSON으로 전달되기 때문에 해당 타입이 JSON인지 확인하고 Body에서 데이터를 추출합니다. 그 후 수행하는 작업은 해당 Pod의 사이드카 주입 요청이 적절한지를 확인하는 것입니다. 해당 과정은 위 그림과 같은 과정을 거칩니다.

1. Pod의 spec.hostNetwork 값이 true인가?
2. 사이드카 생성 요청 대상 Namespace가 Ignored Namespace에 해당하는가?
3. sidecar.istio.io/inject 어노테이션이 존재하거나 대상 Namespace에 자동 주입 활성화 Label이 존재하는가?

먼저 첫번째 조건에 대해서 살펴보면, hostNetwork 값이 true라면, 이는 Pod의 네트워크 설정이 해당 Pod가 동작하는 host 노드의 네트워크 설정을 따라가는 것을 의미합니다. istio에서는 Pod 컨테이너의 iptables를 조작하여 네트워크 트래픽을 변경하는데, 해당 설정이 true일 경우 노드 전체에 장애가 발생할 여지가 있습니다. 따라서 Pod의 hostNetwork가 true인 경우에는 사이드카 주입을 수행하지 않습니다.

두 번째 조건은 사이드카 요청 대상 Namespace가 시스템에서 내부적으로 사용하는 Namespace인 경우에는 요청을 거절합니다. 대상 Namespace는 위 그림과 같이 총 4개입니다.

세 번째 조건은 Pod 요청에 사이드카 주입 어노테이션이 존재하는지 확인하는 것입니다. 해당 어노테이션이 존재하면서 값 주입을 요청하거나 생성 대상 Namespace에 사이드카 자동 주입 Label이 활성화되어있는 경우에는 사이드카 주입을 허가하지만 그렇지 않을 경우에는 주입을 수행하지 않습니다.

4-2 Pod Annotation 검증

이번에는 Pod 내에 존재하는 Annotation 중 istio 동작에 관여하는 Annotation이 지정되어있을 경우 해당 Annotation이 istio에서 요구하는 형태로 작성되어있는지 검증하는 단계입니다. 이전 단계에서는 특정 조건에 부합되지 않은 경우에는 사이드카 주입은 수행하지 않더라도 Pod 생성은 진행되었지만, 해당 단계에서는 Validation을 통과하지 않은 경우에 Pod 생성이 되지 않는 것이 차이점입니다.

위와같이 pilot-discovery 내에는 사용자가 Pod에 입력한 Annotation의 이름이 위 Map에서 제공하는 Annotation과 일치할 경우 입력값이 올바른지 검증하는 함수가 매핑되어있는 것을 확인할 수 있습니다.

따라서 Pod 내부 Annotation을 순회하면서 위 조건에 부합하는 Key Annotation이 존재할 경우 해당 값에 매핑된 검증 함수를 수행하여 올바른 값이 입력되지 않았을 경우 Pod 생성 요청을 거절합니다.

4-3 Concurrency 계산

envoy 구조 포스팅에서 다루어봤듯이 envoy 내부에는 Master 쓰레드와 Worker 쓰레드가 분리되어 있고 해당 쓰레드 개수의 설정은 --concurency 인자에 의해 결정되는 것을 확인했습니다.

istio에서 사이드카를 주입할 때 내부적으로 envoy proxy를 기동시켜야되기 때문에 해당 과정에서는 몇 개의 Worker 쓰레드를 기동시키는 지 계산하여 사이드카 컨테이너 템플릿을 생성할 때 이 과정에서 계산된 값이 주입됩니다.

이때 Concurrency가 계산되는 과정을 살펴보면, 위 그림과 같이 Proxy Config 설정 여부에 따라 달라집니다. Proxy Config는 istio 전체에 전역적으로 설정하거나 특정 Workload에만 적용하거나 아니면 특정 Pod에 대해서 Annotation에서 설정 변경이 가능합니다. 이때 우선순위는 Pod > Workload > Global 순이기 때문에 우선순위에 따라 값이 Override 됩니다.

만약 Concurrency 값이 양수 값이 입력되어있다면, 계산 과정에서는 해당 값이 적용됩니다. 하지만 Concurrency 값이 0일 경우에는 계산 과정이 달라집니다.

가장 먼저 확인하는 것은 sidecar.istio.io/proxyCPULimit Annotation 값이 존재하는지 확인하는 것입니다. 해당 Annotation은 Envoy를 위해 사용되는 CPU의 Limit을 지정하는 값으로 해당 Annotation이 존재한다면, 그 값을 기준으로 Concurrency 값을 계산합니다.

만약 해당 Annotation이 존재하지 않는다면, sidecar.istio.io/proxyCPU 값이 존재하는지 확인합니다. 해당 Annotation은 Envoy를 위해 사용되는 CPU를 의미합니다.

만약 위 두 Annotation이 존재하지 않는다면, 해당 Pod에 지정되어있는 CPU Resource의 Request와 Limit을 확인합니다. 만약 지정된 값이 있으면, 그 값을 기준으로 Concurrency를 계산합니다.

마지막으로 어떠한 조건에도 부합하지 않는다면, 기본 값인 2를 지정합니다.

참고로 Concurrency 계산에 필요한 값이 존재할 경우에는 입력된 값을 1000으로 나눈 값을 올림하여 요구 Concurrency를 계산합니다. 가령 500m이 입력되었다면, CEIL(500/1000) = 1이므로 1개가 지정됩니다.

4-4 Template Yaml 생성

istio-system namespace에 존재하는 istio-sidecar-injector Configmap을 살펴보면, 사이드카 주입을 위한 Template이 Yaml 형식으로 정의된 것을 확인할 수 있습니다.

  args:
  - istio-iptables
  - "-p"
  - {{ .MeshConfig.ProxyListenPort | default "15001" | quote }}
  - "-z"
  - "15006"
  - "-u"
  - "1337"
  - "-m"
  - "{{ annotation .ObjectMeta `sidecar.istio.io/interceptionMode` .ProxyConfig.InterceptionMode }}"
  - "-i"
  - "{{ annotation .ObjectMeta `traffic.sidecar.istio.io/includeOutboundIPRanges` .Values.global.proxy.includeIPRanges }}"
  - "-x"
  - "{{ annotation .ObjectMeta `traffic.sidecar.istio.io/excludeOutboundIPRanges` .Values.global.proxy.excludeIPRanges }}"
  - "-b"
  - "{{ annotation .ObjectMeta `traffic.sidecar.istio.io/includeInboundPorts` .Values.global.proxy.includeInboundPorts }}"
  - "-d"
{{- if excludeInboundPort (annotation .ObjectMeta `status.sidecar.istio.io/port` .Values.global.proxy.statusPort) (annotation .ObjectMeta `traffic.sidecar.istio.io/excludeInboundPorts` .Values.global.proxy.excludeInboundPorts) }}
  - "15090,15021,{{ excludeInboundPort (annotation .ObjectMeta `status.sidecar.istio.io/port` .Values.global.proxy.statusPort) (annotation .ObjectMeta `traffic.sidecar.istio.io/excludeInboundPorts` .Values.global.proxy.excludeInboundPorts) }}"
{{- else }}
  - "15090,15021"
{{- end }}
  {{ if or (isset .ObjectMeta.Annotations `traffic.sidecar.istio.io/includeOutboundPorts`) (ne (valueOrDefault .Values.global.proxy.includeOutboundPorts "") "") -}}
  - "-q"
  - "{{ annotation .ObjectMeta `traffic.sidecar.istio.io/includeOutboundPorts` .Values.global.proxy.includeOutboundPorts }}"
  {{ end -}}
  {{ if or (isset .ObjectMeta.Annotations `traffic.sidecar.istio.io/excludeOutboundPorts`) (ne (valueOrDefault .Values.global.proxy.excludeOutboundPorts "") "") -}}
  - "-o"
  - "{{ annotation .ObjectMeta `traffic.sidecar.istio.io/excludeOutboundPorts` .Values.global.proxy.excludeOutboundPorts }}"
  {{ end -}}
  {{ if (isset .ObjectMeta.Annotations `traffic.sidecar.istio.io/kubevirtInterfaces`) -}}
  - "-k"
  - "{{ index .ObjectMeta.Annotations `traffic.sidecar.istio.io/kubevirtInterfaces` }}"
  {{ end -}}
   {{ if (isset .ObjectMeta.Annotations `traffic.sidecar.istio.io/excludeInterfaces`) -}}
  - "-c"
  - "{{ index .ObjectMeta.Annotations `traffic.sidecar.istio.io/excludeInterfaces` }}"
  {{ end -}}
  - "--log_output_level={{ annotation .ObjectMeta `sidecar.istio.io/agentLogLevel` .Values.global.logging.level }}"
  {{ if .Values.global.logAsJson -}}
  - "--log_as_json"
  {{ end -}}
  {{ if .Values.istio_cni.enabled -}}
  - "--run-validation"
  - "--skip-rule-apply"
  {{ end -}}

위 예시는 Template 내부에 있는 Yaml 중 init-container의 Argument를 설정하는 부분을 발췌했습니다. 자세히 살펴보면 Template에는 사용자가 지정한 값을 기반으로 사이드카 주입을 위한 Yaml의 최종 내용이 결정되도록 디자인 되었음을 확인할 수 있습니다.

해당 Template은 이미 서버 기동시점에 주입이 되었으므로 사용자 요청을 분석하여 Template을 만드는 작업을 수행합니다.

4-5 Template 적용

사이드카 컨테이너 주입을 위한 Template을 만들었으면, 이제 사용자가 요청한 Pod에 Template을 병합하는 과정을 수행합니다.

이를 위해서 첫번째로 하는 작업은 병합을 원활하게 수행하기 위해 Original Pod의 요청 Spec과 Template Yaml을 Map으로 변환합니다.

위 그림은 Pod의 요청을 Map으로 변환한 originalMap과 Template Yaml을 Map으로 변환한 patchMap의 결과입니다. 내용을 살펴보면, patchMap에는 init-container 한개와 Container한개가 존재하는 것을 확인할 수 있습니다. 위 두 컨테이너의 이미지는 pilot-agent이며, 사이드카 컨테이너 주입을 통해 기본적으로 1개의 init-container와 Container가 추가로 삽입되는 것을 확인할 수 있습니다.

개별 Container가 어떤 역할을 수행하는지는 다음 포스팅에서 살펴보도록하며, 지금은 위 그림을 통해 서로 다른 요청 Spec을 병합하기 위해 Map으로 만들었음을 이해하면 좋을 것 같습니다.

두 Map을 만들고나면, 그 다음은 두 Map의 Key, Value를 비교하면서 병합하는 작업을 거칩니다.

위와같이 병합을 완료하고나면 최종적으로 하나의 Map이 완성됩니다. 내용을 살펴보면 Template에 존재하던 init-container 추가와 Template Container 더해져서 컨테이너 수가 2가 되었음을 확인할 수 있습니다.

병합이 완료된 이후에는 부가적인 작업을 수행하기 위해 postProcess 과정을 거칩니다. 이때 만약 Prometheus 설정이 존재한다면, 병합된 결과에 추가적으로 Prometheus 통합을 위한 어노테이션 등이 추가되는 작업을 거칩니다.

그리고 k8s에 반영을 요청하기 위해 JSON으로 데이터를 다시 변환 후 AdmissionResponse를 통해 응답을 반환하여 사이드카가 주입된 Pod 생성을 요청하는 것으로 마무리됩니다.

5. 마치며

이번 포스팅까지 해서 pilot-discovery의 가장 핵심인 Service Discovery와 사이드카 컨테이너 주입에 대해서 살펴봤습니다. Pilot-discovery는 위 두가지 기능 외에도 Multi Cluster 관리, 인증서 관리 등 중요한 기능과 핵심 컴포넌트가 여럿 존재합니다.

하지만 istio-internals 시리즈의 목표는 pilot-discovery와 pilot-agent 그리고 envoy가 어떻게 상호 작용하는지를 살펴보는 것이기 때문에 흐름을 유지하기 위해 우선 pilot-discovery에 대한 탐구는 여기서 마치고 나머지는 추후 포스팅을 통해 다루어 보겠습니다.

다음 포스팅에서는 Sidecar Injector에 의해서 주입된 사이드카 컨테이너의 init-container에 대해서 살펴보겠습니다.

10. [istio-internals] Pilot-discovery - XDS Server

cla9 — Tue, 3 Mar 2026 11:50:29 +0900

1. 서론

이전 포스팅을 통해 envoy를 관리하기 위해서 등장한 istio의 pilot 아키텍처와 Service Discovery 전파를 위한 informer 구조에 대해서 살펴봤습니다. 이번 포스팅에서는 pilot 아키텍처 중 pilot-discovery의 내부 컴포넌트 중 XDS Server에 대해서 살펴보면서 외부로 부터 전달된 Service 및 설정 변경이 어떻게 내부 과정을 거쳐 개별 pilot-agent의 envoy에 전파되는지 알아보겠습니다.

2. XDS Server 개요

이전 포스팅에서 pilot-discovery는 Informer로부터 Kubernetes의 Resource 정보를 전달받으면, Controller의 Handler를 통해서 관련 내용이 XDS Server에게 전달된다고 설명했습니다. 그리고 이를 전달받은 XDS Server의 역할은 개별 Service 들에게 xDS API 형태로 제공하여 Service 정보를 갱신하는 역할을 수행합니다. 이를 위해 XDS Server 내부에는 Service들의 Connection Pool을 관리하고 envoy가 이해할 수 있도록 xDS API로 변환하여 전달하는 컴포넌트 등이 존재합니다.

그렇다면 XDS Server는 어떻게 구성되어있을까요?

핵심 컴포넌트에 대해서만 살펴보자면, 위와 같은 속성을 지니고 있습니다. 그중 특히 informer와 연계되어 Controller의 역할을 처리하는 것은 Enviroment에 속한 ServiceDiscovery입니다. 해당 컴포넌트에 대해서 살펴보겠습니다.

3. ServiceDiscovery

ServiceDiscovery의 주요 역할은 istio의 주요 관심 대상 Resource에 대해서 변경이 감지되었을 때, 이를 수신 받아 XDS Server로 전달하는 Controller 역할을 수행합니다. 위 그림을 살펴보면 총 21개가 관심 대상이며, 파란색으로 표시한 Resource는 istio에서 제공하는 CRD가 아니라 Kubernetes Gateway API에 해당하는 항목입니다.

참고로 Kubernetes Gateway API는 Kubernetes의 Network 서비스에 대한 표준 스펙을 정의하기 위한 Spec으로 자세한 내용은 아래 공식 문서를 참고하시기 바랍니다.

https://gateway-api.sigs.k8s.io/

Introduction - Kubernetes Gateway API

Introduction What is the Gateway API? Gateway API is an open source project managed by the SIG-NETWORK community. It is a collection of resources that model service networking in Kubernetes. These resources - GatewayClass,Gateway, HTTPRoute, TCPRoute, Serv

gateway-api.sigs.k8s.io

istio에서는 Kubernetes Gateway API Resource가 생성/수정/삭제되면, 해당 내용을 분석하여 xDS API 변환하여 전달하도록 구현되어있습니다. 다만 Kubernetes Gateway API는 Kubernetes 설치 시 기본적으로 등록된 API가 아니기 때문에 별도로 설치해야합니다.

istio에서는 Kubernetes Gateway API 지원을 위해서 위 그림과 같이 환경 변수를 통해 pilot-discovery 프로그램을 수행합니다. 이때 PILOT_ENABLE_GATEWAY_API 환경 변수가 true로 지정되어있는지 여부를 확인합니다. 그 결과 값이 true로 지정된 경우에는 위와 같이 istio에서 제공하는 CRD와 더불어 Kuberntes Gateway API의 Resource 정보를 관심 Collection에 추가합니다. 반대로 해당 값이 false인 경우에는 istio에서 제공하는 CRD만 관심 Collection에 추가하도록 구성되어있습니다.

위와 같은 과정을 거치게되면, istio에서 주요 관심 대상에 대한 Resource 추출은 끝나게됩니다. 그 다음 수행해야하는 일은 Controller를 구성하고 Informer에 등록하는 작업입니다.

우선 Controller를 구성했다고 가정하고, 이전 과정에서 추출한 관심 대상을 기반으로 Informer와 연결하는 부분부터 살펴보겠습니다. 이전에 추출한 관심 대상 Resource를 등록하는 작업을 수행합니다. 해당 과정은 총 4가지 절차를 통해 수행됩니다.

1. 먼저 kubernetes에 등록된 CRD 정보를 조회합니다.

2. 조회한 CRD 정보 중에서 istio의 관심대상 Resource에 부합되는 정보만 Filtering 합니다. 이때 Kubernetes Gateway API는 Kubernetes를 설치했다고 해서 기본적으로 등록되는 Resource 정보가 아닙니다. 따라서 별도로 Gateway API CRD 설치(https://istio.io/latest/docs/tasks/traffic-management/ingress/gateway-api/#setup)를 수행하지 않았을 경우에는 등록된 CRD 정보가 없기 때문에 Filtering 됩니다. 반면 해당 CRD가 설치되어있으면 Filtering 결과에 포함될 것입니다. 참고로 위 예시는 설치가 안되어있다는 가정하에 작성하였습니다.

3. 관심 대상 Resource 간에 서로 Group이 다르기 때문에 Group 별로 매칭되는 Informer를 찾습니다.

4. Resource Group에 해당하는 Informer에 Resource 생성/수정/삭제가 발생했을 경우 Callback을 위한 Handler를 등록합니다.

위 코드내용을 살펴보면, 개별 Callback 메소드에서 수행하는 작업은 Controller Queue에 Event 타입과 전달받은 Object 내용을 전달하도록 구성되어있음을 확인할 수 있습니다.

이번에는 ServiceDiscovery 즉 Controller를 구성하고 있는 주요 컴포넌트에 대한 소개와 더불어 해당 컴포넌트와 이전에 설명한 informer 연계 과정이 어떻게 연결되는지를 살펴보겠습니다.

ServiceDiscovery에는 3가지 주요 속성이 존재합니다. 하나씩 살펴보면 다음과 같습니다. 먼저 queue는 informer로부터 Event가 발생하였을 때 이를 전달하는 중간 버퍼의 역할을 수행합니다.

두번째로 살펴볼 것은 handlers입니다. istio의 관심 대상 Resource Group이 여러개이다 보니 GVK(Group Version Kind)별로 대상 informer가 다르고 이를 처리해야하는 Handler 로직 또한 달리 작성해야할 수 있습니다. 따라서 Service Discovery에서는 GVK 별로 Handler를 매핑하여 Map으로 관리하고 있습니다.

이때 GVK 별로 생성되는 Handler의 모습은 위와 같으며, 가장 중요한 부분은 informer로 부터 전달받은 설정을 기반으로 PushRequest 요청을 만들고 이를 XDSServer.ConfigUpdate 메소드를 호출함으로써, XDSServer와 연결 되어있는 모든 Client에게 설정 정보를 동기화하도록 요청하는 것입니다.

세번째로 살펴볼 것은 kinds로 GVK 별로 매핑되는 informer 정보가 다르기 때문에, 해당 정보를 관리하기 위한 용도로 사용됩니다. handlers와 마찬가지로 Map으로 구성되어있으며 GVK 별로 어떤 Resource가 있으며, 어떤 informer와 매칭되어있는지 정보를 구조화하여 담고 있습니다.

지금까지 설명한 내용을 바탕으로 Service Discovery와 istio Kube Client의 연계 과정을 살펴보겠습니다.

1. 관심 대상 Resource를 순회하면서, GVK 별로 대상 informer를 찾습니다.
2. informer를 찾았으면 event 발생할 경우 정보를 전달받기 위한 Handler를 등록합니다. 이때 해당 Handler는 GVK를 Key로 가지고 Callback Function을 Value로 가지는 handlers Map에서 GVK에 매칭되는 Function을 등록합니다. 이때 등록되는 Function에는 XDSServer로 Update하는 코드가 포함되어있습니다.
3. queue에서는 지속적으로 하나씩 processing 하면서 informer로 부터 전달받은 오브젝트 정보를 기반으로 매칭되는 Handler 실행을 통해 XDS Server로 Update를 수행합니다.

여기까지가 XDS Server 내에 위치한 ServiceDiscovery의 역할입니다.

4. Event 전파

이번에는 이전 내용에서 XDSServer.ConfigUpdate 메소드를 호출했을 때, XDS Server 내부에서 어떻게 처리하는지를 살펴보겠습니다.

ConfigUpdate 메소드가 호출되면, 가장 먼저 하는 일은 XDSServer에 있는 PushChannel에 요청을 전달합니다. 위 그림에서 확인할 수 있듯이 해당 속성은 PushRequest를 전달받아 다른 루틴으로 전달하는 Channel임을 알 수 있습니다.

이후 Channel로 전달된 데이터는 내부적으로는 debounce 메소드가 별도의 go routine으로 동작하여 해당 데이터를 처리합니다. 그렇다면 debounce 작업은 왜 하는 것일까요?

4-1 debounce

debounce는 이벤트가 연이어 발생했을 때, 이를 개별적으로 하나씩 처리하지 않고 그룹핑하여 전달하는 것에 목적이 있습니다. 이에 대한 이해를 돕기위해 최대 5명 운송 가능한 엘리베이터를 이용하는 상황을 가정해봅시다.

만약 엘리베이터에 대기하는 사람이 6명이 존재하는 상황에서 최대 5명까지 이용 가능하지만 이용객 한명씩 순차적으로 엘리베이터를 사용할 수 있다면 어떻게 될까요? 당연히 운송 시간은 증가할 것이며, 엘리베이터 가동 비용 측면에서 봤을 때에도 굉장히 비효율입니다. 이때 가장 효율적인 방법은 엘리베이터가 허용 가능한 인원만큼 탑승해서 한번에 운반하는 것입니다. 따라서 위 경우에서는 처음 5명을 태운 승강기를 한번 운행하고 그 다음 한번 더 운행 즉 총 2번의 운행하는 것이 가장 좋습니다.

이번에는 엘리베이터에 한명이 현재 탑승한 상황이라고 가정해봅시다. 이때 시설 관리자 입장에서는 5명까지 이용한 엘리베이터에서 한명만 운행하는 것은 금전적으로 비효율입니다. 따라서 시설 관리자 입장에서만 생각해본다면, 다섯명이 탑승할 때까지 엘리베이터를 기다리게 하는 것이 가장 좋은 선택입니다. 하지만 이 경우에는 다섯명이 탑승할 때까지 엘리베이터가 작동하지 않으므로 탑승객 입장에서는 엄청난 불편함을 초래할 것입니다.

따라서 두 이해 당사자간의 입장을 고려하여 설계된 일반적인 엘리베이터의 모습은 엘리베이터에 탑승객이 탑승하고나서 일정시간이 지날 때까지 탑승하는 인원이 없으면 문이 닫히고 동작하도록 되어있습니다. 또한 중간에 엘리베이터에 탑승하려는 승객이 추가로 발생할 경우에는 센서가 감지하여 엘리베이터 문이 닫히지 않도록 하며, 그때부터 다시 일정 시간 동안 대기하도록 되어있습니다.

위와 같은 엘리베이터는 탑승객 입장에서는 정원이 다 차지 않아도 일정 시간동안 승객의 유입이 없으면 동작하기 때문에 다소 불편함을 감소할 수 있습니다. 또한 시설 관리자 입장에서도 엘리베이터가 아직 닫히지 않는 이상 추가 이용 승객이 발생하면 탑승 가능하기 때문에 합리적인 방법입니다.

이번에는 100명이 이용할 수 있는 엘리베이터가 있고 최초 승객이 탑승 이후 약 10초 이후에 엘리베이터가 자동으로 닫힌다고 가정해봅시다. 이러한 상황에서 최초 승객이 탑승한 이후에 10초마다 새로운 탑승객이 발생한다면 어떻게 될까요? 처음 탑승한 승객은 이전과 같이 엘리베이터가 수용 가능한 모든 인원이 탑승할때까지 대기하게되는 문제가 발생합니다. 따라서 이러한 경우에 승객의 불편함을 최소화할 수 있는 방법은 처음 엘리베이터에 탑승객이 탑승한 이후로부터 최대 대기시간을 설정하여 최대 대기시간을 넘기게되면 추가 승객이 탑승하더라도 타이머가 더 이상 동작하지 않고 닫히도록 구현하는 것입니다. 이렇게 되면 처음 탑승한 승객 입장에서는 최대 대기시간 만큼만 대기하면 되므로 불편함은 최소화 될 수 있을겁니다.

지금까지 엘리베이터 시나리오를 설명했는데, istio에서는 위 시나리오 내용과 같은 이유로 동일하게 debounce를 적용했습니다. istio pilot-discovery에는 모든 pilot-agent와 Connection을 맺고 있는데, 이벤트 하나하나씩 발생할 때마다 broadcast하는 것은 굉장히 통신 비용을 증가하는 요인입니다.

따라서 이때 debounce를 지정하면, 메시지를 효과적으로 처리할 수 있습니다. 가령 최초 PushReqest 요청을 전달받았을 때로 부터 일정 시간 내에 메시지가 유입되는 경우 해당 메시지와 이전 메시지를 병합합니다. 참고로 이때 병합되는 메시지는 PushRequest내에 있는 Reason Slice에 기존 메시지가 추가됩니다.

이후 또 다시 일정 시간 이내에 메시지가 추가 유입되면 병합하고 만약 그 시간동안 메시지가 유입되지 않는다면 지금까지 병합한 메시지를 한번에 전송합니다. 다만 이러한 경우 메시지가 계속 추가로 유입되는 경우 한없이 기다릴 수 있기 때문에 최대 대기 시간을 설정하여 최대 대기 시간이 지나면 메시지 처리를 수행하도록 수행할 수 있습니다.

istio에서는 PILOT_ENABLE_EDS_DEBOUNCE 환경 변수가 true로 되어있을 때 debounce가 작동하도록 설계되었습니다. 해당 값은 기본적으로 true이기 때문에 별도의 설정이 없다면 항상 debounce는 작동하고 있습니다.

그리고 PILOT_DEBOUNCE_AFTER와 PILOT_DEBOUNCE_MAX 값은 이전에 설명한 일정 대기 시간과 최대 대기 시간을 의미합니다. 기본적으로 일정 대기 시간은 100ms 로써 100ms 동안 Event가 발생하면 해당 Event는 하나의 메시지로 병합됩니다. 또한 최대 대기 시간은 10초로 설정되어있으며, 메시지가 아무리 지속 유입이 된다고 할지라도 10초를 넘어가면 메시지 병합을 멈추고 메시지를 발행하도록 되어있습니다.

따라서 만약 istio를 운영하다가 너무 잦은 sync로 인한 overhead가 발생한다면 해당 두 값을 적절하게 튜닝하여 메시지 동기화 속도를 조절할 수 있습니다.

debouce 작업이 끝나면, 하나의 메시지로 통합되며, 이를 통해 하나의 요청만 전달할 수 있습니다. 그 다음 작업은 해당 메시지를 개별 client로 전달하는 것입니다. 이때 전체 Client의 정보는 AdsClients에 저장되어 있습니다. 따라서 Client 별로 해당 메시지를 매핑하여 Queue에 입력합니다. 여기까지가 debounce 작업과 후속 메시지 처리 작업입니다.

4-2 PushQueue

이전 내용에서 debounce 이후 PushQueue에 Client 정보와 요청 정보 메시지를 삽입하는 것을 확인했습니다. 이때 Enqueue 메소드 안에서는 여러가지 작업이 이루어지는데, 이와 관련하여 PushQueue의 구조와 수행 동작에 대해서 살펴보겠습니다.

Push Queue의 주요 속성은 위 3가지입니다. queue에는 Client의 연결을 slice 형태로 저장하고 있고 Client 별로 pending과 processing의 Map이 존재하는 것을 확인할 수 있습니다. 위 세가지 자료 구조는 Push Queue가 동작하는데 있어 주요하게 사용됩니다.

먼저 Queue에 삽입할 때 과정을 살펴보겠습니다.

debounce를 통해 입력되는 쓰레드와 Push Queue 처리 쓰레드는 별개의 go routine으로 동작합니다. 따라서 Push Queue에 빠르게 적재되었을 지라도 Push Queue의 처리 능력에 따라서 아직 처리되지 않고 Queue에 남아있을 수 있습니다.

따라서 가장 먼저 수행하는 일은 queue 속성에 Client를 저장하는 작업 이외에 Client를 Key, 요청 Requset를 Value로 사용하는 pending Map에 메시지를 집어 넣습니다. 또한 Client는 queue Slice에 추가합니다.

이때 모습은 위 그림과 같은 형태일 것입니다. 만약 이러한 상황에서 debounce 작업이 한차례 더 진행되고 이때 Service A에 대해서 새로운 PushRequest가 발생했는데, 아직 Push Queue에서 기존 데이터가 처리되지 않은 상황이라면 어떻게될까요?

아직 메시지가 전송된 상태가 아니기 때문에 debounce에서 메시지들을 Merge 했던것 처럼 해당 Client에 전송되는 Message에 대해서 Merge 작업을 수행하도록 진행합니다. 따라서 Pending의 목적은 처리되지 않은 메시지를 저장함과 동시에 추가로 발행되는 메시지 중 Connection 정보가 일치하는 요청에 대해서는 Merge 작업을 수행하여 메시지 처리량을 높이는 효과가 있습니다.

Push Queue에서 주기적으로 Queue에 데이터가 존재하는지 탐색하고 처리하는 작업은 doSendPushes 메소드에서 수행하는데, 해당 메소드는 별도의 go Routine으로 동작합니다. doSendPushes에서 처리하는 과정은 총 3단계로 이루어져있으며, 이는 다음과 같습니다.

1. Dequeue 명령을 통해 Push Queue에 존재하는 queue에서 Client 정보를 추출하고 pending Map에 존재하는 Client 정보를 삭제합니다. 추가로 작업 진행을 관리하기 위해 processing Map에 Client 정보를 추가합니다. 이때 중요한 점은 Map에 데이터를 넣을 때 Key 값 즉 Client 정보만 Map에 입력하고 Value는 nil로 입력한다는 것입니다. 그 이유에 대해서는 추후 살펴보겠습니다.

2. Client 구조체에 위치한 PushChannel에 데이터를 삽입합니다. 이후 처리 과정은 Client와 연계되어있는 ADS에서 처리합니다. 이에 대해서는 추후 살펴보겠습니다.

3. Client에 데이터 전송이 완료되면, 완료 응답을 수신받습니다. 응답 수신이 완료되면, processing Map에서 해당 정보를 삭제합니다.

위와 같은 세 가지 단계를 거치면 데이터가 정상적으로 처리되는 것을 확인할 수 있습니다.

그렇다면 현재 데이터를 Service A에 전송하고 있는 과정에서 동일한 Client에게 Push Request가 요청되면 어떻게 될까요? 이때는 processing Map을 통해 메시지를 처리합니다.

메시지를 Client에게 전송하면 processing Map에 Connection 정보를 입력하는 것을 이전 내용을 통해 확인했습니다. 따라서 debounce 이후 Queue에 입력하는 과정에서 해당 Map을 확인하면 현재 메시지 전송 상태를 확인할 수 있습니다.

이 경우에는 processing Map에 존재하는 Client 데이터에 Push Request를 추가합니다. 만약 그 이후에도 Client의 전송 완료 메시지를 받기 이전에 Push Request를 전달받으면 지속적으로 Push Request를 Merge 하여 하나의 메시지로 만듭니다.

이후 Client가 작업을 종료하고 전송 완료 응답을 전달하였을 때, processing Map을 살펴봅니다. 이때 Client Key에 해당하는 Value가 nil일 경우에는 메시지 전송 이후로 해당 Client에 요청되는 추가적인 메시지가 없으므로 작업을 종료합니다. 하지만 Value가 nil이 아닐 경우에는 중간에 입력된 메시지가 존재함을 의미합니다. 따라서 그 다음 doSendPushes 싸이클에서 메시지가 다시 처리될 수 있도록 pending 메시지에 해당 Client 정보와 Push Request를 다시 입력하고 queue에도 Client 정보를 삽입합니다.

지금까지 Push Queue에 대해 살펴봤습니다. 이를 통해 메시지를 전달하는 과정에서도 Network overhead를 줄이기 위해 여러가지 최적화 장치가 마련된 모습을 볼 수 있습니다.

5. Connection 관리

지금까지 Event가 발생했을 때, debounce 과정과 이후 Push Queue에서 데이터를 Client에게 전달하고 후속 작업을 처리하는 과정에 대해서 살펴봤습니다. 이번에는 XDS Server Client Connection 관리 주체와 어떻게 통신을 수행하는지 살펴보겠습니다.

envoy에서는 위와 같이 ADS Server에 대한 gRPC interface를 제공합니다. 따라서 istio에서는 해당 ADS Spec에 부합하도록 gRPC 코드가 구현되어있습니다.

istio에서는 사용자 요청을 처리하기 위해서 내부적으로 gRPC Server가 있습니다. pilot-agent는 gRPC에 정의된 interface 호출을 통해 pilot-discovery에 접속을 접속과 더불어 필요한 Resource 정보를 요청합니다.

사용자의 요청을 전달받으면 해당 Server는 별개의 go routine을 통해 receive와 processRequest 두 개의 작업을 수행합니다. 여기서 주목할 점은 receive와 processRequest는 별개로 동작하지만 두 routine간의 Request Channel로 연결되어있다는 점입니다. 지금부터는 두 과정에 대해서 살펴보면서 동작 원리를 관찰해보겠습니다.

먼저 살펴볼 것은 receive입니다.

receive의 역할은 연결된 Connection에서 데이터 처리가 필요할 때 해당 Request를 Requet Channel로 연결하기 위함입니다. 위 코드 내용을 통해 이를 살펴보겠습니다.

최초에 Client가 gRPC 서버에 접속을 요청하면, firstRequest는 true일 것입니다. 이후 for-loop 구문을 수행하는데, 위 코드를 살펴보면 for-loop 자체에는 별도의 조건이 없기 때문에 계속 반복 수행되는 것을 확인할 수 있습니다.

이후 for-loop 구문으로 진입했을 때 눈여겨볼 점은 최초 접속시 initConnection 메소드를 호출한다는 점입니다. 해당 메소드가 수행하는 기능은 사용자의 요청이 적합한지 권한 검사 이후에 XDS Server에 위치하는 AdsClients Slice에 해당 Connection 정보를 추가하는 작업을 진행합니다. 마찬가지로 defer 메소드로 Client가 접속을 종료할 때는 closeConnection 메소드를 호출하여 AdsClients로부터 해당 정보를 삭제하는 과정 또한 진행합니다.

따라서 이전에 Service Discovery 로직에서 Event 정보를 모든 Clients에게 전파할 때 해당 자료 구조를 참조했음을 확인할 수 있는데 receive 로직에서 AdsClients를 관리함을 알 수 있습니다.

사용자 최초 접속 하여 Connection 할당 정보가 완료된 이후, 수행하는 일은 사용자로부터 전달 받은 요청이 있으면 이를 Request Channel로 전달하는 중간 매개체 역할을 수행합니다.

정리하자면 별도의 go routine으로 동작하는 receive 메소드의 역할은 Connection 관리와 더불어 Connection에서 발생한 Request 정보를 Request Channel에 전파하는 것입니다.

이번에는 사용자의 요청을 처리하거나 Server의 전달 요청을 처리하는 로직 부분을 살펴보겠습니다.

해당 로직 또한 마찬가지로 for-loop을 지속적으로 수행하면서 요청 구분에 따라 처리 방법을 달리 수행합니다. 그 중 위 코드가 핵심 로직을 설명합니다.

먼저 살펴볼 것은 사용자의 요청에 대한 처리입니다. Receive go routine에서 사용자 요청을 최초 접수받고 이를 Request Channel에 전파한다고 이전에 설명했습니다. 이때 Channel로 전파된 데이터를 수신받고 processRequset 메소드에 전달하는 역할을 수행합니다.

이때 processRequest 로직에서는 내부적으로 위와 같은 작업이 수행됩니다.

1. Client가 요청한 DiscoveryRequest는 ADS interface에 의해 정의된 Envoy 구조체로써 Discovery를 희망하는 요청 타입(ex Cluster)을 알 수 있습니다. 따라서 먼저 해당 정보를 파싱합니다. 그리고 요청하는 Resource를 지속적으로 추적하기 위해서 Connection 내부에 위치한 WatchedResource map에 해당 Type을 저장합니다.

2. istio 내부에서는 Envoy Spec과 달리 Abstract한 Model 구조를 사용합니다. 따라서 istio에서 통용되는 데이터 구조인 PushRequest로변환합니다.

3. istio는 내부에서 관리하는 데이터 타입 구조를 envoy가 이해할 수 있는 xDS로 변환하기 위해 내부적으로 Generator를 내장하고 있습니다. 위 그림과 같이 Generator는 Map 형태로 되어있으며, 각기 다른 Generator 중 Watched Resource Slice에 저장된 사용자가 원하는 타입에 부합하는 Generator를 찾아 xDS API 스펙에 맞게 변환하는 작업을 수행합니다.

4. 변환 작업이 완료되면, 다시 ADS interface에 의해서 정의된 DiscoveryResponse로 다시 변환합니다. 그리고 해당 정보를 Client에게 반환합니다.

정리하자면, 사용자가 원하는 요청 정보를 분석하여 istio가 관리하고 있는 서비스 정보를 Generator를 통해 envoy가 이해할 수 있는 형태로 변환한 다음 ADS interface가 요구하는 형태로 Wrapping 하여 전달하는 것이 사용자 요청 처리의 핵심 흐름이라고 볼 수 있습니다.

이번에는 Service 생성/수정/삭제로 인해 Server에서 Client에게 데이터를 전달해야되는 상황에 대해서 살펴보겠습니다.

이전 Push Queue 설명을 통해서 최종 통보는 Client Connection에 위치한 Push Channel로 데이터가 전달된다고 설명했습니다. 따라서 위 코드를 살펴보면 PushChannel에 데이터가 들어왔을 때는 빨간색 음영 부분이 감지가 될 것이며, 이를 토대로 pushConnection 메소드를 호출하여 후속 작업을 처리합니다.

이때 pushConnection 내부 처리 과정은 다음과 같습니다.

PushRequest는 이미 PushChannel로 부터 받았으므로 envoy의 요청과는 다르게 메시지를 변환할 필요가 없습니다. 이후 Connection에 등록된 Watched Resource 정보를 모두 가져와서 Generator에 매칭되는 정보로 변환하고 ADS interface에 의해서 정의된 DiscoveryResponse로 다시 변환합니다. 그리고 해당 정보를 Client에게 반환합니다.

해당 과정을 통해 Server의 변경 내용을 Client에게 전파할 수 있습니다.

5. 정리

지금까지 XDS Server에 존재하는 주요 컴포넌트에 대해서 살펴봤습니다. 이번에는 지금까지 배운 내용을 요약해서 전체적인 관점에서 흐름을 간략하게 살펴보겠습니다.

1. 사용자로부터 접속 요청을 전달받으면 Connection을 생성하고 XDS Server 내에 위치한 AdsClients에 저장하여 사용자를 관리합니다.

2. informer에 등록한 Handler를 통해서 관심 대상 Resource를 등록하며, Callback으로 ServiceDiscovery내에 있는 queue로 전달됩니다. 해당 queue에서는 kinds에 등록된 GVK(Group Version Kind)에 매칭된 handler를 실행합니다. 대부분의 handler는 XDSServer.ConfigUpdate 메소드를 수행하고 해당 정보는 PushChannel로 전달됩니다.

3. 내부에는 독립적으로 수행하는 debounce go routine이 존재하여 일정 시간동안 유입되는 메시지를 병합하는 작업을 수행하고 이후 메시지 전달을 위해 Push Queue에 데이터를 저장합니다.

4. Push Queue를 처리하는 로직은 또 다른 별도 go routine을 동작하는 doSubPushes에서 수행되며, 여기서는 Client Connection 정보를 참조하여 해당 Connection의 Push Channel로 데이터를 다시 전달합니다.

5. Push Channel로 전달된 데이터는 내부 Generator를 통해 envoy가 이해할 수 있는 형태로 데이터를 가공한다음 Client로 전달합니다.

6. 마치며

이번 포스팅에서는 istio pilot-discovery에서 가장 중요한 XDS Server에 대해서 살펴봤습니다. 다음 포스팅에서는 인증서 관리와 SDS Server 구조에 대해서 살펴보겠습니다.

9. [istio-internals] istio - Service Discovery

cla9 — Tue, 3 Mar 2026 11:50:07 +0900

1. 서론

envoy-internals 시리즈를 통해 envoy 아키텍처에 대해서 자세하게 살펴봤습니다. 이번부터 진행되는 시리즈는 envoy 위에서 동작하는 istio가 어떻게 상호작용하는지 그리고 이를 위해 어떤 내부 구조를 지니고 동작 원리가 어떻게 되는지에 대해서 자세하게 살펴보고자 합니다.

이번 포스팅에서는 envoy proxy를 활용하기 위한 istio의 역할과 아키텍처에 구조에 대해서 일부 다루어보겠습니다.

2. envoy proxy와 istio

이전 envoy 시리즈를 통해 envoy proxy는 service 앞단에 위치하고 요청에 대한 라우팅 정책, Circuit Breaker, mTLS 통신과 같은 인프라단에서 제공해주는 네트워크 기능을 대신 처리함을 확인했습니다. 그에 따라 Client가 Service를 호출할 때 다이렉트로 Service를 호출하는 것이 아니라 envoy proxy를 경유해서 upstream으로 트래픽이 전달됩니다.

위와 같은 구조를 가졌을 때, 애플리케이션 배포할 때는 대개 Service만 배포하지 않고 envoy proxy와 Service간 연결 설정 정보가 포함된 하나의 형태로 패키징하여 배포합니다. 이러한 배포 형태를 사이드카 패턴이라고 부르며, Kubernetes를 통해 배포할 경우 1개의 Pod내에 Service와 Proxy Container를 엮어서 같이 배포하는 것이 일반적입니다.

이때 Service가 단일로 구성되어있다면, envoy 설정 정보가 포함된 1개의 Pod를 잘 만들어서 배포할 경우 서비스 제공에 문제가 없을 것입니다.

그렇다면 MSA 환경에서는 어떨까요?

MSA 환경에서는 위와 같이 시스템을 구축하기 위해 협력해야하는 Service가 다수가 될 것입니다. 그리고 이때 문제가 되는 것은 협력 해야할 Service가 지속적으로 추가되거나 변경되는 일이 자주 이루어진다는 것입니다. 즉 envoy proxy간 통신을 위해서는 서로간의 정보를 추적하고 이를 반영해야 서비스를 안전하게 제공할 수 있음을 의미합니다.

envoy 구조 포스팅에서 살펴봤듯이 envoy 내부 컴포넌트 변경을 위해서는 static과 dynamic 방법이 있음을 설명했습니다. 만약 Service가 지속적으로 추가되거나 변경될 때 static 방식으로 처리해야한다면, 위 예시와 같이 Service A 입장에서 Service B, Service C가 추가될 때마다 static resources 파일을 변경해서 재기동을 수행해야하는 문제점을 야기합니다. 따라서 이 경우에는 dynamic 방식을 활용하여 xDS를 통해 config 파일 변경 없이 기동 시점에 동적으로 Cluster 정보, Endpoint 정보 등을 변경하는 것이 바람직합니다.

그렇다면 envoy proxy에 xDS를 통해 올바르게 정보를 제공하기 위해서는 누군가는 Service의 등록/수정/삭제 등을 지속적으로 추적하고 관리하는 Control plane이 필요할 것입니다. 아마 눈치채셨겠지만, istio가 바로 해당 Control Plane의 역할을 수행합니다.

그렇다면 istio는 어떠한 원리로 Service의 등록/수정/삭제를 추적하고 관리하고, envoy proxy들과 Connection을 맺고 있으며 어떻게 데이터를 전달할까요?

이러한 목표를 달성하기 위해서 istio에서는 pilot 아키텍처를 제공하였습니다.

Pilot은 말 그대로 조종사를 의미합니다. 마치 istio를 통해서 서비스와 endpoint 정보를 제공하여 올바르게 애플리케이션이 동작할 수 있도록 조종하는 역할을 수행합니다. pilot 아키텍처에는 이를 구현하기 위해 두 개의 컨테이너 이미지가 제공됩니다. 하나는 pilot-discovery 나머지는 pilot-agent입니다. 각각 이미지가 무슨 역할을 수행하는지 알아보겠습니다.

pilot-agent는 envoy proxy를 wrapping하고 있는 프로그램으로써 pilot-discovery로부터 Service 변경 사항을 통지받으면, 내부의 envoy proxy에게 이를 전파하여 envoy proxy 내부 설정을 변경하는 중계자 역할을 수행합니다.

반면 pilot-discovery는 Control Plane의 역할인 등록/수정/삭제되는 Service를 감지하고 이를 연결된 모든 pilot-agent에게 전달하는 역할을 수행합니다. 다만 여기서 알아야 할 중요 포인트는 pilot-discovery 자체가 Service 라이프 사이클을 직접 추적하지 않는다는 점입니다. 즉 외부에 존재하는 Service Registry로부터 관련 이벤트를 전달받아 이를 전파하는 중계의 역할만을 담당합니다. 따라서 istio에서는 3가지 방법을 통해 이벤트를 전달받을 수 있는 창구를 제공합니다.

2-1 MCP

첫번째 방식은 MCP(Mesh Configuration Protocol)를 활용하는 방법입니다. Service Discovery 기능을 제공하는 Platform은 많습니다. 가령 위와같이 Consul, Eureka 등이 예입니다. 이때 개별 Platform 마다 Service Discovery 제공 format은 상이할 것이므로 만약 istio에서 각각의 Platform format을 지원해야한다면, 시스템 의존성이 강해질 것입니다. 이는 유지보수 측면에서 굉장히 어려움을 겪을 수 있음을 의미합니다.

따라서 외부 의존성을 줄이기 위해서 istio 내부에서 사용할 수 있는 MCP를 만들고 Service Discovery에서는 MCP 포맷으로 데이터를 전달받아 처리하도록 설계되었습니다. 또한 개별 Service Registry에서 바로 MCP 포맷으로 보내줄 수 없는 경우에는 위와 같이 중간에 Adapter 역할을 수행하는 MCP Server를 통해 pilot-discovery에 전달하도록 구성할 수 있습니다.

2-2 File

두번째 방식은 File 방식입니다. 이는 local에 저장된 Configuration file을 주기적으로 읽어들여서 메모리에 캐싱하고 해당 정보를 토대로 Configuration을 수행하는 방식입니다. 해당 방식은 주로 istio를 테스트할 때 사용합니다.

2-3 Kubernetes

세번째 방식은 Kubernetes 기반의 Service Discovery 방식입니다. Kubernetes 플랫폼을 사용한다면, 자체적으로 Service의 등록/삭제/수정과 관련된 이벤트를 제공받을 수 있습니다. 저를 포함하여 istio를 사용하는 대부분의 사용자는 kubernetes위에서 istio를 사용하는 경우가 많을 것이기 때문에 대개 Service Discovery Provider로써 Kubernetes를 사용할 것입니다.

본 포스팅 또한 위 세가지 방법 중 Kubernetes를 통한 Service 전달 방식에 대해서 자세하게 알아보겠습니다.

3. Informer

이전 내용에서 확인했듯이 pilot-discovery는 외부에 존재하는 Service Registry로부터 Service의 변경 사항을 전달받아 이를 pilot-agent에게 전달하는 역할을 수행합니다. 그리고 이를 위한 인터페이스 방법으로 3가지가 있음을 확인했습니다. 그 중 kubernetes가 가장 보편적으로 사용되는데, istio는 어떻게 kubernetes로부터 이벤트를 전달받을 수 있을까요?

kuberetes 내부에는 여러가지 Controller 즉 Scheduler, Service controller 등이 있습니다. 그리고 해당 컴포넌트의 역할은 kube-apiserver로부터 관심 대상 Resource에 대해서 변경사항이 발생했을 때, Watch 메커니즘을 통해 Resource를 전달받고 후속 작업을 처리합니다. istio 또한 kubernetes로부터 Resource 변경에 대해 통지를 받아 후속처리하는 역할로써 kubernetes의 Custom Controller라고 볼 수 있습니다.

kubernetes의 Controller는 내부적으로 client-go sdk를 통해서 Kube API Server와 통신하고 Watch 메커니즘을 제공합니다. 그리고 이를 위해서 내부에는 informer구조를 사용하고 있습니다.

그렇다면 informer는 왜 사용할까요? 만약 Controller 내부에 있는 컴포넌트들이 Resource 정보를 얻기 위해서 개별적으로 kube-apiserver와 통신을 수행한다면, kube-apiserver 입장에서는 부하가 걸릴 수 있습니다.

따라서 kubernetes 개발자들은 이러한 kube-apiserver의 API 호출 부담을 줄여주고자 Controller 내부에 캐싱 기능과 kube-apiserver와의 효율적인 통신을 위한 informer 메커니즘을 설계하였습니다.

해당 구조를 개략적으로 살펴보면 위와 같습니다. 가령 하나의 Program안에 여러개의 Controller가 존재하고 그 안에서 Resource 변화를 감지를 통지받아야한다면, informer를 통해 통지를 전달받고 싶은 대상을 등록합니다. 그리고 informer가 kube-apiserver에 요청을 전달하여 list 목록을 얻어와서 자신의 Local Thread Safe Cache에 저장합니다.
(※ 참고로 위 그림의 informer는 SharedInformer 구조를 의미하며, istio에서는 이를 위해 SharedInformerFactory를 사용합니다. 자세한 내용은 https://rudecamel.tistory.com/35 내용을 참고하시기 바랍니다.)

이후 Watch 메커니즘을 통해서 kube-apiserver로 부터 이벤트를 전달받으면, 해당 이벤트 내역을 개별 Controller들에게 Callback 하는 방식으로 이벤트를 처리합니다.

조금 더 자세히 살펴보면, Controller Application을 살펴보면 위와 같이 Client-go에서 제공하는 informer 영역과 Controller의 비즈니스 로직 두 부분으로 나눌 수 있습니다.

이때 Controller가 변경 통지를 희망하는 GroupVersionResource를 informer에게 등록하고 향후 해당 이벤트가 전달되었을 때 처리를 희망하는 내부의 여러 Process들이 Controller에게 Add/Update/Delete Callback Function을 등록합니다.

이후 informer가 기동되면, 다음과 같은 과정을 거칩니다.

1. Reflector가 kube-apiserver에게 llist API를 통해서 가장 최신의 resourceVersion이 포함된 Resource 정보를 가져옵니다.

2. 가져온 Resource 정보는 DeltaFIFO에 적재합니다. DeltaFIFO는 Queue 형태로 구성되어있으며, add, update, delete, list, pop 과 같은 연산을 제공합니다.

3. Informer는 DeltaFIFO에 적재된 데이터를 가져옵니다.

4. Informer는 Indexer에게 전달된 데이터 내용을 저장하도록 명령합니다.

5. Informer에 등록된 Controller의 ResourceEventHandler Callback function을 호출합니다.

6. ResourceEventHandler Callback function에서 filtering 룰을 등록한게 있으면, 해당 이벤트는 제외하고 난 다음 관심 대상의 Resource 정보를 WorkQueue에 삽입합니다.

7. Controller는 WorkQueue로 부터 Resource 정보를 획득하여 자신이 보유한 Processor들에게 전파합니다.

8. Processor들은 전달받은 정보를 토대로 비즈니스 로직을 수행합니다. 만약 이 과정에서 Resource에 대한 정보가 필요하다면, Lister interface를 통해서 Indexer에게 Resource 정보를 요청할 수 있습니다. 요청받은 Indexer는 Local Cache로 부터 정보를 제공하여 Processor에서 불필요하게 kube-apiserver에 질의하는 것을 차단할 수 있습니다.

9. 초기화 과정이 끝나면 Reflector는 Watch API를 요청하여 kube-apiserver로부터 Resource 정보의 변경이 있을 때마다 내용을 전달받습니다. 그리고 이전의 흐름 그대로 호출이 이어지면서, 후속 작업을 수행합니다. 이때 Watch API는 HTTP의 Chunked Transfer-Encoding 기법을 사용하여 Connection을 유지하도록 합니다. 이에 대한 설명은 아래 블로그를 참고하시기 바랍니다.

https://mutpp.tistory.com/10

HTTP Chunked Message를 알아보자

# if 0 두달간의 노예 일상을 이제야 끝나고,, 너무 오랜만에 들여다본 블로그,, 개발자로 지내고 있지만,, 일하고 싶지는 않은 그런 삶,, 갑작스럽게 HTTP 프로토콜을 구현해야할 일이 생겨서, 규격

mutpp.tistory.com

지금까지 client-go에서 제공하는 informer 로직에 대해서 살펴봤습니다. istio를 학습하는데 있어 굳이 kubernetes의 watch 메커니즘을 알아야하나 싶을 수도 있습니다. 하지만 istio의 Service Discovery 동작에 있어서 client-go에서 제공해주는 컴포넌트와 강하게 결합되어 있습니다. 따라서 해당 구조를 이해하면 istio 컴포넌트의 동작 흐름을 쉽게 이해할 수 있습니다.

4. Istio Service Discovery 과정

지금까지 kubernetes가 제공하는 client-go의 informer 구조에 대해서 살펴봤습니다. 지금부터는 istio가 어떻게 informer와 연결되어 Service Discovery를 수행하는지에 대해서 살펴보겠습니다.

informer 구조에서 살펴본 것과 같이 informer에는 여러개의 Controller가 존재하고 해당 Controller가 요구하는 Resource 정보를 가지고 있다가 변화가 발생하면, Controller에게 전달함을 확인했습니다. 그에따라 istio에서는 위와 같이 여러개의 Controller를 정의하고 해당 event 정보를 수신하여 비즈니스 로직을 처리하도록 구성되어있습니다.

Control Plane에서는 pilot-agent와 통신을 위한 gRPC Server가 존재합니다. 해당 Server의 역할은 pilot-agent의 Connection을 저장하고 데이터 통신 시 해당 Server를 통해 pilot-agent에게 정보를 전달하는 역할을 수행합니다. 그리고 해당 gRPC Server를 담당하는 것은 pilot-discovery에 속한 XDS Server입니다.

따라서 Controller의 Event가 감지하면 1차적으로 XDS Server에게 해당 내용이 전달되고 XDS Server에서는 전달받은 Resource를 envoy가 이해할 수 있는 XDS 형태로 변환하여 이를 ADS에 전달하여 연결된 모든 pilot-agent에게 정보를 전달하는 역할을 수행합니다.

5. 마치며

이번 포스팅에서는 envoy proxy에게 xDS 정보 제공을 위한 istio control-plane의 기능과 Service Discovery 과정에 대해서 개략적으로 살펴봤습니다. pilot-discovery의 주요 컴포넌트에 대해서는 추후 다루어보도록 하고 이번 포스팅에서는
kubernetes의 informer 구조에 대한 이해와 XDS Server를 통해 envoy proxy들에게 Service Discovery 기능을 제공한다는 점을 기억하면 좋을 것 같습니다.

8. [envoy-internals] Client 요청 전달 과정 이해하기 - 2

cla9 — Tue, 3 Mar 2026 11:49:46 +0900

1. 서론

이번 포스팅은 지난 포스팅에 이어서 사용자가 Connection 연결을 등록한 이후에 실제 HTTP 요청을 전달했을 때 Upstream까지 어떻게 트래픽이 전달되는지에 대해서 살펴보고자 합니다.

그 과정에서 너무 지엽적인 부분은 다이어그램으로 표현하고 필요한 부분은 envoy 코드를 같이 보면서, 내부 동작 과정에 대한 이해를 집중적으로 해보겠습니다.

이번 포스팅은 특히 HttpConnectionManager와 깊은 연관이 있으므로 먼저 해당 내용을 소개한 이전 블로그 내용을 학습 후 보시는 것을 추천드립니다.

(아직 포스팅 미완성상태인데 공개합니다ㅜ 하단에 코드만 첨부된 내용은 추후 보강하겠습니다)

2. Client HTTP 요청 과정

Client Connection 연결은 설정되었기 때문에 libevent로 Client가 HTTP 접속을 요청하면, 내부적으로 어디로 이벤트를 전달해야하는지 이미 알 수 있습니다. 이전 포스팅 내용에서 ServerConnectionImpl이 생성되면 libevent에 onFileEvent를 Callback 메소드로 등록한다고 설명했습니다. 따라서 이번 포스팅에서는 해당 지점부터 살펴보겠습니다.

connection_impl.cc

void ConnectionImpl::onFileEvent(uint32_t events) {
  ScopeTrackerScopeState scope(this, this->dispatcher_);
  ENVOY_CONN_LOG(trace, "socket event: {}", *this, events);

  if (immediate_error_event_ == ConnectionEvent::LocalClose ||
      immediate_error_event_ == ConnectionEvent::RemoteClose) {
    if (bind_error_) {
      ENVOY_CONN_LOG(debug, "raising bind error", *this);
      // Update stats here, rather than on bind failure, to give the caller a chance to
      // setConnectionStats.
      if (connection_stats_ && connection_stats_->bind_errors_) {
        connection_stats_->bind_errors_->inc();
      }
    } else {
      ENVOY_CONN_LOG(debug, "raising immediate error", *this);
    }
    closeSocket(immediate_error_event_);
    return;
  }

  if (events & Event::FileReadyType::Closed) {
    // We never ask for both early close and read at the same time. If we are reading, we want to
    // consume all available data.
    ASSERT(!(events & Event::FileReadyType::Read));
    ENVOY_CONN_LOG(debug, "remote early close", *this);
    closeSocket(ConnectionEvent::RemoteClose);
    return;
  }

  if (events & Event::FileReadyType::Write) {
    onWriteReady();
  }

  // It's possible for a write event callback to close the socket (which will cause fd_ to be -1).
  // In this case ignore read event processing.
  if (ioHandle().isOpen() && (events & Event::FileReadyType::Read)) {
    onReadReady();
  }
}

소켓에 Write/Read 이벤트가 발생하면, libevent에 의해서 onFileEvent를 호출됩니다. 이때 코드 내용을 살펴보면, Socket이 종료되었을 경우에는 연결을 해제하도록 작업을 수행하며, 그렇지 않은 경우에는 Socket 이벤트 타입이 Write인지 혹은 Read인지에 따라서 각기 다른 메소드를 호출하는 것을 확인할 수 있습니다.

위 경우에는 HTTP 요청으로 인해 Socket에 데이터가 작성된 것이기 때문에 데이터를 읽기 위해서 onReadReady() 메소드가 호출됨을 가정하여 진행하겠습니다.

connection_impl.cc

void ConnectionImpl::onReadReady() {
  ENVOY_CONN_LOG(trace, "read ready. dispatch_buffered_data={}", *this,
                 static_cast<int>(dispatch_buffered_data_));
  const bool latched_dispatch_buffered_data = dispatch_buffered_data_;
  dispatch_buffered_data_ = false;

  ASSERT(!connecting_);

  // We get here while read disabled in two ways.
  // 1) There was a call to setTransportSocketIsReadable(), for example if a raw buffer socket ceded
  //    due to shouldDrainReadBuffer(). In this case we defer the event until the socket is read
  //    enabled.
  // 2) The consumer of connection data called readDisable(true), and instead of reading from the
  //    socket we simply need to dispatch already read data.
  if (read_disable_count_ != 0) {
    // Do not clear transport_wants_read_ when returning early; the early return skips the transport
    // socket doRead call.
    if (latched_dispatch_buffered_data && filterChainWantsData()) {
      onRead(read_buffer_->length());
    }
    return;
  }

  // Clear transport_wants_read_ just before the call to doRead. This is the only way to ensure that
  // the transport socket read resumption happens as requested; onReadReady() returns early without
  // reading from the transport if the read buffer is above high watermark at the start of the
  // method.
  transport_wants_read_ = false;
  IoResult result = transport_socket_->doRead(*read_buffer_);
  uint64_t new_buffer_size = read_buffer_->length();
  updateReadBufferStats(result.bytes_processed_, new_buffer_size);

  // If this connection doesn't have half-close semantics, translate end_stream into
  // a connection close.
  if ((!enable_half_close_ && result.end_stream_read_)) {
    result.end_stream_read_ = false;
    result.action_ = PostIoAction::Close;
  }

  read_end_stream_ |= result.end_stream_read_;
  if (result.bytes_processed_ != 0 || result.end_stream_read_ ||
      (latched_dispatch_buffered_data && read_buffer_->length() > 0)) {
    // Skip onRead if no bytes were processed unless we explicitly want to force onRead for
    // buffered data. For instance, skip onRead if the connection was closed without producing
    // more data.
    onRead(new_buffer_size);
  }

  // The read callback may have already closed the connection.
  if (result.action_ == PostIoAction::Close || bothSidesHalfClosed()) {
    ENVOY_CONN_LOG(debug, "remote close", *this);
    closeSocket(ConnectionEvent::RemoteClose);
  }
}

onReadReady() 메소드 내용은 위와 같습니다. 내용을 살펴보면, buffer에 읽을 데이터가 존재하면 해당 길이만큼 read_buffer에서 읽도록 onRead 메소드를 호출하는 것을 볼 수 있습니다.

connection_impl.cc

void ConnectionImpl::onRead(uint64_t read_buffer_size) {
  ASSERT(dispatcher_.isThreadSafe());
  if (inDelayedClose() || !filterChainWantsData()) {
    return;
  }
  ASSERT(ioHandle().isOpen());

  if (read_buffer_size == 0 && !read_end_stream_) {
    return;
  }

  if (read_end_stream_) {
    // read() on a raw socket will repeatedly return 0 (EOF) once EOF has
    // occurred, so filter out the repeats so that filters don't have
    // to handle repeats.
    //
    // I don't know of any cases where this actually happens (we should stop
    // reading the socket after EOF), but this check guards against any bugs
    // in ConnectionImpl or strangeness in the OS events (epoll, kqueue, etc)
    // and maintains the guarantee for filters.
    if (read_end_stream_raised_) {
      // No further data can be delivered after end_stream
      ASSERT(read_buffer_size == 0);
      return;
    }
    read_end_stream_raised_ = true;
  }

  filter_manager_.onRead();
}

그리고 onRead에서는 filter_manager에 등록된 filterChains에서 데이터를 읽도록 위임합니다.

filter_manager_impl.cc

void FilterManagerImpl::onRead() {
  ASSERT(!upstream_filters_.empty());
  onContinueReading(nullptr, connection_);
}

filter_manager에서는 내부에 존재하는 upstream_filters_를 순차적으로 실행 시켜서 Filter Chains를 수행시킵니다. 이를 위해 onContinueReading 메소드를 호출합니다.

filter_manager_impl.cc

void FilterManagerImpl::onContinueReading(ActiveReadFilter* filter,
                                          ReadBufferSource& buffer_source) {
  // Filter could return status == FilterStatus::StopIteration immediately, close the connection and
  // use callback to call this function.
  if (connection_.state() != Connection::State::Open) {
    return;
  }

  std::list<ActiveReadFilterPtr>::iterator entry;
  if (!filter) {
    connection_.streamInfo().addBytesReceived(buffer_source.getReadBuffer().buffer.length());
    entry = upstream_filters_.begin();
  } else {
    entry = std::next(filter->entry());
  }

  for (; entry != upstream_filters_.end(); entry++) {
    if (!(*entry)->filter_) {
      continue;
    }
    if (!(*entry)->initialized_) {
      (*entry)->initialized_ = true;
      FilterStatus status = (*entry)->filter_->onNewConnection();
      if (status == FilterStatus::StopIteration || connection_.state() != Connection::State::Open) {
        return;
      }
    }

    StreamBuffer read_buffer = buffer_source.getReadBuffer();
    if (read_buffer.buffer.length() > 0 || read_buffer.end_stream) {
      FilterStatus status = (*entry)->filter_->onData(read_buffer.buffer, read_buffer.end_stream);
      if (status == FilterStatus::StopIteration || connection_.state() != Connection::State::Open) {
        return;
      }
    }
  }
}

onContinueReading 메소드는 먼저 read buffer에 입력된 값 만큼을 fetch하는 과정을 수행합니다. 이후 자신이 보유하고 있는 upstream_filters를 순회하면서 사용자 요청 처리를 각각의 필터에 위임합니다.

참고로 해당 메소드는 이전 포스팅에서 Read Filter 등록이 모두 완료된 이후 initializeReadFilters() 실행 과정에서도 호출된 적이 있습니다. 그 당시에는 초기화를 목적으로 onNewConnection()이 수행되었는데, 지금은 초기화가 모두완료된 이후이기 때문에 Filter를 순회하면서 onData를 호출하는 것이 이전과는 다른 차이점입니다.

본 포스팅에서는 HTTP 요청과 관련하여 처리됨을 가정하였으므로, filterChains에 등록된 filter 중HttpConnectionManager 필터의 onData가 호출될 것입니다.

3. HttpConnectionManager

HttpConnectionManager의 onData 메소드가 호출되면, 가장 먼저 수행하는 일은 codec을 생성하는 작업입니다. 해당 내용은 HttpConnectionManager 관련 포스팅에서도 다루었던 내용이며, 본 포스팅에서는 Http 1.1 요청임을 가정하므로 Http1::ServerConnectionImpl 인스턴스가 반환될 것입니다.

해당 과정을 코드와 함께 살펴보면 다음과 같습니다.

1. ServerConnectionImpl에서 filter_manager에게 upstream_filters를 호출하라고 지정하면, 내부에 등록된 HttpConnectionManager의 onData가 호출됩니다.

connection_manager_impl.cc

Network::FilterStatus ConnectionManagerImpl::onData(Buffer::Instance& data, bool) {
  if (!codec_) {
    // Http3 codec should have been instantiated by now.
    createCodec(data);
  }

  ...(후략)...
}

2. HttpConnectionManager에서는 먼저 codec_ 생성여부를 판별한 다음 codec_이 만들어진 적이 없으면 이를 생성합니다.

void ConnectionManagerImpl::createCodec(Buffer::Instance& data) {
  ASSERT(!codec_);
  codec_ = config_.createCodec(read_callbacks_->connection(), data, *this, overload_manager_);

  ...(중략)...
}

이때 내부적으로는 config에 지정된 createCodec 메소드를 다시 재 호출함으로써 codec 할당이 이루어집니다,

config.cc

Http::ServerConnectionPtr HttpConnectionManagerConfig::createCodec(
    Network::Connection& connection, const Buffer::Instance& data,
    Http::ServerConnectionCallbacks& callbacks, Server::OverloadManager& overload_manager) {
  switch (codec_type_) {
  case CodecType::HTTP1:
    return std::make_unique<Http::Http1::ServerConnectionImpl>(
        connection, Http::Http1::CodecStats::atomicGet(http1_codec_stats_, context_.scope()),
        callbacks, http1_settings_, maxRequestHeadersKb(), maxRequestHeadersCount(),
        headersWithUnderscoresAction(), overload_manager);
  case CodecType::HTTP2:
    return std::make_unique<Http::Http2::ServerConnectionImpl>(
        connection, callbacks,
        Http::Http2::CodecStats::atomicGet(http2_codec_stats_, context_.scope()),
        context_.api().randomGenerator(), http2_options_, maxRequestHeadersKb(),
        maxRequestHeadersCount(), headersWithUnderscoresAction(), overload_manager);
  case CodecType::HTTP3:
    return Config::Utility::getAndCheckFactoryByName<QuicHttpServerConnectionFactory>(
               "quic.http_server_connection.default")
        .createQuicHttpServerConnectionImpl(
            connection, callbacks,
            Http::Http3::CodecStats::atomicGet(http3_codec_stats_, context_.scope()),
            http3_options_, maxRequestHeadersKb(), maxRequestHeadersCount(),
            headersWithUnderscoresAction());
  case CodecType::AUTO:
    return Http::ConnectionManagerUtility::autoCreateCodec(
        connection, data, callbacks, context_.scope(), context_.api().randomGenerator(),
        http1_codec_stats_, http2_codec_stats_, http1_settings_, http2_options_,
        maxRequestHeadersKb(), maxRequestHeadersCount(), headersWithUnderscoresAction(),
        overload_manager);
  }
  PANIC_DUE_TO_CORRUPT_ENUM;
}

생성 과정을 살펴보면, 연결된 Protocol 종류에 따라서 Codec이 결정되는 것을 볼 수 있습니다. 본 포스팅에서는 Http 1.1 통신을 가정하여 분석함으로 Http1::ServerConnectionImpl이 생성됩니다.

codec_impl.cc

ServerConnectionImpl::ServerConnectionImpl(
    Network::Connection& connection, CodecStats& stats, ServerConnectionCallbacks& callbacks,
    const Http1Settings& settings, uint32_t max_request_headers_kb,
    const uint32_t max_request_headers_count,
    envoy::config::core::v3::HttpProtocolOptions::HeadersWithUnderscoresAction
        headers_with_underscores_action,
    Server::OverloadManager& overload_manager)
    : ConnectionImpl(connection, stats, settings, MessageType::Request, max_request_headers_kb,
                     max_request_headers_count),
      callbacks_(callbacks),
      response_buffer_releasor_([this](const Buffer::OwnedBufferFragmentImpl* fragment) {
        releaseOutboundResponse(fragment);
      }),
      owned_output_buffer_(connection.dispatcher().getWatermarkFactory().createBuffer(
          [&]() -> void { this->onBelowLowWatermark(); },
          [&]() -> void { this->onAboveHighWatermark(); },
          []() -> void { /* TODO(adisuissa): handle overflow watermark */ })),
      headers_with_underscores_action_(headers_with_underscores_action),
      abort_dispatch_(
          overload_manager.getLoadShedPoint("envoy.load_shed_points.http1_server_abort_dispatch")) {
  owned_output_buffer_->setWatermarks(connection.bufferLimit());
  // Inform parent
  output_buffer_ = owned_output_buffer_.get();
}

ServerConnectionImpl 인스턴스 생성 과정을 살펴보면, 내부적으로 데이터를 읽고 쓰기 위한 Buffer를 생성받으며, 그밖에 ConnectionImpl 생성자를 호출하는 것을 볼 수 있습니다.

3. ConnectionImpl 생성자 호출과정에서 사용자의 요청을 분석할 Parser를 등록합니다. 이때 기본적으로는 LegacyHttpParserImpl이 parser_ 로써 등록됩니다.

codec_impl.cc

ConnectionImpl::ConnectionImpl(Network::Connection& connection, CodecStats& stats,
                               const Http1Settings& settings, MessageType type,
                               uint32_t max_headers_kb, const uint32_t max_headers_count)
    : connection_(connection), stats_(stats), codec_settings_(settings),
      encode_only_header_key_formatter_(encodeOnlyFormatterFromSettings(settings)),
      processing_trailers_(false), handling_upgrade_(false), reset_stream_called_(false),
      deferred_end_stream_headers_(false), dispatching_(false), max_headers_kb_(max_headers_kb),
      max_headers_count_(max_headers_count) {
  if (codec_settings_.use_balsa_parser_) {
    parser_ = std::make_unique<BalsaParser>(type, this, max_headers_kb_ * 1024, enableTrailers(),
                                            codec_settings_.allow_custom_methods_);
  } else {
    parser_ = std::make_unique<LegacyHttpParserImpl>(type, this);
  }
}

참고로 config 설정에 use_balsa_parser가 지정되어있다면, BalsaParser가 지정됩니다.

connection_manager_impl.cc

Network::FilterStatus ConnectionManagerImpl::onData(Buffer::Instance& data, bool) {
  if (!codec_) {
    // Http3 codec should have been instantiated by now.
    createCodec(data);
  }

  bool redispatch;
  do {
    redispatch = false;

    const Status status = codec_->dispatch(data);

    if (isBufferFloodError(status) || isInboundFramesWithEmptyPayloadError(status)) {
      handleCodecError(status.message());
      return Network::FilterStatus::StopIteration;
    } else if (isCodecProtocolError(status)) {
      stats_.named_.downstream_cx_protocol_error_.inc();
      handleCodecError(status.message());
      return Network::FilterStatus::StopIteration;
    }
    ASSERT(status.ok());

    // Processing incoming data may release outbound data so check for closure here as well.
    checkForDeferredClose(false);

    // The HTTP/1 codec will pause dispatch after a single message is complete. We want to
    // either redispatch if there are no streams and we have more data. If we have a single
    // complete non-WebSocket stream but have not responded yet we will pause socket reads
    // to apply back pressure.
    if (codec_->protocol() < Protocol::Http2) {
      if (read_callbacks_->connection().state() == Network::Connection::State::Open &&
          data.length() > 0 && streams_.empty()) {
        redispatch = true;
      }
    }
  } while (redispatch);

  if (!read_callbacks_->connection().streamInfo().protocol()) {
    read_callbacks_->connection().streamInfo().protocol(codec_->protocol());
  }

  return Network::FilterStatus::StopIteration;
}

지금까지 3가지 단계에 걸쳐서 ServerConnectionImpl 생성과 더불어 실제 요청을 처리하는 codec 또한 생성됨을 확인했습니다. 여기까지 완료되면, 그 다음 작업은 위 코드와 같이 codec_ 에게 사용자가 요청한 데이터를 넘겨줌으로써 dispatch 하도록 처리를 위임하고 Codec 내부에서는 다시 parser_를 통해 사용자의 데이터를 분석하고 정제하는 과정을 거칩니다.

이 과정에 대해서 보다 자세하게 이해하기 위해 다이어그램과 코드를 통해 살펴보겠습니다.

1. HttpConnectionManager의 onData 메소드 내에서 codec_인 Http1::ServerConnectionImpl에게 dispatch를 요청합니다.

connection_manager_impl.cc

Network::FilterStatus ConnectionManagerImpl::onData(Buffer::Instance& data, bool) {
  ...(중략)...

    const Status status = codec_->dispatch(data);
  ...(중략)...
}

2. ServerConnectionImpl은 내부에 존재하는 parser_ 프로퍼티를 통해서 데이터 분석을 요청합니다.

codec_impl.cc

Envoy::StatusOr<size_t> ConnectionImpl::dispatchSlice(const char* slice, size_t len) {
  ASSERT(codec_status_.ok() && dispatching_);
  const size_t nread = parser_->execute(slice, len);
  ...(중략)...

  return nread;
}

legacy_parser_impl.cc

  size_t execute(const char* slice, int len) {
    return http_parser_execute(&parser_, &settings_, slice, len);
  }

parser에게 execute 요청을 보내고나면, parser는 내부적으로 사용자 데이터를 전달받아 이를 분석하는 과정을 거칠 것입니다. 그리고 이전 포스팅을 통해 설명했듯이 사전에 정의된 ParserCallback 함수를 통해서 분석 중간중간의 결과물을 Callback을 통해 전달합니다.

3. Parser가 사용자의 데이터를 분석하면서 가장 먼저 onMessageBegin 콜백 함수가 실행됩니다.

legacy_parser_impl.cc

        [](http_parser* parser) -> int {
          auto* conn_impl = static_cast<ParserCallbacks*>(parser->data);
          return static_cast<int>(conn_impl->onMessageBegin());
        },

4. 해당 콜백 함수를 전달받은 ServerConnectionImpl은 ActiveRequest 인스턴스를 생성합니다.

codec_impl.cc

Status ServerConnectionImpl::onMessageBeginBase() {
  if (!resetStreamCalled()) {
    ASSERT(active_request_ == nullptr);
    active_request_ = std::make_unique<ActiveRequest>(*this, std::move(bytes_meter_before_stream_));
    ...(중략)...
  }
  return okStatus();
}

5. ActiveRequest를 만든 이후에 ActiveStream을 새로 생성하기 위해 HttpConnectionManager에게 생성을 요청합니다.

codec_impl.cc

Status ServerConnectionImpl::onMessageBeginBase() {
  if (!resetStreamCalled()) {
    ...(중략)...
    active_request_->request_decoder_ = &callbacks_.newStream(active_request_->response_encoder_);
    ...(중략)...
  }
  return okStatus();
}

6. HttpConnectionManager에서는 새로운 ActiveStream을 생성합니다. 이때 HttpConnectionManager가 보유한 filter_factories 정보 또한 같이 참조하여 ActiveStream 인스턴스 내에 filter_manager_를 구성합니다.

conn_manager_impl.cc

RequestDecoder& ConnectionManagerImpl::newStream(ResponseEncoder& response_encoder,
                                                 bool is_internally_created) {
  TRACE_EVENT("core", "ConnectionManagerImpl::newStream");
  if (connection_idle_timer_) {
    connection_idle_timer_->disableTimer();
  }

  ENVOY_CONN_LOG(debug, "new stream", read_callbacks_->connection());

  Buffer::BufferMemoryAccountSharedPtr downstream_stream_account =
      response_encoder.getStream().account();

  if (downstream_stream_account == nullptr) {
    // Create account, wiring the stream to use it for tracking bytes.
    // If tracking is disabled, the wiring becomes a NOP.
    auto& buffer_factory = read_callbacks_->connection().dispatcher().getWatermarkFactory();
    downstream_stream_account = buffer_factory.createAccount(response_encoder.getStream());
    response_encoder.getStream().setAccount(downstream_stream_account);
  }

  ActiveStreamPtr new_stream(new ActiveStream(*this, response_encoder.getStream().bufferLimit(),
                                              std::move(downstream_stream_account)));

  accumulated_requests_++;
  if (config_.maxRequestsPerConnection() > 0 &&
      accumulated_requests_ >= config_.maxRequestsPerConnection()) {
    if (codec_->protocol() < Protocol::Http2) {
      new_stream->state_.saw_connection_close_ = true;
      // Prevent erroneous debug log of closing due to incoming connection close header.
      drain_state_ = DrainState::Closing;
    } else if (drain_state_ == DrainState::NotDraining) {
      startDrainSequence();
    }
    ENVOY_CONN_LOG(debug, "max requests per connection reached", read_callbacks_->connection());
    stats_.named_.downstream_cx_max_requests_reached_.inc();
  }

  ...(중략)...
  return **streams_.begin();
}

이때 먼저, config에 지정된 max_requests_per_connection을 넘겼는지 확인합니다. 해당 작업은 하나의 Connection 내부에서 여러 Stream이 생성될 때 이를 제한하기 위한 용도로 사용됩니다.

7. Stream 생성이 완료되면, HttpConnectionManager 내부에 존재하는 streams_ List에 추가하고 이를 반환합니다.

conn_manager_impl.cc

RequestDecoder& ConnectionManagerImpl::newStream(ResponseEncoder& response_encoder,
                                                 bool is_internally_created) {
  ...(중략)...
  LinkedList::moveIntoList(std::move(new_stream), streams_);
  return **streams_.begin();
}

8. Stream 인스턴스가 반환되면, 이를 ActiveRequest의 request_decoder_에 저장합니다.

위와 같은 8단계 과정을 거치게되면, 사용자 요청 처리를 위해 초기화 과정이 수행되는 것을 알 수 있습니다. 또한 그 과정에서 ActiveRequest와 Stream 요청 처리를 위한 ActiveStream이 내부적으로 생성되어 저장됨을 확인할 수 있습니다.

초기화 작업이 모두 완료되면, 이후에는 본격적으로 데이터 parsing 작업을 시작합니다. 해당 과정을 살펴보면 다음과 같습니다.

9. 분석 과정에서 먼저 원격지 호출 URL이 무엇인지를 parser가 분석하고 이에 대한 Event를 전파하기 위하여 onUrl 콜백 함수를 호출합니다.

legacy_parser_impl.cc

        [](http_parser* parser, const char* at, size_t length) -> int {
          auto* conn_impl = static_cast<ParserCallbacks*>(parser->data);
          return static_cast<int>(conn_impl->onUrl(at, length));
        },

10. ServerConnectionImpl은 해당 콜백 함수를 호출받으면, 내부에 존재하는 ActiveRequest의 request_url에 parsing된 값을 매핑합니다.

codec_impl.cc

CallbackResult ConnectionImpl::onUrl(const char* data, size_t length) {
  return setAndCheckCallbackStatus(onUrlBase(data, length));
}

codec_impl.cc

Status ServerConnectionImpl::onUrlBase(const char* data, size_t length) {
  if (active_request_) {
    active_request_->request_url_.append(data, length);

    RETURN_IF_ERROR(checkMaxHeadersSize());
  }

  return okStatus();
}

codec_impl.cc

Status ConnectionImpl::checkMaxHeadersSize() {
  const uint32_t total = getHeadersSize();
  if (total > (max_headers_kb_ * 1024)) {
    const absl::string_view header_type =
        processing_trailers_ ? Http1HeaderTypes::get().Trailers : Http1HeaderTypes::get().Headers;
    error_code_ = Http::Code::RequestHeaderFieldsTooLarge;
    RETURN_IF_ERROR(sendProtocolError(Http1ResponseCodeDetails::get().HeadersTooLarge));
    return codecProtocolError(
        absl::StrCat("http/1.1 protocol error: ", header_type, " size exceeds limit"));
  }
  return okStatus();
}

또한 이 과정에서 현재까지 분석된 Header의 길이가 max_headers_kb에 지정된 값(기본 60)을 넘는지를 검증하는 작업 또한 진행합니다.

11. Url 분석 작업이 완료된 이후에는 본격적으로 입력 값 Header를 분석하여 채우기 시작합니다. 이때 Header의 명을 Parsing 했을 경우에는 onHeaderField 콜백을 호출하고, Header의 값을 분석했을 때는 onHeaderValue 콜백을 호출합니다.

12. Header 명과 값을 모두 추출한 경우에는 해당 값을 headers_or_trailers_ 라는 Map에 입력합니다. 해당 자료구조는 Header의 필드명을 Key로 값을 Value로 하는 Map 구조로써 향후 Http 정보를 요청할 때 활용됩니다.

codec_impl.cc

Status ConnectionImpl::completeCurrentHeader() {
  ASSERT(dispatching_);
  ENVOY_CONN_LOG(trace, "completed header: key={} value={}", connection_,
                 current_header_field_.getStringView(), current_header_value_.getStringView());
  auto& headers_or_trailers = headersOrTrailers();

  // Account for ":" and "\r\n" bytes between the header key value pair.
  getBytesMeter().addHeaderBytesReceived(CRLF_SIZE + 1);

  // TODO(10646): Switch to use HeaderUtility::checkHeaderNameForUnderscores().
  RETURN_IF_ERROR(checkHeaderNameForUnderscores());
  if (!current_header_field_.empty()) {
    // Strip trailing whitespace of the current header value if any. Leading whitespace was trimmed
    // in ConnectionImpl::onHeaderValue. http_parser does not strip leading or trailing whitespace
    // as the spec requires: https://tools.ietf.org/html/rfc7230#section-3.2.4
    current_header_value_.rtrim();

    // If there is a stateful formatter installed, remember the original header key before
    // converting to lower case.
    auto formatter = headers_or_trailers.formatter();
    if (formatter.has_value()) {
      formatter->processKey(current_header_field_.getStringView());
    }
    current_header_field_.inlineTransform([](char c) { return absl::ascii_tolower(c); });

    headers_or_trailers.addViaMove(std::move(current_header_field_),
                                   std::move(current_header_value_));
  }

  // Check if the number of headers exceeds the limit.
  if (headers_or_trailers.size() > max_headers_count_) {
    error_code_ = Http::Code::RequestHeaderFieldsTooLarge;
    RETURN_IF_ERROR(sendProtocolError(Http1ResponseCodeDetails::get().TooManyHeaders));
    const absl::string_view header_type =
        processing_trailers_ ? Http1HeaderTypes::get().Trailers : Http1HeaderTypes::get().Headers;
    return codecProtocolError(
        absl::StrCat("http/1.1 protocol error: ", header_type, " count exceeds limit"));
  }

  header_parsing_state_ = HeaderParsingState::Field;
  ASSERT(current_header_field_.empty());
  ASSERT(current_header_value_.empty());
  return okStatus();
}

이번에는 Header 분석이 모두 완료되었을 때 흐름에 대해서 살펴보겠습니다. 해당 과정은 이전에 살펴봤던 Cluster Manager에서의 역할과 Http filter 중 하나인 Router Filter 등이 사용되므로 해당 과정을 이해하기 위해서는 이전 시리즈의 내용에 대한 개념 숙지가 반드시 필요합니다.

13. Parser로 부터 Header 분석이 완료되면, onHeaderComplete 콜백 함수를 호출합니다.

legacy_parser_impl.cc

        [](http_parser* parser) -> int {
          auto* conn_impl = static_cast<ParserCallbacks*>(parser->data);
          return static_cast<int>(conn_impl->onHeadersComplete());
        },

14. 해당 콜백 함수는 ServerConnectionImpl에 지정된 onHeaderCompleteImpl 메서드를 호출합니다.

codec_impl.cc

CallbackResult ConnectionImpl::onHeadersComplete() {
  return setAndCheckCallbackStatusOr(onHeadersCompleteImpl());
}

15. Header를 분석하는 과정에서 저장되었던 headers_or_trailers_ Map에서 RequestMap을 추출합니다. 해당 자료구조는 Http 요청에 필요한 헤더 및 요청에 필요한 속성이 포함된 자료구조입니다.

codec_impl.cc

StatusOr<CallbackResult> ConnectionImpl::onHeadersCompleteImpl() {
  ...(중략)...
  RequestOrResponseHeaderMap& request_or_response_headers = requestOrResponseHeaders();
  ...(중략)...
}

codec_impl.h

  RequestOrResponseHeaderMap& requestOrResponseHeaders() override {
    return *absl::get<RequestHeaderMapPtr>(headers_or_trailers_);
  }

16. RequestMap에 기존 ActiveRequest에서 보관중이던 request_url을 추출하여 Upstream 대상 Url을 설정합니다. 이 과정에서 추가로 Method 타입 또한 지정합니다.

codec_impl.cc

StatusOr<CallbackResult> ConnectionImpl::onHeadersCompleteImpl() {
  ...(중략)...

  auto statusor = onHeadersCompleteBase();
  ...(중략)...
}

codec_impl.cc

Envoy::StatusOr<CallbackResult> ServerConnectionImpl::onHeadersCompleteBase() {
  // Handle the case where response happens prior to request complete. It's up to upper layer code
  // to disconnect the connection but we shouldn't fire any more events since it doesn't make
  // sense.
  if (active_request_) {
    auto& headers = absl::get<RequestHeaderMapPtr>(headers_or_trailers_);
    ...(중략)...

    // Inform the response encoder about any HEAD method, so it can set content
    // length and transfer encoding headers correctly.
    const Http::HeaderValues& header_values = Http::Headers::get();
    active_request_->response_encoder_.setIsResponseToHeadRequest(parser_->methodName() ==
                                                                  header_values.MethodValues.Head);
    active_request_->response_encoder_.setIsResponseToConnectRequest(
        parser_->methodName() == header_values.MethodValues.Connect);

    RETURN_IF_ERROR(handlePath(*headers, parser_->methodName()));
    
    ASSERT(active_request_->request_url_.empty());
    headers->setMethod(parser_->methodName());
    ...(중략)...
  }

  return CallbackResult::Success;
}

codec_impl.cc

Status ServerConnectionImpl::handlePath(RequestHeaderMap& headers, absl::string_view method) {
  const Http::HeaderValues& header_values = Http::Headers::get();
  HeaderString path(header_values.Path);

  bool is_connect = (method == header_values.MethodValues.Connect);

  // The url is relative or a wildcard when the method is OPTIONS. Nothing to do here.
  if (!is_connect && !active_request_->request_url_.getStringView().empty() &&
      (active_request_->request_url_.getStringView()[0] == '/' ||
       (method == header_values.MethodValues.Options &&
        active_request_->request_url_.getStringView()[0] == '*'))) {
    headers.addViaMove(std::move(path), std::move(active_request_->request_url_));
    return okStatus();
  }

  // If absolute_urls and/or connect are not going be handled, copy the url and return.
  // This forces the behavior to be backwards compatible with the old codec behavior.
  // CONNECT "urls" are actually host:port so look like absolute URLs to the above checks.
  // Absolute URLS in CONNECT requests will be rejected below by the URL class validation.
  if (!codec_settings_.allow_absolute_url_ && !is_connect) {
    headers.addViaMove(std::move(path), std::move(active_request_->request_url_));
    return okStatus();
  }

  Utility::Url absolute_url;
  if (!absolute_url.initialize(active_request_->request_url_.getStringView(), is_connect)) {
    RETURN_IF_ERROR(sendProtocolError(Http1ResponseCodeDetails::get().InvalidUrl));
    return codecProtocolError("http/1.1 protocol error: invalid url in request line");
  }
  // RFC7230#5.7
  // When a proxy receives a request with an absolute-form of
  // request-target, the proxy MUST ignore the received Host header field
  // (if any) and instead replace it with the host information of the
  // request-target. A proxy that forwards such a request MUST generate a
  // new Host field-value based on the received request-target rather than
  // forward the received Host field-value.
  headers.setHost(absolute_url.hostAndPort());
  // Add the scheme and validate to ensure no https://
  // requests are accepted over unencrypted connections by front-line Envoys.
  if (!is_connect) {
    headers.setScheme(absolute_url.scheme());
    if (!HeaderUtility::schemeIsValid(absolute_url.scheme())) {
      RETURN_IF_ERROR(sendProtocolError(Http1ResponseCodeDetails::get().InvalidScheme));
      return codecProtocolError("http/1.1 protocol error: invalid scheme");
    }
    if (codec_settings_.validate_scheme_ &&
        absolute_url.scheme() == header_values.SchemeValues.Https && !connection().ssl()) {
      error_code_ = Http::Code::Forbidden;
      RETURN_IF_ERROR(sendProtocolError(Http1ResponseCodeDetails::get().HttpsInPlaintext));
      return codecProtocolError("http/1.1 protocol error: https in the clear");
    }
  }

  if (!absolute_url.pathAndQueryParams().empty()) {
    headers.setPath(absolute_url.pathAndQueryParams());
  }
  active_request_->request_url_.clear();
  return okStatus();
}

17. ActiveRequest에 지정된 request_decoder_ 즉 ActiveStream에게 Header 처리를 위임합니다. 이 과정에서 RequestMap을 인자로 전달합니다.

codec_impl.cc

Envoy::StatusOr<CallbackResult> ServerConnectionImpl::onHeadersCompleteBase() {
    ...(중략)...
    if (parser_->isChunked() ||
        (parser_->contentLength().has_value() && parser_->contentLength().value() > 0) ||
        handling_upgrade_) {
      active_request_->request_decoder_->decodeHeaders(std::move(headers), false);

      // If the connection has been closed (or is closing) after decoding headers, pause the parser
      // so we return control to the caller.
      if (connection_.state() != Network::Connection::State::Open) {
        return parser_->pause();
      }
    } else {
      deferred_end_stream_headers_ = true;
    }
  }

  return CallbackResult::Success;
}

18. ActiveStream에서는 내부에 존재하는 filter_manager_ 에게 먼저 Downstream의 주소와 전달받은 RequestMap을 토대로 만든 header 정보를 매핑합니다. 매핑이 완료되면, 그 이후에는 filter_manager_가 보유한 filter chain을 생성합니다.

참고로 filter_manager_는 ActiveStream이 생성되는 당시에 HttpConnectionManager로 부터 filter_factories_ 의 정보를 전달받았으며, filter chain 생성을 요청받으면, filter_factories_가 보유한 factory 콜백 메소드를 실행시켜 filter를 내부에 생성하는 작업을 수행합니다.

filter 생성이 모두 완료되면, 해당 filter chain을 순회하면서 header 정보 처리를 위임합니다.

19. Http filter 종류 중 하나인 Router filter가 filter chain 가장 마지막에 호출됩니다.

20. Router filter에서는 Upstream 대상 Host 정보와 Connection Pool을 획득하기 위해 우선 ClusterEntry 정보를 ClusterManager에게 요청합니다.

21. Cluster Manager는 자신이 보유하고 있는 thread_local_clusters_ 에서 Router가 요청한 Cluster 정보를 찾습니다.

22. Cluster Manager로 부터 ThreadLocalCluster를 찾아서 Router로 반환합니다.

23. Router에서는 Cluster내 존재하는 host를 통해 Connection 연결을 수행해야합니다. 따라서 전달받은 ThreadLocalCluster를 통해서 Connection Pool 할당을 요청합니다.

24. 이를 전달받은 ThreadLocalCluster(Cluster Entry)는 Cluster Manager에게 요청하여 host_http_conn_pool_map에 할당 받은 Connection Pool이 존재하는지를 확인합니다. 만약 존재한다면, 해당 Connection Pool Map에 있는 Container에 접근합니다. 반면, 존재하지 않는다면 새로운 Container를 생성하여 해당 Map에 추가합니다.

25. Container 내부에는 Cluster 별로 Connection을 관리하는 Pool이 존재합니다. 여기에서 Pool 존재여부를 최종적으로 확인합니다.

26. 최초 접근시에는 Pool이 생성되지 않았을 것이기 때문에 먼저 Cluster가 Connection Pool을 생성이 가능한지 설정된 Resource Limit 설정 값을 살펴봅니다.

27. Resource Limit 설정 값에 이상이 없어 신규 Pool 생성이 가능하면, ClusterManager에게 Pool 할당을 요청합니다. 이때 ClusterManager는 Client가 요구하는 프로토콜이 무엇인지 확인한 다음 해당 요청을 처리할 수 있는 Connection을 생성하여 반환합니다. 그리고 생성된 Pool을 Container가 보유하고 있는 active_pools_에 삽입합니다.

28. 생성된 Pool을 ThreadLocalCluster(Cluster Entry)에 반환합니다.

29. Pool을 Router에게 반환합니다. Router는 전달받은 Pool 정보를 기반으로 Upstream Connection을 생성하기 위해 UpstreamRequest를 생성합니다. 그리고 생성된 UpstreamRequest를 자신이 보유하고 있는 upstream_requests_ 리스트에 추가합니다.

여기서 UpstreamRequest는 전달받은 Connection Pool을 기반으로 Upstream에 연결을 요청하기 위해 설정된 자료구조로써 해당 자료구조를 통해 상위 Host와 통신을 수행할 수 있습니다. 해당 자료구조에 대해서 조금 더 살펴보면 다음과 같습니다.

UpstreamRequest 구조에서 핵심 속성은 위와 같습니다. 위 속성에 대해서 하나씩 살펴보겠습니다.

먼저 conn_pool_은 UpstreamRequest를 관리하는 Connection Pool을 가르키는 포인터입니다. 해당 속성은 이전 ThreadLocalCluster를 통해서 전달받았던 Connection Pool을 가르키고 있습니다. 따라서 해당 Pool을 통해 사용자 요청 Stream을 매핑시킴으로써 데이터 송/수신 역할 처리를 담당할 수 있도록 가교 역할을 수행합니다.

conn_pool_ 내부를 조금 더 살펴보겠습니다. Connection Pool 내부에는 Client를 관리하는 list가 존재합니다. 다만 Connection Pool 내부에 존재하는 Client가 상태가 모두 다를 수 있기 때문에 이를 관리하기 위한 여러 자료구조가 존재합니다.

가령 Connection Pool에서 생성된 Client는 위 그림과 같이 상태를 내부 속성으로 지니고 있는데, 상태가 Ready, Busy, Draining 등에 따라 재사용 가능 여부가 결정됩니다. 그 이유는 현재 Client 사용중인데, 해당 Client를 재사용하게된다면 이는 올바른 서비스를 제공할 수 없기 때문입니다.

따라서 현재 재사용이 가능한 Client 목록을 지니고 있는 ready_clients_, 현재 Stream 처리가 진행중이거나 Drain을 수행중인 Client 목록을 보유하는 busy_clients 그리고 연결을 시도중인 Client 목록을 보유하고 있는 connecting_clients_ 등 여러 자료구조가 존재합니다.

해당 자료구조는 Client의 상태 변이에 따라 저장되는 리스트가 다르며, 만약 재사용이 가능한 ready_clients_ 에서 Client를 사용하여 해당 Client가 Connecting을 수행한다면 connectiong_clients_로 Client 목록이 이동하게 됩니다.

이번에는 Upstream의 filter_manager에 대해서 살펴보겠습니다.

upstream_request.cc

  // Set up the upstream filter manager.
  filter_manager_callbacks_ = std::make_unique<UpstreamRequestFilterManagerCallbacks>(*this);
  filter_manager_ = std::make_unique<UpstreamFilterManager>(
      *filter_manager_callbacks_, parent_.callbacks()->dispatcher(),
      parent_.callbacks()->connection(), parent_.callbacks()->streamId(),
      parent_.callbacks()->account(), true, parent_.callbacks()->decoderBufferLimit(),
      *parent_.cluster(), *this);
  parent_.cluster()->createFilterChain(*filter_manager_);
  // The cluster will always create a codec filter, which sets the upstream

UpstreamRequest 내부 filter_manager는 Upstream 요청을 처리하기 위한 filter를 생성하고 관리하는 역할을 수행합니다.

upstream_codec_filter.h

class UpstreamCodecFilterFactory
    : public Extensions::HttpFilters::Common::CommonFactoryBase<
          envoy::extensions::filters::http::upstream_codec::v3::UpstreamCodec>,
      public Server::Configuration::UpstreamHttpFilterConfigFactory {
public:
  UpstreamCodecFilterFactory() : CommonFactoryBase("envoy.filters.http.upstream_codec") {}

  std::string category() const override { return "envoy.filters.http.upstream"; }
  Http::FilterFactoryCb
  createFilterFactoryFromProto(const Protobuf::Message&, const std::string&,
                               Server::Configuration::UpstreamHttpFactoryContext&) override {
    return [](Http::FilterChainFactoryCallbacks& callbacks) -> void {
      callbacks.addStreamDecoderFilter(std::make_shared<UpstreamCodecFilter>());
    };
  }
  bool isTerminalFilterByProtoTyped(
      const envoy::extensions::filters::http::upstream_codec::v3::UpstreamCodec&,
      Server::Configuration::ServerFactoryContext&) override {
    return true;
  }
};

이때 내부적으로는 위 코드와 같이 UpstreamCodecFilterFactory에 의해서 UpstreamCodecFilter가 UpstreamRequest의 filter chain으로 등록되며, 향후 Upstream 요청을처리하는 역할을 수행합니다.

마지막으로 살펴볼 것은 stream_info_와 upstream_ 속성입니다. stream_info의 경우 현재 Upstream의 메타정보를 관리하는 속성이며, upstream_의 경우 이 다음에 바로 설명하겠지만, UpstreamRequest가 생성된 이후 사용자 요청을 처리하기 위한 헤더 정보 매핑, 해당 요청을 처리해야할 encoder 등의 속성을 지니고 있는 자료구조로써 Upstream 처리를 수행합니다.

지금까지 UpstreamRequest 내부에 포함된 주요 속성에 대해서 살펴봤는데요. 이번에는 UpstreamRequest를 생성한 다음 후속 과정에 대해서 살펴보겠습니다.

30. Router 에서는 upstream_requests_ 에 추가된 UpstreamRequest에게 Header 정보를 전달합니다.

31. UpstreamRequest 내부에서는 내부에 매핑된 pool을 통해 Client를 해당 Pool에 매핑하도록 요청합니다.

32. Pool 내부에는 ready_clients_ 를 먼저 살펴보고 연결 가능한 목록이 존재하면 해당 목록에 존재하는 Client 목록을 얻어와서 현재 Stream을 연결하도록 합니다.

conn_pool_base.cc

  if (!ready_clients_.empty()) {
    ActiveClient& client = *ready_clients_.front();
    ENVOY_CONN_LOG(debug, "using existing fully connected connection", client);
    attachStreamToClient(client, context);
    // Even if there's a ready client, we may want to preconnect to handle the next incoming stream.
    tryCreateNewConnections();
    return nullptr;
  }

이때 위 코드와 같이 먼저 ready_clients_ 로부터 재사용이 가능한 Client 목록이 존재하는지 살펴보고 만약 존재한다면 해당 Client를 재사용하여 사용자의 Context를 해당 Client에게 연결시킵니다.

conn_pool_base.cc

  if (!host_->cluster().resourceManager(priority_).pendingRequests().canCreate()) {
    ENVOY_LOG(debug, "max pending streams overflow");
    onPoolFailure(nullptr, absl::string_view(), ConnectionPool::PoolFailureReason::Overflow,
                  context);
    host_->cluster().stats().upstream_rq_pending_overflow_.inc();
    return nullptr;
  }

하지만 ready_clients_ 목록에 연결 가능한 Client가 존재하지 않는다면, 해당 Host에 연결된 설정을 토대로 pending request 생성 여부를 판별한 다음 해당 설정을 넘어선 Stream 요청이 들어왔을 경우는 연결을 해제하도록 합니다.

반면 Stream 생성이 가능하다면, 해당 요청은 HttpPendingStream으로 생성하여 Pool에 보유한 pending_streams_ 리스트에 이를 추가합니다.

그리고 이렇게 등록된 pending_streams_는 주기적으로 Dispatcher에 존재하는 baseScheduler에 의해서 관리됩니다.

conn_pool_base.cc

void ConnPoolImplBase::onUpstreamReady() {
  while (!pending_streams_.empty() && !ready_clients_.empty()) {
    ActiveClientPtr& client = ready_clients_.front();
    ENVOY_CONN_LOG(debug, "attaching to next stream", *client);
    // Pending streams are pushed onto the front, so pull from the back.
    attachStreamToClient(*client, pending_streams_.back()->context());
    state_.decrPendingStreams(1);
    pending_streams_.pop_back();
  }
  if (!pending_streams_.empty()) {
    tryCreateNewConnections();
  }
}

이때 주기적으로 호출되는 메소드는 onUpstreamReady이며, 해당 메소드의 역할을 살펴보면, pending_streams에 존재하는 stream을 살펴보고 호출 당시 ready_clients_에 재사용 가능한 client가 존재한다면, 해당 client에 pending_streams에 존재하는 stream을 연결시켜주는 역할을 수행하는 것을 볼 수 있습니다.

33. HttpUpstream이 생성되면 UpstreamRequest에 할당하여 이후 해당 Stream을 통해 Upstream과 연결을 수행할 수 있습니다.

지금까지 살펴볼 것은 Header가 분석이 완료된 이후 후속 작업에 대해서 살펴봤습니다. 해당 과정을 요약하자면, Header 정보를 파싱하여 이를 별도 Map에 저장하는 것은 물론 Cluster Manager와 협업을 통해서 Connection Pool을 할당받고 해당 Pool에 존재하는 Client에 연결을 수행하여 Upstream을 만드는 작업을 진행합니다. 이번에는 Http Request의 본문을 파싱하고 이를 해석하는 과정에 대해서 살펴보겠습니다.

34. Parser에서 본문을 분석한 다음 bufferBody callback 함수를 호출합니다.

35. bufferBody를 호출받으면 이를 다시 bufferBody 함수를 호추하여 후속 작업을 이어갑니다.

legacy_parser_impl.cc

static_cast<ParserCallbacks*>(parser->data)->bufferBody(at, length);
return 0;

codec_impl.cc

void ConnectionImpl::bufferBody(const char* data, size_t length) {
  auto slice = current_dispatching_buffer_->frontSlice();
  if (data == slice.mem_ && length == slice.len_) {
    buffered_body_.move(*current_dispatching_buffer_, length);
    dispatching_slice_already_drained_ = true;
  } else {
    buffered_body_.add(data, length);
  }
}

ServerConnectionImpl은 bufferBody 내부에서 전달받은 데이터를 내부의 buffer_body_에 추가합니다.

36. Body 파싱이 모두 완료되면 Parser는 onMessageComplete callback 함수를 호출합니다.

legacy_parser_impl.cc

auto* conn_impl = static_cast<ParserCallbacks*>(parser->data);
return static_cast<int>(conn_impl->onMessageComplete());

37.

1850:

[](http_parser* parser) -> int {

auto* conn_impl = static_cast<ParserCallbacks*>(parser->data);

return static_cast<int>(conn_impl->onHeadersComplete());

codec_impl.cc

CallbackResult ConnectionImpl::onHeadersComplete() {
  return setAndCheckCallbackStatusOr(onHeadersCompleteImpl());
}

codec_impl.cc

CallbackResult ConnectionImpl::onHeadersComplete() {
  return setAndCheckCallbackStatusOr(onHeadersCompleteImpl());
}

codec_impl.cc

StatusOr<CallbackResult> ConnectionImpl::onHeadersCompleteImpl() {
  ASSERT(!processing_trailers_);
  ASSERT(dispatching_);
  ENVOY_CONN_LOG(trace, "onHeadersCompleteBase", connection_);
  RETURN_IF_ERROR(completeCurrentHeader());

  if (!parser_->isHttp11()) {
    // This is not necessarily true, but it's good enough since higher layers only care if this is
    // HTTP/1.1 or not.
    protocol_ = Protocol::Http10;
  }
  RequestOrResponseHeaderMap& request_or_response_headers = requestOrResponseHeaders();
  const Http::HeaderValues& header_values = Http::Headers::get();
  if (Utility::isUpgrade(request_or_response_headers) && upgradeAllowed()) {
    // Ignore h2c upgrade requests until we support them.
    // See https://github.com/envoyproxy/envoy/issues/7161 for details.
    if (absl::EqualsIgnoreCase(request_or_response_headers.getUpgradeValue(),
                               header_values.UpgradeValues.H2c)) {
      ENVOY_CONN_LOG(trace, "removing unsupported h2c upgrade headers.", connection_);
      request_or_response_headers.removeUpgrade();
      if (request_or_response_headers.Connection()) {
        const auto& tokens_to_remove = caseUnorderdSetContainingUpgradeAndHttp2Settings();
        std::string new_value = StringUtil::removeTokens(
            request_or_response_headers.getConnectionValue(), ",", tokens_to_remove, ",");
        if (new_value.empty()) {
          request_or_response_headers.removeConnection();
        } else {
          request_or_response_headers.setConnection(new_value);
        }
      }
      request_or_response_headers.remove(header_values.Http2Settings);
    } else {
      ENVOY_CONN_LOG(trace, "codec entering upgrade mode.", connection_);
      handling_upgrade_ = true;
    }
  }
  if (parser_->methodName() == header_values.MethodValues.Connect) {
    if (request_or_response_headers.ContentLength()) {
      if (request_or_response_headers.getContentLengthValue() == "0") {
        request_or_response_headers.removeContentLength();
      } else {
        // Per https://tools.ietf.org/html/rfc7231#section-4.3.6 a payload with a
        // CONNECT request has no defined semantics, and may be rejected.
        error_code_ = Http::Code::BadRequest;
        RETURN_IF_ERROR(sendProtocolError(Http1ResponseCodeDetails::get().BodyDisallowed));
        return codecProtocolError("http/1.1 protocol error: unsupported content length");
      }
    }
    ENVOY_CONN_LOG(trace, "codec entering upgrade mode for CONNECT request.", connection_);
    handling_upgrade_ = true;
  }

  // https://tools.ietf.org/html/rfc7230#section-3.3.3
  // If a message is received with both a Transfer-Encoding and a
  // Content-Length header field, the Transfer-Encoding overrides the
  // Content-Length. Such a message might indicate an attempt to
  // perform request smuggling (Section 9.5) or response splitting
  // (Section 9.4) and ought to be handled as an error. A sender MUST
  // remove the received Content-Length field prior to forwarding such
  // a message.

#ifndef ENVOY_ENABLE_UHV
  // This check is moved into default header validator.
  // TODO(yanavlasov): use runtime override here when UHV is moved into the main build

  // Reject message with Http::Code::BadRequest if both Transfer-Encoding and Content-Length
  // headers are present or if allowed by http1 codec settings and 'Transfer-Encoding'
  // is chunked - remove Content-Length and serve request.
  if (parser_->hasTransferEncoding() != 0 && request_or_response_headers.ContentLength()) {
    if (parser_->isChunked() && codec_settings_.allow_chunked_length_) {
      request_or_response_headers.removeContentLength();
    } else {
      error_code_ = Http::Code::BadRequest;
      RETURN_IF_ERROR(sendProtocolError(Http1ResponseCodeDetails::get().ChunkedContentLength));
      return codecProtocolError(
          "http/1.1 protocol error: both 'Content-Length' and 'Transfer-Encoding' are set.");
    }
  }
#endif

  // Per https://tools.ietf.org/html/rfc7230#section-3.3.1 Envoy should reject
  // transfer-codings it does not understand.
  // Per https://tools.ietf.org/html/rfc7231#section-4.3.6 a payload with a
  // CONNECT request has no defined semantics, and may be rejected.
  if (request_or_response_headers.TransferEncoding()) {
    const absl::string_view encoding = request_or_response_headers.getTransferEncodingValue();
    if (!absl::EqualsIgnoreCase(encoding, header_values.TransferEncodingValues.Chunked) ||
        parser_->methodName() == header_values.MethodValues.Connect) {
      error_code_ = Http::Code::NotImplemented;
      RETURN_IF_ERROR(sendProtocolError(Http1ResponseCodeDetails::get().InvalidTransferEncoding));
      return codecProtocolError("http/1.1 protocol error: unsupported transfer encoding");
    }
  }

  auto statusor = onHeadersCompleteBase();
  if (!statusor.ok()) {
    RETURN_IF_ERROR(statusor.status());
  }

  header_parsing_state_ = HeaderParsingState::Done;

  // Returning CallbackResult::NoBodyData informs http_parser to not expect a body or further data
  // on this connection.
  return handling_upgrade_ ? CallbackResult::NoBodyData : statusor.value();
}

codec_impl.cc

Envoy::StatusOr<CallbackResult> ServerConnectionImpl::onHeadersCompleteBase() {
  // Handle the case where response happens prior to request complete. It's up to upper layer code
  // to disconnect the connection but we shouldn't fire any more events since it doesn't make
  // sense.
  if (active_request_) {
    auto& headers = absl::get<RequestHeaderMapPtr>(headers_or_trailers_);
    ENVOY_CONN_LOG(trace, "Server: onHeadersComplete size={}", connection_, headers->size());

    if (!handling_upgrade_ && headers->Connection()) {
      // If we fail to sanitize the request, return a 400 to the client
      if (!Utility::sanitizeConnectionHeader(*headers)) {
        absl::string_view header_value = headers->getConnectionValue();
        ENVOY_CONN_LOG(debug, "Invalid nominated headers in Connection: {}", connection_,
                       header_value);
        error_code_ = Http::Code::BadRequest;
        RETURN_IF_ERROR(
            sendProtocolError(Http1ResponseCodeDetails::get().ConnectionHeaderSanitization));
        return codecProtocolError("Invalid nominated headers in Connection.");
      }
    }

    // Inform the response encoder about any HEAD method, so it can set content
    // length and transfer encoding headers correctly.
    const Http::HeaderValues& header_values = Http::Headers::get();
    active_request_->response_encoder_.setIsResponseToHeadRequest(parser_->methodName() ==
                                                                  header_values.MethodValues.Head);
    active_request_->response_encoder_.setIsResponseToConnectRequest(
        parser_->methodName() == header_values.MethodValues.Connect);

    RETURN_IF_ERROR(handlePath(*headers, parser_->methodName()));
    ASSERT(active_request_->request_url_.empty());

    headers->setMethod(parser_->methodName());

    // Make sure the host is valid.
    auto details = HeaderUtility::requestHeadersValid(*headers);
    if (details.has_value()) {
      RETURN_IF_ERROR(sendProtocolError(details.value().get()));
      return codecProtocolError(
          "http/1.1 protocol error: request headers failed spec compliance checks");
    }

    // Determine here whether we have a body or not. This uses the new RFC semantics where the
    // presence of content-length or chunked transfer-encoding indicates a body vs. a particular
    // method. If there is no body, we defer raising decodeHeaders() until the parser is flushed
    // with message complete. This allows upper layers to behave like HTTP/2 and prevents a proxy
    // scenario where the higher layers stream through and implicitly switch to chunked transfer
    // encoding because end stream with zero body length has not yet been indicated.
    if (parser_->isChunked() ||
        (parser_->contentLength().has_value() && parser_->contentLength().value() > 0) ||
        handling_upgrade_) {
      active_request_->request_decoder_->decodeHeaders(std::move(headers), false);

      // If the connection has been closed (or is closing) after decoding headers, pause the parser
      // so we return control to the caller.
      if (connection_.state() != Network::Connection::State::Open) {
        return parser_->pause();
      }
    } else {
      deferred_end_stream_headers_ = true;
    }
  }

  return CallbackResult::Success;
}

1934:

[](http_parser* parser) -> int {

auto* conn_impl = static_cast<ParserCallbacks*>(parser->data);

return static_cast<int>(conn_impl->onMessageComplete());

codec_impl.cc

CallbackResult ConnectionImpl::onMessageComplete() {
  return setAndCheckCallbackStatusOr(onMessageCompleteImpl());
}

codec_impl.cc

StatusOr<CallbackResult> ConnectionImpl::onMessageCompleteImpl() {
  ENVOY_CONN_LOG(trace, "message complete", connection_);

  dispatchBufferedBody();

  if (handling_upgrade_) {
    // If this is an upgrade request, swallow the onMessageComplete. The
    // upgrade payload will be treated as stream body.
    ASSERT(!deferred_end_stream_headers_);
    ENVOY_CONN_LOG(trace, "Pausing parser due to upgrade.", connection_);
    return parser_->pause();
  }

  // If true, this indicates we were processing trailers and must
  // move the last header into current_header_map_
  if (header_parsing_state_ == HeaderParsingState::Value) {
    RETURN_IF_ERROR(completeCurrentHeader());
  }

  return onMessageCompleteBase();
}

codec_impl.cc

void ConnectionImpl::dispatchBufferedBody() {
  ASSERT(parser_->getStatus() == ParserStatus::Ok || parser_->getStatus() == ParserStatus::Paused);
  ASSERT(codec_status_.ok());
  if (buffered_body_.length() > 0) {
    onBody(buffered_body_);
    buffered_body_.drain(buffered_body_.length());
  }
}

body에서 추출할게 있으면 추출한다.

codec_impl.cc

CallbackResult ServerConnectionImpl::onMessageCompleteBase() {
  ASSERT(!handling_upgrade_);
  if (active_request_) {

    // The request_decoder should be non-null after we've called the newStream on callbacks.
    ASSERT(active_request_->request_decoder_);
    active_request_->remote_complete_ = true;

    if (deferred_end_stream_headers_) {
      active_request_->request_decoder_->decodeHeaders(
          std::move(absl::get<RequestHeaderMapPtr>(headers_or_trailers_)), true);
      deferred_end_stream_headers_ = false;
    } else if (processing_trailers_) {
      active_request_->request_decoder_->decodeTrailers(
          std::move(absl::get<RequestTrailerMapPtr>(headers_or_trailers_)));
    } else {
      Buffer::OwnedImpl buffer;
      active_request_->request_decoder_->decodeData(buffer, true);
    }

    // Reset to ensure no information from one requests persists to the next.
    headers_or_trailers_.emplace<RequestHeaderMapPtr>(nullptr);
  }

  // Always pause the parser so that the calling code can process 1 request at a time and apply
  // back pressure. However this means that the calling code needs to detect if there is more data
  // in the buffer and dispatch it again.
  return parser_->pause();
}

conn_manager_impl.cc

// Ordering in this function is complicated, but important.
//
// We want to do minimal work before selecting route and creating a filter
// chain to maximize the number of requests which get custom filter behavior,
// e.g. registering access logging.
//
// This must be balanced by doing sanity checking for invalid requests (one
// can't route select properly without full headers), checking state required to
// serve error responses (connection close, head requests, etc), and
// modifications which may themselves affect route selection.
void ConnectionManagerImpl::ActiveStream::decodeHeaders(RequestHeaderMapPtr&& headers,
                                                        bool end_stream) {
  ENVOY_STREAM_LOG(debug, "request headers complete (end_stream={}):\n{}", *this, end_stream,
                   *headers);
  ScopeTrackerScopeState scope(this,
                               connection_manager_.read_callbacks_->connection().dispatcher());
  request_headers_ = std::move(headers);
  filter_manager_.requestHeadersInitialized();
  if (request_header_timer_ != nullptr) {
    request_header_timer_->disableTimer();
    request_header_timer_.reset();
  }

  // Both saw_connection_close_ and is_head_request_ affect local replies: set
  // them as early as possible.
  const Protocol protocol = connection_manager_.codec_->protocol();
  state_.saw_connection_close_ = HeaderUtility::shouldCloseConnection(protocol, *request_headers_);

  // We end the decode here to mark that the downstream stream is complete.
  maybeEndDecode(end_stream);

  if (!validateHeaders()) {
    ENVOY_STREAM_LOG(debug, "request headers validation failed\n{}", *this, *request_headers_);
    return;
  }

  // We need to snap snapped_route_config_ here as it's used in mutateRequestHeaders later.
  if (connection_manager_.config_.isRoutable()) {
    if (connection_manager_.config_.routeConfigProvider() != nullptr) {
      snapped_route_config_ = connection_manager_.config_.routeConfigProvider()->configCast();
    } else if (connection_manager_.config_.scopedRouteConfigProvider() != nullptr) {
      snapped_scoped_routes_config_ =
          connection_manager_.config_.scopedRouteConfigProvider()->config<Router::ScopedConfig>();
      snapScopedRouteConfig();
    }
  } else {
    snapped_route_config_ = connection_manager_.config_.routeConfigProvider()->configCast();
  }

  // Drop new requests when overloaded as soon as we have decoded the headers.
  if (connection_manager_.random_generator_.bernoulli(
          connection_manager_.overload_stop_accepting_requests_ref_.value())) {
    // In this one special case, do not create the filter chain. If there is a risk of memory
    // overload it is more important to avoid unnecessary allocation than to create the filters.
    filter_manager_.skipFilterChainCreation();
    connection_manager_.stats_.named_.downstream_rq_overload_close_.inc();
    sendLocalReply(Http::Code::ServiceUnavailable, "envoy overloaded", nullptr, absl::nullopt,
                   StreamInfo::ResponseCodeDetails::get().Overload);
    return;
  }

  if (!connection_manager_.config_.proxy100Continue() && request_headers_->Expect() &&
      // The Expect field-value is case-insensitive.
      // https://tools.ietf.org/html/rfc7231#section-5.1.1
      absl::EqualsIgnoreCase((request_headers_->Expect()->value().getStringView()),
                             Headers::get().ExpectValues._100Continue)) {
    // Note in the case Envoy is handling 100-Continue complexity, it skips the filter chain
    // and sends the 100-Continue directly to the encoder.
    chargeStats(continueHeader());
    response_encoder_->encode1xxHeaders(continueHeader());
    // Remove the Expect header so it won't be handled again upstream.
    request_headers_->removeExpect();
  }

  connection_manager_.user_agent_.initializeFromHeaders(*request_headers_,
                                                        connection_manager_.stats_.prefixStatName(),
                                                        connection_manager_.stats_.scope_);

  // Make sure we are getting a codec version we support.
  if (protocol == Protocol::Http10) {
    // Assume this is HTTP/1.0. This is fine for HTTP/0.9 but this code will also affect any
    // requests with non-standard version numbers (0.9, 1.3), basically anything which is not
    // HTTP/1.1.
    //
    // The protocol may have shifted in the HTTP/1.0 case so reset it.
    filter_manager_.streamInfo().protocol(protocol);
    if (!connection_manager_.config_.http1Settings().accept_http_10_) {
      // Send "Upgrade Required" if HTTP/1.0 support is not explicitly configured on.
      sendLocalReply(Code::UpgradeRequired, "", nullptr, absl::nullopt,
                     StreamInfo::ResponseCodeDetails::get().LowVersion);
      return;
    }
    if (!request_headers_->Host() &&
        !connection_manager_.config_.http1Settings().default_host_for_http_10_.empty()) {
      // Add a default host if configured to do so.
      request_headers_->setHost(
          connection_manager_.config_.http1Settings().default_host_for_http_10_);
    }
  }

  if (!request_headers_->Host()) {
    // Require host header. For HTTP/1.1 Host has already been translated to :authority.
    sendLocalReply(Code::BadRequest, "", nullptr, absl::nullopt,
                   StreamInfo::ResponseCodeDetails::get().MissingHost);
    return;
  }

  // Verify header sanity checks which should have been performed by the codec.
  ASSERT(HeaderUtility::requestHeadersValid(*request_headers_).has_value() == false);

  // Check for the existence of the :path header for non-CONNECT requests, or present-but-empty
  // :path header for CONNECT requests. We expect the codec to have broken the path into pieces if
  // applicable. NOTE: Currently the HTTP/1.1 codec only does this when the allow_absolute_url flag
  // is enabled on the HCM.
  if ((!HeaderUtility::isConnect(*request_headers_) || request_headers_->Path()) &&
      request_headers_->getPathValue().empty()) {
    sendLocalReply(Code::NotFound, "", nullptr, absl::nullopt,
                   StreamInfo::ResponseCodeDetails::get().MissingPath);
    return;
  }

  // Currently we only support relative paths at the application layer.
  if (!request_headers_->getPathValue().empty() && request_headers_->getPathValue()[0] != '/') {
    connection_manager_.stats_.named_.downstream_rq_non_relative_path_.inc();
    sendLocalReply(Code::NotFound, "", nullptr, absl::nullopt,
                   StreamInfo::ResponseCodeDetails::get().AbsolutePath);
    return;
  }

  // Path sanitization should happen before any path access other than the above sanity check.
  const auto action =
      ConnectionManagerUtility::maybeNormalizePath(*request_headers_, connection_manager_.config_);
  // gRPC requests are rejected if Envoy is configured to redirect post-normalization. This is
  // because gRPC clients do not support redirect.
  if (action == ConnectionManagerUtility::NormalizePathAction::Reject ||
      (action == ConnectionManagerUtility::NormalizePathAction::Redirect &&
       Grpc::Common::hasGrpcContentType(*request_headers_))) {
    connection_manager_.stats_.named_.downstream_rq_failed_path_normalization_.inc();
    sendLocalReply(Code::BadRequest, "", nullptr, absl::nullopt,
                   StreamInfo::ResponseCodeDetails::get().PathNormalizationFailed);
    return;
  } else if (action == ConnectionManagerUtility::NormalizePathAction::Redirect) {
    connection_manager_.stats_.named_.downstream_rq_redirected_with_normalized_path_.inc();
    sendLocalReply(
        Code::TemporaryRedirect, "",
        [new_path = request_headers_->Path()->value().getStringView()](
            Http::ResponseHeaderMap& response_headers) -> void {
          response_headers.addReferenceKey(Http::Headers::get().Location, new_path);
        },
        absl::nullopt, StreamInfo::ResponseCodeDetails::get().PathNormalizationFailed);
    return;
  }

  ASSERT(action == ConnectionManagerUtility::NormalizePathAction::Continue);
  auto optional_port = ConnectionManagerUtility::maybeNormalizeHost(
      *request_headers_, connection_manager_.config_, localPort());
  if (optional_port.has_value() &&
      requestWasConnect(request_headers_, connection_manager_.codec_->protocol())) {
    filter_manager_.streamInfo().filterState()->setData(
        Router::OriginalConnectPort::key(),
        std::make_unique<Router::OriginalConnectPort>(optional_port.value()),
        StreamInfo::FilterState::StateType::ReadOnly, StreamInfo::FilterState::LifeSpan::Request);
  }

  if (!state_.is_internally_created_) { // Only sanitize headers on first pass.
    // Modify the downstream remote address depending on configuration and headers.
    const auto mutate_result = ConnectionManagerUtility::mutateRequestHeaders(
        *request_headers_, connection_manager_.read_callbacks_->connection(),
        connection_manager_.config_, *snapped_route_config_, connection_manager_.local_info_);

    // IP detection failed, reject the request.
    if (mutate_result.reject_request.has_value()) {
      const auto& reject_request_params = mutate_result.reject_request.value();
      connection_manager_.stats_.named_.downstream_rq_rejected_via_ip_detection_.inc();
      sendLocalReply(reject_request_params.response_code, reject_request_params.body, nullptr,
                     absl::nullopt,
                     StreamInfo::ResponseCodeDetails::get().OriginalIPDetectionFailed);
      return;
    }

    filter_manager_.setDownstreamRemoteAddress(mutate_result.final_remote_address);
  }
  ASSERT(filter_manager_.streamInfo().downstreamAddressProvider().remoteAddress() != nullptr);

  ASSERT(!cached_route_);
  refreshCachedRoute();

  if (!state_.is_internally_created_) { // Only mutate tracing headers on first pass.
    filter_manager_.streamInfo().setTraceReason(
        ConnectionManagerUtility::mutateTracingRequestHeader(
            *request_headers_, connection_manager_.runtime_, connection_manager_.config_,
            cached_route_.value().get()));
  }

  filter_manager_.streamInfo().setRequestHeaders(*request_headers_);

  const bool upgrade_rejected = filter_manager_.createFilterChain() == false;

  // TODO if there are no filters when starting a filter iteration, the connection manager
  // should return 404. The current returns no response if there is no router filter.
  if (hasCachedRoute()) {
    // Do not allow upgrades if the route does not support it.
    if (upgrade_rejected) {
      // While downstream servers should not send upgrade payload without the upgrade being
      // accepted, err on the side of caution and refuse to process any further requests on this
      // connection, to avoid a class of HTTP/1.1 smuggling bugs where Upgrade or CONNECT payload
      // contains a smuggled HTTP request.
      state_.saw_connection_close_ = true;
      connection_manager_.stats_.named_.downstream_rq_ws_on_non_ws_route_.inc();
      sendLocalReply(Code::Forbidden, "", nullptr, absl::nullopt,
                     StreamInfo::ResponseCodeDetails::get().UpgradeFailed);
      return;
    }
    // Allow non websocket requests to go through websocket enabled routes.
  }

  // Check if tracing is enabled.
  if (connection_manager_tracing_config_.has_value()) {
    traceRequest();
  }

  filter_manager_.decodeHeaders(*request_headers_, end_stream);

  // Reset it here for both global and overridden cases.
  resetIdleTimer();
}

위 과정에서 이제 connectionManager와 결합하여 Connection을 만든다.
과정을 조금 자세히 살펴보면 다음과 같다.

header_utility.cc

bool HeaderUtility::shouldCloseConnection(Http::Protocol protocol,
                                          const RequestOrResponseHeaderMap& headers) {
  // HTTP/1.0 defaults to single-use connections. Make sure the connection will be closed unless
  // Keep-Alive is present.
  if (protocol == Protocol::Http10 &&
      (!headers.Connection() ||
       !Envoy::StringUtil::caseFindToken(headers.Connection()->value().getStringView(), ",",
                                         Http::Headers::get().ConnectionValues.KeepAlive))) {
    return true;
  }

  if (protocol == Protocol::Http11 && headers.Connection() &&
      Envoy::StringUtil::caseFindToken(headers.Connection()->value().getStringView(), ",",
                                       Http::Headers::get().ConnectionValues.Close)) {
    return true;
  }

  // Note: Proxy-Connection is not a standard header, but is supported here
  // since it is supported by http-parser the underlying parser for http
  // requests.
  if (protocol < Protocol::Http2 && headers.ProxyConnection() &&
      Envoy::StringUtil::caseFindToken(headers.ProxyConnection()->value().getStringView(), ",",
                                       Http::Headers::get().ConnectionValues.Close)) {
    return true;
  }
  return false;
}

먼저 shouldCloseCOnnection을 통해서 해당 프로토콜이 http2이하인지를 살펴보고 종료 여부를 결정한다.

conn_manager_impl.cc

void ConnectionManagerImpl::ActiveStream::maybeEndDecode(bool end_stream) {
  // If recreateStream is called, the HCM rewinds state and may send more encodeData calls.
  if (end_stream && !filter_manager_.remoteDecodeComplete()) {
    filter_manager_.streamInfo().downstreamTiming().onLastDownstreamRxByteReceived(
        connection_manager_.read_callbacks_->connection().dispatcher().timeSource());
    ENVOY_STREAM_LOG(debug, "request end stream", *this);
  }
}

그 다음에 end_stream이면서 decode 완료 여부를 확인한다.

conn_manager_impl.cc

void ConnectionManagerImpl::ActiveStream::decodeHeaders(RequestHeaderMapPtr&& headers,
                                                        bool end_stream) {
  ....(중략)...

  // We need to snap snapped_route_config_ here as it's used in mutateRequestHeaders later.
  if (connection_manager_.config_.isRoutable()) {
    if (connection_manager_.config_.routeConfigProvider() != nullptr) {
      snapped_route_config_ = connection_manager_.config_.routeConfigProvider()->configCast();
    } else if (connection_manager_.config_.scopedRouteConfigProvider() != nullptr) {
      snapped_scoped_routes_config_ =
          connection_manager_.config_.scopedRouteConfigProvider()->config<Router::ScopedConfig>();
      snapScopedRouteConfig();
    }
  } else {
    snapped_route_config_ = connection_manager_.config_.routeConfigProvider()->configCast();
  }

 ...(중략)...
}

Connection Manager로부터 Route Config가 존재하는지를 확인하고 존재하면 해당 Config 정보를 가져온다. 만약 ScopedRouteConfig가 설정되어있으면, 해당 정보를 가져오고 그렇지 않을 경우에는 Route 정보를 가져올 것이다.

conn_manager_impl.cc

void ConnectionManagerImpl::ActiveStream::snapScopedRouteConfig() {
  // NOTE: if a RDS subscription hasn't got a RouteConfiguration back, a Router::NullConfigImpl is
  // returned, in that case we let it pass.
  snapped_route_config_ = snapped_scoped_routes_config_->getRouteConfig(*request_headers_);
  if (snapped_route_config_ == nullptr) {
    ENVOY_STREAM_LOG(trace, "can't find SRDS scope.", *this);
    // TODO(stevenzzzz): Consider to pass an error message to router filter, so that it can
    // send back 404 with some more details.
    snapped_route_config_ = std::make_shared<Router::NullConfigImpl>();
  }
}

scoped_config_impl.cc

Router::ConfigConstSharedPtr
ScopedConfigImpl::getRouteConfig(const Http::HeaderMap& headers) const {
  ScopeKeyPtr scope_key = scope_key_builder_.computeScopeKey(headers);
  if (scope_key == nullptr) {
    return nullptr;
  }
  auto iter = scoped_route_info_by_key_.find(scope_key->hash());
  if (iter != scoped_route_info_by_key_.end()) {
    return iter->second->routeConfig();
  }
  return nullptr;
}

그외 route를 위한 사전 작업을 수행한다.

conn_manager_impl.cc

void ConnectionManagerImpl::ActiveStream::decodeHeaders(RequestHeaderMapPtr&& headers,
                                                        bool end_stream) {
  ...(중략)...

  if (!state_.is_internally_created_) { // Only sanitize headers on first pass.
    // Modify the downstream remote address depending on configuration and headers.
    const auto mutate_result = ConnectionManagerUtility::mutateRequestHeaders(
        *request_headers_, connection_manager_.read_callbacks_->connection(),
        connection_manager_.config_, *snapped_route_config_, connection_manager_.local_info_);

    // IP detection failed, reject the request.
    if (mutate_result.reject_request.has_value()) {
      const auto& reject_request_params = mutate_result.reject_request.value();
      connection_manager_.stats_.named_.downstream_rq_rejected_via_ip_detection_.inc();
      sendLocalReply(reject_request_params.response_code, reject_request_params.body, nullptr,
                     absl::nullopt,
                     StreamInfo::ResponseCodeDetails::get().OriginalIPDetectionFailed);
      return;
    }

    filter_manager_.setDownstreamRemoteAddress(mutate_result.final_remote_address);
  }
  ...(중략)...
}

그 다음에 하는 일은 DownStreamRemoteAddress를 확인해서 설정하는 작업을 수행한다.

filter_manager.h

  void setDownstreamRemoteAddress(
      const Network::Address::InstanceConstSharedPtr& downstream_remote_address) {
    stream_info_.setDownstreamRemoteAddress(downstream_remote_address);
  }

conn_manager_impl.cc

void ConnectionManagerImpl::ActiveStream::decodeHeaders(RequestHeaderMapPtr&& headers,
                                                        bool end_stream) {
  ...(중략)...

  refreshCachedRoute();

  if (!state_.is_internally_created_) { // Only mutate tracing headers on first pass.
    filter_manager_.streamInfo().setTraceReason(
        ConnectionManagerUtility::mutateTracingRequestHeader(
            *request_headers_, connection_manager_.runtime_, connection_manager_.config_,
            cached_route_.value().get()));
  }

  filter_manager_.streamInfo().setRequestHeaders(*request_headers_);

  const bool upgrade_rejected = filter_manager_.createFilterChain() == false;

  // TODO if there are no filters when starting a filter iteration, the connection manager
  // should return 404. The current returns no response if there is no router filter.
  if (hasCachedRoute()) {
    // Do not allow upgrades if the route does not support it.
    if (upgrade_rejected) {
      // While downstream servers should not send upgrade payload without the upgrade being
      // accepted, err on the side of caution and refuse to process any further requests on this
      // connection, to avoid a class of HTTP/1.1 smuggling bugs where Upgrade or CONNECT payload
      // contains a smuggled HTTP request.
      state_.saw_connection_close_ = true;
      connection_manager_.stats_.named_.downstream_rq_ws_on_non_ws_route_.inc();
      sendLocalReply(Code::Forbidden, "", nullptr, absl::nullopt,
                     StreamInfo::ResponseCodeDetails::get().UpgradeFailed);
      return;
    }
    // Allow non websocket requests to go through websocket enabled routes.
  }

  // Check if tracing is enabled.
  if (connection_manager_tracing_config_.has_value()) {
    traceRequest();
  }

  filter_manager_.decodeHeaders(*request_headers_, end_stream);

  // Reset it here for both global and overridden cases.
  resetIdleTimer();
}

그 다음에는 refreshCachedRoute()을 호출하여 Route를 결정한다.

conn_manager_impl.cc

void ConnectionManagerImpl::ActiveStream::refreshCachedRoute() { refreshCachedRoute(nullptr); }

conn_manager_impl.cc

void ConnectionManagerImpl::ActiveStream::refreshCachedRoute(const Router::RouteCallback& cb) {
  Router::RouteConstSharedPtr route;
  if (request_headers_ != nullptr) {
    if (connection_manager_.config_.isRoutable() &&
        connection_manager_.config_.scopedRouteConfigProvider() != nullptr) {
      // NOTE: re-select scope as well in case the scope key header has been changed by a filter.
      snapScopedRouteConfig();
    }
    if (snapped_route_config_ != nullptr) {
      route = snapped_route_config_->route(cb, *request_headers_, filter_manager_.streamInfo(),
                                           stream_id_);
    }
  }

  setRoute(route);
}

conn_manager_impl.cc

void ConnectionManagerImpl::ActiveStream::snapScopedRouteConfig() {
  // NOTE: if a RDS subscription hasn't got a RouteConfiguration back, a Router::NullConfigImpl is
  // returned, in that case we let it pass.
  snapped_route_config_ = snapped_scoped_routes_config_->getRouteConfig(*request_headers_);
  if (snapped_route_config_ == nullptr) {
    ENVOY_STREAM_LOG(trace, "can't find SRDS scope.", *this);
    // TODO(stevenzzzz): Consider to pass an error message to router filter, so that it can
    // send back 404 with some more details.
    snapped_route_config_ = std::make_shared<Router::NullConfigImpl>();
  }
}

conn_manager_impl.cc

Router::RouteConstSharedPtr
ConnectionManagerImpl::ActiveStream::route(const Router::RouteCallback& cb) {
  if (cached_route_.has_value()) {
    return cached_route_.value();
  }
  refreshCachedRoute(cb);
  return cached_route_.value();
}

conn_manager_impl.cc

/**
 * Sets the cached route to the RouteConstSharedPtr argument passed in. Handles setting the
 * cached_route_/cached_cluster_info_ ActiveStream attributes, the FilterManager streamInfo, tracing
 * tags, and timeouts.
 *
 * Declared as a StreamFilterCallbacks member function for filters to call directly, but also
 * functions as a helper to refreshCachedRoute(const Router::RouteCallback& cb).
 */
void ConnectionManagerImpl::ActiveStream::setRoute(Router::RouteConstSharedPtr route) {
  filter_manager_.streamInfo().route_ = route;
  cached_route_ = std::move(route);
  if (nullptr == filter_manager_.streamInfo().route() ||
      nullptr == filter_manager_.streamInfo().route()->routeEntry()) {
    cached_cluster_info_ = nullptr;
  } else {
    Upstream::ThreadLocalCluster* local_cluster =
        connection_manager_.cluster_manager_.getThreadLocalCluster(
            filter_manager_.streamInfo().route()->routeEntry()->clusterName());
    cached_cluster_info_ = (nullptr == local_cluster) ? nullptr : local_cluster->info();
  }

  filter_manager_.streamInfo().setUpstreamClusterInfo(cached_cluster_info_.value());
  refreshCachedTracingCustomTags();
  refreshDurationTimeout();
  refreshIdleTimeout();
}

cluster_manager_impl.cc

ThreadLocalCluster* ClusterManagerImpl::getThreadLocalCluster(absl::string_view cluster) {
  ThreadLocalClusterManagerImpl& cluster_manager = *tls_;

  auto entry = cluster_manager.thread_local_clusters_.find(cluster);
  if (entry != cluster_manager.thread_local_clusters_.end()) {
    return entry->second.get();
  } else {
    return nullptr;
  }
}

stream_info_impl.h

  void setUpstreamClusterInfo(
      const Upstream::ClusterInfoConstSharedPtr& upstream_cluster_info) override {
    upstream_cluster_info_ = upstream_cluster_info;
  }

upstream cluster 정보를 등록하고 만약 tracing 정보가 추가되어야한다면 해당 정보를 추가한다.
그리고 Timeout 관련해서 refresh를 수행한다.

stream_info_impl.h

  void setUpstreamClusterInfo(
      const Upstream::ClusterInfoConstSharedPtr& upstream_cluster_info) override {
    upstream_cluster_info_ = upstream_cluster_info;
  }

conn_manager_impl.cc

void ConnectionManagerImpl::ActiveStream::decodeHeaders(RequestHeaderMapPtr&& headers,
                                                        bool end_stream) {
  ...(중략)...

  filter_manager_.streamInfo().setRequestHeaders(*request_headers_);

  ...(중략)...

  // Check if tracing is enabled.
  if (connection_manager_tracing_config_.has_value()) {
    traceRequest();
  }

  filter_manager_.decodeHeaders(*request_headers_, end_stream);

  // Reset it here for both global and overridden cases.
  resetIdleTimer();
}

그 다음에는 filter_manager에게 request header 정보를 저장하고 decodeheaders를 통해서 Route 과정을 수행할 수 있또록 진행한다.

filter_manager.h

  void decodeHeaders(RequestHeaderMap& headers, bool end_stream) {
    state_.remote_decode_complete_ = end_stream;
    decodeHeaders(nullptr, headers, end_stream);
  }

filter_manager.cc

void FilterManager::decodeHeaders(ActiveStreamDecoderFilter* filter, RequestHeaderMap& headers,
                                  bool end_stream) {
  // Headers filter iteration should always start with the next filter if available.
  std::list<ActiveStreamDecoderFilterPtr>::iterator entry =
      commonDecodePrefix(filter, FilterIterationStartState::AlwaysStartFromNext);
  std::list<ActiveStreamDecoderFilterPtr>::iterator continue_data_entry = decoder_filters_.end();

  for (; entry != decoder_filters_.end(); entry++) {
    ASSERT(!(state_.filter_call_state_ & FilterCallState::DecodeHeaders));
    state_.filter_call_state_ |= FilterCallState::DecodeHeaders;
    (*entry)->end_stream_ = (end_stream && continue_data_entry == decoder_filters_.end());
    FilterHeadersStatus status = (*entry)->decodeHeaders(headers, (*entry)->end_stream_);
    if (state_.decoder_filter_chain_aborted_) {
      ENVOY_STREAM_LOG(trace,
                       "decodeHeaders filter iteration aborted due to local reply: filter={}",
                       *this, (*entry)->filter_context_.config_name);
      status = FilterHeadersStatus::StopIteration;
    }

    ASSERT(!(status == FilterHeadersStatus::ContinueAndDontEndStream && !(*entry)->end_stream_),
           "Filters should not return FilterHeadersStatus::ContinueAndDontEndStream from "
           "decodeHeaders when end_stream is already false");

    state_.filter_call_state_ &= ~FilterCallState::DecodeHeaders;
    ENVOY_STREAM_LOG(trace, "decode headers called: filter={} status={}", *this,
                     (*entry)->filter_context_.config_name, static_cast<uint64_t>(status));

    (*entry)->decode_headers_called_ = true;

    const auto continue_iteration = (*entry)->commonHandleAfterHeadersCallback(status, end_stream);
    ENVOY_BUG(!continue_iteration || !state_.local_complete_,
              "Filter did not return StopAll or StopIteration after sending a local reply.");

    // If this filter ended the stream, decodeComplete() should be called for it.
    if ((*entry)->end_stream_) {
      (*entry)->handle_->decodeComplete();
    }

    // Skip processing metadata after sending local reply
    if (state_.local_complete_ && std::next(entry) != decoder_filters_.end()) {
      maybeContinueDecoding(continue_data_entry);
      return;
    }

    const bool new_metadata_added = processNewlyAddedMetadata();
    // If end_stream is set in headers, and a filter adds new metadata, we need to delay end_stream
    // in headers by inserting an empty data frame with end_stream set. The empty data frame is sent
    // after the new metadata.
    if ((*entry)->end_stream_ && new_metadata_added && !buffered_request_data_) {
      Buffer::OwnedImpl empty_data("");
      ENVOY_STREAM_LOG(
          trace, "inserting an empty data frame for end_stream due metadata being added.", *this);
      // Metadata frame doesn't carry end of stream bit. We need an empty data frame to end the
      // stream.
      addDecodedData(*((*entry).get()), empty_data, true);
    }

    if (!continue_iteration && std::next(entry) != decoder_filters_.end()) {
      // Stop iteration IFF this is not the last filter. If it is the last filter, continue with
      // processing since we need to handle the case where a terminal filter wants to buffer, but
      // a previous filter has added body.
      maybeContinueDecoding(continue_data_entry);
      return;
    }

    // Here we handle the case where we have a header only request, but a filter adds a body
    // to it. We need to not raise end_stream = true to further filters during inline iteration.
    if (end_stream && buffered_request_data_ && continue_data_entry == decoder_filters_.end()) {
      continue_data_entry = entry;
    }
  }

  maybeContinueDecoding(continue_data_entry);

  if (end_stream) {
    disarmRequestTimeout();
  }
}

그러면 HTTP Connection Manager에는 cors, fault, router 등과 같은 필터가 있을 수 있는데, 해당 필터를 수행한다. 여기서는 router가 수행됨을 가정해보자.

router\config.cc

Http::FilterFactoryCb RouterFilterConfig::createFilterFactoryFromProtoTyped(
    const envoy::extensions::filters::http::router::v3::Router& proto_config,
    const std::string& stat_prefix, Server::Configuration::FactoryContext& context) {
  Stats::StatNameManagedStorage prefix(stat_prefix, context.scope().symbolTable());
  Router::FilterConfigSharedPtr filter_config(new Router::FilterConfig(
      prefix.statName(), context,
      std::make_unique<Router::ShadowWriterImpl>(context.clusterManager()), proto_config));

  return [filter_config](Http::FilterChainFactoryCallbacks& callbacks) -> void {
    callbacks.addStreamDecoderFilter(
        std::make_shared<Router::ProdFilter>(*filter_config, filter_config->default_stats_));
  };
}

filter_manager.h

  void addStreamDecoderFilter(ActiveStreamDecoderFilterPtr filter) {
    // Note: configured decoder filters are appended to decoder_filters_.
    // This means that if filters are configured in the following order (assume all three filters
    // are both decoder/encoder filters):
    //   http_filters:
    //     - A
    //     - B
    //     - C
    // The decoder filter chain will iterate through filters A, B, C.
    LinkedList::moveIntoListBack(std::move(filter), decoder_filters_);
  }

참고로 Router 필터 등록 시에는 위와 같은 필터가 decoder_filters로 등록되어있다.

router.cc

Http::FilterHeadersStatus Filter::decodeHeaders(Http::RequestHeaderMap& headers, bool end_stream) {
  downstream_headers_ = &headers;

  // Extract debug configuration from filter state. This is used further along to determine whether
  // we should append cluster and host headers to the response, and whether to forward the request
  // upstream.
  const StreamInfo::FilterStateSharedPtr& filter_state = callbacks_->streamInfo().filterState();
  const DebugConfig* debug_config = filter_state->getDataReadOnly<DebugConfig>(DebugConfig::key());

  // TODO: Maybe add a filter API for this.
  grpc_request_ = Grpc::Common::isGrpcRequestHeaders(headers);
  exclude_http_code_stats_ = grpc_request_ && config_.suppress_grpc_request_failure_code_stats_;

  // Only increment rq total stat if we actually decode headers here. This does not count requests
  // that get handled by earlier filters.
  stats_.rq_total_.inc();

  // Initialize the `modify_headers` function as a no-op (so we don't have to remember to check it
  // against nullptr before calling it), and feed it behavior later if/when we have cluster info
  // headers to append.
  std::function<void(Http::ResponseHeaderMap&)> modify_headers = [](Http::ResponseHeaderMap&) {};

  // Determine if there is a route entry or a direct response for the request.
  route_ = callbacks_->route();
  if (!route_) {
    stats_.no_route_.inc();
    ENVOY_STREAM_LOG(debug, "no route match for URL '{}'", *callbacks_, headers.getPathValue());

    callbacks_->streamInfo().setResponseFlag(StreamInfo::ResponseFlag::NoRouteFound);
    callbacks_->sendLocalReply(Http::Code::NotFound, "", modify_headers, absl::nullopt,
                               StreamInfo::ResponseCodeDetails::get().RouteNotFound);
    return Http::FilterHeadersStatus::StopIteration;
  }

  // Determine if there is a direct response for the request.
  const auto* direct_response = route_->directResponseEntry();
  if (direct_response != nullptr) {
    stats_.rq_direct_response_.inc();
    direct_response->rewritePathHeader(headers, !config_.suppress_envoy_headers_);
    callbacks_->streamInfo().setRouteName(direct_response->routeName());
    callbacks_->sendLocalReply(
        direct_response->responseCode(), direct_response->responseBody(),
        [this, direct_response,
         &request_headers = headers](Http::ResponseHeaderMap& response_headers) -> void {
          std::string new_path;
          if (request_headers.Path()) {
            new_path = direct_response->newPath(request_headers);
          }
          // See https://tools.ietf.org/html/rfc7231#section-7.1.2.
          const auto add_location =
              direct_response->responseCode() == Http::Code::Created ||
              Http::CodeUtility::is3xx(enumToInt(direct_response->responseCode()));
          if (!new_path.empty() && add_location) {
            response_headers.addReferenceKey(Http::Headers::get().Location, new_path);
          }
          direct_response->finalizeResponseHeaders(response_headers, callbacks_->streamInfo());
        },
        absl::nullopt, StreamInfo::ResponseCodeDetails::get().DirectResponse);
    return Http::FilterHeadersStatus::StopIteration;
  }

  // A route entry matches for the request.
  route_entry_ = route_->routeEntry();
  // If there's a route specific limit and it's smaller than general downstream
  // limits, apply the new cap.
  retry_shadow_buffer_limit_ =
      std::min(retry_shadow_buffer_limit_, route_entry_->retryShadowBufferLimit());
  callbacks_->streamInfo().setRouteName(route_entry_->routeName());
  if (debug_config && debug_config->append_cluster_) {
    // The cluster name will be appended to any local or upstream responses from this point.
    modify_headers = [this, debug_config](Http::ResponseHeaderMap& headers) {
      headers.addCopy(debug_config->cluster_header_.value_or(Http::Headers::get().EnvoyCluster),
                      route_entry_->clusterName());
    };
  }
  Upstream::ThreadLocalCluster* cluster =
      config_.cm_.getThreadLocalCluster(route_entry_->clusterName());
  if (!cluster) {
    stats_.no_cluster_.inc();
    ENVOY_STREAM_LOG(debug, "unknown cluster '{}'", *callbacks_, route_entry_->clusterName());

    callbacks_->streamInfo().setResponseFlag(StreamInfo::ResponseFlag::NoClusterFound);
    callbacks_->sendLocalReply(route_entry_->clusterNotFoundResponseCode(), "", modify_headers,
                               absl::nullopt,
                               StreamInfo::ResponseCodeDetails::get().ClusterNotFound);
    return Http::FilterHeadersStatus::StopIteration;
  }
  cluster_ = cluster->info();

  // Set up stat prefixes, etc.
  request_vcluster_ = route_entry_->virtualCluster(headers);
  if (request_vcluster_ != nullptr) {
    callbacks_->streamInfo().setVirtualClusterName(request_vcluster_->name());
  }
  route_stats_context_ = route_entry_->routeStatsContext();
  ENVOY_STREAM_LOG(debug, "cluster '{}' match for URL '{}'", *callbacks_,
                   route_entry_->clusterName(), headers.getPathValue());

  if (config_.strict_check_headers_ != nullptr) {
    for (const auto& header : *config_.strict_check_headers_) {
      const auto res = FilterUtility::StrictHeaderChecker::checkHeader(headers, header);
      if (!res.valid_) {
        callbacks_->streamInfo().setResponseFlag(
            StreamInfo::ResponseFlag::InvalidEnvoyRequestHeaders);
        const std::string body = fmt::format("invalid header '{}' with value '{}'",
                                             std::string(res.entry_->key().getStringView()),
                                             std::string(res.entry_->value().getStringView()));
        const std::string details =
            absl::StrCat(StreamInfo::ResponseCodeDetails::get().InvalidEnvoyRequestHeaders, "{",
                         StringUtil::replaceAllEmptySpace(res.entry_->key().getStringView()), "}");
        callbacks_->sendLocalReply(Http::Code::BadRequest, body, nullptr, absl::nullopt, details);
        return Http::FilterHeadersStatus::StopIteration;
      }
    }
  }

  const Http::HeaderEntry* request_alt_name = headers.EnvoyUpstreamAltStatName();
  if (request_alt_name) {
    alt_stat_prefix_ = std::make_unique<Stats::StatNameDynamicStorage>(
        request_alt_name->value().getStringView(), config_.scope_.symbolTable());
    headers.removeEnvoyUpstreamAltStatName();
  }

  // See if we are supposed to immediately kill some percentage of this cluster's traffic.
  if (cluster_->maintenanceMode()) {
    callbacks_->streamInfo().setResponseFlag(StreamInfo::ResponseFlag::UpstreamOverflow);
    chargeUpstreamCode(Http::Code::ServiceUnavailable, nullptr, true);
    callbacks_->sendLocalReply(
        Http::Code::ServiceUnavailable, "maintenance mode",
        [modify_headers, this](Http::ResponseHeaderMap& headers) {
          if (!config_.suppress_envoy_headers_) {
            headers.addReference(Http::Headers::get().EnvoyOverloaded,
                                 Http::Headers::get().EnvoyOverloadedValues.True);
          }
          // Note: append_cluster_info does not respect suppress_envoy_headers.
          modify_headers(headers);
        },
        absl::nullopt, StreamInfo::ResponseCodeDetails::get().MaintenanceMode);
    cluster_->stats().upstream_rq_maintenance_mode_.inc();
    return Http::FilterHeadersStatus::StopIteration;
  }

  // Fetch a connection pool for the upstream cluster.
  const auto& upstream_http_protocol_options = cluster_->upstreamHttpProtocolOptions();

  if (upstream_http_protocol_options.has_value() &&
      (upstream_http_protocol_options.value().auto_sni() ||
       upstream_http_protocol_options.value().auto_san_validation())) {
    // Default the header to Host/Authority header.
    absl::string_view header_value = headers.getHostValue();

    // Check whether `override_auto_sni_header` is specified.
    const auto override_auto_sni_header =
        upstream_http_protocol_options.value().override_auto_sni_header();
    if (!override_auto_sni_header.empty()) {
      // Use the header value from `override_auto_sni_header` to set the SNI value.
      const auto overridden_header_value = Http::HeaderUtility::getAllOfHeaderAsString(
          headers, Http::LowerCaseString(override_auto_sni_header));
      if (overridden_header_value.result().has_value() &&
          !overridden_header_value.result().value().empty()) {
        header_value = overridden_header_value.result().value();
      }
    }
    const auto parsed_authority = Http::Utility::parseAuthority(header_value);
    bool should_set_sni = !parsed_authority.is_ip_address_;
    // `host_` returns a string_view so doing this should be safe.
    absl::string_view sni_value = parsed_authority.host_;

    if (should_set_sni && upstream_http_protocol_options.value().auto_sni()) {
      callbacks_->streamInfo().filterState()->setData(
          Network::UpstreamServerName::key(),
          std::make_unique<Network::UpstreamServerName>(sni_value),
          StreamInfo::FilterState::StateType::Mutable);
    }

    if (upstream_http_protocol_options.value().auto_san_validation()) {
      callbacks_->streamInfo().filterState()->setData(
          Network::UpstreamSubjectAltNames::key(),
          std::make_unique<Network::UpstreamSubjectAltNames>(
              std::vector<std::string>{std::string(sni_value)}),
          StreamInfo::FilterState::StateType::Mutable);
    }
  }

  transport_socket_options_ = Network::TransportSocketOptionsUtility::fromFilterState(
      *callbacks_->streamInfo().filterState());

  if (auto downstream_connection = downstreamConnection(); downstream_connection != nullptr) {
    if (auto typed_state = downstream_connection->streamInfo()
                               .filterState()
                               .getDataReadOnly<Network::UpstreamSocketOptionsFilterState>(
                                   Network::UpstreamSocketOptionsFilterState::key());
        typed_state != nullptr) {
      auto downstream_options = typed_state->value();
      if (!upstream_options_) {
        upstream_options_ = std::make_shared<Network::Socket::Options>();
      }
      Network::Socket::appendOptions(upstream_options_, downstream_options);
    }
  }

  if (upstream_options_ && callbacks_->getUpstreamSocketOptions()) {
    Network::Socket::appendOptions(upstream_options_, callbacks_->getUpstreamSocketOptions());
  }

  std::unique_ptr<GenericConnPool> generic_conn_pool = createConnPool(*cluster);

  if (!generic_conn_pool) {
    sendNoHealthyUpstreamResponse();
    return Http::FilterHeadersStatus::StopIteration;
  }
  Upstream::HostDescriptionConstSharedPtr host = generic_conn_pool->host();

  if (debug_config && debug_config->append_upstream_host_) {
    // The hostname and address will be appended to any local or upstream responses from this point,
    // possibly in addition to the cluster name.
    modify_headers = [modify_headers, debug_config, host](Http::ResponseHeaderMap& headers) {
      modify_headers(headers);
      headers.addCopy(
          debug_config->hostname_header_.value_or(Http::Headers::get().EnvoyUpstreamHostname),
          host->hostname());
      headers.addCopy(debug_config->host_address_header_.value_or(
                          Http::Headers::get().EnvoyUpstreamHostAddress),
                      host->address()->asString());
    };
  }

  // If we've been instructed not to forward the request upstream, send an empty local response.
  if (debug_config && debug_config->do_not_forward_) {
    modify_headers = [modify_headers, debug_config](Http::ResponseHeaderMap& headers) {
      modify_headers(headers);
      headers.addCopy(
          debug_config->not_forwarded_header_.value_or(Http::Headers::get().EnvoyNotForwarded),
          "true");
    };
    callbacks_->sendLocalReply(Http::Code::NoContent, "", modify_headers, absl::nullopt, "");
    return Http::FilterHeadersStatus::StopIteration;
  }

  hedging_params_ = FilterUtility::finalHedgingParams(*route_entry_, headers);

  timeout_ = FilterUtility::finalTimeout(*route_entry_, headers, !config_.suppress_envoy_headers_,
                                         grpc_request_, hedging_params_.hedge_on_per_try_timeout_,
                                         config_.respect_expected_rq_timeout_);

  const Http::HeaderEntry* header_max_stream_duration_entry =
      headers.EnvoyUpstreamStreamDurationMs();
  if (header_max_stream_duration_entry) {
    dynamic_max_stream_duration_ =
        FilterUtility::tryParseHeaderTimeout(*header_max_stream_duration_entry);
    headers.removeEnvoyUpstreamStreamDurationMs();
  }

  // If this header is set with any value, use an alternate response code on timeout
  if (headers.EnvoyUpstreamRequestTimeoutAltResponse()) {
    timeout_response_code_ = Http::Code::NoContent;
    headers.removeEnvoyUpstreamRequestTimeoutAltResponse();
  }

  include_attempt_count_in_request_ = route_entry_->includeAttemptCountInRequest();
  if (include_attempt_count_in_request_) {
    headers.setEnvoyAttemptCount(attempt_count_);
  }

  // The router has reached a point where it is going to try to send a request upstream,
  // so now modify_headers should attach x-envoy-attempt-count to the downstream response if the
  // config flag is true.
  if (route_entry_->includeAttemptCountInResponse()) {
    modify_headers = [modify_headers, this](Http::ResponseHeaderMap& headers) {
      modify_headers(headers);

      // This header is added without checking for config_.suppress_envoy_headers_ to mirror what is
      // done for upstream requests.
      headers.setEnvoyAttemptCount(attempt_count_);
    };
  }
  callbacks_->streamInfo().setAttemptCount(attempt_count_);

  route_entry_->finalizeRequestHeaders(headers, callbacks_->streamInfo(),
                                       !config_.suppress_envoy_headers_);
  FilterUtility::setUpstreamScheme(
      headers, callbacks_->streamInfo().downstreamAddressProvider().sslConnection() != nullptr);

  // Ensure an http transport scheme is selected before continuing with decoding.
  ASSERT(headers.Scheme());

  retry_state_ =
      createRetryState(route_entry_->retryPolicy(), headers, *cluster_, request_vcluster_,
                       route_stats_context_, config_.runtime_, config_.random_,
                       callbacks_->dispatcher(), config_.timeSource(), route_entry_->priority());

  // Determine which shadow policies to use. It's possible that we don't do any shadowing due to
  // runtime keys. Also the method CONNECT doesn't support shadowing.
  auto method = headers.getMethodValue();
  if (method != Http::Headers::get().MethodValues.Connect) {
    for (const auto& shadow_policy : route_entry_->shadowPolicies()) {
      const auto& policy_ref = *shadow_policy;
      if (FilterUtility::shouldShadow(policy_ref, config_.runtime_, callbacks_->streamId())) {
        active_shadow_policies_.push_back(std::cref(policy_ref));
        shadow_headers_ = Http::createHeaderMap<Http::RequestHeaderMapImpl>(*downstream_headers_);
      }
    }
  }

  ENVOY_STREAM_LOG(debug, "router decoding headers:\n{}", *callbacks_, headers);

  // Hang onto the modify_headers function for later use in handling upstream responses.
  modify_headers_ = modify_headers;

  conn_pool_new_stream_with_early_data_and_http3_ =
      Runtime::runtimeFeatureEnabled(Runtime::conn_pool_new_stream_with_early_data_and_http3);
  const bool can_send_early_data =
      conn_pool_new_stream_with_early_data_and_http3_ &&
      route_entry_->earlyDataPolicy().allowsEarlyDataForRequest(*downstream_headers_);
  // Set initial HTTP/3 use based on the presence of HTTP/1.1 proxy config.
  // For retries etc, HTTP/3 usability may transition from true to false, but
  // will never transition from false to true.
  bool can_use_http3 =
      !transport_socket_options_ || !transport_socket_options_->http11ProxyInfo().has_value();
  UpstreamRequestPtr upstream_request = std::make_unique<UpstreamRequest>(
      *this, std::move(generic_conn_pool), can_send_early_data, can_use_http3);
  LinkedList::moveIntoList(std::move(upstream_request), upstream_requests_);
  upstream_requests_.front()->acceptHeadersFromRouter(end_stream);
  if (end_stream) {
    onRequestComplete();
  }

  return Http::FilterHeadersStatus::StopIteration;
}

legacy_parser_impl.cc

CallbackResult LegacyHttpParserImpl::pause() { return impl_->pause(); }

legacy_parser_impl.cc

  CallbackResult pause() {
    http_parser_pause(&parser_, 1);
    return CallbackResult::Success;
  }

http_parser.cc

void
http_parser_pause(http_parser *parser, int paused) {
  /* Users should only be pausing/unpausing a parser that is not in an error
   * state. In non-debug builds, there's not much that we can do about this
   * other than ignore it.
   */
  if (HTTP_PARSER_ERRNO(parser) == HPE_OK ||
      HTTP_PARSER_ERRNO(parser) == HPE_PAUSED) {
    uint32_t nread = parser->nread; /* used by the SET_ERRNO macro */
    SET_ERRNO((paused) ? HPE_PAUSED : HPE_OK);
  } else {
    assert(0 && "Attempting to pause parser in error state");
  }
}

Parsing 과정이 끝나면 다시 dispatchSlice에서부터 시작함

codec_impl.cc

Envoy::StatusOr<size_t> ConnectionImpl::dispatchSlice(const char* slice, size_t len) {
  ASSERT(codec_status_.ok() && dispatching_);
  const size_t nread = parser_->execute(slice, len);
  if (!codec_status_.ok()) {
    return codec_status_;
  }

  const ParserStatus status = parser_->getStatus();
  if (status != ParserStatus::Ok && status != ParserStatus::Paused) {
    absl::string_view error = Http1ResponseCodeDetails::get().HttpCodecError;
    if (Runtime::runtimeFeatureEnabled("envoy.reloadable_features.http1_use_balsa_parser")) {
      if (parser_->errorMessage() == "headers size exceeds limit" ||
          parser_->errorMessage() == "trailers size exceeds limit") {
        error = Http1ResponseCodeDetails::get().HeadersTooLarge;
      } else if (parser_->errorMessage() == "header value contains invalid chars") {
        error = Http1ResponseCodeDetails::get().InvalidCharacters;
      }
    }
    RETURN_IF_ERROR(sendProtocolError(error));
    // Avoid overwriting the codec_status_ set in the callbacks.
    ASSERT(codec_status_.ok());
    codec_status_ =
        codecProtocolError(absl::StrCat("http/1.1 protocol error: ", parser_->errorMessage()));
    return codec_status_;
  }

  return nread;
}

Parsing 과정이 끝나면 Parser는 Paused 상태가 되니 Parser를 통해 읽은 size 개수를 반환한다.

codec_impl.cc

Http::Status ConnectionImpl::dispatch(Buffer::Instance& data) {
  ...(중략),,,

  ssize_t total_parsed = 0;
  if (data.length() > 0) {
    current_dispatching_buffer_ = &data;
    while (data.length() > 0) {
      ...(중략)...
      if (!dispatching_slice_already_drained_) {
        ASSERT(statusor_parsed.value() <= slice.len_);
        data.drain(statusor_parsed.value());
      }

      total_parsed += statusor_parsed.value();
      if (parser_->getStatus() != ParserStatus::Ok) {
        // Parse errors trigger an exception in dispatchSlice so we are guaranteed to be paused at
        // this point.
        ASSERT(parser_->getStatus() == ParserStatus::Paused);
        break;
      }
    }
    current_dispatching_buffer_ = nullptr;
    dispatchBufferedBody();
  } else {
    auto result = dispatchSlice(nullptr, 0);
    if (!result.ok()) {
      return result.status();
    }
  }
  ASSERT(buffered_body_.length() == 0);

  ENVOY_CONN_LOG(trace, "parsed {} bytes", connection_, total_parsed);

  // If an upgrade has been handled and there is body data or early upgrade
  // payload to send on, send it on.
  maybeDirectDispatch(data);
  return Http::okStatus();
}

buffer_impl.h

  void drain(uint64_t size) {
    ASSERT(data_ + size <= reservable_);
    data_ += size;
    if (data_ == reservable_) {
      // All the data in the slice has been drained. Reset the offsets so all
      // the data can be reused.
      data_ = 0;
      reservable_ = 0;
    }
  }

codec_impl.cc

Http::Status ConnectionImpl::dispatch(Buffer::Instance& data) {
  ...(중략),,,

  ssize_t total_parsed = 0;
  if (data.length() > 0) {
    current_dispatching_buffer_ = &data;
    while (data.length() > 0) {
      ...(중략)...
      if (parser_->getStatus() != ParserStatus::Ok) {
        // Parse errors trigger an exception in dispatchSlice so we are guaranteed to be paused at
        // this point.
        ASSERT(parser_->getStatus() == ParserStatus::Paused);
        break;
      }
    }
    current_dispatching_buffer_ = nullptr;
    dispatchBufferedBody();
  } else {
    auto result = dispatchSlice(nullptr, 0);
    if (!result.ok()) {
      return result.status();
    }
  }
  ASSERT(buffered_body_.length() == 0);

  ENVOY_CONN_LOG(trace, "parsed {} bytes", connection_, total_parsed);

  // If an upgrade has been handled and there is body data or early upgrade
  // payload to send on, send it on.
  maybeDirectDispatch(data);
  return Http::okStatus();
}

dispatch가 완료되면 parser 상태가 중지이므로 do-while 문을 벗어난다.

codec_impl.cc

void ConnectionImpl::dispatchBufferedBody() {
  ASSERT(parser_->getStatus() == ParserStatus::Ok || parser_->getStatus() == ParserStatus::Paused);
  ASSERT(codec_status_.ok());
  if (buffered_body_.length() > 0) {
    onBody(buffered_body_);
    buffered_body_.drain(buffered_body_.length());
  }
}

parser가 완료되면 body length가 없으므로 처리하는 내용은 없다.

codec_impl.cc

bool ConnectionImpl::maybeDirectDispatch(Buffer::Instance& data) {
  if (!handling_upgrade_) {
    // Only direct dispatch for Upgrade requests.
    return false;
  }

  ENVOY_CONN_LOG(trace, "direct-dispatched {} bytes", connection_, data.length());
  onBody(data);
  data.drain(data.length());
  return true;
}

parser가 완료되면 return fals를 통해 더 이상 데이터 fetch를 수행하지 않는다.

codec_impl.cc

Http::Status ServerConnectionImpl::dispatch(Buffer::Instance& data) {
  ...(중략)...

  if (active_request_ != nullptr && active_request_->remote_complete_) {
    // Read disable the connection if the downstream is sending additional data while we are working
    // on an existing request. Reading from the connection will be re-enabled after the active
    // request is completed.
    if (data.length() > 0) {
      active_request_->response_encoder_.readDisable(true);
    }
  }
  return status;
}

상태를 반환한다.

conn_manager_impl.cc

Network::FilterStatus ConnectionManagerImpl::onData(Buffer::Instance& data, bool) {
...(중략)...

  bool redispatch;
  do {
    ...(중략)...

    if (isBufferFloodError(status) || isInboundFramesWithEmptyPayloadError(status)) {
      handleCodecError(status.message());
      return Network::FilterStatus::StopIteration;
    } else if (isCodecProtocolError(status)) {
      stats_.named_.downstream_cx_protocol_error_.inc();
      handleCodecError(status.message());
      return Network::FilterStatus::StopIteration;
    }
    ASSERT(status.ok());

    // Processing incoming data may release outbound data so check for closure here as well.
    checkForDeferredClose(false);

    // The HTTP/1 codec will pause dispatch after a single message is complete. We want to
    // either redispatch if there are no streams and we have more data. If we have a single
    // complete non-WebSocket stream but have not responded yet we will pause socket reads
    // to apply back pressure.
    if (codec_->protocol() < Protocol::Http2) {
      if (read_callbacks_->connection().state() == Network::Connection::State::Open &&
          data.length() > 0 && streams_.empty()) {
        redispatch = true;
      }
    }
  } while (redispatch);

  if (!read_callbacks_->connection().streamInfo().protocol()) {
    read_callbacks_->connection().streamInfo().protocol(codec_->protocol());
  }

  return Network::FilterStatus::StopIteration;
}

conn_manager_impl.cc

void ConnectionManagerImpl::checkForDeferredClose(bool skip_delay_close) {
  Network::ConnectionCloseType close = Network::ConnectionCloseType::FlushWriteAndDelay;
  if (Runtime::runtimeFeatureEnabled("envoy.reloadable_features.skip_delay_close") &&
      skip_delay_close) {
    close = Network::ConnectionCloseType::FlushWrite;
  }
  if (drain_state_ == DrainState::Closing && streams_.empty() && !codec_->wantsToWrite()) {
    doConnectionClose(close, absl::nullopt,
                      StreamInfo::ResponseCodeDetails::get().DownstreamLocalDisconnect);
  }
}

이후 StopIteration을 return한다.

filter_manager_impl.cc

void FilterManagerImpl::onContinueReading(ActiveReadFilter* filter,
                                          ReadBufferSource& buffer_source) {
  ...(중략)...

  for (; entry != upstream_filters_.end(); entry++) {
    ... (중략)...

    StreamBuffer read_buffer = buffer_source.getReadBuffer();
    if (read_buffer.buffer.length() > 0 || read_buffer.end_stream) {
      FilterStatus status = (*entry)->filter_->onData(read_buffer.buffer, read_buffer.end_stream);
      if (status == FilterStatus::StopIteration || connection_.state() != Connection::State::Open) {
        return;
      }
    }
  }
}

Stopiteration이 반환되었으므로 upstream_filter 또한 종료한다.

filter_manager_impl.cc

void FilterManagerImpl::onRead() {
  ASSERT(!upstream_filters_.empty());
  onContinueReading(nullptr, connection_);
}

onContinueReading 메소드를 종료한다.

connection_impl.cc

void ConnectionImpl::onRead(uint64_t read_buffer_size) {
  ...(중략)...

  filter_manager_.onRead();
}

onRead 메소드를 종료한다.

connection_impl.cc

void ConnectionImpl::onReadReady() {
  ...(중략)...

  read_end_stream_ |= result.end_stream_read_;
  if (result.bytes_processed_ != 0 || result.end_stream_read_ ||
      (latched_dispatch_buffered_data && read_buffer_->length() > 0)) {
    // Skip onRead if no bytes were processed unless we explicitly want to force onRead for
    // buffered data. For instance, skip onRead if the connection was closed without producing
    // more data.
    onRead(new_buffer_size);
  }

  // The read callback may have already closed the connection.
  if (result.action_ == PostIoAction::Close || bothSidesHalfClosed()) {
    ENVOY_CONN_LOG(debug, "remote close", *this);
    closeSocket(ConnectionEvent::RemoteClose);
  }
}

onRead가 끝난 이후 IoAction이 Close된 경우 소켓을 종료한다. 여기서는 정상적인 연결이기 때문에 해당 로직을 수행하지 않는다.

connection_impl.cc

void ConnectionImpl::onFileEvent(uint32_t events) {
  ...(중략)...

  // It's possible for a write event callback to close the socket (which will cause fd_ to be -1).
  // In this case ignore read event processing.
  if (ioHandle().isOpen() && (events & Event::FileReadyType::Read)) {
    onReadReady();
  }
}

최초에 호출했던 onFileEvent를 종료한다.

Kafka Broker 네트워크 구조

cla9 — Fri, 26 May 2023 10:32:46 +0900

서론

Kafka Broker에 대해서 학습한 이후 아래와 같이 PDF를 정리해서 공유했었다. 이후 Kafka Broker의 네트워크 연결은 어떻게 이루어질까에 대한 생각에 이에 대하여 학습하여 공유하고자 한다.

https://www.scribd.com/document/560749821/Kafka-Broker

Kafka Broker | PDF

Kafka Broker 내부 모듈 정리

www.scribd.com

Kafka는 분산 시스템으로써, 수많은 Broker와 Producer, Consumer끼리 통신을 수행하며, Broker 간에도 데이터 복제 및 상태 중재를 위한 네트워크 통신이 사용된다.

그렇다면, Kafka에서는 어떠한 방식으로 통신을 수행할까?

일반적으로 생각해보면, HTTP Protocol을 사용하는 방법으로 이미 구현된 HTTP 프레임워크를 사용하는 것이 개발 입장에서는 쉬울 것이다. 하지만 Kafka 커미터들은 다음과 같은 이슈로 인하여 자체 통신 체계를 구축했다고 한다.

Kafka에서는 빠른 메시지 전달을 위해 Kafka에 최적화된 통신 체계가 필요하다. 또한 커다란 프레임워크 코드 영역에서 Kafka가 필요한 부분은 일부에 불과하다.
라이브러리 의존성과 버전 관리의 어려움이다.

Kafka는 메시지 전달을 위해 빠른 네트워크 성능이 필요하기 때문에, 고성능 통신을 위해 간결하면서도 최적화된 방식이 필요하다. 그리고 라이브러리 및 의존성 문제에서 자유로워야한다. 만약 다른 프레임워크에 의존하게된다면, Broker 및 Client 모두 해당 라이브러리에 대한 강한 의존성이 생긴다. 이는 버전 관리의 어려움이 존재하게되며, Kafka 라이브러리를 포함하는 Client의 파일 크기 또한 커지게 된다. 따라서, 위 두 가지 이슈로 인해 자체 네트워크 모델을 구축하으며, 빠른 메시지 전달과 동시 신뢰성 있는 데이터 전달이 중요하기 때문에 UDP 기반이 아닌 TCP 기반위에서 동작하도록 자체 Protocol을 설계했다.

Kafka 네트워크 모델 기반에는 Java의 NIO API가 광범위하게 사용된다. 따라서, Kafka 네트워크 모델을 살펴보기 앞서 NIO에서 Network 연관 부분만 살펴보자.

NIO

NIO는 New IO의 약자로써 기존 IO 방식에서 발생하는 Blocking 이슈를 개선하기 위해 Java 1.4 부터 새롭게 도입된 기능(JSR-51)이며, 다음과 같은 특징을 지니고 있다.

Non-Blocking
IO Multiplexing

위 두 가지 특징을 기반으로 NIO가 기존 IO와 무엇이 다른지에 대해 살펴보자.

일반적으로 Socket을 활용한 네트워킹 과정을 살펴보면 위와 같다. 여기서 기존 I/O 방식은 Client의 연결을 받아들이는 Accept 부분과 Read, Write 연산 등은 모두 Blocking된다. 이는 즉 Accept의 경우 요청이 들어올 때까지 요청을 반환하지 않음을 의미하며, Read, Write의 작업이 수행되는 동안에도 결과를 리턴 하지 않고 끝날 때까지 대기함을 의미한다.

이러한 경우 일반적인 단일 소켓으로는 여러 요청을 효과적으로 처리할 수 없다. 그 이유는 여러 요청을 빠르게 처리하기 위해서는 Blocking되어 Idle한 시간을 효율적으로 분배하여 다른 작업을 처리 해야하는데, 기존 구조로는 이에 대해 효과적으로 대응할 수 없기 때문이다.

따라서 기존에는 동기식 I/O 방식의 문제점을 해결하고자 각 Client의 연결 요청에 대해 이를 처리할 수 있는 Thread를 생성 후 매핑을 통해 동시성을 해결하고자 했다.

하지만 위와 같이 Multi Thread 방식의 네트워크 통신 방법에는 한계가 존재한다. 그 이유는 아무리 Thread가 Process보다는 가볍다고 하나 개별 요청 별 Thread를 할당하는 방식은 메모리 사용 및 Context Switching에 따른 Overhead가 크기 때문이다. 가령 Thread별 스택을 1M씩만 할당한다고 가정하더라도 1024개 사용자 요청을 처리하기 위해서 생성되는 스택만 1GB가 사용될 것이다. 따라서, 사용자가 증가할 수록 처리량은 감소하게된다.

그렇다면, Non-Blocking으로 처리하면 어떻게 될까?

Non-Blocking 방식은 기존의 Blocking I/O를 유발하는 메소드에 대해서 추가 설정을 통해 Non-Blocking 형태로 구성할 수 있다. 즉 기존에는 메소드 호출 시 작업이 완료될 때까지 기다렸지만, 설정 이후에는 메소드 결과가 즉시 반환하기 때문에, 하나의 소켓 서버 Thread가 여러개의 I/O를 처리할 수 있게되었다.

Non-Blocking 설정 이후로는 위 그림과 같이 단일 Thread에서 여러 사용자의 Channel과 매핑되어 데이터를 처리할 수 있게 되었다. 위 그림만 보면 Thread 개수를 줄일 수 있으니 성능이 많이 향상될 것으로 보인다. 하지만 다음과 같은 문제가 존재한다.

Blocking I/O 방식으로 처리할 경우에는 순차적으로 처리하므로 Blocking 메소드를 벗어났다는 것은 해당 처리가 완료되었음이 어느정도 보장된다. 하지만 Non-Blocking 방식은 작업 요청과 별개로 바로 리턴이 되기 때문에 실제 요청 여부를 확인하기 위해서는 주기적으로 소켓 정보를 Polling하여 처리 가능 여부를 확인해야한다.

List<SocketChannel> channels = new ArrayList<>();
ServerSocketChannel serverSocket = ServerSocketChannel.open();
serverSocket.socket().bind(new InetSocketAddress(9002));
serverSocket.configureBlocking(false);

while (true) {
  SocketChannel channel = serverSocket.accept();
  if (null != channel) {   
    socketChannel.configureBlocking(false);
    channels.add(channel);
  }

  Iterator<SocketChannel> iterator = channels.iterator();
  while (iterator.hasNext()) {
    SocketChannel channel = iterator.next();
    ..(Read 요청 확인 수행 및 처리)...
  }
}

위 코드는 configureBlocking 설정을 통해서 Blocking 방식 API를 Non-Blocking 방식으로 변경한 예제이다. 코드를 살펴보면, accept 혹은 read 수행하면 바로 리턴되므로 요청 확인을 위해서 지속적으로 무한 Loop를 수행하며 확인 과정이 필요하다. 예를 들어 현재 100개의 연결이 이루어져 channels List에 등록되어있다면, 매번 100번의 연결에 대하여 요청 여부를 확인한다.

위와 같은 방식의 경우 무한 Loop로 인하여 CPU overhead가 지속 발생하므로 Non-Blocking 기법만 적용해서는 성능 향상의 효과를 크게 얻을 수 없다. 그렇다면 이러한 문제는 어떻게 해결할까? IO Multiplexing에 대해서 알아보자.

IO Multiplexing

IO Multiplexing 방식은 하나의 Channel을 통해 여러 개의 연결을 관리하는 방식으로 해당 방식에서는 소켓 관리를 OS에서 직접 관리한다. 따라서 사용자 코드에서는 OS에 관리 대상 소켓 정보를 등록하는 단계가 필요하다.

(※ 본 포스팅에서 Kafka는 Linux 환경에서 동작함을 가정하므로 Socket은 FileDescriptor로 취급됨을 참고하자.)

등록 이후에는 OS에서 File descriptor 목록을 가지고 있고, 내부적으로 데이터를 처리해야 될 대상이 발견되면, 해당 정보를 이후 Client에서 요청 시 반환하는 역할을 담당한다. 즉 이전에는 Client에서 직접 처리 요청 대상을 관리했다면, Monitor 역할을 OS가 담당하는 셈이다.

위와 같은 방법을 적용하면, 사용자 코드에서 Connection 개수 여부와 관계없이 처리 대상만 OS로부터 전달받으므로 CPU overhead를 줄일 수 있으므로 적은 Thread로 많은 처리 요청을 수행할 수 있다.

Java의 NIO는 이를 위해서 Selector를 활용한다. Selector는 OS와 사용자 코드 상의 가교 역할을 수행한다. 따라서 사용자 코드에서 Selector에게 처리 대상 Channel 등록을 요청하면, OS에 해당 정보를 전달한다. 그 이후에는 주기적으로 OS에 목록 전달 요청을 전달하면, OS에서 대상 목록을 전달 받아 후속 작업을 처리한다.

(※ JVM 6이상 환경에서 Linux Kernel 2.6 이상을 사용하면, 기본 Selector의 구현체로 Linux의 epoll이 사용된다.)

ServerSocketChannel serverSocket  = ServerSocketChannel.open();
serverSocket.socket().bind(new InetSocketAddress(9002));
serverSocket.configureBlocking(false);

Selector selector = Selector.open();
SelectionKey selectionKey = serverSocket.register(selector, SelectionKey.OP_ACCEPT);

while (true) {

  //select() 메소드는 Blocking 방식으로 동작함.
  selector.select();
  
  Set<SelectionKey> selectionKeys = selector.selectedKeys();
  Iterator<SelectionKey> iterator = selectionKeys.iterator();

  while (iterator.hasNext()) {
    SelectionKey key = iterator.next();
    if (key.isAcceptable()) {
        SocketChannel channel = (ServerSocketChannel)key.channel().accept();
        channel.configureBlocking(false);
        channel.register(selector, SelectionKey.OP_READ);
    } else if (key.isReadable()) {
        SocketChannel channel = (SocketChannel)key.channel();
        ByteBuffer buffer = ByteBuffer.allocate(1024);
        int read = channel.read(buffer);
        
        ...(Read 처리)...        
    }
}

코드를 통해 구체적인 수행 과정을 살펴보면 다음과 같다.

Server 소켓을 생성하고 open() 메소드를 통해 Selector를 생성한다. 해당 메소드는 Linux 내부에 epoll Object를 생성한다.
Client가 IP 및 Port 정보를 통해서 접속 요청을 할 것이다. 그러면 OS는 바인딩된 내부 오브젝트에 반영한다.
사용자 코드에서 select() 메소드를 호출하면, 접속 요청이 존재하므로 해당 정보를 반환한다.
사용자 코드에서 해당 접속 요청을 받아들인 이후에 Read 요청이 들어오면 이를 감지하기 위해 Kernel에 Read 이벤트에 대한 수신을 받을 수 있도록 요청한다. 이때 호출되는 register()를 통해 내부에 epoll_ctl및 epoll_wait 시스템 콜이 호출된다.
Linux Kernel은 해당 요청을 다룰 수 있는 connection이 존재하는지 확인 후 client와 연결한다.
연결이 성공적으로 이루어지면, Selector에게 알림을 통지하고 내부적으로 Channel을 생성한다.
사용자가 데이터 fetch 요청을 전달하면 내부 Buffer에 이를 저장한다. 이때 Buffer의 위치는 direct 방식과 아닐 경우에 따라서 달라질 수 있는데, 이는 나중에 다루도록 한다.
Channel은 연결 역할을 수행할 뿐 데이터 fetch는 Buffer를 통해 이루어진다.
Selector는 지속적으로 poll을 수행하여 Channel에 등록된 Buffer의 내용을 읽어간다.

( ※ 위 그림에서 Channel과 Buffer는 연결된 Client 마다 생성된다.)

위 코드 중 가장 중요한 것은 select()이다. 이는 해당 메소드 또한 Blocking 방식이기 때문이다. 따라서 Selector를 활용한 방식은 완벽한 비동기 방식은 아니므로 Synchronous Non-Blocking 방식이라고 볼 수 있다.

Java의 NIO에 대해서 정리하자면, 기존 동기 방식의 API로 인한 동시성 저하를 막고자 Non-Blocking API를 제공하며, IO Multiplexing을 통해 처리량을 높일 수 있다. 하지만 완전한 방식의 비동기 방식은 아니다.

Kafka Broker Network 구조

지금까지 학습한 Java의 NIO를 바탕으로 Kafka Broker내의 Network 통신을 위한 구조를 살펴보자. Broker 구조는 크게 Socket Server, Request Handler Pool, API 세 가지로 이루어져있다. 해당 컴포넌트에 무엇이 있는지 하나씩 살펴보자.

Socket Server

Socket Server는 사용자 접속 및 요청을 담당하는 역할을 담당하며, Acceptor, Processor, Request Channel로 이루어진 Request-Plane 세트이다.

이전 그림에는 1개의 Plane을 묘사했지만, 실제로는 data-plane과 control-plane 총 2개의 plane이 존재한다. 여기서 control-plane은 Broker와 Controller 간의 통신을 위해 연결된 전용 네트워크이며, data-plane은 Broker 끼리 혹은 client의 요청을 처리하기 위한 네트워크이다.

그렇다면, Request-Plane 구성 요소인 Acceptor, Processor, Request Channel은 각각 무엇일까?

Acceptor는 Client의 접속 요청을 감지하는 문지기의 역할을 수행한다. Acceptor를 통해 연결 요청을 전달받으면, 하위에 존재하는 Processor 중 하나에게 Read/Write 처리를 수행할 수 있도록 연결해준다.

Processor는 연결된 Socket에 대하여 Read/Write 요청이 전달되는 것을 감지하고, 이를 Request Channel의 Request Queue에 전달하는 역할과 실제 작업이 완료된 이후 결과를 전달받아 사용자에게 반환하는 것을 담당한다.

Request Channel은 모든 Processor, Handler, API가 공유하는 전역 저장소로써, 사용자의 요청이 전달되면 해당 정보를 보관하고 처리가 완료되면 요청한 Processor에게 결과를 반환하는 역할을 수행한다.

Socket Server의 구조를 보면, Acceptor가 여러개의 Processor를 가지고 있고 Processor는 Request Channel과 연관이 있음을 알 수 있다. Socket Server에는 data-plane과 control-plane 두 개가 존재한다고 이전에 설명했는데, data-plane의 경우 Acceptor는 여러개의 Processor를 가질 수 있으며, 해당 설정은 num.network.threads 설정을 통해서 개수를 조절할 수 있다. 반면 control-plane의 경우는 Processor가 1개만 존재한다.

Request Handler

Request Handler는 ReuqestChannel에서 Request 정보를 가져와 API에게 처리를 요청하고 요청 결과를 다시 RequestChannel에 전달하는 역할을 담당한다. RequestHandler는 1개가 아니라 여러개의 Thread로 구성될 수 있으며, 이는 num.io.threads 속성을 통해 개수를 조정할 수 있다.

이전 Kafka 버전(0.7)에서는 Request Handler가 따로 존재하지 않았고 Processor를 통해 직접 처리를 수행하였다. 하지만 Network Read/Write 요청을 감지하는 영역과 I/O를 처리하는 부분이 하나의 Thread안에 있으므로 탄력적으로 Thread 개수를 늘리기 어려운 문제가 있었다.

따라서 I/O와 Network 처리를 위한 Thread를 분리함으로써, 현재와 같은 모습을 갖추게 되었다.

API

request.header.apiKey match {
        case ApiKeys.PRODUCE => handleProduceRequest(request, requestLocal)
        case ApiKeys.FETCH => handleFetchRequest(request)
        ...(중략)...
        case _ => throw new IllegalStateException(s"No handler for request api key ${request.header.apiKey}")
      }

API는 Client가 요청한 정보를 기반으로 Kafka 내부 모듈에 필요한 메소드를 호출하는 역할을 담당한다. Kafka Protocol에는 위와 같이 어떤 요청인지 header에 포함시키도록 규정되었다. 따라서 Kafka API가 요구하는 Spec에 맞게 작성하면, 이를 Parsing 하여 개별 모듈로 Routing을 시켜준다. 요청 처리가 완료되면, RequestHelper를 통해 RequestChannel로 전달한다.

동작 과정

지금까지 Kafka Network 구조에 대해서 큰 틀에서 살펴봤다. 이번에는 각 모듈끼리 어떠한 상호작용을 거쳐 동작하는지 살펴보자. 먼저 큰 흐름 속에서 어떻게 동작하는지 보고 이후 코드 레벨에서 보다 자세하게 살펴보도록 하자.

첫 번째로 살펴볼 것은 Client가 접속 요청 시도시 내부 동작 과정이다.

사용자가 접속 요청을 한다.
Acceptor가 해당 접속 요청을 수락하고, 자신이 보유한 Processor 중 하나에게 할당한다. Processor는 해당 요청을 자신이 보유한 Kafka Selector에 요청하여 이후 Client로부터 데이터 처리 요청이 왔을 경우 감지할 수 있도록 사전 준비한다.

Client 접속 요청이 완료되면, Processor는 사용자 요청을 처리할 수 있는 단계가 된다. 이후 사용자 요청이 발생했을 때 처리 과정을 살펴보자.

사용자가 데이터 fetch 요청을 하면, Kernel은 이를 감지한다.
Processor에서 Kafka Selector에게 데이터 fetch 요청 이후 해당 요청을 Request Channel의 Request Queue에 저장한다. 이때 향후 처리 결과를 자신에게 포워딩 하기 위해 Queue 삽입시 자신의 Processor Id를 함께 추가한다.
Request Handler에서 Request Queue에 존재하는 요청을 fetch한다.
해당 요청을 API에게 전달한다.
API는 요청을 처리한다음 자신이 보유한 Request Helper를 통해 RequestChannel로 전달한다.
Request Channel은 Processor Id를 보고 해당 Processor의 Response Queue에 결과를 삽입한다.
Processor는 Response Queue 내용을 확인하고 Client에게 결과를 전달한다.

지금까지 살펴본 내용은 큰 틀에서 컴포넌트간 상호 작용에 대해서 확인했다. 이번에는 코드 레벨에서 자세하게 각 모듈이 어떻게 구동되고 상호작용하는지 알아보자.

Socket Server 동작 과정

// data-plane
private val dataPlaneProcessors = new ConcurrentHashMap[Int, Processor]()
private[network] val dataPlaneAcceptors = new ConcurrentHashMap[EndPoint, Acceptor]()
val dataPlaneRequestChannel = new RequestChannel(maxQueuedRequests, DataPlaneMetricPrefix, time, apiVersionManager.newRequestMetrics)

// control-plane
private var controlPlaneProcessorOpt : Option[Processor] = None
private[network] var controlPlaneAcceptorOpt : Option[Acceptor] = None
val controlPlaneRequestChannelOpt: Option[RequestChannel] = config.controlPlaneListenerName.map(_ =>
    new RequestChannel(20, ControlPlaneMetricPrefix, time, apiVersionManager.newRequestMetrics))

가장 먼저 살펴볼 것은 Socket Server에 속한 2개의 plane이 어떻게 구성되어있는지 살펴보자. 위 내용을 살펴보면, 2개의 plane이 서로 다른점이 몇 가지 보인다.

data-plane의 경우 Acceptor, Processor가 여러개이지만, controlPlane의 경우 하나만 존재한다.
data-plane의 경우 RequestChannel 내에 존재하는 RequestQueue의 크기를 queued.max.requests 속성 크기만큼 지정 가능한 반면, control-plane의 경우는 20개로 크기가 고정되어있다.

def startup(startProcessingRequests: Boolean = true,
            controlPlaneListener: Option[EndPoint] = config.controlPlaneListener,
            dataPlaneListeners: Seq[EndPoint] = config.dataPlaneListeners): Unit = {
this.synchronized {
      createControlPlaneAcceptorAndProcessor(controlPlaneListener)
      createDataPlaneAcceptorsAndProcessors(config.numNetworkThreads, dataPlaneListeners)
      ...(중략)...
}

Socket Server를 생성하고 나면, 해당 Server를 기동하는 startup 메소드가 호출된다. 이때 개별 data, control plane 각각에 대하여 Acceptor와 Processor를 생성하는 메소드가 실행된다.

private def createDataPlaneAcceptorsAndProcessors(dataProcessorsPerListener: Int,
                                                    endpoints: Seq[EndPoint]): Unit = {
  endpoints.foreach { endpoint =>
    connectionQuotas.addListener(config, endpoint.listenerName)
    val dataPlaneAcceptor = createAcceptor(endpoint, DataPlaneMetricPrefix)
    addDataPlaneProcessors(dataPlaneAcceptor, endpoint, dataProcessorsPerListener)
    dataPlaneAcceptors.put(endpoint, dataPlaneAcceptor)      
  }
}

private def addDataPlaneProcessors(acceptor: Acceptor, endpoint: EndPoint, newProcessorsPerListener: Int): Unit = {
  ...(중략)...    
  for (_ <- 0 until newProcessorsPerListener) {
    val processor = newProcessor(nextProcessorId, dataPlaneRequestChannel, connectionQuotas, listenerName, securityProtocol, memoryPool, isPrivilegedListener)
    ...(중략)...
    dataPlaneRequestChannel.addProcessor(processor)
    nextProcessorId += 1
  }
  ...(중략)...
  acceptor.addProcessors(listenerProcessors, DataPlaneThreadPrefix)
}

두 가지 생성 메소드 중 data-plane 생성 코드를 살펴보자. 위와같이 listeners를 통해서 전달받은 endpoint 별로 acceptor가 생성되며, num.network.threads 개수만큼 processor 또한 생성 된다. processor 생성 이후 acceptor와 channel에 해당 processor를 등록한다.

해당 과정을 통해 Acceptor와 RequestChannel의 Processor 간의 매핑 관계를 이해할 수 있다.

Acceptor 동작과정

def run(): Unit = {
serverChannel.register(nioSelector, SelectionKey.OP_ACCEPT)
...(중략)...
try {
  while (isRunning) {
    try {
      acceptNewConnections()
      ...(중략)...
    }
    catch {
      ...(중략)...
    }
  }
}

설정 작업이 마무리되면, listeners에 매핑된 Endpoint 개수 만큼의 Kafka 쓰레드를 생성하여 Acceptor에게 할당한다. 위 코드는 Acceptor에게 쓰레드 할당 후 start() 호출 이후 수행 과정을 나타낸다.

NIO Selector를 통해 Accept 이벤트를 통지할 수 있도록 요청하면, 내부적으로 Kernel에 epoll 오브젝트가 생성되고, Accept 요청이 왔을 때 이를 수신받을 수 있음을 이전 NIO 개념을 학습하면서 살펴봤다.

소켓 정보 등록 후에는 무한 Loop를 통해 새로운 연결 요청이 있는지를 확인한다.

private def acceptNewConnections(): Unit = {
  val ready = nioSelector.select(500)
  if (ready > 0) {
    val keys = nioSelector.selectedKeys()
    val iter = keys.iterator()
    while (iter.hasNext && isRunning) {
      try {
        val key = iter.next
        ...(중략)...
        if (key.isAcceptable) {
          accept(key).foreach { socketChannel =>
            ...(중략)...
            var processor: Processor = null
            do {
                ...(중략)...
                processor = synchronized {
                currentProcessorIndex = currentProcessorIndex % processors.length
                processors(currentProcessorIndex)
              }
              currentProcessorIndex += 1
            } while (!assignNewConnection(socketChannel, processor, retriesLeft == 0))
          }
        } else
          throw new IllegalStateException("Unrecognized key state for acceptor thread.")
      } catch {
        ...(중략)...
      }
    }
  }
}

이때 select() 메소드를 통해 Accept 요청이 들어왔는지를 OS에게 확인하는데, 해당 메소드는 Blocking 메소드이므로 무한 대기를 막기 위해 500ms 기간의 Timeout을 지정한다. 이 과정에서 Accept 요청이 들어온다면, 자신이 보유하고 있는 Processor 중 하나에게 향후 Read/Write 요청에 대한 처리를 담당하도록 한다. 이때 살펴볼 것은 Processor에게 균등한 분배를 위해서 Round-Robin 방식으로 접속 요청을 분배한다는 점이다.

Acceptor의 역할은 여기까지이고, 지금 부터는 위 코드를 통해 새로운 요청이 Processor에게 할당된 이후 처리 과정에 대해서 살펴보자.

Processor 동작 과정

이전에 Acceptor에서 Processor에게 요청을 할당한다고 했는데, 해당 과정은 어떻게 이루어질까? 먼저 Processor가 지닌 프로퍼티에 대해 먼저 살펴보자.

위 그림을 살펴보면 일반 Selector가 아닌 Kafka Selector를 내부 프로퍼티로 가지고 있는 것을 확인할 수 있다. 여기서 Kafka Selector에는 내부에 NIO의 Selector를 포함하며, 그 외에 Kafka 데이터 송수신에 필요한 프로퍼티 및 내부 메소드를 지닌 클래스이다.

Kafka Selector에는 위 그림외에도 수많은 내부 프로퍼티가 존재하지만, 일부만 간추려서 알아보자. nioSelector는 Java NIO의 selector를 의미한다.

channel은 Processor를 통해 연결된 Client와의 Channel을 의미하며, Connection Id 와 KafkaChannel로 이루어진 Map이다. 따라서 특정 Client와 연결 시 Connection Id 기준으로 해당 Channel과 연결한다.

completedSends, completedReceives 및 disconnected는 데이터 송수신 및 close 처리 시, 해당 요청을 임시 저장하는 용도의 buffer로써 활용된다.

여기까지 Kafka Selector에 대해서 알아보고 이번에는 Processor의 또 다른 주요 프로퍼티 중 하나인 newConnections에 대해서 알아보자. 해당 자료구조는 Queue로써 Acceptor가 새로운 요청을 Processor에게 할당할 때, 해당 Queue에 입력이 된다.

이제 Processor의 내부 프로퍼티를 토대로 Processor 동작 과정에 대해 살펴보자.

override def run(): Unit = {
  ...(중략)...
  try {
    while (isRunning) {
      try {
        configureNewConnections()
        processNewResponses()
        poll()
        processCompletedReceives()
        processCompletedSends()
        processDisconnected()
        closeExcessConnections()
      } catch {
        ...(중략)...
      }
    }
  }
  ...(중략)...
}

Processor 또한 Acceptor와는 별개의 Thread로 수행된다. 위 코드는 Processor 기동 시작 후 수행 과정을 나타내며, 무한 Loop를 통해서 동일한 작업을 지속 반복 수행하는 것을 확인할 수 있다. 위 코드와 같이 7개의 동작을 수행하는데, 전부다 살펴보지는 않고 주요 동작에 대해서만 살펴보자.

configureNewConnections()

  private def configureNewConnections(): Unit = {
    var connectionsProcessed = 0
    while (connectionsProcessed < connectionQueueSize && !newConnections.isEmpty) {
      val channel = newConnections.poll()
      try {
        ...(중략)...
        selector.register(connectionId(channel.socket), channel)
        connectionsProcessed += 1
      } catch {
        ...(중략)...
      }
    }
  }

configureNewConnections 메소드는 newConnections를 통해 새로운 Channel이 입력되면, Connection Id를 부여한 다음 해당 정보를 Kafka Selector에게 전달하여 궁극 적으로는 OS 내부에 해당 소켓 정보를 등록시킨다. 따라서, Processor가 지닌 Kafka Selector를 통해서 향후 Read/Write 요청이 들어왔을 때 이를 감지해 후속 작업을 처리할 수 있다.

processNewResponse()

private def processNewResponses(): Unit = {
  var currentResponse: RequestChannel.Response = null
  while ({currentResponse = dequeueResponse(); currentResponse != null}) {
    val channelId = currentResponse.request.context.connectionId
    try {
      currentResponse match {
        case response: NoOpResponse =>
          ...(중략)...
        case response: SendResponse =>
          sendResponse(response, response.responseSend)
        case response: CloseConnectionResponse =>
          ...(중략)...
          close(channelId)
        ...(중략)...  
      }
    } catch {
        ...(중략)...
    }
  }
}

processNewResponse() 메소드는 RequestHandler를 통해 API 호출 후 Client에게 결과를 전달하는 과정을 처리한다. API 수행이 모두 완료되면, Channel을 통해 Processor의 개별 ResponseQueue에 결과가 적재된다.

그 이후 위 코드가 실행되면, dequeueResponse() 메소드를 통해 결과를 추출 이후 결과 유형에 따라서 처리를 달리 수행한다.

protected[network] def sendResponse(response: RequestChannel.Response, responseSend: Send): Unit = {
  val connectionId = response.request.context.connectionId
  ...(중략)...
  
  if (openOrClosingChannel(connectionId).isDefined) {
    selector.send(new NetworkSend(connectionId, responseSend))
    ...(중략)...
  }
}

만약 해당 요청이 SendResponse라면, 위 코드와 같이 Kafka Selector의 저장 Buffer에 임시 보관하도록 요청한다.

private def close(connectionId: String): Unit = {
  openOrClosingChannel(connectionId).foreach { channel =>
    ...(중략)...
    selector.close(connectionId)
    ...(중략)...
  }
}

만약 처리 유형이 CloseConnectionResponse 형태라면, Selector에게 close 요청을 전달하여 Channel을 정상적으로 종료하도록 한다. 그리고 Kafka Selector는 자신이 지닌 Client 연결 항목에서 해제하고 Channel을 종료시킨다.

poll()

private def poll(): Unit = {
  val pollTimeout = if (newConnections.isEmpty) 300 else 0
  try selector.poll(pollTimeout)
  catch {
    ...(중략)...
  }
}

poll() 메소드는 KafkaSelector를 통해 데이터가 Channel에 존재하면, fetch를 요청하는 작업이다.

이때 Kafka Selector의 내부 동작 방식은 복잡하지만, 핵심 부분만 도식화해보면 위 흐름과 같다.

Processor가 poll()을 통해 변경 대상 Channel 확인 및 데이터 fetch를 요청한다.
Kafka Selector 내부 nioSelector를 통해서 Kernel에 변경 대상 Channel이 존재하는지를 요청한다.
Kernel 내부에서 변화가 감지된 Channel 정보를 전달한다.
해당 Channel이 데이터 수신이 가능한 상태라면 데이터를 추출하여 completedReceives에 저장한다. 만약 processNewResponse() 메소드 수행 결과 전달할 데이터가 존재한다면, Selector 쓰기 임시 버퍼에 저장되어있을 것이다. 해당 내용을 completedSends에 저장한다.

※ completedSends, completedReceives에 저장된 데이터는 다음에 확인할 processCompletedReceives()와 processCompletedSends() 과정을 통해서 처리된다.

processCompletedReceives()

private def processCompletedReceives(): Unit = {
  selector.completedReceives.forEach { receive =>
    try {
      openOrClosingChannel(receive.source) match {
        case Some(channel) =>           
            ...(중략)...
          val connectionId = receive.source
          val context = new RequestContext(header, connectionId, channel.socketAddress,channel.principal, listenerName, securityProtocol,
                  channel.channelMetadataRegistry.clientInformation, isPrivilegedListener, channel.principalSerde)

          val req = new RequestChannel.Request(processor = id, context = context, startTimeNanos = nowNanos, memoryPool, receive.payload, requestChannel.metrics, None)

          ...(중략)...
          requestChannel.sendRequest(req)
          ...(중략)...                        
        case None => ...(중략)...
      }
    } catch {
      ...(중략)...
    }
  }
  selector.clearCompletedReceives()
}

이전에 poll() 과정이 끝나고나면, 데이터 수신이 완료된 내용은 completedReceives에 저장됨을 확인했다. processCompletedReceives()는 해당 내용을 가져와서 처리를 수행하기 위해 Context를 만들고 이를 RequestChannel에 추가한다. 이때 데이터 처리 이후 자신의 Processor가 후속 작업을 처리하기 위해서 요청시 자신의 Processor Id를 파라미터로 넘기는 것을 참고하자.

Channel에 Request 요청을 넣은 이후에는 completedReceives 내용을 초기화하여 이후 중복 처리 되지 않도록한다.

processCompletedSends()

private def processCompletedSends(): Unit = {
  selector.completedSends.forEach { send =>
    try {
      ...(중략)...

      // Invoke send completion callback
      response.onComplete.foreach(onComplete => onComplete(send))

      ...(중략)...
    } catch {
      ...(중략)...
    }
  }
  selector.clearCompletedSends()
}

발송할 데이터는 poll() 메소드 수행 과정을 통해 모두 completedSends에 저장되어있다. 이후 해당 메소드에서 실제 후속 작업 처리를 진행함으로써, Client에게 결과를 반환하고, completedSends를 모두 초기화 한다.

지금까지, Processor 동작 과정에 대해서 살펴봤다. 해당 내용을 정리하자면 다음과 같다.

Acceptor로 부터 Client를 할당 받는다.
API로 부터 처리 결과를 전달받으면, Kafka Selector에 존재하는 임시 버퍼(각 Channel마다 존재)에 저장한다.
Kafka Selector로부터 Client의 요청이 있는지 확인하며, 이 과정에서 사용자의 요청이 전달된다면, completedReceives에 저장하고, API 처리 결과를 completedSends에 한데 모은다.
completedReceives은 사용자의 요청이므로 Request Channel에 전달하여 데이터 처리 요청하고, completedSends 내용은 결과를 Client에 반환하는 후속 작업을 처리한다.

Request Handler 동작 과정

class KafkaRequestHandlerPool(val brokerId: Int,
                              val requestChannel: RequestChannel,
                              val apis: ApiRequestHandler,
                              time: Time,
                              numThreads: Int,
                              requestHandlerAvgIdleMetricName: String,
                              logAndThreadNamePrefix : String) extends Logging with KafkaMetricsGroup {
  ...(중략)...

  val runnables = new mutable.ArrayBuffer[KafkaRequestHandler](numThreads)
  for (i <- 0 until numThreads) {
    createHandler(i)
  }

  def createHandler(id: Int): Unit = synchronized {
    runnables += new KafkaRequestHandler(id, brokerId, aggregateIdleMeter, threadPoolSize, requestChannel, apis, time)
    KafkaThread.daemon(logAndThreadNamePrefix + "-kafka-request-handler-" + id, runnables(id)).start()
  }
  
  ...(중략)...
}

Request Handler는 KafkaRequestHandlerPool 내부에 존재한다. 따라서 먼저 KafkaRequestHandlerPool가 생성된다. 생성 당시 SocketServer와 연결될 Channel과 API로 전달할 APIRequestHandler가 인자로 같이 전달되는 것을 참고하자. 또한 RequestHandler는 단일 쓰레드로 동작하는 것이 아니라 num.io.threads 인자에 따라 개수 조절이 가능하므로 생성 당시 해당 값 또한 전달된다.

위 과정을 통해 KafkaHandler는 데몬쓰레드로 동작한다.

def run(): Unit = {
  while (!stopped) {
    ...(중략)...
    val req = requestChannel.receiveRequest(300)
    req match {
      case RequestChannel.ShutdownRequest =>
        ...(중략)...
        completeShutdown()
        return

      case request: RequestChannel.Request =>
        try {
          ...(중략)...
          apis.handle(request, requestLocal)
        } catch {
          ...(중략)...
        }
        ...(중략)...
    }
  }
  completeShutdown()
}

RequestHandler의 역할은 단순하다. 만약 연결되어있는 Channel이 종료된다면, Handler의 역할이 더이상 필요 없으므로 종료한다. 반면 RequestChannel에서 Request가 존재한다면, API에게 처리를 위임한다.

API 동작 과정

class ControllerApis(val requestChannel: RequestChannel,
                     val authorizer: Option[Authorizer],
                     val quotas: QuotaManagers,
                     val time: Time,
                     val supportedFeatures: Map[String, VersionRange],
                     val controller: Controller,
                     val raftManager: RaftManager[ApiMessageAndVersion],
                     val config: KafkaConfig,
                     val metaProperties: MetaProperties,
                     val controllerNodes: Seq[Node],
                     val apiVersionManager: ApiVersionManager) extends ApiRequestHandler with Logging {

  val requestHelper = new RequestHandlerHelper(requestChannel, quotas, time)
  
  override def handle(request: RequestChannel.Request, requestLocal: RequestLocal): Unit = {
    try {
      request.header.apiKey match {
        case ApiKeys.FETCH => handleFetch(request)
        case ApiKeys.FETCH_SNAPSHOT => handleFetchSnapshot(request)
        ...(중략)...
        case _ => throw new ApiException(s"Unsupported ApiKey ${request.context.header.apiKey}")
      }
    } catch {
      case e: FatalExitError => throw e
      case e: ExecutionException => requestHelper.handleError(request, e.getCause)
      case e: Throwable => requestHelper.handleError(request, e)
    }
  }
}

API는 사용자 요청을 라우터의 역할로써, Header에 명시된 API Key를 보고 요청을 전달한다.

def handleFetch(request: RequestChannel.Request): Unit = {
  authHelper.authorizeClusterOperation(request, CLUSTER_ACTION)
  handleRaftRequest(request, response => new FetchResponse(response.asInstanceOf[FetchResponseData]))
}

요청이 전달되면, 요청을 처리하고 결과를 반환하기 위해서 위와 같이 반환 메소드를 호출한다.

private def handleRaftRequest(request: RequestChannel.Request,
                              buildResponse: ApiMessage => AbstractResponse): Unit = {
  val requestBody = request.body[AbstractRequest]
  ...(중략)...

  future.whenComplete { (responseData, exception) =>
    val response = if (exception != null) {
      requestBody.getErrorResponse(exception)
    } else {
      buildResponse(responseData)
    }
    requestHelper.sendResponseExemptThrottle(request, response)
  }
}

반환 메소드 안에서는 ResponseBody를 만든 이후에 requestHelper를 통하여 반환을 위임한다.

def sendResponseExemptThrottle(request: RequestChannel.Request,
                               response: AbstractResponse,
                               onComplete: Option[Send => Unit] = None): Unit = {
  ...(중략)...
  requestChannel.sendResponse(request, response, onComplete)
}

requestHelper는 해당 결과를 requestChannel에 전달함으로써 API 역할은 마무리된다.

Request Channel 동작 과정

Request Channel은 Processor와 Handler 그리고 API가 상호 작용에 필수적인 컴포넌트로써 요청을 전달하고 결과를 수신받는 중간 버퍼의 역할을 담당한다.

class RequestChannel(val queueSize: Int,
                     val metricNamePrefix: String,
                     time: Time,
                     val metrics: RequestChannel.Metrics) extends KafkaMetricsGroup {
  import RequestChannel._
  private val requestQueue = new ArrayBlockingQueue[BaseRequest](queueSize)
  private val processors = new ConcurrentHashMap[Int, Processor]()
  ...(중략)...

  def addProcessor(processor: Processor): Unit = {
    if (processors.putIfAbsent(processor.id, processor) != null)
      warn(s"Unexpected processor with processorId ${processor.id}")

    ...(중략)...
  }
  
  ...(중략)...
}

RequestChannel의 핵심 프로퍼티는 requestQueue와 processors이다. 여기서 requestQueue는 사용자 요청을 저장하는 임시 버퍼의 역할을 수행하며, queueSize를 통해 전달된다. 해당 값은 이전에 Socket Server를 살펴볼 때 확인했듯이 data-plane과 control-plane에 따라서 서로 다른 값을 지니고 있다.

processors는 API로부터 결과를 반환할 때 Processor Id를 기반으로 빠르게 Processor 객체를 찾기 위한 자료구조로 사용되며, Socket Server의 구동 당시 Acceptor와 Processor가 만들어지고 나면, addProcessor 메소드를 통해서 Processor Id와 참조 객체를 전달받아 processors 자료구조에 삽입하게 된다.

private[network] def sendResponse(response: RequestChannel.Response): Unit = {
  ...(중략)...
  
  val processor = processors.get(response.processor)

  if (processor != null) {
    processor.enqueueResponse(response)
  }
}

이후 API로부터 결과를 전달받게되면, response에 저장된 processor Id를 기반으로 processors에서 참조 객체를 찾아 Processor에 위치한 Response Queue에 결과를 삽입한다.

마무리

지금까지 Kafka Broker 입장에서 네트워크 모델이 어떻게 구성되어있고 요청/응답이 어떤 식으로 이루어지는지 살펴봤다. 내부 구조를 살펴보면서, Kafka에 대한 이해가 조금 더 올라간 것 같다.

혹시 틀린 부분이 있으면 언제든 피드백 부탁드립니다.

7. [envoy-internals] Client 요청 전달 과정 이해하기 - 1

cla9 — Thu, 25 May 2023 12:14:05 +0900

1. 서론

이번 포스팅은 그동안 envoy-internals 시리즈의 이해를 바탕으로 사용자가 Http 전달을 요청했을 때, Envoy 내부구조를 토대로 네트워크 요청이 어떻게 흘러가는지에 대해서 전체적인 흐름을 상세히 조망해보는 시간을 가져보려 합니다. 사실 envoy에 대해서 분석했던 계기 중 하나가 도대체 어떻게 사용자의 요청이 전달되는지에 대한 궁금증에서 출발했기 때문에 이번 포스팅을 위해서 이전 시리즈의 내용이 존재했다고 생각합니다. 따라서 이번 내용은 이전 내용에 대한 이해가 선행되어야하므로 이전 시리즈 내용을 정독하고 보시는 것을 추천드립니다.

2. Worker 쓰레드 소켓 할당 과정

이전 시리즈 내용을 통해 Listener Manager에서 네트워크 요청 처리를 위해서 여러개의 Worker 쓰레드를 생성하는 것을 이해할 수 있었습니다. 이때 Worker 쓰레드 생성 갯수는 envoy 생성 당시 --concurrency 인자에 의해서 결정되는 것 또한 확인했습니다. 이번에는 Envoy 기동 과정 중 Worker 쓰레드 상호작용을 살펴보면서 Worker 쓰레드에서 어떻게 네트워크 요청을 처리하는지 살펴보겠습니다.

위 그림은 --concurrency 값이 2개이고 static_config, dynamic_config에 의해서 등록된 Listener 개수 또한 2개이면서 모두 TCP임을 가정했습니다. 이때 기동 과정을 살펴보면 다음과 같습니다.

1. Envoy 기동 과정에서 --concurrency 값을 살펴보고 Listener Manager에게 Worker 쓰레드 생성을 요청합니다. Listener Manager는 Worker 쓰레드를 요청만큼 생성합니다. 이 과정에서 Worker 쓰레드 내부에 Dispatcher와 Connection Handler가 생성됩니다.

2. Worker 쓰레드가 생성되는 과정에서 Envoy의 TLS를 관장하는 메인 쓰레드 InstanceImpl에 쓰레드를 등록합니다. 이 과정에서 InstanceImpl에서 Worker 쓰레드에 위치한 Dispatcher 정보를 registered_threads_ 에 저장할 수 있으며, 향후 Worker 쓰레드의 Dispatcher에 참조가 가능합니다.

3. Worker 쓰레드 생성이 마무리되면, Config 파일 파싱 도중 static configuration 정보를 등록하기 위해 Listener Manager에게 Config 정보 등록을 요청합니다. 해당 과정은 향후 LDS에 의해서도 생성될 수 있습니다. 이 과정에서 Listener Component Factory를 통해 --concurrency 만큼 Socket을 생성합니다.

4. Envoy의 설정이 모두 완료되면, Listener Manager에게 기동을 요청합니다.

5. Listener Manager에서는 기동 과정에서 등록된 Listener Config 정보를 Worker 쓰레드에 모두 Bind하기 위해 개별 Worker 쓰레드에게 Listener 생성을 요청합니다.

6. Worker 쓰레드내에 존재하는 Connection Handler에 Listener를 생성하기 위해 먼저 Listener로부터 자신의 Worker 쓰레드 번호에 해당하는 Socket 정보를 얻어옵니다. 그리고 Worker 쓰레드에서 외부 요청을 참조하기 위해 Dispatcher에게 Socket 정보를 전달하면서 Listener 생성을 요청합니다.

connection_handler_impl.cc

details->addActiveListener(
    config, address, listener_reject_fraction_, disable_listeners_,
    std::make_unique<ActiveTcpListener>(
        *this, config, runtime,
        socket_factory->getListenSocket(worker_index_.has_value() ? *worker_index_ : 0),
        address, config.connectionBalancer(*address)));

active_tcp_listener.cc

ActiveTcpListener::ActiveTcpListener(Network::TcpConnectionHandler& parent,
                                     Network::ListenerConfig& config, Runtime::Loader& runtime,
                                     Network::SocketSharedPtr&& socket,
                                     Network::Address::InstanceConstSharedPtr& listen_address,
                                     Network::ConnectionBalancer& connection_balancer)
    : OwnedActiveStreamListenerBase(
          parent, parent.dispatcher(),
          parent.dispatcher().createListener(std::move(socket), *this, runtime, config.bindToPort(),
                                             config.ignoreGlobalConnLimit()),
          config),
      tcp_conn_handler_(parent), connection_balancer_(connection_balancer),
      listen_address_(listen_address) {
  connection_balancer_.registerHandler(*this);
}

7. Dispatcher는 전달받은 Socket 정보를 토대로 Listener를 생성하여 반환합니다. 이때 주의해서 살펴볼 것은 사용자가 접속했을 때, 인자로 전달받은 TcpListenerCallbacks에게 Accept 요청을 수행하는데 호출되는 주체가 Connection Handler에서 전달한 ActiveTcpListener라는 것입니다. 따라서 향후 사용자가 접속하게되면, 그에 대한 Accept 처리는 ActiveTcpListener가 담당하게됩니다.

dispatcher_impl.cc

Network::ListenerPtr DispatcherImpl::createListener(Network::SocketSharedPtr&& socket,
                                                    Network::TcpListenerCallbacks& cb,
                                                    Runtime::Loader& runtime, bool bind_to_port,
                                                    bool ignore_global_conn_limit) {
  return std::make_unique<Network::TcpListenerImpl>(*this, random_generator_, runtime,
                                                    std::move(socket), cb, bind_to_port,
                                                    ignore_global_conn_limit);
}

8. 생성된 Listener에서는 소켓 정보를 libevent에 등록하여 향후 Client가 접속을 요청했을 때 libevent에 의해 요청을 전달받을 수 있도록 등록합니다.

tcp_listener_impl.cc

socket_->ioHandle().initializeFileEvent(
    dispatcher, [this](uint32_t events) -> void { onSocketEvent(events); },
    Event::FileTriggerType::Level, Event::FileReadyType::Read);

위와같이 8단계를 거치게되면, 생성된 모든 Worker 쓰레드에서 Listener 및 소켓을 생성하고 Client 요청을 수신받을 수 있는 상태가 완료됩니다.

3. Client Connection 연결 과정

지금까지 Envoy를 기동하는 과정에서 Worker 쓰레드가 생성되고, Listener 및 Socket을 생성하는 것을 살펴봤습니다.

tcp_listener_impl.cc

TcpListenerImpl::TcpListenerImpl(Event::DispatcherImpl& dispatcher, Random::RandomGenerator& random,
                                 Runtime::Loader& runtime, SocketSharedPtr socket,
                                 TcpListenerCallbacks& cb, bool bind_to_port,
                                 bool ignore_global_conn_limit)
    : BaseListenerImpl(dispatcher, std::move(socket)), cb_(cb), random_(random), runtime_(runtime),
      bind_to_port_(bind_to_port), reject_fraction_(0.0),
      ignore_global_conn_limit_(ignore_global_conn_limit) {
  if (bind_to_port) {
    socket_->ioHandle().initializeFileEvent(
        dispatcher, [this](uint32_t events) -> void { onSocketEvent(events); },
        Event::FileTriggerType::Level, Event::FileReadyType::Read);
  }
}

이때 dispatcher를 통해서 libevent에서 해당 소켓에 이벤트가 감지되면, onSocketEvent 메소드를 호출하도록 위 코드와 같이 등록됩니다. 즉 이 과정을 통해서 각각의 Worker 쓰레드에 존재하는 Listener는 dispatcher에 의해 libevent로 등록되었으므로 사용자가 OS로부터 Socket 생성을 요청했을 때, OS는 등록된 socket 중 하나를 임의로 선정하여 요청을 전달할 수 있게됩니다.

그렇다면 Listener 설정이 모두 완료된 이후 Client로부터 Connection 요청이 들어오면 어떠한 과정을 거치게될까요?

먼저 Socket Event가 감지되면, 위와 같이 두개의 Worker 쓰레드 중 누가 해당 요청을 처리해야하는지 선택해야합니다. 이때 Worker 쓰레드 선정에 대한 결정은 이전에 설명했듯이 전적으로 OS가 수행합니다. 따라서 가령 위와같이 Worker_0번이 선택되었으면, 해당 쓰레드의 onSocketEvent가 실행될 것입니다.

tcp_listener_impl.cc

void TcpListenerImpl::onSocketEvent(short flags) {
  ASSERT(bind_to_port_);
  ASSERT(flags & (Event::FileReadyType::Read));

  while (1) {
    if (!socket_->ioHandle().isOpen()) {
      PANIC(fmt::format("listener accept failure: {}", errorDetails(errno)));
    }

    sockaddr_storage remote_addr;
    socklen_t remote_addr_len = sizeof(remote_addr);

    IoHandlePtr io_handle =
        socket_->ioHandle().accept(reinterpret_cast<sockaddr*>(&remote_addr), &remote_addr_len);
    if (io_handle == nullptr) {
      break;
    }

    if (rejectCxOverGlobalLimit()) {
      io_handle->close();
      cb_.onReject(TcpListenerCallbacks::RejectCause::GlobalCxLimit);
      continue;
    } else if (random_.bernoulli(reject_fraction_)) {
      io_handle->close();
      cb_.onReject(TcpListenerCallbacks::RejectCause::OverloadAction);
      continue;
    }

    const Address::InstanceConstSharedPtr& local_address =
        local_address_ ? local_address_ : io_handle->localAddress();

    const Address::InstanceConstSharedPtr remote_address =
        (remote_addr.ss_family == AF_UNIX)
            ? io_handle->peerAddress()
            : Address::addressFromSockAddrOrThrow(remote_addr, remote_addr_len,
                                                  local_address->ip()->version() ==
                                                      Address::IpVersion::v6);
    cb_.onAccept(
        std::make_unique<AcceptedSocketImpl>(std::move(io_handle), local_address, remote_address));
  }
}

onSocketEvent 메소드가 호출되면, 가장 먼저 수행하는 것은 연결된 Connection 갯수가 Global 설정을 넘어섰는지 확인합니다. 이 과정에서 Global Limit이 지정되어있고 신규 연결 요청이 Limit을 넘어서게되면, 해당 소켓에 대한 연결은 Close하고 종결처리 합니다.

이때 Global Limit으로 지정될 수 있는 값은 overload.global_downstrea_max_connections에 의해서 지정될 수 있으며, 해당 값은 OverloadManager에 의해서 관리되는 값입니다. 따라서 현재 Socket에 Accepted된 개수가 해당 값을 넘었을 경우에는 Socket 연결을 해제합니다. 해당 값에 대한 자세한 설명은 envoy 공식문서를 참고 바랍니다.

반대로 요청이 Global Limit을 넘지 않았을 경우는 AcceptedSocket을 생성하고 Worker 쓰레드 내 Listener는 Socket 연결에 대한 Accept 처리를 위임합니다.

위 그림은 AcceptedSocket 클래스 구조를 나타냅니다. 위 내용을 통해서 우리는 AcceptedSocket을 만드는 이유에 대해서 유추해볼 수 있습니다. 코드를 살펴보면, global_accetped_socket_count_ 라는 값이 static으로 지정되어있음을 알 수 있습니다. 그리고 생성자, 소멸자 단계에서 해당 값이 증감하는 것 또한 알 수 있습니다.

이를 통해서 확인되는 사실은 Socket이 접속하면 현재 Accepted된 Socket 개수를 파악할 수 있습니다. 또한 새로운 Socket이 연결되었을 때 Global Limit을 넘는지 검증할 수 있는 기준을 제시합니다.

AcceptedSocket을 만들고나면 그 다음에는 해당 Socket을 Listener에서 Accept하는 과정이 진행됩니다.

tcp_listener_impl.cc

void TcpListenerImpl::onSocketEvent(short flags) {
  ...(중략)...
  cb_.onAccept(
        std::make_unique<AcceptedSocketImpl>(std::move(io_handle), local_address, remote_address));
}

이전에 살펴본 onSocketEvent 메소드의 마지막 줄을 살펴보면, 저장된 Callback에서 onAccept를 수행해달라고 요청하는 것을 볼 수 있습니다. 이는 TcpListenerImpl을 생성할 때, 해당 Callback 값이 Worker에 존재하는 ActiveTcpListener 이므로 해당 ActiveTcpListener가 실질적으로 Accept를 수행함을 의미합니다.

active_tcp_listener.cc

void ActiveTcpListener::onAccept(Network::ConnectionSocketPtr&& socket) {
  if (listenerConnectionLimitReached()) {
    RELEASE_ASSERT(socket->connectionInfoProvider().remoteAddress() != nullptr, "");
    ENVOY_LOG(trace, "closing connection from {}: listener connection limit reached for {}",
              socket->connectionInfoProvider().remoteAddress()->asString(), config_->name());
    socket->close();
    stats_.downstream_cx_overflow_.inc();
    return;
  }

  onAcceptWorker(std::move(socket), config_->handOffRestoredDestinationConnections(), false);
}

ActiveTcpListener에서의 Accept 과정을 살펴보면 위 코드와 같습니다.

먼저 listenerConnectionLimitReached 메소드를 수행하면서 이를 위반할 경우 Socket을 Close하는 것을 볼 수 있습니다. 이는 이전의 Connection은 Envoy 전체의 Connection을 살펴본 것이라면, 이번에는 개별 listener 별로 Connection 제한이 있는지 검사하고 만약 지정된 값이 있을 경우 그 값을 넘어서게되면 Accept하지 않습니다. 해당 설정은 Listener에서 수행할 수 있으며 envoy 공식 문서에서 이에 대해서 소개하고 있으니 참고 바랍니다.

ActiveTcpListener에서는 Limit 검사만 체크하고 다시 Socket에 대한 Accept는 onAcceptWorker 메소드 호출을 통해 후속 작업을 처리합니다.

active_tcp_listener.cc

void ActiveTcpListener::onAcceptWorker(Network::ConnectionSocketPtr&& socket,
                                       bool hand_off_restored_destination_connections,
                                       bool rebalanced) {
  if (!rebalanced) {
    Network::BalancedConnectionHandler& target_handler =
        connection_balancer_.pickTargetHandler(*this);
    if (&target_handler != this) {
      target_handler.post(std::move(socket));
      return;
    }
  }

  auto active_socket = std::make_unique<ActiveTcpSocket>(*this, std::move(socket),
                                                         hand_off_restored_destination_connections);

  onSocketAccepted(std::move(active_socket));
}

이번에는 onAcceptWorker 메소드 내용을 살펴보겠습니다. 해당 코드를 살펴보면 connection_balancer에 의해서 TargetHandler를 구하는 것을 볼 수 있습니다.

그렇다면 connection_balancer는 무엇일까요?

static_resources:
  listeners:
  - connection_balance_config:
      extend_balance:
        name: envoy.network.connection_balance.dlb
        typed_config:
          "@type": type.googleapis.com/envoy.extensions.network.connection_balance.dlb.v3alpha.Dlb

envoy에서는 쓰레드간의 효율적인 Socket 분배를 위해서 만약 하드웨어에서 DLB 지원이 된다면, 이를 사용하여 Connection을 안정적으로 분배할 수 있는 기능을 제공합니다. 이때 위와 같이 connection_balance_config를 지정하면, 해당 설정을 토대로 connection_balancer가 Target을 지정합니다.

해당 기술은 내부적으로는 Intel DLB hardware를 통해 구현되며, 위와 같이 Config 설정이 지정되어있다면 다른 Target으로 Load를 분산시킬 수 있습니다. 만약 지정되지 않았다면, 현재 Worker 쓰레드에서 Accept 과정이 정상적으로 진행될 것입니다. 이와 관련된 자세한 내용은 envoy 공식문서에 설명되어있으니 참고 바랍니다.

참고로 본 포스팅에서는 DLB 설정이 지정되어있지 않았다고 가정하므로 현재 Worker 쓰레드에서 해당 처리를 진행한다고 가정하겠습니다.

active_tcp_listener.cc

void ActiveTcpListener::onAcceptWorker(Network::ConnectionSocketPtr&& socket,
                                       bool hand_off_restored_destination_connections,
                                       bool rebalanced) {
  ...(중략)...

  auto active_socket = std::make_unique<ActiveTcpSocket>(*this, std::move(socket),
                                                         hand_off_restored_destination_connections);

  onSocketAccepted(std::move(active_socket));
}

connection_balancer에 의해서 선정된 target이 자기 자신이라면 해당 연결을 허용하기 위해 ActiveTcpSocket을 만드는 것을 볼 수 있습니다.

ActiveTcpSocket까지 생성되면, 향후 Client의 요청은 해당 Socket을 통해서 모두 처리가됩니다.

즉 이말은 이전에 Envoy를 처음 학습할 때 살펴봤듯이 Client가 Envoy에게 특정 API를 요청하면, 내부적으로 Listener Filters와 Filter Chains를 통과하면서 Upstream 대상을 찾고 전달한다고 했는데, 이 과정을 수행하는 주체가 해당 소켓이 됩니다. 따라서 Active Tcp Socket은 이를 지원하기 위해서 다양한 내부 프로퍼티가 있는데, 그 중 Filter와 관련된 것이 accept_filters 입니다. 해당 속성을 기반으로 향후 Listener Filters를 만들고 이를 수행하고 그 다음에는 Filter Chains를 생성하고 이를 수행하는 작업을 진행합니다. 그리고 해당 작업을 위해서 ActiveTcpSocket을 만든 이후 onSocketAccepted를 호출합니다.

active_stream_listener_base.h

void onSocketAccepted(std::unique_ptr<ActiveTcpSocket> active_socket) {
  // Create and run the filters
  if (config_->filterChainFactory().createListenerFilterChain(*active_socket)) {
    active_socket->startFilterChain();
  } else {
    // If create listener filter chain failed, it means the listener is missing
    // config due to the ECDS. Then close the connection directly.
    active_socket->socket().close();
    ASSERT(active_socket->isEndFilterIteration());
  }

  // Move active_socket to the sockets_ list if filter iteration needs to continue later.
  // Otherwise we let active_socket be destructed when it goes out of scope.
  if (!active_socket->isEndFilterIteration()) {
    active_socket->startTimer();
    LinkedList::moveIntoListBack(std::move(active_socket), sockets_);
  } else {
    if (!active_socket->connected()) {
      // If active_socket is about to be destructed, emit logs if a connection is not created.
      if (active_socket->streamInfo() != nullptr) {
        emitLogs(*config_, *active_socket->streamInfo());
      } else {
        // If the active_socket is not connected, this socket is not promoted to active
        // connection. Thus the stream_info_ is owned by this active socket.
        ENVOY_BUG(active_socket->streamInfo() != nullptr,
                  "the unconnected active socket must have stream info.");
      }
    }
  }
}

위 코드는 onSocketAccepted 메소드 내용입니다. 코드를 살펴보면, Socket이 Accepted 되면 가장 먼저 해당 소켓에 해당되는 ListenerFilterChain을 생성하고 FilterChain을 수행하는 것을 볼 수 있습니다. 즉 이 과정부터 해당 소켓은 각종 Filter들을 통과하면서 Upstream 연결이 이어지게됩니다.

해당 과정을 조금 더 자세히 살펴보겠습니다.

이전 내용을 토대로 ActiveTcpListener 에서 ActiveTcpSocket을 만든 것을 확인했습니다. 그리고 createListenerFactory 메소드를 호출하면서 생성한 ActiveTcpSocket을 전달했습니다.

그러면 내부적으로는 Listener Config에 이미 저장되어있는 listener_filter_factories 내부에 매핑된 Factory Callback을 하나씩 실행시키면서 ActiveTcpSocket의 accept_filters에 Filter를 하나씩 생성하는 과정을 거칩니다. 해당 과정을 코드로 살펴보면 다음과 같습니다.

listener_impl.cc

bool ListenerImpl::createListenerFilterChain(Network::ListenerFilterManager& manager) {
  if (Configuration::FilterChainUtility::buildFilterChain(manager, listener_filter_factories_)) {
    return true;
  } else {
    ENVOY_LOG(debug, "New connection accepted while missing configuration. "
                     "Close socket and stop the iteration onAccept.");
    missing_listener_config_stats_.extension_config_missing_.inc();
    return false;
  }
}

위 코드는 ActiveTcpListener 에서 ActiveTcpSocket을 생성 후 ListenerFilterChain을 생성하기 위해 createListenerFilterChain 메소드를 호출하였을 때 과정을 나타냅니다. 코드를 살펴보면, buildFilterChain 함수 호출을 통해 자신이 보유하고 있는 listener_filter_factories_ 목록을 전달하는 것을 볼 수 있습니다.

configuration_impl.cc

bool FilterChainUtility::buildFilterChain(Network::ListenerFilterManager& filter_manager,
                                          const Filter::ListenerFilterFactoriesList& factories) {
  for (const auto& filter_config_provider : factories) {
    auto config = filter_config_provider->config();
    if (!config.has_value()) {
      return false;
    }
    auto config_value = config.value();
    config_value(filter_manager);
  }

  return true;
}

buildFilterChain 내부를 살펴보면, 전달받은 factories를 순회하면서 callback 함수를 순차적으로 수행시키는 것을 볼 수 있습니다. 그리고 해당 callback을 수행할 때 전달받은 ActiveTcpSocket 정보를 다시 넘기는 것을 확인할 수 있습니다.

config.cc

[listener_filter_matcher, config](Network::ListenerFilterManager& filter_manager) -> void {
  filter_manager.addAcceptFilter(listener_filter_matcher, std::make_unique<Filter>(config));
};

위 코드는 http instpector Listener Filter의 Factory 코드이며, 개별 Listener Filter Factory의 리턴 값은 위와 같이 FilterManager 즉 ActiveTcpSocket 정보로 받아서 addAcceptFilter 메소드를 호출하고 있는 것을 볼 수 있습니다. 또한 인자를 통해서 Factory에서 보유하고 있는 Filter 정보를 새롭게 생성하여 전달하는 것을 볼 수 있습니다.

active_tcp_socket.h

void addAcceptFilter(const Network::ListenerFilterMatcherSharedPtr& listener_filter_matcher,
                     Network::ListenerFilterPtr&& filter) override {
  accept_filters_.emplace_back(
      std::make_unique<GenericListenerFilter>(listener_filter_matcher, std::move(filter)));
}

그리고 ActiveTcpSocket에서는 전달받은 Filter를 accept_filters에 추가함으로써 Listener Filter Chain을 완성합니다.

active_stream_listener_base.h

void onSocketAccepted(std::unique_ptr<ActiveTcpSocket> active_socket) {  
  ...(중략)...
    active_socket->startFilterChain();
  ...(후략)...
}

FilterChain이 완성되면, startFilterChain()을 통해 ListenerFilterChain을 차례로 수행하도록 요청합니다.

active_tcp_socket.h

void startFilterChain() { continueFilterChain(true); }

startFilterChain()은 다시 내부에 continueFilterChain 메소드에 처리를 위임합니다.

active_tcp_socket.cc

void ActiveTcpSocket::continueFilterChain(bool success) {
  if (success) {
    bool no_error = true;
    if (iter_ == accept_filters_.end()) {
      iter_ = accept_filters_.begin();
    } else {
      iter_ = std::next(iter_);
    }

    for (; iter_ != accept_filters_.end(); iter_++) {
      Network::FilterStatus status = (*iter_)->onAccept(*this);
      if (status == Network::FilterStatus::StopIteration) {        
        if (!socket().ioHandle().isOpen()) {          
          no_error = false;
          break;
        } else {
          // If the listener maxReadBytes() is 0, then it shouldn't return
          // `FilterStatus::StopIteration` from `onAccept` to wait for more data.
          ASSERT((*iter_)->maxReadBytes() != 0);
          if (listener_filter_buffer_ == nullptr) {
            if ((*iter_)->maxReadBytes() > 0) {
              createListenerFilterBuffer();
            }
          } else {
            // If the current filter expect more data than previous filters, then
            // increase the filter buffer's capacity.
            if (listener_filter_buffer_->capacity() < (*iter_)->maxReadBytes()) {
              listener_filter_buffer_->resetCapacity((*iter_)->maxReadBytes());
            }
          }
          if (listener_filter_buffer_ != nullptr) {
            listener_filter_buffer_->activateFileEvent(Event::FileReadyType::Read);
          }
          // Waiting for more data.
          return;
        }
      }
    }
    // Successfully ran all the accept filters.
    if (no_error) {
      newConnection();
    } else {
      // Signal the caller that no extra filter chain iteration is needed.
      iter_ = accept_filters_.end();
    }
  }

  // Filter execution concluded, unlink and delete this ActiveTcpSocket if it was linked.
  if (inserted()) {
    unlink();
  }
}

continueFilterChain 코드 내용을 자세히 살펴보면, 생성된 Listener Filters(accept_filters)를 순회하면서 onAccept를 통해 Filter로직을 수행하는 것을 볼 수 있습니다.

만약 Filter onAccept 순회 도중에 Stop을 해야될 경우가 존재한다면, 이유를 살펴보고 요청을 중지하던지 아니면 설정 변경 후 재수행을 수행하도록 작성되어있습니다.

그리고 모든 Filter 순회가 종료되면, 사용자 요청에 대한 Metadata 및 요청 정보를 모두 분석하였으므로 그 다음에는 newConnection() 메소드를 호출하여 본격적으로 downstream간의 연결을 위한 작업을 진행합니다.

active_tcp_socket.cc

void ActiveTcpSocket::newConnection() {
  connected_ = true;

  // Check if the socket may need to be redirected to another listener.
  Network::BalancedConnectionHandlerOptRef new_listener;

  if (hand_off_restored_destination_connections_ &&
      socket_->connectionInfoProvider().localAddressRestored()) {
    // Find a listener associated with the original destination address.
    new_listener =
        listener_.getBalancedHandlerByAddress(*socket_->connectionInfoProvider().localAddress());
  }

  // Reset the file events which are registered by listener filter.
  // reference https://github.com/envoyproxy/envoy/issues/8925.
  if (listener_filter_buffer_ != nullptr) {
    listener_filter_buffer_->reset();
  }

  if (new_listener.has_value()) {
    ...(중략)...
    new_listener.value().get().onAcceptWorker(std::move(socket_), false, false);
  } else {
    // Set default transport protocol if none of the listener filters did it.
    if (socket_->detectedTransportProtocol().empty()) {
      socket_->setDetectedTransportProtocol("raw_buffer");
    }
    accept_filters_.clear();
    // Create a new connection on this listener.
    listener_.newConnection(std::move(socket_), std::move(stream_info_));
  }
}

newConnection 메소드를 호출하면, 다른 Listener로 Redirect 해야할 필요가 있는지를 살펴보고 listener에 새로운 Connection 할당을 요청합니다.

active_stream_listener_base.cc

void ActiveStreamListenerBase::newConnection(Network::ConnectionSocketPtr&& socket,
                                             std::unique_ptr<StreamInfo::StreamInfo> stream_info) {
  // Find matching filter chain.
  const auto filter_chain = config_->filterChainManager().findFilterChain(*socket);
  if (filter_chain == nullptr) {
    ...(중략)...
    socket->close();
    return;
  }
 ...(후략)...
}

newConnection 메소드를 살펴보면, 먼저 Listener의 FilterChainManager로부터 해당 소켓 정보에 해당하는 Filter Chain을 찾는 과정을 수행합니다. 그리고 이 과정에서 매칭되는 Filter Chain을 찾지 못한다면, 연결된 Socket을 종료하고 마칩니다.

filter_chain_manager_impl.cc

const Network::FilterChain*
FilterChainManagerImpl::findFilterChain(const Network::ConnectionSocket& socket) const {
  if (matcher_) {
    return findFilterChainUsingMatcher(socket);
  }

  const auto& address = socket.connectionInfoProvider().localAddress();

  const Network::FilterChain* best_match_filter_chain = nullptr;
  // Match on destination port (only for IP addresses).
  if (address->type() == Network::Address::Type::Ip) {
    const auto port_match = destination_ports_map_.find(address->ip()->port());
    if (port_match != destination_ports_map_.end()) {
      best_match_filter_chain = findFilterChainForDestinationIP(*port_match->second.second, socket);
      if (best_match_filter_chain != nullptr) {
        return best_match_filter_chain;
      } else {
        // There is entry for specific port but none of the filter chain matches. Instead of
        // matching catch-all port 0, the fallback filter chain is returned.
        return default_filter_chain_.get();
      }
    }
  }
  // Match on catch-all port 0 if there is no specific port sub tree.
  const auto port_match = destination_ports_map_.find(0);
  if (port_match != destination_ports_map_.end()) {
    best_match_filter_chain = findFilterChainForDestinationIP(*port_match->second.second, socket);
  }
  return best_match_filter_chain != nullptr
             ? best_match_filter_chain
             // Neither exact port nor catch-all port matches. Use fallback filter chain.
             : default_filter_chain_.get();
}

위 코드는 Filter Chain Manager로 부터 Filter Chain을 찾는 과정을 보여줍니다.

Filter Chain Manager는 Listener 기동 시점에 설정 정보를 파싱하여 Filter Chain 정보를 모두 가지고 있습니다. 따라서 Socket의 Address 정보를 토대로 원하는 Filter Chain을 찾아서 반환해줍니다. 만약에 상응하는 Filter Chain 정보를 찾지 못한 경우에는 Default Filter Chain을 반환합니다.

active_stream_listener_base.cc

void ActiveStreamListenerBase::newConnection(Network::ConnectionSocketPtr&& socket,
                                             std::unique_ptr<StreamInfo::StreamInfo> stream_info) {
  ...(중략)...
  stream_info->setFilterChainName(filter_chain->name());
  auto transport_socket = filter_chain->transportSocketFactory().createDownstreamTransportSocket();
  auto server_conn_ptr = dispatcher().createServerConnection(
      std::move(socket), std::move(transport_socket), *stream_info);
  if (const auto timeout = filter_chain->transportSocketConnectTimeout();
      timeout != std::chrono::milliseconds::zero()) {
    server_conn_ptr->setTransportSocketConnectTimeout(
        timeout, stats_.downstream_cx_transport_socket_connect_timeout_);
  }
  server_conn_ptr->setBufferLimits(config_->perConnectionBufferLimitBytes());
  ...(중략)...
  const bool empty_filter_chain = !config_->filterChainFactory().createNetworkFilterChain(
      *server_conn_ptr, filter_chain->networkFilterFactories());
  if (empty_filter_chain) {
    ...(중략),,,
    server_conn_ptr->close(Network::ConnectionCloseType::NoFlush);
  }
  newActiveConnection(*filter_chain, std::move(server_conn_ptr), std::move(stream_info));
}

매칭되는 Filter Chain을 찾았으면, 위 코드와 같은 과정을 거칩니다. 주요 내용을 살펴보면 다음과 같습니다.

1. Downstream을 위한 Transport Socket을 생성합니다.

2. dispatcher에게 ServerConnection을 요청합니다.

dispatcher_impl.cc

Network::ServerConnectionPtr
DispatcherImpl::createServerConnection(Network::ConnectionSocketPtr&& socket,
                                       Network::TransportSocketPtr&& transport_socket,
                                       StreamInfo::StreamInfo& stream_info) {
  ASSERT(isThreadSafe());
  return std::make_unique<Network::ServerConnectionImpl>(
      *this, std::move(socket), std::move(transport_socket), stream_info, true);
}

이때 내부적으로 dispatcher에서는 ServerConnectionImpl을 생성하는 것을 볼 수 있습니다.

connection_impl.cc

ServerConnectionImpl::ServerConnectionImpl(Event::Dispatcher& dispatcher,
                                           ConnectionSocketPtr&& socket,
                                           TransportSocketPtr&& transport_socket,
                                           StreamInfo::StreamInfo& stream_info, bool connected)
    : ConnectionImpl(dispatcher, std::move(socket), std::move(transport_socket), stream_info,
                     connected) {}

생성되는 ServerConnectionImpl의 생성자는 위와 같으며, 부호 생성자에게 전달받은 인자들을 넘깁니다.

connection_impl.cc

ConnectionImpl::ConnectionImpl(Event::Dispatcher& dispatcher, ConnectionSocketPtr&& socket,
                               TransportSocketPtr&& transport_socket,
                               StreamInfo::StreamInfo& stream_info, bool connected)
    : ConnectionImplBase(dispatcher, next_global_id_++),
      transport_socket_(std::move(transport_socket)), socket_(std::move(socket)),
      stream_info_(stream_info), filter_manager_(*this, *socket_),
      write_buffer_(dispatcher.getWatermarkFactory().createBuffer(
          [this]() -> void { this->onWriteBufferLowWatermark(); },
          [this]() -> void { this->onWriteBufferHighWatermark(); },
          []() -> void { /* TODO(adisuissa): Handle overflow watermark */ })),
      read_buffer_(dispatcher.getWatermarkFactory().createBuffer(
          [this]() -> void { this->onReadBufferLowWatermark(); },
          [this]() -> void { this->onReadBufferHighWatermark(); },
          []() -> void { /* TODO(adisuissa): Handle overflow watermark */ })),
      write_buffer_above_high_watermark_(false), detect_early_close_(true),
      enable_half_close_(false), read_end_stream_raised_(false), read_end_stream_(false),
      write_end_stream_(false), current_write_end_stream_(false), dispatch_buffered_data_(false),
      transport_wants_read_(false) {

  if (!connected) {
    connecting_ = true;
  }

  Event::FileTriggerType trigger = Event::PlatformDefaultTriggerType;

  // We never ask for both early close and read at the same time. If we are reading, we want to
  // consume all available data.
  socket_->ioHandle().initializeFileEvent(
      dispatcher_, [this](uint32_t events) -> void { onFileEvent(events); }, trigger,
      Event::FileReadyType::Read | Event::FileReadyType::Write);

  transport_socket_->setTransportSocketCallbacks(*this);

  // TODO(soulxu): generate the connection id inside the addressProvider directly,
  // then we don't need a setter or any of the optional stuff.
  socket_->connectionInfoProvider().setConnectionID(id());
  socket_->connectionInfoProvider().setSslConnection(transport_socket_->ssl());
}

ConnectionImpl 생성자 내부를 살펴보면, Socket 내부에 Write/Read 전용 Buffer를 설정하는 것을 볼 수 있습니다. 해당 Buffer는 사용자가 HTTP 요청을 전달했을 때 데이터를 읽는 용도 그리고 upstream으로부터 응답 데이터가 전달되었을 때 기록하는 용도로 사용됩니다.

또한 downstream을 위한 transport_socket 생성 및 Filter Chains 관리를 위한 filter_manager를 생성합니다.

중요하게 살펴볼 부분은 향후 Socket 내부에 Read/Write 이벤트가 감지되면 이를 통지받고 후속 작업을 처리하기 위해 Dispatcher에게 onFileEvent()를 등록하는 부분입니다. 이는 내부적으로 다시 libevent에게 등록이 되며, 향후 Client가 HTTP 요청을 전달하게 되면, 해당 메소드로 요청 항목이 전달되어 후속 작업을 수행할 수 있습니다.

3. Filter Chain으로부터 생성해야할 Filter 목록을 확인하여 Filter Chains(Network Filters)를 생성합니다.

ServerConnection을 생성하고 나면, 그 다음에는 Filter Chains를 생성하는 작업을 수행합니다. 이를 위해 Listener 에게 FilterChain 생성을 요청합니다. 이때 생성되는 Filter Chains는 ServerConnection 내부에 매핑되어야하기 때문에 해당 정보를 Filter Chains와 같이 전달합니다.

listener_impl.cc

bool ListenerImpl::createNetworkFilterChain(
    Network::Connection& connection,
    const std::vector<Network::FilterFactoryCb>& filter_factories) {
  return Configuration::FilterChainUtility::buildFilterChain(connection, filter_factories);
}

요청을 전달받은 Listener는 Filter Chains 생성 처리를 buildFilterChain util 함수에 위임합니다.

configuration_impl.cc

bool FilterChainUtility::buildFilterChain(Network::FilterManager& filter_manager,
                                          const std::vector<Network::FilterFactoryCb>& factories) {
  for (const Network::FilterFactoryCb& factory : factories) {
    factory(filter_manager);
  }

  return filter_manager.initializeReadFilters();
}

buildFilterChains는 전달받은 Filter를 순차적으로 순회하면서 ServerConnection 내부에 생성하도록 Callback 팩토리 메소드를 수행합니다.

config.cc

return [singletons, filter_config, &context,
        clear_hop_by_hop_headers](Network::FilterManager& filter_manager) -> void {
  auto hcm = std::make_shared<Http::ConnectionManagerImpl>(
      *filter_config, context.drainDecision(), context.api().randomGenerator(),
      context.httpContext(), context.runtime(), context.localInfo(), context.clusterManager(),
      context.overloadManager(), context.mainThreadDispatcher().timeSource());
  if (!clear_hop_by_hop_headers) {
    hcm->setClearHopByHopResponseHeaders(false);
  }
  filter_manager.addReadFilter(std::move(hcm));
};

가령 위 코드는 Http Connection Manager Filter에서 반환하는 Callback Factory 메소드가 수행되었다고 가정해봤습니다.

이때 인자로 ServerConnection을 전달받았으며, 해당 람다내에서는 HttpConnectionManager를 생성한 다음 ServerConnection 내부에 addReadFilter를 호출하여 Filter 정보를 등록하는 것을 볼 수 있습니다.

connection_impl.cc

void ConnectionImpl::addReadFilter(ReadFilterSharedPtr filter) {
  filter_manager_.addReadFilter(filter);
}

이 경우 호출되는 ServerConnection 내부에서는 filter_manager를 통해 readFilter를 등록하도록 재요청합니다.

filter_manager_impl.cc

void FilterManagerImpl::addReadFilter(ReadFilterSharedPtr filter) {
  ASSERT(connection_.state() == Connection::State::Open);
  ActiveReadFilterPtr new_filter = std::make_unique<ActiveReadFilter>(*this, filter);
  filter->initializeReadFilterCallbacks(*new_filter);
  LinkedList::moveIntoListBack(std::move(new_filter), upstream_filters_);
}

filter_manager에서 addReadFilter가 호출되면, 생성된 Filter에 ActiveReadFilter 정보를 전달하여 해당 Filter 내에서 향후 Callback할 수 있도록 initializeReadFilterCallbacks를 등록합니다. 그리고 자신의 upstream_filters_에 Read Filter를 등록하는 것을 볼 수 있습니다.

conn_manager_impl.cc

void ConnectionManagerImpl::initializeReadFilterCallbacks(Network::ReadFilterCallbacks& callbacks) {
  read_callbacks_ = &callbacks;
  stats_.named_.downstream_cx_total_.inc();
  stats_.named_.downstream_cx_active_.inc();
  if (read_callbacks_->connection().ssl()) {
    stats_.named_.downstream_cx_ssl_total_.inc();
    stats_.named_.downstream_cx_ssl_active_.inc();
  }

  read_callbacks_->connection().addConnectionCallbacks(*this);

  if (!read_callbacks_->connection()
           .streamInfo()
           .filterState()
           ->hasData<Network::ProxyProtocolFilterState>(Network::ProxyProtocolFilterState::key())) {
    read_callbacks_->connection().streamInfo().filterState()->setData(
        Network::ProxyProtocolFilterState::key(),
        std::make_unique<Network::ProxyProtocolFilterState>(Network::ProxyProtocolData{
            read_callbacks_->connection().connectionInfoProvider().remoteAddress(),
            read_callbacks_->connection().connectionInfoProvider().localAddress()}),
        StreamInfo::FilterState::StateType::ReadOnly,
        StreamInfo::FilterState::LifeSpan::Connection);
  }

  if (config_.idleTimeout()) {
    connection_idle_timer_ = read_callbacks_->connection().dispatcher().createScaledTimer(
        Event::ScaledTimerType::HttpDownstreamIdleConnectionTimeout,
        [this]() -> void { onIdleTimeout(); });
    connection_idle_timer_->enableTimer(config_.idleTimeout().value());
  }

  if (config_.maxConnectionDuration()) {
    connection_duration_timer_ = read_callbacks_->connection().dispatcher().createTimer(
        [this]() -> void { onConnectionDurationTimeout(); });
    connection_duration_timer_->enableTimer(config_.maxConnectionDuration().value());
  }

  read_callbacks_->connection().setDelayedCloseTimeout(config_.delayedCloseTimeout());

  read_callbacks_->connection().setConnectionStats(
      {stats_.named_.downstream_cx_rx_bytes_total_, stats_.named_.downstream_cx_rx_bytes_buffered_,
       stats_.named_.downstream_cx_tx_bytes_total_, stats_.named_.downstream_cx_tx_bytes_buffered_,
       nullptr, &stats_.named_.downstream_cx_delayed_close_timeout_});
}

등록된 Filter가 Http Connection Manager Filter임을 가정하였으므로, initializeReadFilter를 호출하면, 위 코드 구문이 호출될 것입니다. 해당 코드를 개략적으로 살펴보면, Callback을 자신의 프로퍼티에 등록하는 작업 외에 metric 정보를 갱신하는 것을 볼 수 있습니다. 또한 Timeout이 발생하면 이를 처리하기 위해 dispatcher에게 다양한 Timer 생성 및 Timeout 발생 시 처리 하도록 등록하는 등 Read Filter 동작과 관련된 기본 초기화 작업을 수행합니다.

Http Connection Manager의 경우는 Read Filter의 역할만을 수행하기 때문에 filter_manager 내부에 upstream_filters에만 filter가 추가됩니다. 하지만 FilterChain Factory 내부에는 Read Filter 뿐만 아니라 Writer Filter의 역할을 수행하는 것도 있고 Read/Write를 모두 수행하는 Filter가 존재합니다.

filter_manager_impl.cc

void FilterManagerImpl::addWriteFilter(WriteFilterSharedPtr filter) {
  ASSERT(connection_.state() == Connection::State::Open);
  ActiveWriteFilterPtr new_filter = std::make_unique<ActiveWriteFilter>(*this, filter);
  filter->initializeWriteFilterCallbacks(*new_filter);
  LinkedList::moveIntoList(std::move(new_filter), downstream_filters_);
}

void FilterManagerImpl::addFilter(FilterSharedPtr filter) {
  addReadFilter(filter);
  addWriteFilter(filter);
}

이 경우에는 람다내에서 ServerConnectionImpl에 Filter 생성을 요청할 때 addWriteFilter 혹은 addFilter 메소드를 호출합니다. 가령 addWriterFilter의 경우는 Writer Filter만의 역할을 수행하기 때문에 궁극적으로는 filter_manager의 downstream_filters_ 에 추가되면서 Read Filter 등록과 마찬가지로 ActiveWriterFilter 인스턴스를 만들어서 향후 Callback할 수 있도록 initializeWriteFilterCallbacks를 등록하는 것을 볼 수 있습니다.

반면 addFilter의 경우는 Read/Write를 모두 수행할 때 호출되기 때문에 addReadFilter와 addWriteFilter를 차례대로 호출합니다.

configuration_impl.cc

bool FilterChainUtility::buildFilterChain(Network::FilterManager& filter_manager,
                                          const std::vector<Network::FilterFactoryCb>& factories) {
  for (const Network::FilterFactoryCb& factory : factories) {
    factory(filter_manager);
  }

  return filter_manager.initializeReadFilters();
}

Filter Factories로 부터 Filter 생성이 모두 완료되면, ServerConnectionImpl 내부 filter_manager에는 upstream 전용 filter와 downstream 전용 filter가 모두 생성되어있습니다. 그 과정이 완료되면 ServerConnectionImpl 내부의 initializeReadFilters()를 호출 합니다.

connection_impl.cc

bool ConnectionImpl::initializeReadFilters() { return filter_manager_.initializeReadFilters(); }

그리고 해당 요청을 전달받은 ServerConnectionImpl 내부에서는 다시 filter_manager에게 해당 요청 처리를 위임합니다.

filter_manager_impl.cc

bool FilterManagerImpl::initializeReadFilters() {
  if (upstream_filters_.empty()) {
    return false;
  }
  onContinueReading(nullptr, connection_);
  return true;
}

void FilterManagerImpl::onContinueReading(ActiveReadFilter* filter,
                                          ReadBufferSource& buffer_source) {
  // Filter could return status == FilterStatus::StopIteration immediately, close the connection and
  // use callback to call this function.
  if (connection_.state() != Connection::State::Open) {
    return;
  }

  std::list<ActiveReadFilterPtr>::iterator entry;
  if (!filter) {
    connection_.streamInfo().addBytesReceived(buffer_source.getReadBuffer().buffer.length());
    entry = upstream_filters_.begin();
  } else {
    entry = std::next(filter->entry());
  }

  for (; entry != upstream_filters_.end(); entry++) {
    if (!(*entry)->filter_) {
      continue;
    }
    if (!(*entry)->initialized_) {
      (*entry)->initialized_ = true;
      FilterStatus status = (*entry)->filter_->onNewConnection();
      if (status == FilterStatus::StopIteration || connection_.state() != Connection::State::Open) {
        return;
      }
    }

    StreamBuffer read_buffer = buffer_source.getReadBuffer();
    if (read_buffer.buffer.length() > 0 || read_buffer.end_stream) {
      FilterStatus status = (*entry)->filter_->onData(read_buffer.buffer, read_buffer.end_stream);
      if (status == FilterStatus::StopIteration || connection_.state() != Connection::State::Open) {
        return;
      }
    }
  }
}

해당 처리 과정을 살펴보면, 초기에 upstream_filters_에 등록할 때 ActiveReadFilter 인스턴스를 새로 생성해서 등록했는데 초기 initialized_ 값은 기본적으로 false 입니다. 따라서 위 코드에서는 등록된 upstream_filters_ 를 순회하면서 가장 먼저 onNewConnection() 작업을 수행할 것입니다.

여기에는 등록된 Filter가 Http Connection Manager 하나만 존재한다고 가정하기 때문에, 해당 Filter의 onNewConnection()이 호출됩니다.

connection_manager_impl.cc

Network::FilterStatus ConnectionManagerImpl::onNewConnection() {
  if (!read_callbacks_->connection().streamInfo().protocol()) {
    // For Non-QUIC traffic, continue passing data to filters.
    return Network::FilterStatus::Continue;
  }
  // Only QUIC connection's stream_info_ specifies protocol.
  Buffer::OwnedImpl dummy;
  createCodec(dummy);
  ASSERT(codec_->protocol() == Protocol::Http3);
  // Stop iterating through each filters for QUIC. Currently a QUIC connection
  // only supports one filter, HCM, and bypasses the onData() interface. Because
  // QUICHE already handles de-multiplexing.
  return Network::FilterStatus::StopIteration;
}

해당 코드를 잠시 살펴보면, QUIC 트래픽인지 확인하고 일반 HTTP 프로토콜이라면 해당 Filter 사용이 가능하도록 구현되어있음을 확인할 수 있습니다.

여기까지 수행하면 Filter Chains를 생성하고 Filter의 초기화까지 수행하는 전 과정을 살펴볼 수 있습니다.

active_stream_listener_base.cc

void ActiveStreamListenerBase::newConnection(Network::ConnectionSocketPtr&& socket,
                                             std::unique_ptr<StreamInfo::StreamInfo> stream_info) {
  ...(중략)...
  const bool empty_filter_chain = !config_->filterChainFactory().createNetworkFilterChain(
      *server_conn_ptr, filter_chain->networkFilterFactories());
  if (empty_filter_chain) {
    ...(중략),,,
    server_conn_ptr->close(Network::ConnectionCloseType::NoFlush);
  }
  newActiveConnection(*filter_chain, std::move(server_conn_ptr), std::move(stream_info));
}

앞서 살펴본 긴 과정의 Filter Chains를 생성하고나면, Filter Chains가 존재하는지 여부를 bool 값으로 반환합니다. 만약에 Filter Chains 생성 과정에서 생성된 FilterChains가 전혀 존재하지 않는다면, Stream을 연결하여 작업을 이어나가는 것이 무의미하기 때문에 해당 Server Connection을 종료합니다. 그렇지 않을 경우 생성된 Filter Chains를 기반으로 ActiveConnection을 생성하는 과정을 진행합니다.

active_tcp_listener.cc

void ActiveTcpListener::newActiveConnection(const Network::FilterChain& filter_chain,
                                            Network::ServerConnectionPtr server_conn_ptr,
                                            std::unique_ptr<StreamInfo::StreamInfo> stream_info) {
  auto& active_connections = getOrCreateActiveConnections(filter_chain);
  auto active_connection =
      std::make_unique<ActiveTcpConnection>(active_connections, std::move(server_conn_ptr),
                                            dispatcher().timeSource(), std::move(stream_info));
  // If the connection is already closed, we can just let this connection immediately die.
  if (active_connection->connection_->state() != Network::Connection::State::Closed) {
    ENVOY_CONN_LOG(
        debug, "new connection from {}", *active_connection->connection_,
        active_connection->connection_->connectionInfoProvider().remoteAddress()->asString());
    active_connection->connection_->addConnectionCallbacks(*active_connection);
    LinkedList::moveIntoList(std::move(active_connection), active_connections.connections_);
  }
}

여기서 ActiveConnection이란 생성된 Filter Chains를 사용하는 Connection이 얼마나 있는지를 관리하기 위한 자료구조 입니다. 따라서 getOrCreateActiveConnection 메소드를 호출함으로써, 먼저 해당 Filter에 존재하는 ActiveConnection이 있는지를 살펴봅니다.

active_stream_listener_base.cc

ActiveConnections& OwnedActiveStreamListenerBase::getOrCreateActiveConnections(
    const Network::FilterChain& filter_chain) {
  ActiveConnectionCollectionPtr& connections = connections_by_context_[&filter_chain];
  if (connections == nullptr) {
    connections = std::make_unique<ActiveConnections>(*this, filter_chain);
  }
  return *connections;
}

active_stream_listener_base.h

absl::flat_hash_map<const Network::FilterChain*, ActiveConnectionCollectionPtr>
    connections_by_context_;

active_stream_listener_base.h

class ActiveConnections : public Event::DeferredDeletable {
public:
  ActiveConnections(OwnedActiveStreamListenerBase& listener,
                    const Network::FilterChain& filter_chain);
  ~ActiveConnections() override;

  // listener filter chain pair is the owner of the connections
  OwnedActiveStreamListenerBase& listener_;
  const Network::FilterChain& filter_chain_;
  // Owned connections.
  std::list<std::unique_ptr<ActiveTcpConnection>> connections_;
};

이때 ActiveConnections를 가져오는 메소드는 위 코드와 같으며, 내부적으로는 FilterChain 별로 ActiveConnection 목록을 관리하는 hash map을 통해서 참조하는 것을 확인할 수 있습니다.

ActiveConnections를 가져오면 신규로 생성하는 ActiveConnection을 만들고 ActiveConnections에 추가하는 것으로 Client의 접속 요청 이후 Connection 할당 과정은 마무리됩니다.

4. Client Connection 연결 과정 정리

이전에 Client Connection 연결 과정을 코드를 통해서 어떻게 구성되는지 집중적으로 살펴봤습니다. 다만 지엽적인 내용까지 살펴보느라 전체적인 흐름을 이해하기 쉽지 않았을 수도 있습니다. 따라서 이번에는 큰 그림에서 컴포넌트간 메시지 교환을 중점으로 Client Connection이 어떻게 연결되는지 개략적으로 다시 살펴보도록 하겠습니다.

1. Libevent 로 부터 Listener 가 Listen 하고 있는 소켓으로 사용자의 Connection 연결 요청이 접수되었을 때, 내부적으로 존재하는 Worker 쓰레드 중 하나를 선정하여 해당 Listener의 onSocketEvent 메소드를 호출합니다. 참고로 위 예시에서는 Listener 0에 요청이 전달되었을 때 Worker 0번 쓰레드가 담당한다고 가정하여 ActiveTcpListener 0이 수신받았습니다.

2. ActiveTcpListener에서는 전체 연결된 Connection 개수가 Global Limit을 넘었는지 확인하고 내부적으로 AcceptedSocket을 거쳐 ActiveTcpSocket을 생성하여 Connection 연결을 Accept합니다.

3. 생성된 Socket에서 Listener Filter Chain을 생성하기 위해 Listener Config에게 Listener Filter Chain 정보를 요청합니다.

4. Listener Config는 Envoy 기동 과정에서 Parsing되었거나 LDS로 부터 갱신된 Listener Filter Chains 정보를 기반으로 Chains 내부에 존재하는 Factory Callback 메소드를 순회하면서 ActiveTcpSocket 내부에 있는 accept_filters에 Listener Filter를 생성하여 바인딩합니다.

5. ActiveTcpSocket은 Listener Filters를 순회하면서 onAccept를 수행합니다.

6. Filter Chains(Network Filters)를 생성하기 위해 ActiveTcpListener는 Listener Config 로부터 보유하고 있는 Filter Chains 정보를 요청합니다.

7. Listener Config 내부에 존재하는 filter_chain_manager에는 Trie, HashMap 등을 비롯하여 Filter Chain 정보를 빠르게 찾기 위한 다양한 자료구조가 존재하는데, 이를 활용하여 사용자 요청한 Filter Chain 정보를 제공합니다.

8. ActiveTcpListener는 ServerConnetionImpl을 생성하기 위해 Dispatcher에 요청합니다.

9. Dispatcher는 ServerConnectionImpl을 생성합니다.

10. 생성된 ServerConnectionImpl은 사용자가 접속 연결 이후 실질적으로 HTTP 요청 시, 이벤트를 수신 받아야되기 때문에 Dispatcher에게 Socket 이벤트를 전달하도록 등록 요청합니다.

11. Didpatcher는 Libevent에게 ServerConnectionImpl이 요청한 정보를 등록합니다. 이후 해당 Socket에 이벤트가 감지되면 ServerConnectionImpl이 등록한 onFileEvent 메소드를 호출합니다.

12. ActiveTcpListener는 Filter Chains를 생성하기 위해 Listner Config에게 처리를 요청합니다.

13. Listener Config는 Util 함수를 활용하여 Filter Chains를 생성합니다. 이때 Filter의 특성에 따라 Read Filter인 경우에는 ServerConnectionImpl 내에 있는 filter_manager의 upstream_filters_에 매핑되고 Write Filter라면 downstream_filters_에 매핑됩니다. 만약 Read/Write 둘 다 처리하는 경우에는 두 군데 모두 입력합니다.

14. 생성된 Filter Chain에 연결된 Server Connection 정보를 관리하기 위해 ActiveTcpSocket 내부에 있는 connections_by_contexts_에 신규로 생성된 ActiveConnection 정보를 등록합니다.

5. 마무리

이번 포스팅에서는 사용자가 HTTP 요청을 통해 envoy의 기능을 이용하고자 할 때 내부적으로 Listener 구성이 어떻게 되어있는지 그리고 Client Connection이 어떻게 할당되는지에 대해서 집중적으로 알아봤습니다.

envoy를 처음 학습하면, 이러한 과정이 마법처럼 느껴지는데 코드를 통해서 살펴보니 동작 과정에 대해서 어느정도 이해할 수 있었던 것 같습니다. 다음 포스팅에서는 연결이 완료된 이후 실제 HTTP 요청이 전달될 때 처리 과정에 대해서 살펴보겠습니다.

6. [envoy-internals] Http Connection Manager

cla9 — Wed, 24 May 2023 11:50:44 +0900

1. 서론

이전 시리즈 내용을 통해서 Envoy에서 가장 중요한 2가지 컴포넌트인 Listener Manager와 Cluster Manager에 대해서 살펴봤습니다.

다시 한번 전체 과정을 간략하게 표현해보면 다음과 같습니다.사용자의 접속 요청이 전달되면, Listener에서 요청을 전달받고 이에 부합하는 Cluster를 찾아 Downstream과 Upstream을 연결합니다. 이때 만약 사용자 요청이 Http 연결일 경우에는 Listener에서 Cluster Manager로 Cluster를 요청하는 주체가 Listener가 보유하고 있는 Network Filter 중 하나인 HttpConnectionManager입니다. 해당 컴포넌트는 Listener 내부에 존재하는 Filter이지만, 사용자 요청처리를 수행하는데 있어 중요한 역할을 수행하기 때문에. 이번 포스팅에서는 HttpConnectionManager의 기능에 대해서 살펴보겠습니다.

2. HttpConnectionManager

이전 포스팅을 통해 Listener 하위에는 위 그림과 같이 Filter Chains를 관리하는 filter_chain_manager가 존재함을 확인했습니다.

출처 :https://www.envoyproxy.io/docs/envoy/latest/intro/life_of_a_request#listener-tcp-accept

해당 구조 내부에는 위 그림과 같이 Trie 구조가 존재하는데, 이는 사용자가 Listener를 통해서 연결을 원하는 domain을 전달했을 때, 해당 요청에 부합되는 Filter Chain을 찾기 위한 용도로 사용됩니다. 따라서 각각의 Trie 별로 매칭되는 노드에는 Filter들이 Chain 형식으로 매핑되어있습니다.

따라서 사용자가 접속을 요청하면, 내부적으로는 해당 Trie를 검색해서 사용자의 요청에 부합되는 항목의 Filter Chain 목록을 반환합니다. 그리고 해당 Chain 목록을 전달받으면, Chain을 탐색하면서 매핑된 Factory Callback을 실행하여 Filter Chain을 구성합니다.

Envoy가 제공하는 Network Filter는 굉장히 많은 종류가 있는데요. 그 중 HttpConnectionManager는 Http 요청을 처리하는 Filter로써 이에 대해서 다루어보고자 합니다.

HttpConnectionManager는 Network Filter이므로 앞서 설명한 것과 같이 사용자가 명시한 도메인에 해당되는 Network Filter 목록에 Http 처리가 매핑되어있을 경우 Filter Chain에 포함되어있을 것입니다.

이때 사용자가 Listener에 접속을 요청할 때마다 위 그림과 같이 내부적으로 Upstream Connection을 만듭니다. 위 그림은 현재 2개의 Connection이 생성되었음을 가정했습니다. 이때 각각의 ServerConnection은 별개의 Network Filter Chain을 가지고 있게되고 만약 2개의 Connection이 모두 Http 처리를 담당해야한다면 위 그림과 같이 2개의 별개 HttpConnectionManager가 생성될 것입니다.

그렇다면 HttpConnectionManager는 어떻게 구성되어있을까요?

생성된 HttpConnectionManager는 대략 위와 같은 모습을 구성하고 있습니다. 물론 그림으로 표현한 속성 이외에 다양한 프로퍼티가 존재하지만, 핵심이라고 생각하는 몇 개만 표현했습니다. 그렇다면 각각의 속성은 무엇이며 어떤 과정을 거쳐 생성될까요? 핵심적인 요소에 대해서 하나씩 살펴보겠습니다.

3. RDS

먼저 살펴볼 것은 RDS입니다. 해당 컴포넌트는 이전에 살펴본 HttpConnectionManager의 속성 중 config_와 관련이 있습니다. 해당 config안에는 HttpConnectionManager를 구성하는데 있어 필요한 속성이 지정되어있는데요. 그중 Route 관련 속성은 route_config_provider입니다.

이전에 살펴본 그림에서 HttpConnectionManager와 SingletonManager가 연관관계를 맺고 있는 것을 확인했는데요. SingletonManager가 가진 속성 중에서 RouteConfigProviderManager가 RDS 처리를 담당하고 있습니다.

그렇다면 왜 SingletonManager에 의해서 해당 속성이 관리될까요? 위 그림을 살펴보면 HttpConnectionManager는 사용자의 Connection 별로 여러개가 생성됨을 볼 수 있습니다. 하지만 RDS 처리 또한 각각의 HttpConnectionManager를 통해 관리되어야한다면, RDS 처리를 위한 overhead 또한 증가하게되고 무엇보다 동일한 정보가 중복 관리되기 때문에 관리 용이성 또한 증가합니다. 따라서 전역적으로 하나의 인스턴스만을 생성함으로써 데이터를 한 곳에서 관리하고 모든 HttpConnectionManager가 이를 공유하도록 싱글톤 패턴이 적용되어있습니다.

해당 내용을 코드로 살펴보면 다음과 같습니다.

config.cc

Utility::Singletons Utility::createSingletons(Server::Configuration::FactoryContext& context) {
  std::shared_ptr<Http::TlsCachingDateProviderImpl> date_provider =
      context.singletonManager().getTyped<Http::TlsCachingDateProviderImpl>(
          SINGLETON_MANAGER_REGISTERED_NAME(date_provider), [&context] {
            return std::make_shared<Http::TlsCachingDateProviderImpl>(
                context.mainThreadDispatcher(), context.threadLocal());
          });

  Router::RouteConfigProviderManagerSharedPtr route_config_provider_manager =
      context.singletonManager().getTyped<Router::RouteConfigProviderManager>(
          SINGLETON_MANAGER_REGISTERED_NAME(route_config_provider_manager), [&context] {
            return std::make_shared<Router::RouteConfigProviderManagerImpl>(context.admin());
          });

  Router::ScopedRoutesConfigProviderManagerSharedPtr scoped_routes_config_provider_manager =
      context.singletonManager().getTyped<Router::ScopedRoutesConfigProviderManager>(
          SINGLETON_MANAGER_REGISTERED_NAME(scoped_routes_config_provider_manager),
          [&context, route_config_provider_manager] {
            return std::make_shared<Router::ScopedRoutesConfigProviderManager>(
                context.admin(), *route_config_provider_manager);
          });

  auto http_tracer_manager = context.singletonManager().getTyped<Tracing::HttpTracerManagerImpl>(
      SINGLETON_MANAGER_REGISTERED_NAME(http_tracer_manager), [&context] {
        return std::make_shared<Tracing::HttpTracerManagerImpl>(
            std::make_unique<Tracing::TracerFactoryContextImpl>(
                context.getServerFactoryContext(), context.messageValidationVisitor()));
      });

  std::shared_ptr<Http::DownstreamFilterConfigProviderManager> filter_config_provider_manager =
      Http::FilterChainUtility::createSingletonDownstreamFilterConfigProviderManager(
          context.getServerFactoryContext());

  return {date_provider, route_config_provider_manager, scoped_routes_config_provider_manager,
          http_tracer_manager, filter_config_provider_manager};
}

코드를 살펴보면 위와 같이 가장 먼저 하는 것은 SingletonManager에 등록된 인스턴스 중에서 RouteConfigProviderManager, ScopedRoutesConfigProviderManager 와 더불어 다양한 Manager 등 다양한 Manager를 가져오는 작업을 선행합니다.

이때 중요한 것은 앞서 언급한 2가지 Manager이며, RouteConfigProviderManager는 route_config 정보를 기반으로 RDS 혹은 StaticRouteConfig를 처리하는 인스턴스를 생성하는 역할을 수행합니다. 반면 ScopedRoutesConfigProviderManager는 Listener 설정에 scoped_routes 설정이 존재할 때 해당 scoped_routes를 처리하는 인스턴스를 생성하는 역할을 수행합니다.

config.cc

switch (config.route_specifier_case()) {
case envoy::extensions::filters::network::http_connection_manager::v3::HttpConnectionManager::
    RouteSpecifierCase::kRds:
case envoy::extensions::filters::network::http_connection_manager::v3::HttpConnectionManager::
    RouteSpecifierCase::kRouteConfig:
  route_config_provider_ = Router::RouteConfigProviderUtil::create(
      config, context_.getServerFactoryContext(), context_.messageValidationVisitor(),
      context_.initManager(), stats_prefix_, route_config_provider_manager_);
  break;
case envoy::extensions::filters::network::http_connection_manager::v3::HttpConnectionManager::
    RouteSpecifierCase::kScopedRoutes:
  scoped_routes_config_provider_ = Router::ScopedRoutesConfigProviderUtil::create(
      config, context_.getServerFactoryContext(), context_.initManager(), stats_prefix_,
      scoped_routes_config_provider_manager_);
  break;
case envoy::extensions::filters::network::http_connection_manager::v3::HttpConnectionManager::
    RouteSpecifierCase::ROUTE_SPECIFIER_NOT_SET:
  PANIC_DUE_TO_CORRUPT_ENUM;
}

HttpConnectionManager를 구성하는 단계에서 전달받은 두 속성은 이후 route 관련 정보를 생성하는데 사용됩니다. 다만 두 속성 모두가 생성되지는 않으며, 기존에 지정된 설정내역을 살펴보고 하나를 생성합니다.

즉 위 코드와 같이 config에 지정된 route_specifier에 의해서 결정됩니다. 만약 route_config 설정이 지정되어있다면, 기존에 SingletonManager로부터 부여받은 route_config_provider_manager를 전달하여 route 처리를 수행할 수 있는 route_config_provider를 전달받습니다. 반면 scoped_route라면 scoped_route_config_provider_manager를 전달하여 scoped_route_config_provider를 전달받습니다.

본포스팅에서는 route_config만 지정되어있음을 가정하며, 따라서 위 코드에서는 route_config_provider_ 만이 생성되었음을 전제로 진행하겠습니다. 또한 route를 처리하는 방식이 static이 아닌 dynamic xDS를 활용한 동적 변경을 가정하겠습니다.

route_config_provider가 생성된 이후 RDS를 매핑하는 과정을 살펴보면 위그림과 같습니다.

1. HttpConnectionManager에 매핑되어있는 route_config_provider를 기반으로 route config를 분석할 수 있는 인스턴스를 생성합니다. 이후 RouteConfigProviderManager에 존재하는 dynamic_route_config_providers_ 로부터 rds 메시지 값을 해시한 결과를 기반으로 dynamic_route_config_providers_ Map에 존재하는지 살펴보고 만약 존재한다면, 해당 provider를 반환합니다.

2. dynamic_route_config_providers_에 존재하지 않는다면, RDS 생성을 위해 Cluster Manager로부터 Subscription factory를 요청합니다.

3. xDS에 전달받기 원하는 타입 및 수신 callback을 Multiplexer에 등록합니다.

4. 등록이 완료된 이후 Subscription을 반환합니다.

5. RdsRouteConfigProviderImpl 인스턴스를 생성하고 그 안에 subscription을 바인딩합니다. 또한 dynamic_route_config_providers_ Map에 해당 인스턴스를 삽입함으로써 이후 동일한 요청이 전달되면, 새로운 provider를 생성하지 않고 매핑된 값을 반환합니다.

route_config_provider_manager_impl.h

auto subscription = std::make_shared<RdsRouteConfigSubscription>(
    std::move(config_update), std::move(resource_decoder), rds.config_source(),
    rds.route_config_name(), manager_identifier, factory_context,
    stat_prefix + absl::AsciiStrToLower(getRdsName()) + ".",
    absl::AsciiStrToUpper(getRdsName()), manager_);
auto provider = std::make_shared<RdsRouteConfigProviderImpl>(std::move(subscription),
                                                             factory_context);

6. 해당 provider와 subscription 정보를 반환합니다.

7. RdsRouteConfigProviderImpl 내부에서는 xDS API가 변경이 생겼을 때, 내부에서 ThreadLocalStorage에 존재하는 ThreadLocalConfig의 내용을 변경함으로써, 쓰레드 전체에 동일한 데이터를 공유할 수 있도록 유지합니다.

위와 같은 7가지 단계를 통해서 HttpConnectionManager가 생성될 때 Singleton Manager를 통해 전역적으로 RDS를 관리하는 하나의 provider를 공급받고, ThreadLocalStorage를 활용해서 모든 쓰레드에서 동일한 데이터에 대한 접근이 가능하도록 공유합니다.

4. Http filter

HttpConnectionManager는 Http 처리를 담당합니다. 이때 해당 컴포넌트 내부에는 http 처리를 위한 무수한 filter가 존재합니다. 참고로 envoy 공식 문서를 살펴보면 지정할 수 있는 filter가 여러가지 있음을 확인할 수 있습니다. 그리고 그 중에는 Routing을 담당하는 Router Filter 또한 존재합니다.

따라서 사용자의 요청이 전달되면 Network Filter Chain이 수행되면서 HttpConnectionManager가 실행되고 그리고 그 안에서 다시 HttpConnectionManager가 보유한 Http Filter들이 수행되면서 사용자의 요청이 처리됩니다.

이를 조금 더 살펴보겠습니다.

config.cc

Http::FilterChainHelper<Server::Configuration::FactoryContext,
                        Server::Configuration::NamedHttpFilterConfigFactory>
    helper(filter_config_provider_manager_, context_.getServerFactoryContext(), context_,
           stats_prefix_);
helper.processFilters(config.http_filters(), "http", "http", filter_factories_);

HttpConnectionManager를 구성하는 config 속성을 살펴보면, 해당 Config를 생성할 때 http_filters를 위한 factory를 생성하는 것을 볼 수 있습니다. 이때 이미 사용자가 지정하거나 LDS에 의해서 갱신된 Listener의 Config 정보를 살펴보면, 지정된 http filter 목록을 확인할 수 있습니다.

따라서 FilterChainHelper를 통해서 Config 정보를 토대로 filter_factories라는 Filter를 생성하는 Factory Callback의 리스트를 채우도록 처리를 위임합니다.

FilterChainHelper는 해당 요청을 전달받으면, DependencyManager를 통해서 전달된 Filter의 우선순위를 고려하여 정상적으로 입력이 되었는지를 검사합니다. 그리고 Filter간의 Dependency에 문제가 없게 Config가 전달되었다면, 이를 HttpConnectionManager가 보유한 filter_factories에 Filter 생성을 위한 Callback Factory 메소드를 매핑시킵니다.

위 과정을 거쳐 생성된 filter_factories_는 향후 사용자가 Http 요청을 전달하기 위해 Stream을 생성할 때 내부에 존재하는 filter_manager_로 해당 filter_factories_를 전달시켜 해당 filter_manager_가 http filter chain을 생성하고 수행할 수 있도록 처리를 위임합니다.

5. Codec

이번에 살펴볼 것은 codec입니다. HttpConnectionManager에서 codec은 사용자의 요청 정보를 분석하는 역할을 수행합니다. 사용자가 전달한 raw데이터를 지정된 프로토콜 형태로 파싱하고 분석하여 처리하는 과정에서 사용됩니다.

그림을 살펴보면, codec_은 HttpConnectionManager 내부에 있는 config에 의해서 생성할 수 있습니다. 이때 사용자의 Http 요청은 Http 1.1, Http 2.0 혹은 Http 3.0(Quic) 형태일 수 있습니다. 위 세가지 프로토콜 모두 HttpConnectionManager가 처리하는데요. 각각의 처리방식과 포맷이 다르기 때문에 사용자의 요청이 전달되었을 때, 가정 먼저 수행하는 일은 사용자의 요청이 어떤 프로토콜 형태인지를 파악하는 것입니다.

config.cc

Http::ServerConnectionPtr
HttpConnectionManagerConfig::createCodec(Network::Connection& connection,
                                         const Buffer::Instance& data,
                                         Http::ServerConnectionCallbacks& callbacks) {
  switch (codec_type_) {
  case CodecType::HTTP1:
    return std::make_unique<Http::Http1::ServerConnectionImpl>(
        connection, Http::Http1::CodecStats::atomicGet(http1_codec_stats_, context_.scope()),
        callbacks, http1_settings_, maxRequestHeadersKb(), maxRequestHeadersCount(),
        headersWithUnderscoresAction());
  case CodecType::HTTP2:
    return std::make_unique<Http::Http2::ServerConnectionImpl>(
        connection, callbacks,
        Http::Http2::CodecStats::atomicGet(http2_codec_stats_, context_.scope()),
        context_.api().randomGenerator(), http2_options_, maxRequestHeadersKb(),
        maxRequestHeadersCount(), headersWithUnderscoresAction());
  case CodecType::HTTP3:
#ifdef ENVOY_ENABLE_QUIC
    return std::make_unique<Quic::QuicHttpServerConnectionImpl>(
        dynamic_cast<Quic::EnvoyQuicServerSession&>(connection), callbacks,
        Http::Http3::CodecStats::atomicGet(http3_codec_stats_, context_.scope()), http3_options_,
        maxRequestHeadersKb(), maxRequestHeadersCount(), headersWithUnderscoresAction());
#else
    // Should be blocked by configuration checking at an earlier point.
    PANIC("unexpected");
#endif
  case CodecType::AUTO:
    return Http::ConnectionManagerUtility::autoCreateCodec(
        connection, data, callbacks, context_.scope(), context_.api().randomGenerator(),
        http1_codec_stats_, http2_codec_stats_, http1_settings_, http2_options_,
        maxRequestHeadersKb(), maxRequestHeadersCount(), headersWithUnderscoresAction());
  }
  PANIC_DUE_TO_CORRUPT_ENUM;
}

이를 Config에서 분석한 다음 Http 1.1일 경우에는 Http1::ServerConnectionImpl, Http 2.0일 경우에는 Http2:ServerConnectionImpl Http 3.0일 경우에는 QuicHttpServerConnectionImpl을 반환하여 HttpConnectionManager 내부에 존재하는 codec_에 매핑하는 작업을 수행합니다.

codec.h

class Connection {
public:
  virtual ~Connection() = default;

  /**
   * Dispatch incoming connection data.
   * @param data supplies the data to dispatch. The codec will drain as many bytes as it processes.
   * @return Status indicating the status of the codec. Holds any errors encountered while
   * processing the incoming data.
   */
  virtual Status dispatch(Buffer::Instance& data) PURE;

  /**
   * Indicate "go away" to the remote. No new streams can be created beyond this point.
   */
  virtual void goAway() PURE;

  /**
   * @return the protocol backing the connection. This can change if for example an HTTP/1.1
   *         connection gets an HTTP/1.0 request on it.
   */
  virtual Protocol protocol() PURE;

  /**
   * Indicate a "shutdown notice" to the remote. This is a hint that the remote should not send
   * any new streams, but if streams do arrive that will not be reset.
   */
  virtual void shutdownNotice() PURE;

  /**
   * @return bool whether the codec has data that it wants to write but cannot due to protocol
   *              reasons (e.g, needing window updates).
   */
  virtual bool wantsToWrite() PURE;

  /**
   * Called when the underlying Network::Connection goes over its high watermark.
   */
  virtual void onUnderlyingConnectionAboveWriteBufferHighWatermark() PURE;

  /**
   * Called when the underlying Network::Connection goes from over its high watermark to under its
   * low watermark.
   */
  virtual void onUnderlyingConnectionBelowWriteBufferLowWatermark() PURE;
};

프로토콜마다 처리 방법이 다양하지만, 모든 ServerConnectionImpl은 위와 같은 Interface 스펙을 준수합니다. 따라서 HttpConnectionManager에서는 위 interface에 정의된 메소드를 호출하여 처리를 위임할 수 있습니다. 다만 본 포스팅에서는 Http 1.1을 기준으로 처리 과정을 분석하기 때문에 Http1::ServerConnectionImpl이 반환되었다고 가정하겠습니다.

그렇다면 Http 1.1을 처리하기 위한 ServerConnectionImpl은 어떤 역할을 수행할까요? 해당 구조에 대해서 조금 더 자세히 살펴보겠습니다.

ServerConnectionImpl을 살펴보면, 여러 속성이 있지만 그 중 가장 중요한 속성은 위 2가지 입니다. 먼저 Parser_에 대해서 알아보겠습니다.

5-1. Parser

parser_의 역할은 Client로 부터 전달된 요청 내역을 Http 1.1 스펙에 맞게 분석하여 envoy가 원하는 형태로 데이터를 구성하는 작업을 담당합니다. 이때 envoy 내부에는 해당 내역을 처리하는 Parser가 2개가 존재합니다.

codec_impl.cc

ConnectionImpl::ConnectionImpl(Network::Connection& connection, CodecStats& stats,
                               const Http1Settings& settings, MessageType type,
                               uint32_t max_headers_kb, const uint32_t max_headers_count)
    : connection_(connection), stats_(stats), codec_settings_(settings),
      encode_only_header_key_formatter_(encodeOnlyFormatterFromSettings(settings)),
      processing_trailers_(false), handling_upgrade_(false), reset_stream_called_(false),
      deferred_end_stream_headers_(false), dispatching_(false), max_headers_kb_(max_headers_kb),
      max_headers_count_(max_headers_count) {
  if (Runtime::runtimeFeatureEnabled("envoy.reloadable_features.http1_use_balsa_parser")) {
    parser_ = std::make_unique<BalsaParser>(type, this, max_headers_kb_ * 1024, enableTrailers());
  } else {
    parser_ = std::make_unique<LegacyHttpParserImpl>(type, this);
  }
}

첫 번째는 LegacyHttpParserImpl로써 envoy가 기존부터 제공해온 Parser입니다. 이후 해당 Parser의 성능 개선을 위해 추가로 개발한 것이 BalsaParser입니다. 다만 BalsaParser는 아직 완전하지는 않으며, envoy에서 해당 Parser를 사용하려면

'envoy.reloadable_features.http1_use_balsa_parser' 옵션을 활성화했을 경우 사용할 수 있습니다. 참고로 본 포스팅에서는 기본으로 사용되는 LegacyHttpParserImpl에 대해서 다루어보겠습니다.

parser_가 생성되면, 추후 parser_에게 사용자 요청을 처리하도록 위임할 것입니다. 이때 Parser가 처리 중간 중간마다 특정 event 즉 header 필드명이 무엇인지 하나씩 파악했거나, header 값을 분석했을 때 이를 요청자인 ServerConnection 에게 알려줘야 해당 데이터들을 전달받아 envoy가 원하는 형태로 데이터를 가공하거나 그 이후 처리해야할 비즈니스 로직을 수행할 수 있을 것입니다.

이때 ServerConnectionImpl은 기본적으로 ParserCallbacks Virtual Class를 상속받았으며, 그 안에 정의된 메소드는 해당 메소드가 호출될 때 수행해야할 비즈니스 로직이 구현되어있습니다. 구현해야할 메소드는 위와 같이 총 10개이며, 각각의 의미는 다음과 같습니다.

메소드명	의미
onMessageBegin	Request/Response가 시작될 때 호출되는 callback으로 반환 값으로 성공/실패 메시지가 반환됨
onUrl	URL data를 Parser가 분석했을 때 호출되는 callback으로 반환 값으로 성공/실패 메시지가 반환됨
onStatus	Status data를 Parser가 분석헀을 때 호출되는 callback으로 반환 값으로 성공/실패 메시지가 반환됨
onHeaderField	header의 field 명을 수신받았을 때 호출되는 callback으로 반환 값으로 성공/실패 메시지가 반환됨
onHeaderValue	header의 value 값을 수신받았을 때 호출되는 callback으로 반환 값으로 성공/실패 메시지가 반환됨
onHeaderComplete	header 분석이 완료되었을 때 호출되는 callback으로 반환 값으로 성공/실패 메시지가 반환됨
bufferBody	body data를 분석했을 때 호출되는 callback
onMessageComplete	Parser가 HTTP 데이터를 모두 분석 완료했을 때 호출되는 callback으로 반환 값으로 성공/실패 메시지가 반환됨
onChunkHeader	chunk header를 받았을 때 호출되는 callback

이후 Parser에서는 처리 도중 중간 중간에 ParserCallbacks에 정의된 메소드를 호출함으로써, ServerConnectionImpl에게 Parsing 결과를 중간 중간 callback 하도록 구현되었습니다.

legacy_parser_impl.cc

Impl(http_parser_type type, void* data) : Impl(type) {
  parser_.data = data;
  settings_ = {
      [](http_parser* parser) -> int {
        auto* conn_impl = static_cast<ParserCallbacks*>(parser->data);
        return static_cast<int>(conn_impl->onMessageBegin());
      },
      [](http_parser* parser, const char* at, size_t length) -> int {
        auto* conn_impl = static_cast<ParserCallbacks*>(parser->data);
        return static_cast<int>(conn_impl->onUrl(at, length));
      },
      [](http_parser* parser, const char* at, size_t length) -> int {
        auto* conn_impl = static_cast<ParserCallbacks*>(parser->data);
        return static_cast<int>(conn_impl->onStatus(at, length));
      },
      [](http_parser* parser, const char* at, size_t length) -> int {
        auto* conn_impl = static_cast<ParserCallbacks*>(parser->data);
        return static_cast<int>(conn_impl->onHeaderField(at, length));
      },
      [](http_parser* parser, const char* at, size_t length) -> int {
        auto* conn_impl = static_cast<ParserCallbacks*>(parser->data);
        return static_cast<int>(conn_impl->onHeaderValue(at, length));
      },
      [](http_parser* parser) -> int {
        auto* conn_impl = static_cast<ParserCallbacks*>(parser->data);
        return static_cast<int>(conn_impl->onHeadersComplete());
      },
      [](http_parser* parser, const char* at, size_t length) -> int {
        static_cast<ParserCallbacks*>(parser->data)->bufferBody(at, length);
        return 0;
      },
      [](http_parser* parser) -> int {
        auto* conn_impl = static_cast<ParserCallbacks*>(parser->data);
        return static_cast<int>(conn_impl->onMessageComplete());
      },
      [](http_parser* parser) -> int {
        // A 0-byte chunk header is used to signal the end of the chunked body.
        // When this function is called, http-parser holds the size of the chunk in
        // parser->content_length. See
        // https://github.com/nodejs/http-parser/blob/v2.9.3/http_parser.h#L336
        const bool is_final_chunk = (parser->content_length == 0);
        static_cast<ParserCallbacks*>(parser->data)->onChunkHeader(is_final_chunk);
        return 0;
      },
      nullptr // on_chunk_complete
  };
}

즉 위 코드와 같이 LegacyHttpParserImpl 내부에는 Parsing 중간 중간 처리 결과를 반환할 수 있도록, settings_에 함수를 매핑했는데, 이때 ParserCallbacks에 정의된 규약에 따른 메소드를 호출하여 결과를 전달하는 것을 볼 수 있습니다.

5-2. Active Request

이번에는 Http1::ServerConnectionImpl이 보유하고 있는 속성 중 두번째인 active_request_ 에 대해서 알아보겠습니다.

codec_impl.h

  struct ActiveRequest : public Event::DeferredDeletable {
    ActiveRequest(ServerConnectionImpl& connection, StreamInfo::BytesMeterSharedPtr&& bytes_meter)
        : response_encoder_(connection, std::move(bytes_meter),
                            connection.codec_settings_.stream_error_on_invalid_http_message_) {}
    ~ActiveRequest() override = default;

    void dumpState(std::ostream& os, int indent_level) const;
    HeaderString request_url_;
    RequestDecoder* request_decoder_{};
    ResponseEncoderImpl response_encoder_;
    bool remote_complete_{};
  };

ActiveRequest는 위와 같이 Parser에 의해서 데이터를 Parsing 하는 과정에서 RequestDecoder, url, ResponseEncoder 등을 가지고 있는 구조체입니다. 해당 구조체를 통해서 Parsing 단계에서 connection 객체에 대한 작업 요청 및 url, encoder 지정 및 수행등을 담당합니다.

해당 자료구조가 사용되는 흐름을 보려면 사용자 요청을 처리하는 전단계를 살펴봐야하는데요. 이번 포스팅은 HttpConnectionManager의 특징에 대해서 살펴보기 때문에 ActiveRequest의 존재에 대해서만 이번 포스팅에서는 언급하고 해당 자료구조의 쓰임새는 다음 포스팅에서 보다 자세히 다루어보겠습니다.

6. Stream

이번에는 HttpConnectionManager가 관리하는 Stream 목록에 대해서 살펴보겠습니다. Stream은 Http 요청을 전달하는 하나의 흐름으로써, 하나의 Connection을 맺은 상태로 Http 요청을 전달하기 위해 여러 Stream을 생성할 수 있습니다. 따라서 이러한 개별 Stream들의 그룹을 관리하기 위해서 HttpConnectionManager 내부에는 streams_라는 List를 보유하고 있습니다.

streams_ List는 ActiveStream을 포함하고 있는데, 해당 Stream 내부에는 Http 요청에 필요한 필수적인 항목들이 포함되어있습니다. 그렇다면 ActiveStream은 언제 생성될까요?

codec_impl.cc

Status ServerConnectionImpl::onMessageBeginBase() {
  if (!resetStreamCalled()) {
    ASSERT(active_request_ == nullptr);
    active_request_ = std::make_unique<ActiveRequest>(*this, std::move(bytes_meter_before_stream_));
    if (resetStreamCalled()) {
      return codecClientError("cannot create new streams after calling reset");
    }
    active_request_->request_decoder_ = &callbacks_.newStream(active_request_->response_encoder_);

    // Check for pipelined request flood as we prepare to accept a new request.
    // Parse errors that happen prior to onMessageBegin result in stream termination, it is not
    // possible to overflow output buffers with early parse errors.
    RETURN_IF_ERROR(doFloodProtectionChecks());
  }
  return okStatus();
}

과정을 간략하게 살펴보면, 이전에 Parser에 대해서 살펴봤을 때, Client가 데이터 처리를 요청하면 이를 분석해서 특정 Event마다 통지한다고 설명했습니다. 이때 onMessageBegin 이벤트가 발생하면 ServerConnection 에서는 ActiveRequest를 먼저 생성하고 ActiveRequest 하위에 request_decoder_ 속성에 새로운 Stream을 만듭니다. 이때 만들어지는 Stream이 ActiveStream입니다.

이후 생성된 ActiveStream은 위 과정에서 표현되지는 않았지만 Parsing 과정이 진행되면서 지속적으로 참조되고 Parsing이 완료되는 시점에서 Stream 내부에 매핑된 정보에 의하여 Http 전송이 이루어지게됩니다.

이번에는 ActiveStream의 속성에 대해서 살펴보겠습니다. stream_id는 Stream 마다 생성되는 id로써, ActiveStream이 생성하는 당시에 임의의 값으로 지정됩니다.

filter_manager_ 는 이전에 Http filter에 대해서 잠깐 살펴볼 때 등장한 프로퍼티명으로써, ActiveStream 내에 Http filter 생성 및 처리를 위임하는데 관여하는 프로퍼티입니다. 사용자 요청을 처리하는 과정에서 Http filter 처리가 필요한 순간에 해당 인스턴스가 사용됩니다.

그 다음 살펴볼 것은 timer입니다. ActiveStream 내부에는 다양한 Timer가 존재하는데, 해당 timer의 역할은 timer가 지정된 시간내에 요구하는 조건이 충족되지 않으면, 해당 연결을 해제하는 역할을 수행합니다. 이때 각각의 Timer는 Dispatcher 로부터 Timer를 생성받아 지정된 시간내에 조건이 충족되면 Timer를 Reset 하여 다시 지정된 시간만큼을 대기하며, 시간이 초괴되면 연결을 해제합니다. 개별 Timer의 역할을 살펴보면 다음과 같습니다.

타이머	기능
stream_idle_timer_	해당 Stream이 연결되고 어떠한 활동도 일어나지 않았을 때, 지정된 idle 시간을 초과하면 Stream 해제
request_timer_	Stream이 생성되고 난 이후 Request를 시작하고 응답이 올 때까지 대기시간을 의미하며, 지정된 시간 초과하면 Stream 해제
request_header_timer_	Downstream에서 header를 전송하고 나서 이에 대한 응답이 올 때까지의 대기시간을 의미하며, 지정된 시간 초과하면 Stream 해제
max_stream_duration_timer_	Stream이 생성되고 종료될 때까지 지속할 수 있는 시간을 의미하며, 지정된 시간을 초과하면 Stream 해제

상기 Timer와 관련해서는 envoy 공식 문서에서 확인할 수 있으며, 적정한 값 설정을 통해서 Stream이 생성되고 무한정 대기하지 않도록 처리할 수 있습니다.

7. Timer

HttpConnectionManager에서 마지막으로 살펴볼 것은 내부 프로퍼티에 존재하는 Timer입니다. 방금전에 개별 Stream 내부에서 여러 Timer 들을 살펴봤었는데, HttpConnectionManager 또한 Timer를 보유하고 있습니다.

HttpConnectionManager가 보유한 주요 Timer는 위와같이 2개입니다. 이는 HttpConnectionManager가 생성하는 단계에서 Dispatcher에게 요청하여 Timer를 생성합니다.

connection_idle_timer_의 경우는 HttpConnectionManager가 생성된 이후 어떠한 Stream이 생성되지 않았을 때, idle 시간을 얼마나 부여할지를 측정하는 Timer입니다. 따라서 해당 시간 동안 Stream 연결이 이루어지지 않는다면, 연결을 해제합니다.

반면 connection_duration_timer_는 HttpConnectionManager가 생성되고 모든 처리가 완료될 때까지 즉 사용자의 연결 요청을 완수하는데 걸리는 데드라인을 측정하는 Timer입니다. 따라서 해당 시간 동안 모든 요청이 완료되지 않는다면, 연결을 해제합니다.

8. 마치며

이번 포스팅을 통해서 HttpConnectionManager가 보유하고 있는 속성에 대해서 알아봤습니다. 다만 이번 포스팅만으로는 HttpConnectionManager가 보유하고 있는 컴포넌트가 어떻게 상호작용하여 사용자의 요청을 처리하는지 완벽하게 이해하기는 힘듭니다. 이 부분은 이 다음 포스팅에서 진행되는 Envoy 프록시 연결 과정을 관찰하면서 조금 더 자세하게 살펴보겠습니다.

5. [envoy-internals] Listener Manager

cla9 — Tue, 23 May 2023 10:16:15 +0900

1. 서론

이번 포스팅은 지난번에 이어서 Envoy의 주요 컴포넌트 중 하나인 Listener와 Listener를 관리하는 Listener Manager에 대해서 살펴보고자 합니다.

2. Listener Manager 개요

Listener Manager는 단어에서 유추할 수 있듯이 Listener를 관리하는 역할을 수행합니다. 즉 Listener를 생성하고 관리합니다. 두 번째 역할을 LDS를 생성하고 관리하는 역할을 겸합니다. 이번 포스팅에서는 이에 대해서 하나씩 살펴보겠습니다. 먼저 살펴볼 것은 Listener 생성 및 관리 기능입니다.

Listener Manager는 Listener를 생성 후 관리한다고 설명했습니다. 여기서 꼭 기억해야할 특징은 Listener Manager가 생성한 Listener는 단일 쓰레드 기반으로 동작하지 않는다는 점입니다. 그렇다면 Envoy는 왜 Listener를 단일 쓰레드로 동작하지 않고 멀티 쓰레드로 동작시켰을까요? 이를 이해하기 위해서 사례를 통해 먼저 사용자의 요청을 처리하는 쓰레드가 하나일 경우 야기되는 문제점을 살펴보겠습니다.

envoy에 여러 API 요청이 들어오게되면, 그 중 하나가 쓰레드를 선점하게되고 해당 요청을 처리할 것입니다. 이때 만약 다른 API 요청이 전달된다면 어떻게 될까요? 쓰레드를 선점하고 있다면, 해당 쓰레드가 처리하는 작업 요청이 끝날 때까지 다른 요청은 대기해야할 것입니다. 따라서 이 경우 병렬성이 매우 떨어지게 됩니다. 특히나 다른 API 요청을 처리하는 Listener의 경우 미리 선점한 Listener의 작업에 의해 해당 API 요청 또한 대기하는 이슈가 발생합니다. 따라서 단일 쓰레드로 이를 처리하기에는 성능 이슈가 필연적으로 발생합니다.

따라서 envoy에서는 API 요청을 처리하는 쓰레드를 하나가 아니라 여러개를 구성하도록 설계되었습니다. 또한 생성된 Worker 쓰레드는 모든 Listener와 연결 되어있도록 구성되었습니다.

envoy는 기동 당시 --concurrency 인자를 통해 생성할 Worker 쓰레드의 개수를 지정할 수 있습니다. 만약 위 그림과 같이 3으로 지정하였다면, 내부적으로는 3개의 Worker 쓰레드를 Listener Manager가 생성합니다. 또한 만약 Config에 지정된 Listener가 2개라면 위와 같이 2개의 Listener가 생성됩니다.

Listener와 Worker 쓰레드가 모두 생성되고나면, 모든 Worker 쓰레드는 모든 Listener를 Listen 하도록 합니다. 그렇다면 모든 Worker 쓰레드가 모든 Listener를 Listen 하는 것은 어떤 것을 의미할까요?

만약 특정 Listener 별로 Worker 쓰레드를 할당할 수 있다면, 위와 같이 부하가 집중되는 Listener에 쓰레드를 많이 부여할 수 있습니다. 가령 위 그림과 같이 Listener0에 명시적으로 더 많은 쓰레드를 할당함으로써 Listener0 요청에 빠른 처리가 가능합니다.

하지만 만약 위와 같이 지정한 상황에서 갑자기 Listener 1쪽에 트래픽이 몰릴 경우에는 해당 Listener에 지정된 쓰레드는 하나이기 때문에 탄력적으로 대응할 수 없습니다.

따라서 envoy에서는 Active Listener 별로 영역을 정해서 Worker 쓰레드를 샤딩하지 않도록 구성되어있습니다. 즉 사용자 Connection이 요청되었을 때, 모든 Worker 쓰레드가 모든 Listener를 Listen하고 있기 때문에 어떠한 Worker 쓰레드에 사용자 Connection을 할당하더라도 문제가 없습니다. 또한 어떤 Worker 쓰레드에 사용자 요청을 할당하는 지에 대한 결정은 Kernel이 Socket을 Accept한 다음 결정합니다. 결국 Worker 쓰레드에 대한 Connection 할당 권한은 OS에 있습니다.

Connection이 Accept되어 Worker 쓰레드에 Socket이 배정되면, 해당 Socket은 이후에 Worker 쓰레드를 벗어나지 않습니다. 따라서 이후 제공되는 서비스는 최초 연결 시점에 할당된 Worker 쓰레드에서 이루어집니다.

지금까지 Listener Manager에서 생성되는 Worker 쓰레드에 대해서 살펴봤습니다. 그렇다면 Worker 쓰레드 생성 외에 Listener Manager는 어떤 역할을 하고 있을까요? Listener Manager가 담당하는 역할에 대해서 살펴보겠습니다.

3. Listener 생성

Listener Manager의 첫 번째 역할은 Listener 생성입니다. config 파일에 위치한 static_resources 정보에 포함된 Listener 정보를 살펴보고 그에따른 Listener를 생성합니다.

configuration_impl.cc

void MainImpl::initialize(const envoy::config::bootstrap::v3::Bootstrap& bootstrap,
                          Instance& server,
                          Upstream::ClusterManagerFactory& cluster_manager_factory) {
  ...(중략)...

  const auto& listeners = bootstrap.static_resources().listeners();
  ENVOY_LOG(info, "loading {} listener(s)", listeners.size());
  for (ssize_t i = 0; i < listeners.size(); i++) {
    ENVOY_LOG(debug, "listener #{}:", i);
    server.listenerManager().addOrUpdateListener(listeners[i], "", false);
  }

  ...(중략)...
}

이는 위 코드와 같이 Config 내용을 파싱한 이후 담겨있는 bootstrap 구조에서 static listener 정보를 추출한 결과를 토대로 Listener Manager에게 Listener를 생성하라고 요구하는 것을 볼 수 있습니다.

이때 생성되는 Listener는 어떤 과정을 거치며 내부적으로 어떤 속성을 가지고 있을까요?

Envoy 관련 첫 포스팅에서 Client 요청이 전달되면, 위 그림과 같은 트래픽 흐름이 전달된다고 설명했습니다. 이때 Listener와 연결된 Listener Filters와 Network Filters는 Listener가 관리합니다. 따라서 Listener의 역할 중 하나는 Listener Filters와 Filter Chains(Network Filters)를 생성하는 것입니다.

static_resources:
  listeners:
  - name: listener_https
    address:
      socket_address:
        protocol: TCP
        address: 0.0.0.0
        port_value: 80
    listener_filters:
    - name: "envoy.filters.listener.tls_inspector"
      typed_config:
        "@type": type.googleapis.com/envoy.extensions.filters.listener.tls_inspector.v3.TlsInspector
    - name: "envoy.filters.listener.http_inspector"
      typed_config:
        "@type": type.googleapis.com/envoy.extensions.filters.listener.http_inspector.v3.HttpInspector

가령 위와 같이 envoy config 파일에 listener_filters 기입되었다고 가정하면, Listener를 생성하는 단계에서 해당 필터들을 파악하고 생성하는 역할을 수행해야합니다.

이를 위해서 Listener 내부에는 Listener Filters를 생성하는 listener_filter_factories와 Filter Chains를 생성하는 filter_chain_manager가 존재합니다.

Listener Filters는 Worker 쓰레드에 바인딩된 소켓마다 해당 Filter들이 생성되기 때문에, Filter를 생성하여 Listener가 보관하지 않고 Filter를 생성할 수 있는 Callback 메소드들의 Pointer를 Vector Container에 저장하고 있습니다. 따라서 Client가 접속을 요청했을 경우 Worker 쓰레드에 소켓이 할당되면, 이후 listener_filter_factories에 지정된 Callback 메소드들을 순회하면서 사용자에게 적합한 Filter 목록을 만들어줍니다.

출처 :https://www.envoyproxy.io/docs/envoy/latest/intro/life_of_a_request#listener-tcp-accept

Filter Chains(Network Filters)는 L3/L4를 담당하는 Filter로써 Listener Config 설정에 존재하는 Filter 목록들을 참조하여 내부적으로 여러 Filter Factory를 만듭니다.

    filter_chains:
    - filter_chain_match:
        server_names: ["acme.com"]
      transport_socket:
        name: envoy.transport_sockets.tls
        typed_config:
          "@type": type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.DownstreamTlsContext
          common_tls_context:
            tls_certificates:
            - certificate_chain: {filename: "certs/servercert.pem"}
              private_key: {filename: "certs/serverkey.pem"}        
      filters:
      - name: envoy.filters.network.http_connection_manager
        typed_config:
          "@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
          stat_prefix: ingress_http
          use_remote_address: true
          http2_protocol_options:
            max_concurrent_streams: 100
          route_config:
            name: local_route
            virtual_hosts:
            - name: local_service
              domains: ["acme.com"]
              routes:
              - match:
                  path: "/foo"
                route:
                  cluster: some_service
          http_filters:
          - name: envoy.filters.http.router
            typed_config:
              "@type": type.googleapis.com/envoy.extensions.filters.http.router.v3.Router

가령 위와같이 Listener 하위에 filter_chains를 정의했다고 가정해봅시다. 그러면 Listener를 생성하는 과정에서 해당 Config 내용을 확인하고 Transport Socket Factory와 Network Filter Factory를 구성합니다.

이때 filter_chain_manager의 역할은 사용자가 입력한 Filter Config 내용이 정상인지 검증을 하고 Filter 목록을 빠르게 찾기 위한 자료구조 및 Filter 생성 Callback을 생성하여 저장합니다. 이때 생성되는 Callback은 Listener와 마찬가지로 사용자가 실제 접속해서 Socket이 만들어졌을 때 해당 Socket에서 Network Filters 생성을 할때 사용됩니다.

listener_manager_impl.cc

    for (auto& address : listener.addresses()) {
      listener.addSocketFactory(std::make_unique<ListenSocketFactoryImpl>(
          factory_, address, socket_type, listener.listenSocketOptions(), listener.name(),
          listener.tcpBacklogSize(), bind_type, creation_options, server_.options().concurrency()));
    }

지금까지 listener 생성 과정에서 Listener Filters와 Filter Chains(Network Filters)가 생성되는 것을 살펴봤습니다. 그 밖에 중요하게 살펴봐야할 점은 Listener가 외부 요청으로부터 Accept 하기 위한 Socket을 생성한다는 점입니다. 그리고 생성되는 Socket의 개수는 --concurrency로 전달된 인자 개수 만큼 생성됩니다.

그렇다면 왜 --concurrency 만큼 Socket을 생성할까요?

그 이유는 향후 Listener 별로 Worker 쓰레드에게 모두 바인딩을 수행하는데, 이때 Listener에서 생성한 Socket을 개별 쓰레드에서 참조가 가능하도록 하기 위함입니다.

listener_impl.cc

Network::SocketSharedPtr socket = factory.createListenSocket(
    local_address_, socket_type, options_, bind_type_, socket_creation_options_, worker_index);

따라서 Listener 생성 과정에서 Listner Component Factory가 Socket을 생성하여 개별 Worker 쓰레드에서 향후 참조할 수 있도록 사전 작업을 수행합니다.

3-1 Worker 생성 및 Listener 바인드

listener_manager_impl.cc

  for (uint32_t i = 0; i < server.options().concurrency(); i++) {
    workers_.emplace_back(
        worker_factory.createWorker(i, server.overloadManager(), absl::StrCat("worker_", i)));
  }

Listener Manager가 생성될 때, 생성자 코드 내부에서는 위와 같이 전달받은 worker_factory를 통해서 Worker 쓰레드를 생성하는 것을 볼 수 있습니다. 그리고 생성하는 쓰레드의 개수는 인자로 전달된 --concurrency에 기반하고 있습니다.

listener_manager_impl.cc

void ListenerManagerImpl::startWorkers(GuardDog& guard_dog, std::function<void()> callback) {
  ...(중략)...
  uint32_t i = 0;

  ...(중략)...
  
  for (auto listener_it = active_listeners_.begin(); listener_it != active_listeners_.end();) {
    auto& listener = *listener_it;
    listener_it++;

   ...(중략)...
    for (const auto& worker : workers_) {
      addListenerToWorker(*worker, absl::nullopt, *listener,
                          [this, listeners_pending_init, callback]() {
                            if (--(*listeners_pending_init) == 0) {
                              stats_.workers_started_.set(1);
                              callback();
                            }
                          });
    }
  }
  for (const auto& worker : workers_) {
    ...(중략)...
    worker->start(guard_dog, worker_started_running);
    ...(중략)...
    i++;
  }

  ...(후략)...
}

이후 Envoy가 기동 될때, 위 코드와 같이 등록된 모든 active_listeners를 순회하면서, 모든 worker 쓰레드에 bind 하는 것을 볼 수 있습니다. 해당 내용에 대해서 조금 더 자세히 살펴보면 다음과 같습니다.

이전에 Listener 생성 과정을 살펴보면서, 위 그림과 같이 Worker 쓰레드 개수 만큼 개별 Listener에서 Socket을 생성함을 확인했습니다. 이때 생성된 Socket을 Worker 쓰레드에서 사용하기 위해서는 소켓을 각 쓰레드별로 바인딩하는 작업을 수행해야합니다.

connection_handler_impl.cc

for (auto& socket_factory : config.listenSocketFactories()) {
  auto address = socket_factory->localAddress();
  // worker_index_ doesn't have a value on the main thread for the admin server.
  details->addActiveListener(
      config, address, listener_reject_fraction_, disable_listeners_,
      std::make_unique<ActiveTcpListener>(
          *this, config, runtime,
          socket_factory->getListenSocket(worker_index_.has_value() ? *worker_index_ : 0),
          address, config.connectionBalancer(*address)));
}

따라서 개별 쓰레드에서는 위 코드를 수행하면서, ActiveTcpListener를 생성하는 것을 확인할 수 있습니다. 위 코드에서 주목할 부분은 socket_factory(Listener)로부터 getListenSocket 메소드를 호출하면서 인자로 Worker 쓰레드의 index 번호를 넘기는 것을 확인할 수 있습니다.

listener_impl.cc

Network::SocketSharedPtr ListenSocketFactoryImpl::getListenSocket(uint32_t worker_index) {  
  ASSERT(worker_index < sockets_.size() && sockets_[worker_index] != nullptr);
  return sockets_[worker_index];
}

이때 Listener 내부에서는 Worker 인덱스에 해당하는 Socket을 반환함으로써 Worker 쓰레드에서 해당 Listener를 참조할 수 있도록 합니다.

4. LDS 관리

Listener Manager의 두 번째 역할은 LDS를 통한 dynamic resource 처리입니다. 이때 LDS의 생성은 Listener Component Factory에서 수행하며, 생성된 LDS에서 Listener Manager를 참조하도록 하여 LDS 정보가 수신되었을 때, Listener Manager가 이를 처리할 수 있도록 연관관계가 맺어져있습니다.

LDS 생성 및 처리 과정을 보면 아래와 같습니다.

1. Listener Component Factory로부터 LDS를 생성합니다.

2. Listener Manager를 LDS에서 참조하도록 합니다.

3. xDS API 수행을 위해 Cluster Manager로부터 Subscription Factory 인스턴스를 요청합니다.

4. Subscription Factory로부터 Subscription 생성을 요청합니다.

5. Subscription Factory에서는 gRPC 통신이 가능하도록 설정 후 Subscription을 발급합니다.

6. gRPC Mux를 통해 Management Server와 통신을 수행합니다.

7. LDS api_type 변경 이벤트 통지 시, 해당 Subscription에 알림을 전달합니다.

8. Subscription내에 매핑된 LDS Callback을 호출합니다.

9. LDS에서는 Listener Manager를 참조하여 변경 사항에 맞추어 Listener 정보를 동기화 시킵니다.

위와 같은 과정을 거쳐 Listener Manager에서는 LDS 요청에 맞추어 최신 정보를 동기화시킵니다. 해당 과정의 대부분은 이전 Cluster Manager 설명 포스팅을 통해서 자세하게 소개하였으므로 해당 내용을 이해했다면, 위 과정의 흐름의 진행은 자연스러울 것입니다. 혹시 기억이 잘 안나신다면, 이전 포스팅 정독을 통해 관련 내용을 복기해보시는 것을 추천드립니다.

5. 마치며

지금까지 Listener Manager를 기동하면서 Worker 쓰레드 및 Listener 생성하여 이를 바인딩하는 역할과 LDS 처리역할에 대해서 살펴봤습니다. 또한 개별 Listener에서는 Configuration에 따라서 여러 Filter를 생성하기 위한 Callback 리스트를 관리하는 것을 살펴볼 수 있었습니다. 이 과정에서 생성된 정보등을 통해 향후 Client에서 Listener에 접속을 요청하면 이를 전달받아 후속 처리를 진행할 수 있습니다. 다만 이번 포스팅에서는 해당 내용에 대해서는 다루지 않으며, 이 다음 포스팅에서 조금 더 자세하게 접속 요청이 어떻게 처리되는지를 살펴보겠습니다.

4. [envoy-internals] Cluster Manager - Load Balancer

cla9 — Fri, 19 May 2023 09:39:07 +0900

1. 서론

이전 포스팅을 통해서 Envoy Cluster Manager의 역할에 대해서 살펴봤습니다. Cluster Manager는 Cluster 관리 뿐만 아니라 Multiplexer 및 Subscription 생성에 관여합니다. 이번 포스팅에서는 Cluster Manager에서 관리하는 Cluster 내부에서 지정할 수 있는 Load Balancer 종류와 설정 방법에 대해서 다루고자합니다. 이번 포스팅 내용은 Envoy에 대한 설명 뿐만 아니라 Load Balancer 종류에 대한 알고리즘에 대한 개념 설명 위주로 알아보면서 어떻게 envoy가 Load Balancing을 처리하는지에 대해서 살펴보고자 합니다.

2. Envoy Loadbalancer

cluster_manager_impl.cc

ClusterManagerImpl::ThreadLocalClusterManagerImpl::ClusterEntry::ClusterEntry(
    ThreadLocalClusterManagerImpl& parent, ClusterInfoConstSharedPtr cluster,
    const LoadBalancerFactorySharedPtr& lb_factory)
    : parent_(parent), lb_factory_(lb_factory), cluster_info_(cluster) {
  priority_set_.getOrCreateHostSet(0);

  // TODO(mattklein123): Consider converting other LBs over to thread local. All of them could
  // benefit given the healthy panic, locality, and priority calculations that take place.
  if (cluster->lbSubsetInfo().isEnabled()) {
    lb_ = std::make_unique<SubsetLoadBalancer>(
        cluster->lbType(), priority_set_, parent_.local_priority_set_, cluster->stats(),
        cluster->statsScope(), parent.parent_.runtime_, parent.parent_.random_,
        cluster->lbSubsetInfo(), cluster->lbRingHashConfig(), cluster->lbMaglevConfig(),
        cluster->lbRoundRobinConfig(), cluster->lbLeastRequestConfig(), cluster->lbConfig(),
        parent_.thread_local_dispatcher_.timeSource());
  } else {
    switch (cluster->lbType()) {
    case LoadBalancerType::LeastRequest: {
      ASSERT(lb_factory_ == nullptr);
      lb_ = std::make_unique<LeastRequestLoadBalancer>(
          priority_set_, parent_.local_priority_set_, cluster->stats(), parent.parent_.runtime_,
          parent.parent_.random_, cluster->lbConfig(), cluster->lbLeastRequestConfig(),
          parent.thread_local_dispatcher_.timeSource());
      break;
    }
    case LoadBalancerType::Random: {
      ASSERT(lb_factory_ == nullptr);
      lb_ = std::make_unique<RandomLoadBalancer>(priority_set_, parent_.local_priority_set_,
                                                 cluster->stats(), parent.parent_.runtime_,
                                                 parent.parent_.random_, cluster->lbConfig());
      break;
    }
    case LoadBalancerType::RoundRobin: {
      ASSERT(lb_factory_ == nullptr);
      lb_ = std::make_unique<RoundRobinLoadBalancer>(
          priority_set_, parent_.local_priority_set_, cluster->stats(), parent.parent_.runtime_,
          parent.parent_.random_, cluster->lbConfig(), cluster->lbRoundRobinConfig(),
          parent.thread_local_dispatcher_.timeSource());
      break;
    }
    case LoadBalancerType::ClusterProvided:
    case LoadBalancerType::LoadBalancingPolicyConfig:
    case LoadBalancerType::RingHash:
    case LoadBalancerType::Maglev:
    case LoadBalancerType::OriginalDst: {
      ASSERT(lb_factory_ != nullptr);
      lb_ = lb_factory_->create();
      break;
    }
    }
  }
}

Envoy에서 Load Balancer는 ClusterEntry 내부에 존재하는 프로퍼티로써, ClusterEntry 생성 당시에 같이 생성됩니다. 이는 위 코드에서도 확인할 수 있으며, 생성자 내부에서 지정된 LoadBalancerType에 따라서 각기 다른 LoadBalancer가 지정됨을 확인할 수 있습니다.

그렇다면 Load Balancer 생성 이후 해당 과정은 어느 단계에서 이루어질까요?

이전 포스팅에서 Router로 부터 Connection Pool 획득 과정에 대해서 다루었습니다. 이 과정에서 Connection Pool을 획득하려면 먼저 host가 지정되어야합니다. 따라서 위 단계에서 4번째 단계 즉 Router가 Cluster 정보를 얻은 다음 Connection Pool을 요청하는 단계에서 Cluster Entry 내부에서는 가장먼저 Load Balancer에게 요청하여 어떤 host에 사용자 요청을 할당할 것인지를 요청합니다. 그리고 해당 host 정보를 토대로 Cluster Manager에게 해당 host에 대한 Connection Pool 요청을 수행합니다.

그렇다면 envoy에서 제공하는 Load Balancer는 어떤 종류가 있으며, 각 종류별로 어떻게 동작할까요? 이에 대해서 개념적으로 살펴보겠습니다.

3. Latency 관점

하나의 Cluster 안에 여러개의 Host가 매핑되어있다고 가정해봅시다. 그러면 사용자가 연결 요청을 시도하면, Cluster 내부에 있는 여러 Host 중 하나를 Load Balancer가 선택할 것입니다. 이때 어떤 Host를 선택하는 것이 효율적일까요? 특정 Host에만 요청을 집중한다면, 결국 해당 Host의 처리 능력이 떨어지게되고 결국에는 해당 Host에 장애가 발생할 것입니다. 이를 처리하기 위해 응답속도 관점에서 고려할 수 있는 Load Balancing 알고리즘 종류에 대해 알아보겠습니다.

3-1 Random

첫 번째로 고려해볼 수 있는 것은 Random 알고리즘입니다. Random 알고리즘은 말 그대로 Load를 분배할 때, 임의로 아무 host에 배정함을 의미합니다. 따라서 해당 알고리즘은 특별할 것이 없으며, 굉장히 단순하고 구현하기가 쉽습니다. 즉 이말은 Load Balancing을 수행하는데 있어 overhead가 적다는 것을 의미합니다.

하지만 Random 알고리즘은 무작위로 부하를 분배하는 알고리즘이기 때문에 트래픽이 몰렸을 때, 완벽히 균등하게 모든 Host에 부하가 분배되지 못할 수 있습니다. 즉 운이 좋지 않으면 특정 노드에 부하가 몰릴 수 있음을 의미합니다. 따라서 해당 알고리즘은 트래픽이 적으며, Load Balancing 수행에 대한 overhead를 줄이고 싶을 때 사용하면 좋습니다.

envoy에서는 아래와 같이 lb_policy를 random으로 지정함으로써 Random 알고리즘을 사용하여 부하를 분산할 수 있습니다.

static_resources:
  clusters:
  - name: my_service
    connect_timeout: 0.25s
    type: strict_dns
    lb_policy: random
    load_assignment:
      cluster_name: my_service
      endpoints:
      - lb_endpoints:
        - endpoint:
            address:
              socket_address:
                address: 127.0.0.1
                port_value: 8080
        - endpoint:
            address:
              socket_address:
                address: 127.0.0.1
                port_value: 8081
        - endpoint:
            address:
              socket_address:
                address: 127.0.0.1
                port_value: 8082

3-2. Round Robin

두 번째로 살펴볼 것은 Round Robin 알고리즘입니다.

Round Robin 알고리즘은 보편적으로 많이 사용되는 Load Balancing 알고리즘으로 부하를 모든 Host 서버를 순환하면서 균등하게 분배하는 방식을 의미합니다. 가령 위 그림과 같이 6대의 Client 요청을 분배한다고 가정해봅시다. 그러면 3대의 B/E 서버에 순차적으로 하나씩 Client 요청을 분배합니다. 따라서 첫 요청은 Host 1에게 두번째 요청은 Host 2에게 분배하는 등 요청이 들어올 때마다 균등하게 분배합니다. 해당 알고리즘은 Random과 더불어 구현이 굉장히 단순합니다. Load Balancer 입장에서는 연결된 Host 중에서 이전에 분배했던 Host가 누구였는지 기억한다면, 그 다음에 분배해야될 대상이 누군지 알 수 있기 때문입니다.

static_resources:
  clusters:
  - name: my_service
    connect_timeout: 0.25s
    type: strict_dns
    lb_policy: round_robin
    load_assignment:
      cluster_name: my_service
      endpoints:
      - lb_endpoints:
        - endpoint:
            address:
              socket_address:
                address: 127.0.0.1
                port_value: 8080
        - endpoint:
            address:
              socket_address:
                address: 127.0.0.1
                port_value: 8081
        - endpoint:
            address:
              socket_address:
                address: 127.0.0.1
                port_value: 8082

envoy에서는 위와같이 lb_policy를 round_robin으로 지정하여 Round Robin 알고리즘으로 부하 분산을 수행할 수 있습니다.

3-2-1 Weighted Round Robin

Round Robin 알고리즘은 부하가 몰릴 경우에도 순차적으로 Host에게 부하를 분배하기 때문에 효율적으로 동작합니다. 하지만 여기에는 전제조건이 붙습니다. 그것은 모든 Host가 처리 시간이 동일함을 가정하였을 경우입니다. 이 경우 모든 서버의 하드웨어 스펙이 동일하지 않는다면 어떤 일이 벌어질까요?

가령 Host 1의 하드웨어 사양이 나머지 두 개의 서버보다 2배 이상 좋다고 가정해봅시다. 이 경우 부하를 위와 같이 동일하게 분산하면, Host 1의 경우는 사용자의 요청을 다른 서버보다 빠르게 처리하여 idle 상태일 동안 나머지 서버에서는 여전히 사용자의 요청을 처리하는 경우가 발생합니다. 이 경우 요청 분배를 Host 1에 조금 더 할 수 있다면, 처리 속도를 높일 수 있음에도 불구하고 일반적인 Round Robin의 알고리즘의 경우에는 이를 처리할 수 없습니다. 따라서 이러한 하드웨어 성능 차이를 고려하기 위해 추가된 것이 가중치(Weight)입니다.

static_resources:
  clusters:
  - name: my_service
    connect_timeout: 0.25s
    type: strict_dns
    lb_policy: round_robin
    load_assignment:
      cluster_name: my_service
      endpoints:
      - lb_endpoints:
        - endpoint:
            address:
              socket_address:
                address: 127.0.0.1
                port_value: 8080
          load_balancing_weight: 2      
        - endpoint:
            address:
              socket_address:
                address: 127.0.0.1
                port_value: 8081
          load_balancing_weight: 1      
        - endpoint:
            address:
              socket_address:
                address: 127.0.0.1
                port_value: 8082
          load_balancing_weight: 3

가중치는 위와 같이 각각의 endpoint 별로 load_balancing_weight 속성을 추가할 수 있습니다. 위 예시는 해당 서버의 처리 능력을 고려하여 운영자가 임의로 매핑한 값이라고 가정해봅시다.

이 경우 Round-Robin 방식으로 동작하지만, 각각의 Server 별로 가중치가 존재하기 때문에 이를 고려하여 위와같이 부하를 분배합니다. 즉 이전과 동일하게 6개의 요청을 전달받는다고 가정한다면, Host 1은 전체 부하의 33% 정도를 할당 받으며, Host 2는 17%, Host 3의 경우는 50%의 부하를 분배받는 것을 볼 수 있습니다.

3-3 Least Request

지금까지 Random과 Round-Robin 알고리즘에 대해 살펴봤습니다. 위 두 알고리즘은 구현이 굉장히 쉽다는 장점이 존재합니다. 특히 Round-Robin의 경우는 부하가 집중될 때도 적은 overhead를 가지면서 적절히 부하를 분배할 수 있습니다. 하지만 Round-Robin에 가중치까지 적용하였다 할지라도 여기에는 이만큼 처리할 수 있다는 가정을 기반으로 처리하는 것이지 실제 처리량을 기반으로 Load Balancer가 부하를 처리하지는 않습니다.

가령 위 그림과 같이 Host 서버의 하드웨어 스펙이 모두 동일하다고 가정해봅시다. 또한 해당 host들이 매핑된 실제 서버에는 하나의 B/E만 존재하는 것이 아니라 여러 다른 app이 존재한다고 가정해봅시다. 이는 서버가 k8s 클러스터 등으로 구성되어있다면 충분히 가능한 시나리오일 것입니다.

이 경우 Round-Robin으로 분배하거나 Weighted Round-Robin을 적용하기 쉽지 않을 것입니다. 따라서 이 경우에는 실제 응답 요청을 처리하는 Connection 개수를 실시간으로 모니터링하면서 부하를 얼마나 감당할 수 있는지를 살펴보고 Load Balancer가 부하가 적은 쪽으로 전달하는 것이 효율적입니다.

가령 Least Request 알고리즘 환경에서는 위와 같이 현재 6개 Host에 부하를 분배한 상황에서 가령 Host 2에서 2번 요청에 대한 처리가 완료되어 Connection을 해제하였을 때, 그 다음 7번 요청을 Host 2에게 분배하는 방식입니다. 따라서 이를 지원하는 Load Balancer 타입에는 현재 연결된 active_requests가 몇 개인지를 관리하고 있습니다.

또한 Least Request 알고리즘을 사용하는 환경에서도 서버마다 하드웨어 스펙등이 다를 수 있기 때문에 가중치를 적용할 수 있습니다.

static_resources:
  clusters:
  - name: my_service
    connect_timeout: 0.25s
    type: strict_dns
    lb_policy: least_request
    load_assignment:
      cluster_name: my_service
      endpoints:
      - lb_endpoints:
        - endpoint:
            address:
              socket_address:
                address: 127.0.0.1
                port_value: 8080
            load_balancing_weight: 2
        - endpoint:
            address:
              socket_address:
                address: 127.0.0.1
                port_value: 8081
            load_balancing_weight: 1
        - endpoint:
            address:
              socket_address:
                address: 127.0.0.1
                port_value: 8082
            load_balancing_weight: 3

가령 위와 같이 envoy에서 지정했다면, 내부적으로는 아래와 같은 공식을 적용하여 가중치 값이 높은 쪽으로 부하가 분산됩니다. 참고로 해당 공식은 envoy 공식 문서에서 발췌하였습니다.

weight = load_balancing_weight / (active_requests + 1)^active_request_bias

참고로 active_request_bias 값은 load balancing 과정에서 active_requests에 대하여 우선 순위를 조정할 수 있는 값으로써 envoy config를 통해 지정할 수 있으며, 기본 값은 1.0입니다.

4. 가용성 관점

지금까지 세 가지 알고리즘에 대해서 살펴봤습니다. 세 가지 알고리즘의 특성은 구현이 용이하며, 합리적인 부하 분산을 균등하게 해준다는 점에서 이점이 존재합니다. 하지만 다음과 같은 상황에서는 어떨까요?

가령 위 그림과 같이 3개의 Host가 있고 각각의 Host에는 별개의 Cache 레이어가 존재하는 시스템이라고 가정해봅시다. 해당 시스템은 시스템 규모가 너무 커서 사용자별로 특정 데이터를 샤딩하여 각각의 Host 별개 Cache에 보관한다고 가정해봅시다. 이때 Cache Hit를 높이기 위해서는 특정 사용자 요청은 특정 Host로 보내져야 효율적일 것입니다.

하지만 Random, Round-Robin, Least Request 알고리즘은 이러한 특성을 보장해주지 않습니다. 그 이유는 해당 알고리즘은 해당 시점 전달된 트래픽 부하 분산에 초점이 맞추어져있기 때문입니다. 따라서 이전 요청 응답 전달 이후 같은 사용자 요청이 전달되었을 때, 각기 다른 Host로 전달될 가능성이 매우 높습니다. 그리고 어디로 배정될지 운영자 입장에서는 정확히 알 수 없기 때문에 운영상 불확실성을 가지고 있습니다. 이러한 불확실성은 대규모 시스템을 운영하는 입장에서는 엄청난 부담이 아닐 수 없습니다.

그렇다면 이러한 특성을 고려한다면, 어떻게 부하 분산하는 것이 좋을까요?

일반적으로 많이 사용하는 방법은 Hash 함수와 Modular를 활용하는 것입니다. 즉 위 그림과 같이 Host 목록에 대해서 특정 Key(사용자 Id) 등을 활용한 Hash 값을 토대로 Modular 연산을 적용하면, 특정 사용자 요청에 대해서는 매번 같은 결과 값이 나오게되니 아무리 요청을 많이 할지라도 특정 Host로 전달됨이 보장됩니다. 참고로 Modular 연산을 적용하는 이유는 아무리 Hash 값이 다르더라도 서버의 갯수만큼으로 Modular 연산을 수행하면, 서버 갯수 이내만큼의 값을 얻을 수 있기 때문입니다.

가령 Modular 연산 결과가 0이면 Host 1, 1이면 Host 2, 2이면 Host 3으로 할당된다고 가정했을 때, 사용자1의 Hash 값이 1이 나왔다면, 매번 Host 2로 전달이 보장됩니다.

위와 같이 살펴봤을 경우 Hash 와 Modular 연산 적용 또한 부하 부하를 적절히 분산하는데, 도움이 되는 것으로 보입니다. 하지만 여기에는 다음과 같은 문제가 있습니다.

가령 위와 같이 Host 1 ~ 3에 Connection과 사용자 데이터들이 Cache에 할당되어있다고 가정해봅시다. 이때 해당 비즈니스가 트래픽이 급격히 올라 Scale Out을 해야하는 상황이 발생하면 어떻게 해야할까요?

위 그림을 살펴보면 기존 Modular 연산은 Host 개수가 3개기 때문에 1 ~ 3 Host에만 할당할 수 있을 뿐 Host 4에는 할당할 수 없습니다. 따라서 Host 4를 수용하기 위해서는 Host 4를 Host 리스트에 포함하고 나머지 연산 또한 4로 변경해야할 것입니다.

하지만 이 경우 지금까지 분배되었던 Connection과 데이터 저장에 커다란 이슈가 발생합니다.

기존에 Hash 값이 11인 경우에는 원래대로라면 Host 3에 지속 라우팅이 되었어야 합니다. 하지만 연산 수식이 달라졌기 때문에, Host 4가 추가된 이후에는 수식의 결과에 따라(11%4=3) Host 4에 라우팅 될 것입니다. 따라서 Scale out 이후에도 서비스 안정성을 유지하기 위해서는 기존 Host 들에 연결된 Connection과 Cache된 데이터들에 대한 재분배가 필요합니다.

그렇다면 어느정도 데이터가 재분배가 일어나야할까요? 위 사례를 기반으로 데이터 재분배가 일어난 다음 상황을 살펴보겠습니다. 이해를 돕기위해 데이터 재분배가 발생한 항목은 파란색 음영으로 표시하였습니다.

위 그림의 결과를 통해서 확인할 수 있는 사실은 Host 4 추가 이후 기존 데이터까지 포함해서 총 75%의 데이터 이동이 필요하며, 그만큼 Connection 또한 재분배가 일어난다는 점입니다. 이는 Scale out 수행해야하는 운영자 입장에서는 엄청난 부담으로 작용할 수 있습니다. 그 이유는 데이터 이동과 Connection을 분배하는 과정에서 발생하는 overhead로 인해 자칫 다른 Host에도 장애가 발생할 수 있기 때문입니다.

따라서 Hash와 Modular 연산을 통해서 부하를 분산하는 환경에서는 Scale Out이 발생할 때, Connection 분배와 데이터 이동을 최소화하는 방안을 강구해야합니다. 그렇다면 어떻게 이를 해결할 수 있을까요?

첫 번째로 고민해볼 수 있는 방법은 Scale Out 시에 기존 서버 대비 2배씩 확장하는 방법입니다.

가령 위 그림과 같이 기존 3대의 Host에서 Scale Out을 위해 서버를 2배로 확장했을 때 모습입니다. 이때 Connection 및 데이터 재분배 현황을 보면, 서버를 2배로 늘렸을 때 데이터 재분배 비율이 50% 정도로 낮아진 것을 볼 수 있습니다. 또한 데이터 이동 현황을 보면, 기존 Host가 보유하고 있던 데이터 중 일부가 다른 Host에게 그대로 전달된 것을 확인할 수 있습니다. 이는 데이터를 마이그레이션 해야하는 운영자 입장에서도 계획을 세우기 훨씬 수월하며, 분배에 대한 비효율도 다소 줄일 수 있습니다. 하지만 매번 Scale Out이 필요할 경우 서버를 2배씩 늘리는 것은 매우 비효율 적일 것입니다. 또한 이는 Scale Out시에는 도움이 될 수 있지만, Scale In을 수행하는 경우에는 문제가 발생합니다. Scale In을 수행할 때는 1/2씩 서버를 줄여야하는데 현실적으로 힘들기 때문입니다.

따라서 대규모 시스템에서 Scale in/out이 잦은 Application을 사용하는 경우 단순한 Hash 함수와 Modular 연산의 적용은 운영 안정성이 저하되는 이슈를 낳습니다.

4-1 Ring Hash(Consistent Hashing)

이전에 살펴봤듯이 Hash와 Modular 기반으로 부하를 분산시에 Scale In/Out에 탄력적으로 대응하기 위해서는 서버 추가/삭제 이후 Connection과 연관된 데이터 재분배되는 양이 적어야 합니다. 이때 Consistent Hashing 알고리즘은 이에 대한 해결책을 제시해줍니다.

Consistent Hashing 방식은 위와 같이 Host 들이 하나의 Circle 안에 배치되어있다고 가정합니다. 그리고 각각의 Host가 담당하게될 Hash 값의 데이터 범위를 할당하여 그 안에 위치한 Connection을 담당하는 구조입니다. 이때 두 Host 사이에 위치한 Hash 값을 지닌 Connection은 시계 방향에 위치한 Host에 할당되는 것이 특징입니다.

Host	데이터 담당 범위
Host 1	해시값 <= 10724 OR 해시값 > 12345
Host 2	10724 < 해시값 <= 11224
Host 3	11224 < 해시값 <= 12345

즉 위와 같이 각각의 Host 별로 Client 요청에 대한 Hash 값을 계산하였을 때, 해당 Hash 값이 담당하는 Host를 범위로써 관리합니다. 위와 같이 Ring Hash가 구축된 상태에서 Client 요청이 들어왔다고 가정해보겠습니다.

Case 1. 해시값 10765 요청 전달 시

해당 해시값이 10765이므로, 이는 Host1의 데이터 범위인 10724 보다 크고 Host 2의 해시값 범위인 11224보다 작으므로 Host 2에 할당될 것입니다. 또한 이후에 동일한 해시값이 입력된다면 지속적으로 Host 2에 할당됨이 보장됩니다.

Case 2. 해시값 12086 요청 전달 시

해시값이 12086의 요청이 전달되면, 11224보다 크고 12345보다 작으므로 Host 3에 Connection이 할당됩니다.

이후 지속적인 Connection 연결이 요청되었고 그 결과 위와 같은 모습이 되었다고 가정해봅시다. 위 그림을 살펴보면 Host 1은 해시값이 5576과, 12567에 해당하는 Connection이 연결된 상황이라고 볼 수 있습니다. 만약 이 상황에서 Host 1에 장애가 발생하여 Down되었을 경우 어떻게 될까요?

Ring Hash를 살펴보면, Host 1이 없어졌을 경우 그 다음 연결된 Host는 Host 2임을 알 수 있습니다. 따라서 Consistent Hashing 알고리즘에서는 Host 1에 할당되었던 기존 Connection이 Host 2로 모두 이관됨을 확인할 수 있습니다.

또한 위 결과를 통해 흥미로운 사실을 알 수 있습니다. Host 삭제에 따른 변화를 살펴보면, 기존 Host 1에 할당된 Connection만 영향을 받을 뿐 그외 나머지 Host에 연결된 Connection에는 전혀 영향을 받지 않는 것을 확인할 수 있습니다. 이를 통해 알 수 있는 사실은 Consistent Hashing 알고리즘을 사용할 경우에는 이전과 달리 Host 추가/삭제에 따른 영향도가 적어짐을 알 수 있습니다.

하지만 위와 같은 기본 Consistent Hashing 방식은 문제점이 존재합니다. 위 그림을 통해 살펴보면 Host 1이 Down 되었을 때 그 부하가 고스란히 Host 2에게 전달되는 것을 확인할 수 있습니다. 이는 Host 2 입장에서는 엄청난 부담으로 작용할 수 있습니다. 두 번째 문제는 Hash 값이 고르게 분포되지 않을 경우 특정 Host에 연결되는 Connection이 많을 수 있음을 의미합니다. 가령 위 예에서는 비교적 Hash 값이 고르게 분포되어 각각의 Host에서 Connection을 수행할 수 있었습니다. 하지만 상황에 따라서는 특정 Hash 범위 값이 지속 할당되면, 특정 Host에만 부하가 집중될 수 있습니다. 따라서 이를 보완하기 위해서 추가적으로 Virtual Node를 추가하는 방법을 많이 사용합니다.

4-2-1 Virtual Node

기존의 문제점이 서버 추가/제거 시 특정 Host에 Connection 재매핑이 몰린다는 특징이 있었습니다. 따라서 이러한 문제를 해결하기 위해서는 Virtual Node를 추가합니다. 이해를 돕기 위해 사례를 통해 확인해보겠습니다.

위와 같이 Host 별로 하나씩 Ring에 배치하는 것이 아니라 Ring Hash에 여러개의 Virtual Node를 생성하여 해시값을 부여하고 위 그림과 같이 배치를 수행합니다. 그러면 각각의 Node와 데이터 사이의 해시값 범위가 줄어들게 됩니다. 따라서 위 그림과 같이 Connection 별로 Hash 값을 수행한 결과가 조금 더 다양한 Host로 매핑될 수 있습니다.

이러한 상황에서 Host 1에 Down이 발생하면 어떻게 될까요? 기존에 Host 1에 매핑되었던 Connection Hash 값 12567만 재배치를 수행하면 되기 때문에, 기존의 Consistent Hashing 방식 보다는 재배치되는 Connection 수가 많이 줄어들 수 있습니다.

이렇듯 Virtual Node를 Ring Hash에 추가하면, 재배치의 이점과 Virtual Node 개수가 증가할 수록 상대적으로 촘촘하게 Ring에 배치되기 때문에 부하를 보다 고르게 분산할 수는 있습니다. 다만 이러한 방법도 완벽하게 부하를 고르게 분산할 수는 없습니다.

Consistent Hashing 방식의 구현체는 다양하게 존재하는데, envoy는 위와 같이 내부에 virtual node가 추가된 형태의 자체 Consistent Hashing 방식으로 구현되어있습니다.

이때 각각의 host 별로 Virtual Node 할당을 위해서 envoy에서는 Configuration 설정에 minimum_ring_size, maximum_ring_size, 그리고 Hash 함수 등을 설정할 수 있으며, 각각의 Host 별로도 load_balancing_weight를 지정하여 개별 Host 별로 할당받는 hash bucket 개수를 조정할 수 있습니다.

이를 적용한 envoy configuration 예시는 다음과 같습니다.

static_resources:
  clusters:
  - name: my_service
    connect_timeout: 0.25s
    type: strict_dns
    lb_policy: ring_hash
    ring_hash_lb_config:
      minimum_ring_size: 1024
    load_assignment:
      cluster_name: my_service
      endpoints:
      - lb_endpoints:
        - endpoint:
            address:
              socket_address:
                address: 127.0.0.1
                port_value: 8080
          load_balancing_weight: 2      
        - endpoint:
            address:
              socket_address:
                address: 127.0.0.1
                port_value: 8081
          load_balancing_weight: 1      
        - endpoint:
            address:
              socket_address:
                address: 127.0.0.1
                port_value: 8082
          load_balancing_weight: 3

지금까지 Consistent Hashing 방식에 대해서 살펴봤습니다. 그렇다면 Consistent Hashing 방식은 어떤 경우 사용하면 좋을까요? 이 방식은 Cluster와 Server의 변경이 잦은 경우 즉 대규모 환경에서 Reliability가 중요한 경우 Connection의 안정적인 재매핑을 위해 사용하면 좋습니다.

하지만 Ring Hash를 만들고 이를 유지하기 위해서는 기존에 소개한 다른 알고리즘(Random, Round-Robin, Least Request)에 비해 조금 더 많은 메모리 사용이 필요합니다. 또한 Cluster로부터 Server가 추가되거나 제거될 때 Hash Ring을 재구축 해야하기 때문에 update가 다른 알고리즘에 비해 조금 느린 특성이 있습니다.

따라서 해당 알고리즘을 사용한다면 이러한 특징을 참고하여 여러 알고리즘과 비교 및 PoC를 통해 선정하는 것이 좋습니다.

4-2 Maglev

마지막으로 소개할 알고리즘은 Maglev 입니다. 해당 알고리즘은 Google에서 사용하는 Load Balancing 알고리즘으로 Consistent Hashing에 비해 부하를 보다 균등하게 분산해줄 수 있습니다. 또한 Consistent Hashing 알고리즘과 마찬가지로 서버의 삭제/수정 시에 Connection 재매핑 비율을 줄여줍니다. 해당 알고리즘 특징에 대해 살펴보면 다음과 같습니다.

Maglev 방식을 통해 부하를 분산하기 위해서는 2가지 자료구조가 필요합니다.

첫 번째는 Lookup table입니다. Lookup table은 추후 Load Balancer가 어떤 Host로 보낼지 라우팅 정보를 기록하는 리스트입니다. 즉 라우팅 당시 해시 값을 Lookup table의 사이즈만큼으로 나머지 연산을 했을 때 나오는 index를 기준으로 Lookup table에 매핑된 Host로 라우팅을 수행합니다. 위 예시의 경우 Lookup table의 사이즈를 임의로 7로 선정했는데, Lookup table의 사이즈는 변경이 가능하며, 사이즈가 크면 클 수록 향후 서버 추가/삭제 등의 영향을 적게 받습니다.

두 번째 살펴볼 것은 Permutation table입니다. 해당 자료구조는 각 Host 별로 Lookup 테이블 인덱스 어디에 매핑될 지를 희망하는 우선순위를 나타냅니다. 따라서, Lookup table의 사이즈가 결정되면, 가장 먼저 수행하는 것은 각각의 Host 별로 어디에 매핑되기를 희망하는지를 해시 연산을 통해 계산합니다. 해당 과정을 Permutation이라고 부릅니다.

Permutation이 끝나고 나면, 위와 같이 각 Host 별로 우선순위를 결정할 수 있습니다. 그다음에 수행할 작업은 Permutation table을 토대로 Lookup table 내용을 채우는 작업입니다.

이 과정은 Popluation 이라고 부르며, 해당 과정을 통해 Maglev 알고리즘이 균등하게 부하를 분산할 수 있도록 Lookup table을 채워줍니다. 그렇다면 Popluation은 어떻게 이루어질까요? 위 Permuation table을 기초로 Popluation 과정을 조금 더 자세히 살펴보겠습니다.

출처 : https://static.googleusercontent.com/media/research.google.com/en//pubs/archive/44824.pdf

N : Host 개수

M : Lookup table 크기

next[] : Permutation table 내에서 Host 별로 다음 index를 추적을 위한 배열

entry[] : Lookup table

Google의 Maglev 논문을 살펴보면, 위와 같이 Popluation 하는 과정에 대한 Pseudocode를 살펴볼 수 있습니다. 해당 과정을 몇 단계만 차례차례 살펴보면서 동작 과정에 대해서 이해해보겠습니다.

Step 1.

가장 먼저 수행하는 작업은 Lookup table과 Next 배열의 초기화입니다. 이때 Lookup table의 모든 원소는 -1로 Next 배열의 경우 배열의 index를 가르켜야 하기 때문에 0으로 초기화하는 것이 특징입니다.

Step 2.

초기화가 완료되면, Host 별로 순차적으로 Lookup table을 갱신합니다. 먼저 0번 Host의 index가 현재 Next에서 0이므로 Permutation table의 0번 index를 살펴봅니다. 이때 Host 0은 Lookup table의 3번 index에 매핑되기 희망하므로 Lookup table의 해당 index을 탐색합니다. 이때 Lookup table에 해당 값이 -1 즉 아무 값도 매핑되지 않은 상태이므로 갱신이 가능합니다. 따라서 해당 index를 Host 0번 서버의 index인 0번으로 갱신합니다.

이후 Next 배열에서 그 다음 Permutation Table의 다음 참조 index를 가르키기 위해서 1증가한 값으로 갱신합니다.

Step 3.

Host 0번이 매핑되었으므로 그 다음은 Host 1 차례입니다. Host 1의 현재 index가 0번이므로 Permutation table에서 해당 index를 살펴봅니다. 이때 Host 1은 Lookup table의 0번 index에 매핑되기 희망하므로 Lookup table의 해당 index를 탐색합니다. 살펴본 결과, 해당 index 값이 -1 이므로 선택될 수 있습니다. 따라서 Lookup table의 0번 index를 Host 1번의 값인 1로 갱신합니다. 또한 Next 배열에서 다음 값을 참조하기 위해서 1증가한 값으로 갱신합니다.

Step 4.

그 다음은 Host 2번이 Lookup table에 매핑될 차례입니다. 이전과 마찬가지로 Next 배열에서 해당 Host의 Permutation table 참조 index가 0번이므로 0번을 살펴봅니다. 이때 Host 2는 Lookup table에서 3번 위치에 매핑되기를 희망합니다. 따라서 Lookup table이 3번 index를 살펴봅니다.

하지만 Host 0번에 기존에 선점하였기 때문에, 해당 index에 Host 2를 매핑할 수는 없습니다. 따라서 다른 Lookup table 위치를 탐색해야합니다.

이 경우에는 Permutation table의 다음 index 참조를 위해 먼저 Next 배열에 저장된 값을 1증가시킵니다. 이후 Permutation table에서 증가된 index 위치를 탐색합니다. 결과를 살펴보면, 두 번째로 선호하는 자리가 4번 index이기 때문에 Lookup table에서 해당 index를 탐색합니다. 살펴본 결과 해당 값은 -1이기 때문에 선점이 가능합니다. 따라서 Lookup table의 4번 index는 Host 2에게 배정합니다.

만약 또 충돌이 발생했다면, 방금전 수행했던 절차대로 Next 배열의 값을 1 증가시키고, Permutation table의 해당 위치를 탐색하여 Lookup table에 해당하는 index 값이 -1이 나올 때까지를 반복 수행하여 매핑을 수행합니다.

Host 2의 매핑이 완료되었으면, Next 배열의 값을 1 증가 시켜, 다음 Permutation table 참조 index를 갱신합니다.

Step 5.

Host 2까지 매핑이 모두 완료되었으면, 다시 Host 0의 차례입니다. 따라서 Step 2-4 단계를 반복하면서, 개별 Host가 선호하는 Lookup table 갱신을 수행합니다. 해당 과정은 Lookup table이 완성될 때까지 반복합니다.

Permutatiion 과정이 모두 끝나고 나면, 위 그림과 같이 Lookup table이 완성됩니다. 완성된 결과를 살펴보면, 모든 Host가 균등하게 배분되었음을 알 수 있습니다. 이는 Permutation 단계에서 각 Host 별로 돌아가면서 Lookup table을 순차적으로 갱신했기 때문입니다.

따라서 이후 Load Balancer는 Hash 값에 대한 Modular 연산을 통해서 Host에게 부하를 분산할 수 있게됩니다.

그렇다면 Maglev 알고리즘을 사용하는 상황에서 Host의 삭제가 발생했을 경우 어떻게 될까요?

이전과 마찬가지로 Permutation 과정을 진행합니다. 하지만 Permutation을 수행해도 기존 Host가 희망하는 해시값 기반 우선순위에는 변화가 없습니다. 따라서 Host 1이 제거될 경우 기존 table에서 Host 1 데이터들만 제거되어 갱신될 뿐, 기존 Host 들이 선호하는 값은 그대로입니다.

이후 Popluation을 진행하면, 위 그림의 Lookup table과 같이 변경됩니다. 이때 유심히 볼 점은 기존 Host들이 선호했던 Lookup table의 index 변화는 없는 상태에서 Host 1이 희망했던 index에만 다른 Host로 채워졌음을 알 수 있습니다. 따라서 이는 기존의 다른 Host들에게 연결된 Connection은 그대로 유지한채 기존 Host 1에 연결된 Connection만 재연결이 필요함을 의미합니다. 따라서 안정성을 확보할 수 있는 장점이 존재합니다.

지금까지 Maglev 방식에 대해서 살펴봤습니다. envoy에서는 다음과 같이 lb_policy를 maglev로 지정함으로써 해당 알고리즘을 사용할 수 있습니다.

static_resources:
  clusters:
  - name: my_service
    connect_timeout: 0.25s
    type: strict_dns
    lb_policy: maglev
    maglev_lb_config:
      table_size: 65536
    load_assignment:
      cluster_name: my_service
      endpoints:
      - lb_endpoints:
        - endpoint:
            address:
              socket_address:
                address: 127.0.0.1
                port_value: 8080
          load_balancing_weight: 2      
        - endpoint:
            address:
              socket_address:
                address: 127.0.0.1
                port_value: 8081
          load_balancing_weight: 1      
        - endpoint:
            address:
              socket_address:
                address: 127.0.0.1
                port_value: 8082
          load_balancing_weight: 3

이때 위와 같이 maglev_lb_config를 통해 Lookup table의 크기를 변경할 수 있습니다. 참고로 Lookup table의 크기를 키우면 키울 수록 Host Down에 대한 Connection 재분배에 대한 영향도를 줄일 수 있으며, envoy에서는 기본값이 65536이고 최대 5000011개로 지정할 수 있습니다.

이때 Lookup table 사이즈를 키우게되면, Connection 재분배 비율은 줄일 수 있으나 Memory를 그만큼 사용하며, Population에 드는 시간이 증가하므로 마찬가지로 적절한 PoC를 통해서 적정 값을 도출하는 것이 좋습니다.

지금까지 Maglev에 대해서 살펴봤는데요. Maglev는 Consistent Hashing 방식에 비해 어떤 이점을 가지고 있을까요?

1. Traffic Balancing

Maglev의 경우는 ECMP(Equal-Cost Multipath) 라우팅을 추구합니다. Lookup table을 구성할 때 모든 Host가 동등한 비율로 배분하여 Traffic 전달 시에 보다 균등하게 부하를 분산할 수 있도록 추가합니다.

2. 단순한 설정

Maglev의 경우는 Virtual Node를 생성하지 않습니다. Consistent Hasing 방식의 경우는 Virtual Node 생성을 위한 여러 기타 설정이나 균등하게 부하를 분산하기 위해 기타 Hashing 파라미터를 조정해야할 수 있지만 Maglev는 Table 사이즈를 조정하는 정도를 통해서 목표를 달성할 수 있습니다.

하지만 Maglev를 사용하기 위해서는 Permutation Table, Lookup table, Next 등 다양한 자료구조가 사용되며, Host 생성/추가 발생 시에 Permutation과 Popluation 작업이 지속 발생되기 때문에 상대적으로 높은 메모리와 CPU 비용이 요구됩니다. 따라서 무조건 Maglev 방식이 좋다고 말할 수는 없으며, 언제나 비즈니스 상황과 인프라 환경에 맞추어 테스트 후 적절한 방법을 사용하는 것이 좋다고 볼 수 있습니다.

8. 마치며

지금까지 envoy에서 제공하는 다양한 Load Balancing 알고리즘 방법에 대해서 살펴봤습니다. 업무 환경에 적용할 때는 비즈니스 환경의 규모 및 성능을 고려하여 적절한 Load Balancing 전략을 차용하는 것이 중요합니다. 따라서 각각의 알고리즘이 어떻게 동작하며, 어떠한 특징이 있는지 잘 이해하고 있는 것이 무엇보다 중요하다고 볼 수 있겠습니다.

3. [envoy-internals] Cluster Manager - 역할

cla9 — Thu, 18 May 2023 11:44:49 +0900

1. 서론

앞선 두 개의 포스팅을 통해 envoy 고수준 아키텍처 구조 및 쓰레딩 모델에 대해서 학습하였습니다. 이번 포스팅 부터는 Envoy의 가장 핵심이되는 주요 컴포넌트에 대해서 각 컴포넌트가 세부적으로 어떻게 구성되어있는지 그리고 컴포넌트간에 상호 작용이 어떻게 이루어지는지에 대해 자세하게 살펴보겠습니다.

참고로 이번 포스팅의 내용은 TCP 기반 설정이 구성되었다는 가정하에 작성하였습니다.

2. Envoy 구조

이 시리즈의 첫 번째 포스팅에서 Listener, Endpoint, Cluster 개념에 대해서 간략하게 살펴봤습니다. 그 중 Endpoint의 경우 Cluster와 종속적인 관계를 지니므로 Cluster에서 Endpoint를 관리합니다. 따라서 envoy의 핵심 컴포넌트를 꼽자면 Listener와 Cluster라고 봐도 무방합니다. 그렇다면 Listener와 Cluster는 누가 관리하고 어떻게 생성될까요? 위 그림을 보면 Listener Manager와 Cluster Manager가 해당 컴포넌트를 관리하는 것을 짐작할 수 있습니다.

실제로 envoy server 기동 코드를 살펴보면 config.yaml 파일을 읽어서 envoy 기동에 필요한 사용자 정의 설정을 파싱하는 작업을 선행합니다. 그 이후 주요 컴포넌트 기동에 필요한 항목등을 생성합니다.

이때 위 그림을보면 Listener Component Factory와 Cluster Manager Factory를 생성하는 것을 볼 수 있습니다. 여기서 Factory라는 말에서 의미가 바로 전달되듯이 해당 Factory 들은 Listener Manager와 Cluster Manager를 생성하는데 있어 중요 역할을 수행합니다.

지금부터는 Listener Component Factory로부터 생성되는 Listener Manager의 세부 구조와 Cluster Manager Factory로부터 생성되는 Cluster Manager에 대해서 상세하게 알아보고자 합니다. 다만 이번 포스팅에서는 Cluster Manager에 대해서 중점적으로 알아보고 Listener는 다음 포스팅에서 다루겠습니다.

3. Subscription Factory 관리

Cluster Manager는 Cluster Manager Factory로 부터 생성되는 컴포넌트로써, 이름을 통해 유추할 수 있듯이 Cluster를 관리하는 역할을 수행합니다. 따라서 이에 대한 이해를 위해서는 Cluster 관리가 어떻게 이루어지는지 먼저 학습하는 것이 좋습니다. 하지만 그 전에 Cluster Manager의 주요 역할 중 하나인 Subscription Factory 관리와 gRPC Multiplexer에 대해서 먼저 다루어보고자 합니다.

이를 먼저 다루는 이유는 Cluster Manager에서 관리하는 Cluster를 등록하는 방식에는 Static 방식과 Dynamic 방식이 존재하는데, Dynamic 방식의 Cluster Update 과정에 대해 이해하려면 Subscription과 gRPC Multiplexer에 대한 이해가 선행되어야하기 때문입니다.

방금 전 언급했듯이 Cluster Manager의 역할 중 하나는 Subscription Factory를 관리하는 것이라고 설명했습니다. 그렇다면, Subscription은 무엇이고 Subscription Factory는 어떤 역할을 수행할까요? 이 부분에 대해서 살펴보겠습니다.

이전에 Envoy는 xDS API를 통한 Resource(Listener, Endpoint 등)를 관리한다고 언급한바 있습니다.

참고로 xDS API에는 gRPC, Rest API, 파일 동기화 방법이 있지만, 여기서는 gRPC 방식을 사용한다고 가정하겠습니다.

이때 gRPC 통신을 위해서 내부적으로 Multiplexer를 사용하는데, 자원 동기화 요청이 Envoy로 전달되면, 이를 수신받아 해당 Resource를 처리하는 모듈(CDS, LDS, EDS 등)에게 전달 해줘야합니다. 그리고 처리하는 모듈 쪽에서는 사전에 Callback을 등록하여 응답이 전달되면 해당 Callback을 실행할 수 있도록 합니다.

이 과정에서 중간 매개체 역할을 하는 것이 Subscription입니다. 즉 Resource를 처리하는 모듈에서 Config 대상 오브젝트 타입과 Callback을 Subscription 객체로 생성하여 등록합니다. 그리고 해당 Subscription 생성은 Subscription Factory가 수행하고, 추후 gRPC Multiplexer에 등록합니다. 이후 gRPC Multiplexer로 부터 Resource 동기화 요청이 수신되면, 해당 요청에 상응하는 Subscription의 Callback이 호출되어 데이터 동기화 처리를 수행할 수 있게됩니다.

예를 통해서 살펴보겠습니다. 가령 Listener Manager에서 LDS를 등록한다고 가정하겠습니다. 이 경우 먼저 Cluster Manager의 Subscription Factory로부터 Subscription 생성을 요청합니다. 이때 Subscription Factory는 내부 gRPC Multiplexer에 해당 정보를 등록합니다. 이후 LDS 요청 타입의 응답이 전달되었을 경우 Callback을 통해 Listener Manager에게 응답을 전달합니다.

이때 Cluster Manager는 Subscription Factory를 내부 프로퍼티로 가지고 있고, 외부의 다른 컴포넌트로부터 Subscription 생성, 삭제 등의 처리를 위임받아 처리하는 역할을 수행합니다.

이를 조금 더 자세히 표현하면, 개별 xDS API들은 SubscriptionBase 클래스를 상속받고 있으며, 해당 클래스에는 각각 Config Update에 대하여 수행해야할 메소드들이 정의되어있습니다. 따라서 각각의 API는 구현이 요구되는 메소드들에 대해서 모듈 특성에 따라 처리방법이 기술되어있습니다. 이후 xDS API를 사용하기 위해서 Cluster Manager에 존재하는 Subscription Factory로부터 Subscription을 요청하는데, 이때 Subscription Factory 내부에서는 Multiplexer에 해당 Callback 정보를 등록하고 생성된 Subscription을 반환합니다.

4. gRPC Multiplexer

지금까지 xDS API 사용을 위해 Subscription Factory로부터 Subscription을 생성받는 과정에 대해서 살펴봤습니다. 이번에는 subscription 생성 이후 상호작용 수행하는 gRPC Multiplexer의 구성요소 및 동작 원리에 대해서 살펴보겠습니다.

gRPC Multiplexer에는 SotW를 위한 GrpcMuxSotw, Delta XDS를 위한 GrpcMuxDelta 등 여러가지 GrpcMuxImpl을 위한 구현체가 존재합니다. 그리고 해당 구현체는 공통적으로 위 3가지 컴포넌트가 내부에 존재합니다. 해당 컴포넌트가 무엇이고 어떠한 역할을 하는지 살펴보겠습니다.

1. watchMap은 외부에서 생성한 Subscription을 기반으로 gRPC 통신 수행결과를 전달받아 Callback 함수를 실행시키기 위한 자료구조로써 Watch 객체를 생성하여 저장합니다. Watch 객체에는 사용자가 지정한 Callback이 매핑되어있습니다.

2. gRPC 통신을 위해서는 SubscriptionState가 필요합니다. 해당 객체는 SubscriptionStateFactory로 부터 생성이 가능하며, SubscriptionState에는 WatchMap에 존재하는 Watch 객체를 매핑하여, 향후 gRPC 응답이 반환되었을 때 이를 전달할 수 있도록 기능이 구현되어있습니다.

3. grpcStream은 gRPC 통신을 수행하는 주체로써 외부 Management Server와 통신을 담당합니다.

gRPC Multiplexer는 여러개가 존재할 수 있는데, 개별 Multiplexer들을 관리하기 위해서 외부에 AllMuxes가 존재합니다. AllMuxes는 생성되는 여러개의 GrpcMuxImpl의 정보를 관리하기 위한 자료구조로써 hash set 형태로 생성되는 모든 GrpcMuxImpl을 관리합니다.

지금까지 gRPC Multiplexer와 관련하여 컴포넌트 정보를 확인했습니다. 아직은 gRPC를 통한 동기화 과정을 살펴보지 않았기 때문에 위 컴포넌트가 어떻게 상호작용하며 어떤 역할을 수행하는지 와닿지 않을 수 있습니다. 따라서 실제 사용자가 Subscription을 요청하여 데이터가 처리되는 과정을 살펴보면서 각각의 컴포넌트가 어떻게 연계되는지를 살펴보겠습니다.

1. 이전에 설명했듯이 xDS API를 사용하려는 CDS, EDS, LDS 등은 Cluster Manager가 가지고 있는 Subscription Factory로부터 Subscription을 전달받아야합니다. 따라서 먼저 Cluster Manager로부터 Subscription Factory 정보를 얻어옵니다.

2. Subscription Factory는 CDS, EDS, LDS 등에 매핑되어있는 api_type(SotW, Delta 등)을 분석하여 적절한 GrpcMuxImpl 구현체를 반환하도록 요청합니다.

3. api_type에 따른 GrpcMuxImpl 구현체를 생성한 이후 Subscription에 해당정보를 매핑하여 반환합니다.

4. Subscription을 전달받으면, 이후 통신 수행을 위하 GrpcMuxImpl에게 통신 수행을 요청합니다.

5. GrpcMuxImpl은 WatchMap에 Subscription에서 요구하는 type_url 정보에 해당하는 Watch 정보가 존재하는지 확인합니다. 만약 존재하지 않는다면 새로운 Watch를 생성합니다. 이때 Watch에는 Subscription에 존재하는 Callback을 저장합니다.

6. WatchMap에 type_url에 해당하는 Watch 정보가 없을 경우 SubscriptionStateFactory로부터 새로운 SubscriptionState를 생성합니다. 이때 생성되는 SubscriptionState에는 5번 단계에서 생성한 Watch 정보를 포함시켜, 향후 gRPC 응답이 왔을 때 해당 Watch에게 응답 수신 행위를 수행할 수 있도록 설정합니다. SubscriptionState 생성이 완료되면, 해당 정보는 GrpcMuxImpl 내부에 존재하는 subscriptions_ 자료구조에 저장됩니다.

7. SubscriptionState를 통해 gRPC 통신을 수행을 요청합니다.

8. gRPCStream은 xDS의 Management Server(ex: istio)와 연결을 수행하여 DiscoveryRequest를 요청합니다. 이후 Management Server로부터 Discovery Response를 전달하면 이를 수신받습니다.

9. gRPCStream은 응답 메시지의 type_url을 기준으로 subscriptions_ 자료구조에서 해당 type_url에 해당하는 Subscription을 찾아 응답 메시지를 전달합니다.

10. SubscriptionState는 6번 단계에서 매핑한 Watch를 통해 응답 처리를 위임합니다.

11. Watch는 생성당시 저장된 요청자의 Callback을 수행하여 처리를 위임합니다.

지금까지 gRPC Multiplexer에 대해서 살펴봤습니다. 이전 시나리오에서는 1개의 Subscription이 등록되고 gRPC 통신이 수행되는 과정에 대해서 살펴봤습니다. 실제로는 CDS, EDS, LDS 등 여러개의 Subscription이 존재하기 때문에 Subscription Factory에서 생성되는 Subscription은 다수가 될 수 있으며, 그에 따라 gRPC Mux 내부에는 Watch와 SubscriptionState 수가 다수가 될 수 있습니다. 마찬가지로 gRPC를 통해 수행되는 Mux 타입이 다수라면 해당 타입 또한 여러개가 될 수 있습니다.

5. Cluster 관리

지금까지 Cluster Manager의 기능 중 하나인 gRPC Multiplexer와 Subscription 관리에 대해서 살펴봤습니다. 이번에는 Cluster Manager에서 가장 핵심이 되는 Cluster 관리에 대해서 살펴보겠습니다.

Cluster Manager는 이름 그대로 Cluster를 관리하는 컴포넌트이기 때문에 가장 중요한 역할은 Cluster의 생성과 삭제 수정등을 수행하는 것 입니다.

Cluster Manager는 기동 당시에 Cluster Manager Factory에 의해서 생성됨을 이전에 설명했습니다. 이때 생성 과정에서 주요하게 살펴볼 부분은 Cluster Manager 생성과 동시에 CDS 설정이 존재한다면, CDS를 생성하고 config.yaml에 존재하는 Static Resource는 Parsing 정보를 토대로 읽어들어 ClusterData를 생성하는 것입니다. 또한 이후 CDS를 통해 ClusterData 정보가 업데이트되면, 해당 정보를 Cluster Manager가 전달받아 업데이트를 수행하는 것 또한 Cluster Manager의 역할입니다.

static_resources:
  clusters:
  - name: local_service
    connect_timeout: 0.25s
    type: STRICT_DNS
    lb_policy: ROUND_ROBIN
    load_assignment:
      cluster_name: local_service
      endpoints:
      - lb_endpoints:
        - endpoint:
            address:
              socket_address: { address: webservice, port_value: 90 }         
    health_checks:
      timeout: 3s
      interval: 90s
      unhealthy_threshold: 5
      healthy_threshold: 5
      no_traffic_interval: 240s      
      http_health_check:
        path: "/ping"
        event_log_path: /var/log/envoy/health_check.log
        expected_statuses:
          start: 200
          end: 201
    outlier_detection:
      consecutive_5xx: 2
      base_ejection_time: 30s
      max_ejection_percent: 40
      interval: 20s
      success_rate_minimum_hosts: 5
      success_rate_request_volume: 10

해당 과정에 대해서 조금 더 알아보기 위해 예를 통해서 살펴보겠습니다. 가령 위와 같이 static cluster 정보가 존재한다고 가정해봅시다. 여기서 Cluster 정보를 살펴보면, Load Balancing, Health Check, Outlier Detection 정보가 포함되어있는 것을 확인할 수 있습니다. 따라서 이를 통해 유추하자면 Envoy 내부에서 Cluster를 관리할 때 그 안에는 Load Balancing, Health Check 및 Outlier Detection을 수행하는 컴포넌트가 존재할 것이라는 것을 알 수 있습니다.

이번에는 Cluster Manager에서 Cluster를 만드는 과정에 대해서 살펴보겠습니다.

먼저 살펴볼 것은 static resource에 존재하는 cluster 정보를 Cluster Manager에서 관리하는 방법입니다. 해당 과정은 Envoy 기동 과정에서 수행되는 작업으로 생성 과정을 간략하게 살펴보면 다음과 같습니다. 먼저 envoy 기동시에 config 파일을 파싱합니다. 이후 Cluster Manager의 Cluster 저장을 위해 ClusterData 구조로 만들어서 이를 active_clusters_ 라고 불리는 map에 Cluster 정보를 저장합니다. 그렇다면 active_clusters_는 어떻게 구성되어있을까요?

해당 자료구조는 위 그림과 같이 Cluster 이름과 Cluster 정보로 이루어진 Map입니다. Cluster가 생성된 이후에 active_clusters_에 ClusterData를 추가하며, Cluster 삭제 이벤트가 발생하면 이를 삭제하는 등 해당 자료구조를 통하여 Cluster Manager가 관리하고 있는 Cluster의 종류와 갯수 현행화를 수행합니다.

이때 Map의 Value로 저장되는 것은 ClusterDataPtr으로써 파싱된 결과를 ClusterData 데이터 구조로 만들고 이에 대한 포인터 값을 저장하는데, ClusterData가 보유한 내부 속성 중 중요한 속성 설명 및 생성 과정에 대해 조금 더 자세히 알아보겠습니다.

먼저 Parsing된 Cluster 정보를 토대로 ClusterData 인스턴스 생성을 위해 ProdClusterManagerFactory에게 처리를 위임합니다. 해당 Factory 내부에서는 다시 ClusterFactoryImplBase에게 Cluster 생성 주체를 위임합니다.

cluster_factory_impl.cc

std::pair<ClusterSharedPtr, ThreadAwareLoadBalancerPtr>
ClusterFactoryImplBase::create(Server::Configuration::ServerFactoryContext& server_context,
                               const envoy::config::cluster::v3::Cluster& cluster,
                               ClusterFactoryContext& context) {
  auto stats_scope = generateStatsScope(cluster, context.stats());
  std::unique_ptr<Server::Configuration::TransportSocketFactoryContextImpl>
      transport_factory_context =
          std::make_unique<Server::Configuration::TransportSocketFactoryContextImpl>(
              server_context, context.sslContextManager(), *stats_scope, context.clusterManager(),
              context.stats(), context.messageValidationVisitor());

  std::pair<ClusterImplBaseSharedPtr, ThreadAwareLoadBalancerPtr> new_cluster_pair =
      createClusterImpl(server_context, cluster, context, *transport_factory_context,
                        std::move(stats_scope));

  if (!cluster.health_checks().empty()) {
    if (cluster.health_checks().size() != 1) {
      throw EnvoyException("Multiple health checks not supported");
    } else {
      new_cluster_pair.first->setHealthChecker(HealthCheckerFactory::create(
          cluster.health_checks()[0], *new_cluster_pair.first, context.runtime(),
          context.mainThreadDispatcher(), context.logManager(), context.messageValidationVisitor(),
          context.api()));
    }
  }

  new_cluster_pair.first->setOutlierDetector(Outlier::DetectorImplFactory::createForCluster(
      *new_cluster_pair.first, cluster, context.mainThreadDispatcher(), context.runtime(),
      context.outlierEventLogger(), context.api().randomGenerator()));

  new_cluster_pair.first->setTransportFactoryContext(std::move(transport_factory_context));
  return new_cluster_pair;
}

ClusterFactoryImplBase의 처리 과정을 살펴보기 위해 코드레벨로 확인해보겠습니다. ProdClusterManagerFactory로 부터 Cluster 생성 처리를 위임받은 ClusterFactoryImpl의 create 메소드내용을 살펴보면, Socket 관리, Cluster, HeathChecker, OutlierDetector를 생성하기 위해 각각의 Factory에게 처리를 위임하고 생성 결과를 전달받아 Cluster에 할당하는 것을 볼 수 있습니다. 참고로 여기서 생성되는 HealthCheker 및 OutlierDetector에 대한 자세한 설명은 조금 뒤에 다시 살펴보겠습니다.

위 코드에서 실제 Cluster 생성은 createClusterImpl 메소드내에서 이루어지며, 해당 메소드 내에서는 Proto 파일 정의에 따른 인스턴스 생성과 실제 Parsing 내용을 결합한 Cluster 인스턴스를 전달받습니다.

Cluster 생성이 완료된 이후에는 Cluster 인스턴스와 내부에 Parsing된 정보를 토대로 생성된 HealthChecker, OutlierDetector, LoadBalancer가 존재할 것입니다. 이후에는 다음과 과정을 추가로 거칩니다.

1. healthChecker가 등록되어있다면, hostCheckCompleteCallback 함수를 등록시킵니다. 해당 함수는 host가 Health Check가 실패했을 때, 해당 정보를 Cluster Manager에게 전달하고, 결과적으로는 해당 Cluster가 Connection Pool에서 해제하도록 후속 작업을 수행하기 위한 용도로 사용됩니다.

2. outlierDector가 등록되어있다면, changeStateCallback 함수를 등록시킵니다. 해당 함수는 만약 host가 Outlier로 판정되고, ejection 상황이라면, 해당 정보를 Cluster Manager에게 전달하고, 결과적으로는 해당 Cluster가 Connection Pool에서 해제하도록 후속 작업을 수행하기 위한 용도로 사용됩니다.

3. Callback이 모두 등록이 완료되면, Cluster에 설정된 Load Balancer를 생성하기 위한 메타데이터를 등록합니다. 이때 등록되는 Load Balancer 타입은 lb_policy에 명시된 종류에 따라 다르게 생성되며, Round Robin, Least Request, Hash Ring과 같은 타입들을 지원합니다.

4. 생성된 Cluster 정보를 Cluster Manager가 관리하는 active_clusters_ 에 추가합니다.

위 네가지 과정을 거치게되면 ClusterData 설정은 마무리됩니다. 지금까지 static resource로 등록된 Cluster 처리 과정에 대해서 살펴봤습니다. 이번에는 CDS를 통해 dynamic으로 등록되는 resource 처리 과정에 대해서 살펴보겠습니다.

Dynamic 설정의 경우에는 CDS를 통해 처리됨을 설명했습니다. 따라서 CDS 처리를 위해서는 Cluster Manager에서 관리하는 gRPC Multiplexer(ads_mux)와 Subscription Factory와의 상호작용이 필요합니다. 이를 토대로 CDS를 통한 동기화 과정을 살펴보면 다음과 같습니다.

1. CDS 등록을 위해 가장 먼저 Cluster Manager에 존재하는 Subscription Factory로부터 Subscription을 요청합니다.

2. Subscription Factory는 Subscription을 반환하기 CDS가 전달받기 희망하는 Resource 타입에 대한 데이터 요청 및 Callback 처리를 위해 Multiplexer에 이를 등록합니다.

3. CDS가 요청하는 Resource 타입 등록 및 해당 Subscription을 CDS에 반환합니다.

4. 외부에서 Cluster 변화(생성/삭제/수정)가 감지되어 Envoy에 통지되면 해당 내용이 Multiplexer를 지나 Callback을 통해 CDS로 전달될 것입니다. 이때 CDS 내부에서는 이를 처리하기 위해 CdsApiHelper에게 처리를 위임합니다.

5. CdsApiHelper에서는 해당 내용을 정제합니다. Cluster Manager에 위치한 active_clusters_에 해당 내용을 반영합니다.

만약 기존 Cluster의 업데이트라면 해당 내용을 수정하고, 신규 추가라면 Cluster 정보를 active_clusters_에 추가할 것입니다.

5-1. Cluster Entry

지금까지 Static 방식과 Dynamic 방식을 통해서 Cluster Manager가 Cluster를 관리하기 위해 사용되는 active_clusters_에 Cluster 정보를 현행화하는 방식에 대해서 살펴봤습니다. 하지만 여기서 active_clusters_에서 값으로 관리되는 ClusterData는 Cluster의 역할 중 핵심 기능을 포함하고 있지 않습니다.

그렇다면 Cluster가 제공하는 핵심 기능은 무엇일까요?

Cluster 의 가장 중요한 기능 중 하나는 Client가 Cluster 내에 존재하는 여러 B/E host와의 연결을 시도할 때, 중간에서 Client의 연결과 B/E의 연결을 이어주는 Connection Pool 인터페이스 기능을 제공한다는 점입니다.

해당 기능은 active_clusters_가 관리하는 ClusterData에서 이를 제공하지 않습니다. 따라서 Cluster Manager에서는 active_clusters_ 를 Cluster 변경이 생겼을 때(CDS) 관리하는 메타데이터 용도로써 내부적으로 관리하고 외부와의 Cluster 연결 등에는 별도 자료구조(thread_local_clusters_)와 ClusterData를 확장한 ClusterEntry를 통해서 Connection Pool 관리 기능과 Load Balancer 기능을 제공합니다.

따라서 이번에는 Static, Dynamic 방식을 통해서 active_clusters_에 등록된 이후 진행되는 후속 과정과 이를 통해서 생성되는 ClusterEntry 및 ClusterEntry를 관리하는 thread_local_clusters_ 에 대해서 살펴보겠습니다.

Cluster Manager를 구동하는 과정에서 수행하는 작업 중 하나는 Main 쓰레드에 존재하는 Dispatcher를 통해 TLS를 할당받는 것입니다. 이때 생성하는 Slot은 ThreadLocalClustManagerImpl 로써, 외부에 존재하는 모듈이나 내부에서 Cluster 데이터 동기화를 수행할 때 해당 Slot에 존재하는 인스턴스를 활용합니다.

그리고 Cluster Manager 내부에는 thread_local_clusters_라고 불리는 Map이 존재하는데, 해당 Map은 Key로써는 Cluster의 이름을 Value는 ClusterData를 기반으로 만들어진 ClusterEntry를 가지고 있습니다. 즉 이전에 설명했듯이 Connection Pool 기능과 실질적인 LoadBalancer 인스턴스를 지니고 있는 ClusterEntry를 해당 자료구조가 가지고 있으며, 외부 모듈에서는 thread_local_clusters_ 접근을 통해 Cluster Manager가 보유하고 있는 Cluster 정보에 대해 참조가 가능합니다.

그렇다면 Static, Dynamic 등록을 통해서 active_clusters_에 생성된 Cluster 정보를 기반으로 어떤 시점에 thread_local_clusters_를 만들어낼까요? ClusterEntry 생성과 thread_local_clusters_ 삽입 과정을 통해서 이해해보겠습니다. 먼저 Static Cluster 등록부터 살펴보겠습니다.

Static Resource가 모두 등록되면 해당 ClusterData는 모두 active_clusters_에 저장되어있을 것입니다. 이후 Cluster Manager 설정이 끝나게되면, active_clusters_를 순회하면서 초기화 작업을 진행합니다.

이때 수행하는 작업은 크게 4단계로 이루어져있습니다.

1. 개별 ClusterData를 순회하면서 Cluster에 멤버가 추가되거나 우선순위가 변경되었을 때 후속 작업을 수행하기 위한 Callback을 등록합니다.

2. 등록되어있는 Callback의 역할은 Cluster Manager가 여러개일 경우 개별 Cluster Manager에서 보유중인 local cluster를 업데이트 하는 것입니다. 따라서 Cluster Manager 동기화를 위해 TLS Slot에 저장된 ThreadLocalClusterManagerImpl을 참조하여 후속 작업 처리를 요청합니다.

3. Callback 등록이 완료되면, thread_local_clusters_에 Cluster를 생성하기 위해 TLS Slot에 저장된 ThreadLocalClusterManagerImpl를 참조하여 모든 Cluster Manager에게 Cluster 생성에 대한 내용을 통지하고 이를 전달받은 Cluster Manager에서는 ClusterEntry를 생성하여 자신의 thread_local_clusters_에 저장합니다.

ClusterEntry는 ClusterData에 저장된 info 정보를 포함하고 있으며, 내부에는 클러스터 관리를 위한 여러 속성이 존재합니다. 그 중 몇개만 소개하자면, 먼저 Connection Pool에 접근할 수 있는 인터페이스 기능 제공을 포함합니다. 그리고 등록된 B/E의 host 및 우선순위를 관리하기 위한 PrioritySetIml이 있습니다. LoadBalancer는 해당 Cluster에 대해 외부에서 사용자 접속 요청이 들어왔을 때 실질적으로 LoadBalancer를 수행하기 위한 인스턴스가 매핑되며, AsyncClient를 통해서 Upstream과 연결을 수행합니다.

4. 만약 Cluster의 변경에 대하여 외부에서 통지를 받기위해 Callback을 등록했었다면, Cluster 변경에 대한 통지를 외부에게 알립니다.

위와 같은 과정을 거쳐 Static Resource로 등록한 자원들이 active_clusters_에 최초 저장이되고 이를 토대로 다시 전체 Cluster Manager에서 Cluster Entry를 만들고 이를 자신의 thread_local_clusters_에 저장함으로써 Cluster 관리가 이루어집니다. 또한 이후에는 외부에서 Cluster 접근을 요청할 때 thread_local_clusters_를 통해서 해당 Cluster 정보 참조가 가능해집니다.

Dynamic Resource 등록의 경우 이전에 active_clusters_ 에 추가함을 설명했는데, 이 과정에서 Cluster 초기화를 후속 진행합니다. 이때 ClusterEntry가 생성되고 해당 데이터가 thread_local_clusters_에 추가되면서 Cluster Manager에서 Cluster 동기화가 이루어집니다.

5-2. Connection Pool 관리

이번에는 Cluster Entry 내부에 있는 ConnectionPool 인스턴스를 통해서 Cluster Manager가 어떻게 Connection Pool을 관리하는지에 대해서 살펴보고자 합니다. 여기서 Connection Pool 관리는 Cluster Manager가 하며, 외부에서는 Cluster Entry를 통해 Cluster Manager에서 관리하는 Connection Pool 획득 및 해제등의 요청을 수행할 수 있습니다. 따라서 이 부분에 대해서 자세히 알아보도록 하겠습니다.

Cluster Manager 내부에는 Connection Pool을 관리하기 위한 map이 여러개 존재합니다. 그 중 host_http_conn_pool_map은 http 요청 관련 Connection Pool을 관리하며, 그 밖에 TCP 기반으로 Connection이 이루어지는 요청의 경우는 host_tcp_conn_pool_map을 통해 Connection Pool을 관리합니다. 본 포스팅에서는 Http 연결 요청에 대한 처리만을 다루고 있으므로 Cluster Manager에서 관리하는 host_http_conn_pool_map에 대해서만 설명하겠습니다.

host_http_conn_pool_map은 이름을 통해 알 수 있듯이 Map 자료구조입니다. 이는 HostPtr을 Key로 하며, Value는 Connection을 관리하기 위한 Container로 구성되어있습니다. 그리고 해당 Container 안에는 Connection Pool Map이 별도로 존재합니다.

따라서, 외부에서 Connection 연결을 시도하기 위해서는 먼저 host를 기반으로 host_http_conn_pool_map으로 부터 Container를 획득해야하며, 그 안에 존재하는 Connection Map을 통해 Connection 할당 및 해제를 수행할 수 있습니다.

그렇다면 Connection 할당 및 해제는 언제 어떻게 이루어질까요?

Envoy 관련 첫 포스팅 때, Envoy의 내부 흐름은 위와 같이 진행된다고 설명한 적이 있습니다. 여기서 Listener를 통해 Cluster에 접근하고 Load Balancing을 수행하는 과정에서 Cluster Manager를 통해 Endpoint 즉 host가 지정됩니다. 그리고 이 과정에서 Connection Pool로부터 Connection을 할당받아 요청을 전달할 수 있습니다. 정리하자면 Connection Pool로부터 Connection을 할당 받는 시점은 Load Balancing이 완료된 이후입니다.

위 그림으로 표시된 영역을 조금 더 자세히 확대하여 구체적으로 내부 컴포넌트가 어떻게 연계되는지 살펴보겠습니다.

1. Listener를 거쳐 Router에 도달하게되면, Client의 요청이 어떤 Cluster에게 전달되어야하는지 이미 알고 있습니다. 따라서 Router에서는 Cluster Manager에게 자신이 접근하고자 하는 Cluster 정보를 요청합니다.

2. Cluster Manager는 자신이 보유하고 있는 thread_local_clusters_ 에서 Router가 요청한 Cluster 정보를 찾습니다.

cluster_manager_impl.cc

ThreadLocalCluster* ClusterManagerImpl::getThreadLocalCluster(absl::string_view cluster) {
  ThreadLocalClusterManagerImpl& cluster_manager = *tls_;

  auto entry = cluster_manager.thread_local_clusters_.find(cluster);
  if (entry != cluster_manager.thread_local_clusters_.end()) {
    return entry->second.get();
  } else {
    return nullptr;
  }
}

참고로 이때 thread_local_clusters_에 저장된 값은 ClusterEntry이지만, ClusterEntry는 ThreadLocalCluster를 상속받기 때문에 리턴 타입은 ThreadLocalCluster로 하여 ThreadLocalCluster에서 제공되는 메소드만 호출 가능합니다.

3. Cluster Manager로 부터 ThreadLocalCluster를 찾아서 Router로 반환합니다.

4. Router에서는 Cluster내에 존재하는 host를 통해 Connection 연결을 수행해야되기 때문에, 전달받은 ThreadLocalCluster를 통해 Connection Pool 할당을 요청합니다.

5. 이를 전달받은 ThreadLocalCluster(ClusterEntry)는 Cluster Manager에게 요청하여 host_http_conn_pool_map 에 할당 받은 Connection Pool이 존재하는지를 확인합니다. 만약 존재한다면 해당 Connection Pool Map에 있는 Container에 접근합니다. 반면 존재하지 않는다면 새로운 Container를 생성하여 해당 Map에 추가합니다.

7. Container 내부에는 Cluster 별로 Connection을 관리하는 Pool을 가지고 있습니다. 그리고 여기에서 Pool 존재여부를 최종적으로 확인하고, 해당 Pool을 반환합니다. 해당 과정을 코드로 살펴보면 다음과 같습니다.

conn_pool_map_impl.cc

template <typename KEY_TYPE, typename POOL_TYPE>
typename ConnPoolMap<KEY_TYPE, POOL_TYPE>::PoolOptRef
ConnPoolMap<KEY_TYPE, POOL_TYPE>::getPool(const KEY_TYPE& key, const PoolFactory& factory) {
  Common::AutoDebugRecursionChecker assert_not_in(recursion_checker_);

  auto pool_iter = active_pools_.find(key);
  if (pool_iter != active_pools_.end()) {
    return std::ref(*(pool_iter->second));
  }
  ResourceLimit& connPoolResource = host_->cluster().resourceManager(priority_).connectionPools();
  // We need a new pool. Check if we have room.
  if (!connPoolResource.canCreate()) {
    // We're full. Try to free up a pool. If we can't, bail out.
    if (!freeOnePool()) {
      host_->cluster().stats().upstream_cx_pool_overflow_.inc();
      return absl::nullopt;
    }

    ...(중략)...
  }

  auto new_pool = factory();
  connPoolResource.inc();
  for (const auto& cb : cached_callbacks_) {
    new_pool->addIdleCallback(cb);
  }

  auto inserted = active_pools_.emplace(key, std::move(new_pool));
  return std::ref(*inserted.first->second);
}

active_pools_가 Container가 보유하고 있는 Pool을 의미합니다. 해당 과정을 살펴보면, 먼저 Container 내부에서 관리하는 active_pools_에서 해당 pool이 존재하는지를 찾습니다. 참고로 여기서 key 값은 protocol을 uint8_t로 캐스팅한 값입니다.

그리고 만약 값이 존재하지 않았을 때에는, 해당 Cluster가 Connection Pool을 생성이 가능한지 Resource Limit 설정 값을 살펴봅니다. 그리고 생성이 불가할 경우에는 위 코드와 같이 nullopt를 반환하는 것을 볼 수 있습니다.

8. 만약 Resource Limit 설정 값을 확인했을 경우 신규 Pool 생성이 가능한 경우에는 기존에 입력받은 factory 메소드로부터 신규로 Pool을 할당받고자 호출합니다.

cluster_manager_impl.cc

Http::ConnectionPool::InstancePtr ProdClusterManagerFactory::allocateConnPool(
    Event::Dispatcher& dispatcher, HostConstSharedPtr host, ResourcePriority priority,
    std::vector<Http::Protocol>& protocols,
    const absl::optional<envoy::config::core::v3::AlternateProtocolsCacheOptions>&
        alternate_protocol_options,
    const Network::ConnectionSocket::OptionsSharedPtr& options,
    const Network::TransportSocketOptionsConstSharedPtr& transport_socket_options,
    TimeSource& source, ClusterConnectivityState& state, Http::PersistentQuicInfoPtr& quic_info) {

  Http::HttpServerPropertiesCacheSharedPtr alternate_protocols_cache;
  if (alternate_protocol_options.has_value()) {
    // If there is configuration for an alternate protocols cache, always create one.
    alternate_protocols_cache = alternate_protocols_cache_manager_->getCache(
        alternate_protocol_options.value(), dispatcher);
  } else if (!alternate_protocol_options.has_value() &&
             (protocols.size() == 2 ||
              (protocols.size() == 1 && protocols[0] == Http::Protocol::Http2)) &&
             Runtime::runtimeFeatureEnabled(
                 "envoy.reloadable_features.allow_concurrency_for_alpn_pool")) {
    // If there is no configuration for an alternate protocols cache, still
    // create one if there's an HTTP/2 upstream (either explicitly, or for mixed
    // HTTP/1.1 and HTTP/2 pools) to track the max concurrent streams across
    // connections.
    envoy::config::core::v3::AlternateProtocolsCacheOptions default_options;
    default_options.set_name(host->cluster().name());
    alternate_protocols_cache =
        alternate_protocols_cache_manager_->getCache(default_options, dispatcher);
  }

  absl::optional<Http::HttpServerPropertiesCache::Origin> origin =
      getOrigin(transport_socket_options, host);
  if (protocols.size() == 3 &&
      context_.runtime().snapshot().featureEnabled("upstream.use_http3", 100)) {
    ASSERT(contains(protocols,
                    {Http::Protocol::Http11, Http::Protocol::Http2, Http::Protocol::Http3}));
    ASSERT(alternate_protocol_options.has_value());
    ASSERT(alternate_protocols_cache);
#ifdef ENVOY_ENABLE_QUIC
    Envoy::Http::ConnectivityGrid::ConnectivityOptions coptions{protocols};
    if (quic_info == nullptr) {
      quic_info = Quic::createPersistentQuicInfoForCluster(dispatcher, host->cluster());
    }
    return std::make_unique<Http::ConnectivityGrid>(
        dispatcher, context_.api().randomGenerator(), host, priority, options,
        transport_socket_options, state, source, alternate_protocols_cache, coptions,
        quic_stat_names_, stats_, *quic_info);
#else
    (void)quic_info;
    // Should be blocked by configuration checking at an earlier point.
    PANIC("unexpected");
#endif
  }
  if (protocols.size() >= 2) {
    if (Runtime::runtimeFeatureEnabled(
            "envoy.reloadable_features.allow_concurrency_for_alpn_pool") &&
        origin.has_value()) {
      ENVOY_BUG(origin.has_value(), "Unable to determine origin for host ");
      envoy::config::core::v3::AlternateProtocolsCacheOptions default_options;
      default_options.set_name(host->cluster().name());
      alternate_protocols_cache =
          alternate_protocols_cache_manager_->getCache(default_options, dispatcher);
    }

    ASSERT(contains(protocols, {Http::Protocol::Http11, Http::Protocol::Http2}));
    return std::make_unique<Http::HttpConnPoolImplMixed>(
        dispatcher, context_.api().randomGenerator(), host, priority, options,
        transport_socket_options, state, origin, alternate_protocols_cache);
  }
  if (protocols.size() == 1 && protocols[0] == Http::Protocol::Http2 &&
      context_.runtime().snapshot().featureEnabled("upstream.use_http2", 100)) {
    return Http::Http2::allocateConnPool(dispatcher, context_.api().randomGenerator(), host,
                                         priority, options, transport_socket_options, state, origin,
                                         alternate_protocols_cache);
  }
  if (protocols.size() == 1 && protocols[0] == Http::Protocol::Http3 &&
      context_.runtime().snapshot().featureEnabled("upstream.use_http3", 100)) {
#ifdef ENVOY_ENABLE_QUIC
    if (quic_info == nullptr) {
      quic_info = Quic::createPersistentQuicInfoForCluster(dispatcher, host->cluster());
    }
    return Http::Http3::allocateConnPool(dispatcher, context_.api().randomGenerator(), host,
                                         priority, options, transport_socket_options, state,
                                         quic_stat_names_, {}, stats_, {}, *quic_info);
#else
    UNREFERENCED_PARAMETER(source);
    // Should be blocked by configuration checking at an earlier point.
    PANIC("unexpected");
#endif
  }
  ASSERT(protocols.size() == 1 && protocols[0] == Http::Protocol::Http11);
  return Http::Http1::allocateConnPool(dispatcher, context_.api().randomGenerator(), host, priority,
                                       options, transport_socket_options, state);
}

여기서 할당된 factory 메소드는 ClusterManager에서 관리하는 allocateCoonPool이 최종적으로는 호출되며, Cluster Manager에서는 client가 요구하는 프로토콜이 무엇인지 확인한 다음에 해당 요청을 처리할 수 있는 Connection을 생성하여 반환합니다. 그리고 생성된 Pool을 Container가 보유하고 있는 active_pools_에 삽입합니다.

9. 생성된 Pool을 ThreadLocalCluster에 반환합니다.

10. Pool을 Router에게 반환합니다. 이후 해당 Router에서는 전달받은 Pool을 통해 Downstream과 Upstream과의 연결 작업을 요청할 수 있게됩니다.

위와 같이 10단계를 거치게되면, Router는 Connection Pool을 할당받아 요청을 처리할 수 있게되었음을 확인할 수 있습니다. 반면 Connection 해제는 Router로 전달되었던 Connection Pool을 통해 해제를 요청할 수 있습니다.

6. ADS 관리

dynamic_resources:
  lds_config:
    resource_api_version: V3
    ads: {}
  cds_config:
    resource_api_version: V3
    ads: {}
  ads_config:
    transport_api_version: V3
    api_type: GRPC
    grpc_services:
      envoy_grpc:
        cluster_name: envoy-control-xds

이전 포스팅에서 xDS API와 함께 ADS (Aggregate Discovery Service)에 대해서 설명했습니다. Cluster Manager의 또 다른 ADS를 생성하고 관리하는 것입니다. 즉 Cluster Manager에서는 xDS API를 위한 Subscription, gRPC Multiplxer 및 ADS 관리를 총체적으로 담당합니다.

7. Health Check 동작 원리

지금까지 Static Resource 그리고 CDS를 통한 Cluster 추가에 대해서 살펴봤습니다. 이번에는 ClusterData를 생성하는 과정에서 Health Check, Outlier Detector가 어떻게 생성되고 동작하는지 살펴보겠습니다. 먼저 살펴볼 것은 Health Check 입니다.

이전에 살펴봤듯이 ClusterData를 생성하는 과정에서 Outlier Detector, Health Chekcer, Load Balancer 등이 추가됨을 확인할 수 있습니다. 이때 Health Checker를 생성하는 역할은 HealthCheckerFactory가 담당하며, 이후 수행과정을 살펴보면 다음과 같습니다.

Config를 통해 전달받은 Cluster 내부에는 Http 방식 뿐만 아니라 Tcp, gRPC 혹은 Custom 방식의 Health Check를 지정할 수 있습니다. 따라서 HealthCheckerFactory에서는 사용자가 입력한 Config의 Heath Checker 방식을 확인하고 그에 걸맞는 Health Checker를 생성하도록 지정합니다. 본 포스팅에서는 Http 기반으로 생성했음을 가정하였음으로 ProdHttpHealthCheckerImpl을 생성할 것입니다.

생성된 Health Checker 인스턴스는 ClusterData의 HealthChecker에 바인딩되어 동작합니다.

cluster_manager_impl.cc

  if (new_cluster->healthChecker() != nullptr) {
    new_cluster->healthChecker()->addHostCheckCompleteCb(
        [this](HostSharedPtr host, HealthTransition changed_state) {
          if (changed_state == HealthTransition::Changed &&
              host->healthFlagGet(Host::HealthFlag::FAILED_ACTIVE_HC)) {
            postThreadLocalHealthFailure(host);
          }
        });
  }

Health Checker가 매핑되고 나면 Cluster Manager에서는 Health Checker가 정상적으로 매핑되어있는지를 확인합니다. 그리고 인스턴스가 존재할 경우에는 Health Checker에서 비정상 Health 대상으로 판단한 host에 대해서 ejection 수행을 위한 Callback을 등록합니다.

이때 postThreadLocalHealthFailure는 TLS를 통해서 Health가 실패했음을 전달하며, 이를 수신받은 Cluster Manager에서는 해당 host에 연결된 Connection Pool을 해제하는 작업을 수행합니다.

수행 과정을 살펴보면 위 그림과 같습니다.

1. Health Checker에서 주기적으로 Health Check를 수행하다가 이상이 발생하면, 내부 종료 작업을 먼저 거친 뒤에 등록된 Callback을 통해 외부로 전파합니다.

2. Cluster Manager에서는 기존에 등록한 Callback 함수를 수행합니다. 이때 내부적으로 ThreadLocalClusterManagerImpl을 참조하여 해당 Host 이상 여부를 전체로 전파합니다.

3. Dispatcher를 통해 해당 내역을 전달받은 Cluster Manager에서는 Connection을 해제하기 위하여 Connection Pool에서 해당 host 내부에 존재하는 Connection들을 순차적으로 종료하고 해당 Pool 또한 Close 시킵니다.

해당 과정이 정상적으로 완료되면, Health Check에 따른 연결된 Client 및 host 또한 정상적으로 종료되는 것을 이해할 수 있습니다. 그렇다면 Health Check는 어떻게 이루어질까요? Health Check Factory로부터 만들어진 ProdHttpHealthCheckerImpl 인스턴스의 구조와 수행 과정을 살펴보면서 조금 더 자세하게 알아보겠습니다.

1. ProdHttpHealthCheckerImpl 생성자 내부에서 Cluster 데이터변경이 발생했을 때 처리를 위한 Callback을 등록합니다.

2. 해당 Callback은 호출될 때 추가되는 host 정보와 삭제되는 host 정보를 같이 전달받는데, 이를 토대로 추가되는 host 정보를 active_sessions_ 에 Session을 만들어 추가합니다. 반대로 삭제되는 host 정보 또한 active_sessions_ 에서 삭제합니다.

3. 이때 추가되는 Session에는 Health Check를 정기적으로 수행하기 위해서 Dispatcher에 존재하는 libevent로 부터 Timer를 할당받습니다. 이때 생성되는 timer는 총 2개로 Health Check를 주기적으로 수행하기 위한 interval_timer_와 timeout을 판별하기 위한 timeout_timer_ 를 생성합니다.

여기서 Health Check는 Session 내에 생성되는 Timer에 의해 이루어지므로 Session 생성 과정을 보다 자세하게 살펴보겠습니다.

onInterval은 HealthCheck를 위해 주기적으로 호출되는 메소드로써, 아래와 같은 4가지 단계를 거칩니다.

1. client_가 존재하는지를 살펴보고 client_가 존재하지 않는다면 최초 실행임을 의미하므로 Connection을 생성합니다. 이때 생성된 Connection은 CodecClient를 통해 Wrapping 되는데, CodecClient는 HTTP Codec 타입에 따라서 생성되는 ClientConnectionImpl 인스턴스 타입입니다.

2. Stream을 생성합니다.

3. Health Check 관련 Header 설정을 진행합니다. 이때 method 및 path 등은 Health Check 설정으로 입력된 값을 따릅니다.

4. Upstream 설정 및 Health Check 처리를 위한 encoding 처리를 담당합니다.

위 과정이 마무리되면, 주기에 맞추어 Health Check 요청을 HTTP로 전달할 것입니다. 그렇다면 HTTP 요청에 대한 응답은 어떻게 처리될까요?

HttpActiveHealthCheckSession의 구조를 보면, 위와 같이 여러 Class가 상속되어있음을 확인할 수 있습니다. 그 중 요청 응답 처리는 ResponseDecoder 내부 정의된 I/F에 의해서 호출됩니다. 참고로 해당 과정에서 호출되는 메소드는 decodeHeaders와 decodeData 입니다. 따라서 HttpActiveHealthCheckSession 내부에 정의된 하기 2개의 메소드가 호출됩니다.

health_checker_impl.cc

void HttpHealthCheckerImpl::HttpActiveHealthCheckSession::decodeHeaders(
    Http::ResponseHeaderMapPtr&& headers, bool end_stream) {
  ASSERT(!response_headers_);
  response_headers_ = std::move(headers);
  if (end_stream) {
    onResponseComplete();
  }
}

void HttpHealthCheckerImpl::HttpActiveHealthCheckSession::decodeData(Buffer::Instance& data,
                                                                     bool end_stream) {
  if (parent_.response_buffer_size_ != 0) {
    if (!parent_.receive_bytes_.empty() &&
        response_body_->length() < parent_.response_buffer_size_) {
      response_body_->move(data, parent_.response_buffer_size_ - response_body_->length());
    }
  } else {
    if (!parent_.receive_bytes_.empty()) {
      response_body_->move(data, data.length());
    }
  }

  if (end_stream) {
    onResponseComplete();
  }
}

위 메소드에서 살펴볼 것은 data가 전달이 완료되지 않았을 경우에는 response_body 데이터를 지속 수신받는 것을 알 수 있고 stream이 종료되었을 경우에는 onResponseComplete() 메소드가 호출됨을 알 수 있습니다. 즉 Health Check를 결정하는 요인은 onResponseComplete() 메소드 내부에서 이루어짐을 짐작할 수 있습니다.

health_checker_impl.cc

void HttpHealthCheckerImpl::HttpActiveHealthCheckSession::onResponseComplete() {
  request_in_flight_ = false;

  switch (healthCheckResult()) {
  case HealthCheckResult::Succeeded:
    handleSuccess(false);
    break;
  case HealthCheckResult::Degraded:
    handleSuccess(true);
    break;
  case HealthCheckResult::Failed:
    handleFailure(envoy::data::core::v3::ACTIVE, /*retriable=*/false);
    break;
  case HealthCheckResult::Retriable:
    handleFailure(envoy::data::core::v3::ACTIVE, /*retriable=*/true);
    break;
  }

  if (shouldClose()) {
    client_->close();
  }

  response_headers_.reset();
  response_body_->drain(response_body_->length());
}

onResponseComplete() 메소드 내부를 살펴보면, healthCheck에 대한 결과를 기점으로 Switch로 분기하여 각기 다른 결과를 호출하는 것을 볼 수 있습니다. 만약 Failure가 발생한다면, 해당 timer를 disabled 시키고 종료처리할 것이며, shouldClose() 호출로 인해 client 연결 또한 종료됩니다.

만약 정상적으로 처리되었다면, 지속적으로 Health Check를 주기적으로 반복하여 정상여부 확인을 반복합니다.

8. Outlier Detection 동작 원리

지금까지 Health Checker의 생성 및 동작과정에 대해서 살펴봤다면, 이번에는 Outlier Detector가 생성되는 과정과 동작 방법에 대해 살펴보겠습니다.

Outlier Detector는 ClusterData 생성 당시에 DetectorImplFactory에 의해서 생성됩니다. 이때 생성되는 Outlier Detector의 인스턴스는 DetectorImpl이며 해당 인스턴스가 ClusterData의 OutlierDetector에 바인딩되어 동작합니다.

해당 내용을 코드를 통해서 살펴보겠습니다.

outlier_detection_impl.cc

DetectorSharedPtr DetectorImplFactory::createForCluster(
    Cluster& cluster, const envoy::config::cluster::v3::Cluster& cluster_config,
    Event::Dispatcher& dispatcher, Runtime::Loader& runtime, EventLoggerSharedPtr event_logger,
    Random::RandomGenerator& random) {
  if (cluster_config.has_outlier_detection()) {

    return DetectorImpl::create(cluster, cluster_config.outlier_detection(), dispatcher, runtime,
                                dispatcher.timeSource(), std::move(event_logger), random);
  } else {
    return nullptr;
  }
}

다만 위 코드와 같이 모든 ClusterData에서 OutlierDetector를 생성하는 것은 아니며, Static 혹은 Dynamic Resource 내에 outlier_detection 설정이 활성화되어있는 경우에만 생성됩니다. 만약 해당 설정이 비활성화 되어있다면, OutlierDetector는 nullptr이 매핑됩니다.

cluster_manager_impl.cc

  if (new_cluster->outlierDetector() != nullptr) {
    new_cluster->outlierDetector()->addChangedStateCb([this](HostSharedPtr host) {
      if (host->healthFlagGet(Host::HealthFlag::FAILED_OUTLIER_CHECK)) {
        ENVOY_LOG_EVENT(debug, "outlier_detection_ejection",
                        "host {} in cluster {} was ejected by the outlier detector",
                        host->address()->asStringView(), host->cluster().name());
        postThreadLocalHealthFailure(host);
      }
    });
  }

OutlierDetector가 매핑되고 나면 Cluster Manager에서는 Outlier Detector가 정상적으로 매핑되어있는지를 확인합니다. 그리고 인스턴스가 존재할 경우에는 Outlier Detector에서 Ejection 대상으로 판단한 host에 대해서 ejection 수행을 위한 Callback을 등록합니다.

이때 postThreadLocalHealthFailure는 TLS를 통해서 Health가 실패했음을 전달하며, 이를 수신받은 Cluster Manager에서는 해당 host에 연결된 Connection Pool을 해제하는 작업을 수행합니다. 해당 작업은 Health Check를 수행하면서 실패했을 때 Connection 해제하는 과정과 완벽하게 동일합니다.

지금까지 Outlier Detector 설정 관련해서 살펴봤습니다. 이번에는 실제 Outlier Detector가 수행하는 기능에 대해서 조금 더 자세하게 살펴보기 위해 Outlier로 등록되는 DetectorImpl 구조 및 동작 원리에 대해서 살펴보겠습니다.

이를 위해 DetectorImpl을 생성 과정에 대해서 상세하게 짚어보겠습니다.

1. DetectorImpl 내부에서도 정기적으로 Cluster 내부에 존재하는 host들의 상태를 살펴보고 Outlier Detection을 지정한 임계치를 넘어가는 host를 점검하기 위해 Dispatcher로 부터 Timer를 할당받아 interval_timer_에 지정하는 작업을 합니다.

2. 그 다음은 외부에서 Cluster 내부 host가 추가되거나 삭제되는 등의 작업이 발생했을 때 Outlier Detector에서도 이를 감지하고 설정을 변경해야되기 때문에 ClusterEntry 내부에 존재하는 PriortySet에 Callback을 추가합니다. 해당 Callback 등록을 통해 실질적으로 Cluster 내부 host 변경이 발생했을 경우 이를 Detector가 통지받아 후속 작업을 수행할 수 있습니다. Callback을 전달받으면, 내부에서는 hosts를 관리하는 host_monitors_ Map 자료구조에 해당 hosts의 변경사항을 기록합니다. 이때 host 별로 DetectorHostMonitorImpl 인스턴스를 생성하여 Outlier Detection을 위한 기본 속성을 저장하는데, 이는 잠시 후 다시 살펴보겠습니다.

3. DetectorImpl 생성이 완료되면, ClusterData OutlierDetector에 매핑합니다.

4. ClusterData를 active_clusters_에 추가합니다.

5. ClusterManager에서 해당 OutlierDetector에게 Callback을 등록합니다. 이는 Outlier Detection 판정이 된 host에 대해서 Client 연결 종료 등의 후속작업을 처리하기 위함입니다.

위와 같은 과정을 거치고나면, Outlier Detector는 본격적으로 본인의 역할을 수행할 수 있습니다. 이번에는 초기화가 완료된 이후 후속 작업 진행 절차에 대해서 살펴보겠습니다.

outlier_detection_impl.cc

void DetectorImpl::armIntervalTimer() {
  interval_timer_->enableTimer(std::chrono::milliseconds(
      runtime_.snapshot().getInteger(IntervalMsRuntime, config_.intervalMs())));
}

먼저 초기화 작업이 끝나고나서 가장 먼저 수행하는 작업은 timer를 활성화 시키는 것입니다. 이는 위 메소드를 호출하여 실행되며, interval_timer_의 수행 주기는 위와 같이 config에 지정된 값을 활용하는 것을 볼 수 있습니다. 그렇다면, interval_timer_를 활성화 시켰을 때 어떤 작업을 수행할까요?

outlier_detection_impl.cc

DetectorImpl::DetectorImpl(const Cluster& cluster,
                           const envoy::config::cluster::v3::OutlierDetection& config,
                           Event::Dispatcher& dispatcher, Runtime::Loader& runtime,
                           TimeSource& time_source, EventLoggerSharedPtr event_logger,
                           Random::RandomGenerator& random)
    : config_(config), dispatcher_(dispatcher), runtime_(runtime), time_source_(time_source),
      stats_(generateStats(cluster.info()->statsScope())),
      interval_timer_(dispatcher.createTimer([this]() -> void { onIntervalTimer(); })),
      event_logger_(event_logger), random_generator_(random) {
  // Insert success rate initial numbers for each type of SR detector
  external_origin_sr_num_ = {-1, -1};
  local_origin_sr_num_ = {-1, -1};
}

이는 위와 같이 해당 DetectorImpl의 생성자 코드를 살펴보면 힌트를 얻을 수 있습니다. 내용을 살펴보면 dispatcher로부터 timer를 생성받고나서 해당 timer가 호출해야되는 callback이 지정된 것을 확인할 수 있습니다. 이는 위와 같이 onIntervalTimer() 메소드가 지정되어있습니다. 따라서 주기적으로 onIntervalTimer() 메소드가 호출됨으로써 Outlier Detection 작업을 수행함을 알 수 있습니다.

outlier_detection_impl.cc

void DetectorImpl::onIntervalTimer() {
  MonotonicTime now = time_source_.monotonicTime();

  for (auto host : host_monitors_) {
    checkHostForUneject(host.first, host.second, now);

    // Need to update the writer bucket to keep the data valid.
    host.second->updateCurrentSuccessRateBucket();
    // Refresh host success rate stat for the /clusters endpoint. If there is a new valid value, it
    // will get updated in processSuccessRateEjections().
    host.second->successRate(DetectorHostMonitor::SuccessRateMonitorType::LocalOrigin, -1);
    host.second->successRate(DetectorHostMonitor::SuccessRateMonitorType::ExternalOrigin, -1);
  }

  processSuccessRateEjections(DetectorHostMonitor::SuccessRateMonitorType::ExternalOrigin);
  processSuccessRateEjections(DetectorHostMonitor::SuccessRateMonitorType::LocalOrigin);

  armIntervalTimer();
}

그렇다면, 해당 메소드는 어떻게 구현되어있을까요?

위 코드와 같이 host_monitors_에 매핑된 전체 host들에 대해서 순회하면서 ejection 여부를 판단합니다. 만약 ejection이 결정되었다면, 해당 host_monitors_에 저장된 Monitor 정보를 초기화하고 ejection을 수행합니다. 또한 외부로부터 등록된 callback을 호출시켜, 후속 작업을 진행할 수 있도록 합니다.

참고로 host_monitors_에 매핑된 인스턴스는 DetectorHostMonitorImpl 인스턴스이며, 해당 인스턴스 내부에는 Outlier Detection을 판별하기 위한 여러가지 내부 속성 프로퍼티 값들이 존재합니다. 해당 프로퍼티 값은 Client가 Cluster Manager로부터 Connection Pool을 받아 Upstream host에 Http 요청을 완료한 이후에 전달받은 응답값을 토대로 Router가 갱신을 수행합니다.

따라서 Outlier Detector 내부에서 onIntervalTimer()가 수행될 때 해당 Monitor 인스턴스 내부 속성 값을 기준으로 ejection 여부를 판별할 수 있습니다.

outlier_detection_impl.cc

void DetectorImpl::armIntervalTimer() {
  interval_timer_->enableTimer(std::chrono::milliseconds(
      runtime_.snapshot().getInteger(IntervalMsRuntime, config_.intervalMs())));
}

모든 host_monitors_ 순회가 모두 끝나고 나면 다시 timer를 활성화 시켜 다음 outlier detection 처리를 반복 수행함으로써 지속적인 Outlier Detection 확인이 가능합니다.

9. 마치며

이번 포스팅에서는 Cluster Manager의 기능에 대해 일부 살펴봤습니다. Cluster Manager의 가장 중요한 것은 Cluster 관리입니다. 다만 그 외에도 ads 관리 및 subscription factory 등을 담당하는 것을 살펴봤습니다.

다음 포스팅에서는 Cluster에 지정되는 Load Balancer 종류에 대해 개념적으로 살펴보도록 하겠습니다.

2. [envoy-internals] 쓰레딩 모델과 데이터 공유

cla9 — Wed, 17 May 2023 14:09:32 +0900

1. 서론

이전 포스팅에서는 envoy를 이해하는데 아주 기초적인 컴포넌트 종류에 대한 설명을 진행했습니다. 이번 포스팅에서는 envoy 내부 여러 쓰레드가 존재하는데, 쓰레드간에 데이터는 어떻게 이루어지는지 그리고 쓰레딩 모델은 어떻게 구성되어있는지에 대해서 살펴보겠습니다. 본격적으로 진행하기 앞서 envoy는 멀티 쓰레딩 모델이지만 내부적으로 Lock을 통해 데이터 동기화를 수행하지 않습니다. 어떻게 Lock 없이 데이터 동기화가 가능할까요? envoy 쓰레딩 모델을 학습함으로써 궁금증을 해소해보는 시간을 가져보겠습니다.

2. Threading Model

Envoy 내부에는 전체를 관장하는 Main 쓰레드와 Network 요청과 라우팅을 처리하기 위한 여러 Worker 쓰레드가 존재합니다. 또한 그 외에도 파일 동기화를 위해 별도 File Flush 쓰레드가 별도로 존재합니다.

정리하자면 envoy 내부에는 Main, Worker, File Flush 쓰레드 총 3가지로 구성되었다고 볼 수 있습니다.

여기서 Main 쓰레드는 envoy 내부의 xDS 정보를 관리하고, Admin Server, Health Check 등 Envoy 프로세스가 수행하는데 있어 중추적인 데이터를 관리하고 부가적인 Admin 기능을 제공합니다. 따라서 Envoy를 기동하는데 있어 주요 Metadata 정보는 Main 쓰레드에서 생성되며, 필요 시 다른 쓰레드로 해당 정보를 공유합니다.

그렇다면 envoy 내부에서 Main 쓰레드와 다수로 생성되는 Worker 쓰레드간의 데이터 공유가 필요할 경우에는 어떻게 해야할까요?

첫 번째로 생각해볼 수 있는 방법은 쓰레드간 공유 Data를 생성한 다음에 Main 쓰레드에서 데이터 변경이 필요한 경우 Worker 쓰레드가 해당 공유 Data 접근이 모두 끝나는 시점에 Exclusive Lock을 걸어 Worker 쓰레드의 접근을 일시적으로 차단한 다음 데이터를 변경하여 쓰레드 안정성을 확보하는 방법입니다. 하지만 위와 같은 방식은 동시성이 떨어지는 단점이 존재합니다.

두 번째 방법은 모든 쓰레드에 걸쳐 동일한 데이터를 가지고 있는 상태에서 Data 변경이 발생하면, Main 쓰레드에서 데이터를 변경한 다음 모든 Worker 쓰레드에 수정된 Data를 전달하는 것입니다. 이 경우에는 특정 Worker 쓰레드가 바라보고 있는 원본 Data에 대해 Main 쓰레드에서 수정을 가해도 Worker 쓰레드가 바라보는 원본 Data는 해당 시점에 변경되지 않기 때문에 쓰레드 안정성을 확보할 수 있습니다.

위와 같이 설계된 디자인에서는 쓰레드 외부간에는 데이터가 공유되지 않지만, 내부에서는 해당 데이터를 전역적으로 공유해서 사용할 수 있습니다. 이러한 기법을 Thread Local이라고 부릅니다.

다만 위 예시에서는 1개의 데이터에 대한 동기화 과정을 표현했는데, envoy 내부에는 Main과 Worker 쓰레드 간의 xDS 업데이트를 위해 사용되는 데이터 항목이 많습니다. 따라서 실제로는 위 그림과 같이 하나의 데이터 인스턴스가 아니라 여러개의 Vector 자료 구조로 개별 쓰레드 별로 관리되어야 할 것입니다.

위 그림과 같이 데이터를 관리하면, Lock 없이 쓰레드 안정성을 다소 확보하는 것을 확인할 수 있었습니다. 그렇다면 여기에는 비효율이 없을까요?

가만 생각해보면, 개별 쓰레드 별로 동일한 데이터를 모두 가지고 있기 때문에 쓰레드 안정성은 확보할 수 있으나 똑같은 데이터가 모든 쓰레드에서 독립적으로 존재하기 때문에 메모리 낭비가 커지는 단점이 존재합니다.

따라서 envoy에서는 이를 해결 하기 위해서 Shared Pointer와 자체 TLS(Thread Local Storage)를 구축하였습니다. 이와 관련해는 조금 뒤에 더 자세히 다루어보겠습니다.

3. Distpatcher

Envoy의 TLS(Thread Local Storage)를 살펴보기 위해서는 내부의 중추적인 역할을 수행하는 Dispatcher에 대해서 알아야합니다. 따라서 TLS를 다루기 이전에 Dispatcher에 대해서 알아보고 넘어가겠습니다.

이전에 Threading Model을 통해서 메인 쓰레드와 Worker 쓰레드 사이에 데이터 공유가 이루어졌음을 확인했습니다. 그렇다면 Worker 쓰레드 입장에서는 메인 쓰레드가 보낸 데이터를 어떻게 확인하고 후속 작업을 처리할까요?

envoy에서는 Dispatcher가 중간 매개체 역할을 해줍니다. 여기서 Dispatcher는 Main 쓰레드에서 보낸 데이터를 수신받으면, 이를 감지하고 Worker 쓰레드에게 통지하여 후속 작업이 진행될 수 있도록 가교 역할을 수행합니다.

해당 과정을 조금 더 자세히 살펴보면 위 그림과 같습니다.

envoy에서 Main 쓰레드를 포함하여 모든 쓰레드에는 Dispatcher가 존재합니다. 해당 Dispatcher는 자체적인 event loop를 가지고 있어서 별도의 life cycle이 존재합니다.

이 경우 가령 위 그림과 같이 Main 쓰레드에 Event가 발행할 경우 Main 쓰레드는 개별 Worker 쓰레드에 존재하는 Dispatcher에게 Event의 Callback 내용을 전달합니다. Worker 쓰레드에는 전달된 Event를 내부 Buffer에 저장하며, 저장된 Buffer에서 하나씩 Event를 추출하여 작업을 수행합니다.

그렇다면 Dispatcher의 내부는 어떻게 구성되어있을까요?

envoy Dispatcher 내부에는 자체적인 event loop가 있다고 했는데, 해당 기능은 자체 구현하지 않고 C언어의 라이브러리인 libevent를 사용합니다. 다만 libevent가 C언어로 구성되어있기 때문에 메모리 관리를 위해 libevent에서 제공하는 자료구조를 unique_ptr 스마트 포인터로 감싸서 자동으로 관리할 수 있도록 Wrapping 하였습니다. 따라서 Dispatcher의 핵심은 libevent라고 볼 수 있습니다.

libevent 라이브러리는 다양한 기능을 제공하는데, 핵심 기능은 event가 발생되었을 때 이를 감지하고 알림을 전달해주는 역할을 수행합니다. libevent 공식 홈페이지를 보면 제공하는 기능에 대해서 보다 상세하게 소개되어있으며, 이에 대해서는 아래 공식 홈페이지를 참조하시기 바랍니다.

https://libevent.org/

libevent

The libevent API provides a mechanism to execute a callback function when a specific event occurs on a file descriptor or after a timeout has been reached. Furthermore, libevent also support callbacks due to signals or regular timeouts. libevent is meant t

libevent.org

지금까지 Dispatcher를 통한 Event 전달 과정과 해당 기능을 수행하는 libevent에 대해서 알아봤습니다. 이번에는 Dispatcher에서 Event를 전달하는 부분을 코드를 살펴보면서, 조금 더 수행 과정에 대해서 들여다보겠습니다.

먼저 쓰레드간에 데이터 공유 시, 쓰레드 별로 작업 부하가 다를 수 있기 때문에 전달된 Event가 즉시 처리될 수 없습니다. 따라서 Dispatcher 내부에는 Buffer를 위해 위와 같이 post_callbacks_ 라는 자료 구조에 Event Callback을 저장합니다.

위 코드를 통해서 방금 전 설명한 내용처럼 Dispatcher의 post를 통해서 Callback Event가 전달되면, 바로 처리하지 않고 내부에 존재하는 post_callbacks_ 자료구조에 해당 callback 함수를 저장하는 것을 확인할 수 있습니다.

그렇다면, 해당 callback은 언제 실행될까요?

위 코드는 Dispatcher의 생성자 부분입니다. 여기서 Dispatcher를 구성하기 위해 다양한 속성들이 Member Initializer에 의해서 매핑되고 있지만, Event 전달 관점에서 주목할 부분은 빨간색으로 밑줄 친 영역입니다.

Dispatcher 내부에는 Scheduler가 존재하는데, post callback을 처리하기 위해서 별도 Scheduler를 통해 수행할 수 있습니다. 이때 위와 같이 runPostCallbacks()라는 메소드를 호출하는 것을 확인할 수 있습니다.

해당 메소드의 역할을 살펴보면, post_callbacks_에 저장된 내용이 하나도 없을 때까지 Event 내용을 하나씩 꺼내서 실행시키는 역할을 수행합니다. 이후 모든 작업이 완료되면, 향후 Post 메소드를 통해 Event가 유입될 때까지 작업을 진행하지 않습니다.

지금까지 Dispatcher 내부 동작 과정에 대해서 살펴봤습니다. 이번에는 Dispatcher가 취급하는 Event 종류에 대해서 알아보겠습니다.

Dispatcher를 통해 전달되는 Event는 모두 위 클래스를 상속받습니다. 해당 클래스 내용을 잠시 살펴보면, event 타입의 프로퍼티를 기본적으로 가지고 있으며, 해당 클래스가 소멸할 때 event를 release 하도록 되어있습니다.

해당 event를 상속하는 Event 타입은 위 그림과 같이 크게 3가지로 나뉩니다.

첫 번째는 Signal Event입니다. 이는 생성 즉시 Event를 발행할 때 사용되는 Event 타입입니다.

두 번째는 Timer Event입니다. 해당 Event는 내부 속성에 Timer가 존재하여, 지정된 시간이 지난 이후 Event를 발행할 수 있으며, Timer를 활성화하거나 비 활성화 등을 통해서 Timer를 조정할 수 있습니다.

세 번째는 File Event입니다. 해당 Event 타입은 File에 읽기 혹은 쓰기등의 내부 Event가 발생했을 때, 해당 Event를 전달하는 것을 목적으로 합니다. 또한 Linux의 경우 Socket은 File로 취급됩니다. 따라서 Socket을 쓰거나 읽을 때, 해당 Event를 감지하여 전달할 수 있습니다.

envoy에서는 위 세가지 Event 타입을 폭넓게 활용하여 여러 쓰레드간에 데이터 공유에 활용합니다.

4. TLS(Thread Local Storage)

Threading Model을 설명하면서, 쓰레드마다 동일한 데이터를 보관할 경우 메모리 낭비로 인해 비효율이 발생함을 설명하고 이를 위해서 envoy에서는 TLS를 사용한다고 언급했습니다. envoy의 TLS에 대해서 알아보면서, envoy가 어떻게 메모리 낭비를 줄이기 위해 최적화 기법을 사용했는지를 살펴보겠습니다.

TLS는 말 그대로 Thread Local 객체들을 저장하는 저장소이므로 가장 먼저 해야할 일은 TLS에 저장되는 타입에 대한 정의가 필요합니다.

그에 따라 위와 같이 TLS에 저장하려는 데이터 타입에는 envoy에서 정의한 ThreadLocalObject 타입을 필수적으로 상속 받아야합니다. 그렇다면 ThradLocalObject 클래스는 어떻게 정의되어있을까요?

ThreadLocalObject 클래스를 살펴보면, 그 안에 어떠한 속성도 정의되어있지 않으며 asType 메소드가 존재하여 지정된 타입으로 캐스팅하여 반환하는 기능만을 제공하는 것을 확인할 수 있습니다.

또한 위 코드에서 주목할 부분은 ThreadLocalObject를 Shared Pointer로 감싼 타입을 새로 정의했다는 것입니다.

위 코드는 각 쓰레드별로 저장되는 TLS 구조의 모습입니다. 해당 구조체에는 각 쓰레드별로 구동되는 Dispatcher 정보를 저장할 수 있는 속성과, 이전 코드에서 확인한 ThreadLocalObject를 Shared Pointer로 감싼 타입을 Vector Container로 가지고 있는 것을 확인할 수 있습니다.

그렇다면 위와 같이 Shared Pointer 형태로 데이터를 관리하면 어떤 이점이 있을까요?

첫 번째로 얻을 수 있는 이점은 데이터 자체를 저장하는 것이 아니라 Pointer를 지니고 있으므로 데이터 중복을 줄일 수 있으며, 메모리 주소 값을 저장하므로 비용이 많이 절감됩니다.

두 번째는 Shared Pointer로 데이터를 가르키는 것이기 때문에 메모리 관리를 자동으로 수행할 수 있습니다.

가령 위와 같이 Shared Pointer로 가르키는 오브젝트에 대한 링크가 모두 해제되었을 경우 참조 카운트가 0이므로 자동으로 메모리를 해제할 수 있습니다.

그렇다면 위와 같이 Shared Pointer를 사용하게 되면 모든 문제가 해결될까요? 정답은 그렇지 않습니다. 위와 같이 구성하게 되면 결국 처음에 야기되었던 문제점이 다시 발생합니다. 그 이유는 결국 공유 데이터를 가르키는 것이기 때문에 결론적으로는 쓰레드 안정성에 대한 이슈가 다시 불거지기 때문입니다.

따라서 envoy에서는 기존에 살펴본 Dispatcher와 각 쓰레드별로 Shared Pointer를 지정하도록 구성함으로써 이러한 문제를 해결하고자 했습니다. 이와 관련해서는 다음 시나리오를 통해서 확인해보겠습니다.

위와 같이 두 개의 쓰레드에서 서로 동일한 Thread Local Object를 가르키고 있다고 가정해봅시다. 이러한 상황에서 Thread Local Object의 업데이트가 필요할 경우 다음과 같은 과정을 수행합니다.

1. 변경을 수행해야하는 쓰레드에서 Thread Local Object를 새로 만들고 기존 Thread Local Object를 가르키던 포인터를 신규 Object를 가르키도록 변경합니다.

2. 변경을 수행한 쓰레드에서 다른 쓰레드에게 변경 내용을 전파합니다. 따라서 해당 쓰레드의 Dispatcher에게 post 요청을 통해 변경 Event를 전달합니다.

3. Dispatcher는 전달된 Event 내역을 자신의 buffer에 저장하였다가 쓰레드에게 데이터 변경 내용을 전달합니다.

4. Event를 전달받은 쓰레드에서는 Event를 통해 전달된 Callback을 수행하면서 자신이 가르키고 있는 Thread Local Object를 신규로 변경합니다. 이 과정을 통해 모든 쓰레드에서 새로운 Thread Local Object로 변경이 완료되면, 기존의 Thread Local Object의 참조 카운트는 0이 되므로 삭제할 수 있습니다.

위와 같이 4가지 과정을 수행하면, 쓰레드 안정성을 확보할 수 있습니다. 그 이유는 첫 번째 단계를 살펴보면, 두 개의 쓰레드가 공유 데이터를 바라보고 있다가 특정 쓰레드에서 데이터 변경이 수행되었을 경우 다른 쓰레드에 영향을 미치지 않기 때문입니다. 이후 다른 쓰레드의 event loop 수행 과정에서 변경 내용을 통지받으면 그제서야 변경된 데이터를 바라볼 수 있도록 적용됩니다.

이는 데이터 변경이 발생되었을 때 동일 시점에 모든 쓰레드에서 공유 데이터를 바라볼 수 있는 Strict Consistency는 포기하더라도 Eventually Consistency를 적용함으로써 쓰레드 안정성, 메모리 효율성과 성능을 얻는 것이 이점이 크기 때문입니다.

지금까지 TLS에 대해서 기본적인 동작 과정에 대해서 개략적으로 살펴봤습니다. 이번에는 조금 더 구체적으로 Thread Local Data를 활용해서 Envoy내 쓰레드 끼리 어떻게 동기화를 수행하는지에 대해서 살펴보겠습니다.

4-1 Envoy TLS 동작 과정

Envoy 내부에는 TLS를 관장하기 위해 InstanceImpl 인스턴스가 존재합니다. 이를 위해 해당 클래스 내부에는 TLS와 쓰레드간 상호작용을 위한 여러 메소드와 속성이 포함되어있습니다. 코드를 토대로 해당 클래스에 대해서 자세하게 살펴보겠습니다.

위 코드에서 먼저 눈에 띄는 것은 TLS를 위한 자료구조인 ThreadLocalData 구조체가 해당 클래스내에 포함된 것을 확인할 수 있습니다. 또한 ThreadLocalData는 C++의 thread_local 키워드가 붙어있어 쓰레드내 전역적으로 공유되는 데이터임을 알 수 있습니다.

그 다음 눈 여겨 볼 점은 dispatcher를 저장하는 점과 registered_threads_ 속성을 통해 해당 쓰레드와 연결되는 쓰레드들을 관리한다는 점입니다.

void InstanceImpl::registerThread(Event::Dispatcher& dispatcher, bool main_thread) {
  ASSERT_IS_MAIN_OR_TEST_THREAD();
  ASSERT(!shutdown_);

  if (main_thread) {
    main_thread_dispatcher_ = &dispatcher;
    thread_local_data_.dispatcher_ = &dispatcher;
  } else {
    ASSERT(!containsReference(registered_threads_, dispatcher));
    registered_threads_.push_back(dispatcher);
    dispatcher.post([&dispatcher] { thread_local_data_.dispatcher_ = &dispatcher; });
  }
}

실제 Thread 등록은 Worker 쓰레드가 생성되는 시점에 registerThread 메소드를 호출하여 InstanceImpl에 등록됩니다. 이때 호출되는 코드를 살펴보면, 등록되는 Thread가 Main 쓰레드인 경우와 그렇지 않은 경우가 분리되어서 저장되는 것을 확인할 수 있습니다.

그밖에 InstanceImpl 코드를 더 살펴보면, 그 전에는 보지 못했던 Slot 구조체와 이를 저장하는 slots_ Vector Container가 존재하는 것을 알 수 있습니다. Slot은 무엇이고 어떤 역할을 수행할까요?

InstainceImpl은 ThreadLocalData를 thread_local 속성으로 가지고 있지만, 사용자가 ThreadLocalData에 데이터를 할당하고자 할때 직접 할당하는 것을 방지하도록 설계되어있습니다.

대신 Client는 ThreadLocalData에 대한 추가,수정,삭제 작업을 희망할 경우 InstanceImpl로 부터 Slot을 할당 받아야합니다. 여기서 Slot은 ThreadLocalData에 작업 수행 및 ThreadLocalData를 공유하는 모든 쓰레드에게 명령을 요청하기 위한 일종의 interface라고 볼 수 있습니다.

SlotPtr InstanceImpl::allocateSlot() {
  ASSERT_IS_MAIN_OR_TEST_THREAD();
  ASSERT(!shutdown_);

  if (free_slot_indexes_.empty()) {
    SlotPtr slot = std::make_unique<SlotImpl>(*this, slots_.size());
    slots_.push_back(slot.get());
    return slot;
  }
  const uint32_t idx = free_slot_indexes_.front();
  free_slot_indexes_.pop_front();
  ASSERT(idx < slots_.size());
  SlotPtr slot = std::make_unique<SlotImpl>(*this, idx);
  slots_[idx] = slot.get();
  return slot;
}

Slot을 할당받기 위해서는 Client는 InstanceImpl에게 allocateSlot() 메소드를 호출할 수 있습니다. 이때 내부적으로는 비어있는 Slot을 관리하는 free_slot_indexes가 존재하는데, free한 Slot이 비었을 경우 Slot을 추가로 생성해서 반환하는 것을 볼 수 있습니다. 반면 비어있는 Slot이 존재한다면, 해당 Slot의 index를 기반으로 Slot을 반환합니다.

위 코드에서 주목할 부부은 Slot을 생성할 때, 두 번째 인자에 비어있는 Slot의 index를 지정한다는 점입니다. 따라서 Client 입장에서 전달받은 Slot에서는 Instance 내부에 존재하는 slots_ list에서 몇 번째 index에 Slot이 생성되었는지 알 수 있습니다.

void InstanceImpl::SlotImpl::set(InitializeCb cb) {
  ASSERT_IS_MAIN_OR_TEST_THREAD();
  ASSERT(!parent_.shutdown_);

  for (Event::Dispatcher& dispatcher : parent_.registered_threads_) {
    // See the header file comments for still_alive_guard_ for why we capture index_.
    dispatcher.post(wrapCallback(
        [index = index_, cb, &dispatcher]() -> void { setThreadLocal(index, cb(dispatcher)); }));
  }

  // Handle main thread.
  setThreadLocal(index_, cb(*parent_.main_thread_dispatcher_));
}

Client는 Slot을 할당 받으면, Thread Local에 저장하기 위한 Callback Event를 등록할 수 있습니다. 이때 위 코드와 같이 set 메소드를 통해 저장할 수 있으며, 코드 내용을 자세히 살펴보면, 등록된 Thread를 모두 순회하면서 dispatcher에게 post 메소드를 호출하여, 각자 쓰레드가 보유한 setThreadLocal을 호출하도록 요구하는 것을 볼 수 있습니다.

해당 과정을 통해서 쓰레드 내의 변경 사항을 다른 쓰레드에 전파하게 됩니다.

void InstanceImpl::setThreadLocal(uint32_t index, ThreadLocalObjectSharedPtr object) {
  if (thread_local_data_.data_.size() <= index) {
    thread_local_data_.data_.resize(index + 1);
  }

  thread_local_data_.data_[index] = object;
}

setThreadLocal 코드는 위와 같습니다. 해당 코드 내용을 보면 ThreadLocalData 구조체 내에있는 data_에 접근하여 Slot에 지정된 index에 해당하는 위치에 Callback을 저장하는 것을 볼 수 있습니다.

Client에서 수행할 수 있는 두 번째 요청은 runOnAllThreads 입니다. InstanceImpl로 부터 전달받은 Slot에는 index 값과 더불어 InstanceImpl에 대한 parent_ 속성에 저장되어있습니다.

void InstanceImpl::SlotImpl::runOnAllThreads(const UpdateCb& cb) {
  parent_.runOnAllThreads(dataCallback(cb));
}

따라서 Client 입장에서 전달받은 Slot에 runOnAllThreads 명령을 요청하면, 내부적으로는 InstanceImpl에게 runOnAllThreads를 실행시키도록 위임합니다.

void InstanceImpl::runOnAllThreads(Event::PostCb cb) {
  ASSERT_IS_MAIN_OR_TEST_THREAD();
  ASSERT(!shutdown_);

  for (Event::Dispatcher& dispatcher : registered_threads_) {
    dispatcher.post(cb);
  }

  // Handle main thread.
  cb();
}

요청을 전달받은 InstanceImpl에서는 이전과 마찬가지로 registered_threads_에 등록된 dispatcher 들을 순회하면서 사용자가 전달한 Callback을 전달하고 Main 쓰레드 내에서 해당 Callback 또한 실행시킴으로써 연관된 모든 쓰레드에서 사용자 요청을 처리하도록 작업을 수행합니다.

지금까지 InstanceImpl을 통해 쓰레드를 등록, Thread Local Object 할당 및 Dispatcher를 활용한 데이터 공유 과정에 대해서 살펴봤습니다. 이번에는 Envoy가 종료될 때 TLS 초기화가 어떻게 이루어지는지 살펴보겠습니다.

void InstanceImpl::shutdownGlobalThreading() {
  ASSERT_IS_MAIN_OR_TEST_THREAD();
  ASSERT(!shutdown_);
  shutdown_ = true;
}

Envoy가 종료될 때, InstanceImpl에 suhtdownGlobalThreading() 메소드를 호출하여 종료를 요청합니다. 다만 해당 메소드의 역할은 InstanceImpl 내부에 존재하는 shutdown_ bool 값을 true로 변경하는 것입니다.

void InstanceImpl::shutdownThread() {
  ASSERT(shutdown_);
  for (auto it = thread_local_data_.data_.rbegin(); it != thread_local_data_.data_.rend(); ++it) {
    it->reset();
  }
  thread_local_data_.data_.clear();
}

이후 개별적인 Worker 쓰레드는 shutdownThread() 메소드를 호출함으로써 쓰레드 별로 종료 과정이 이루어집니다. 이때 위 코드에서 주목할 부분은 ThreadLocalData 내부 데이터를 종료할 때, 뒤에서부터 reset 과정이 진행되는 점입니다.

그 이유는 ThreadLocalData를 구성할 때 가장 먼저 적재되는 데이터는 ClusterManager에서 생성되는 ThreadLocalObject이고 해당 데이터들은 종료될 때까지 수정이 이루어지지 않는 데이터이면서, 여러 Object에서 참조될 수 있는 가장 중요한 데이터일 수 있습니다.

따라서 중요도가 가장 낮은 Object 부터 종료를 시작해서 가장 높은 Object를 나중에 종료시킴으로써 의존성이 강한 Object가 먼저 삭제되어 발생될 수 있는 문제를 예방합니다.

5. 마치며

지금까지 Envoy 쓰레드 모델과, TLS에 대해서 살펴봤습니다. TLS를 이해하기 위해서는 Dispatcher의 기능 중 일부에 이해해야하기 때문에 이 부분에 대해서도 다루어봤습니다.

또한 코드를 살펴보면서 Envoy에서 Lock을 사용하지 않고도 공유 데이터를 사용하기 위해 많은 고민이 반영되었음을 확인할 수 있었습니다.

Envoy의 쓰레딩 모델과 TLS를 이해하는 것은 istio를 이해하는데 있어서도 중요합니다. Envoy 내부에서 xDS API 업데이트가 발생되었을 때 내부적으로 TLS를 통해서 데이터 변경을 전파하고 반영하기 때문입니다. 그러한 측면에서 이번 포스팅 내용은 어렵지만 중요하다고 볼 수 있습니다.

1. [envoy-internals] 아키텍처 Overview

cla9 — Wed, 17 May 2023 11:26:22 +0900

1. 서론

istio를 처음 사용하면, 이전과 달리 설치가 및 설정 방법이 편해져서 사용하기 쉽습니다. 그럼에도 불구하고 istio를 운영하는 것은 여전히 어려운 일입니다. 그 이유는 istio에 문제가 생겼을 때 이를 해결하기 위해서는 istio 내부 아키텍처에 대한 이해가 필수적이기 때문입니다.

istio는 엄밀히 말해서 envoy proxy를 관리하는 컨트롤러라고 볼 수 있습니다. 따라서 istio 뿐만 아니라 envoy proxy의 내부 구조에 대해서도 잘 알고 있어야합니다. 이번 포스팅부터 진행되는 envoy internals 시리즈는 envoy 내부 구조와 흐름에 대해서 살펴보면서, 트러블 슈팅을 위한 인사이트를 갖는 것을 목적으로 하고 있습니다. 다만 모든 내용을 다루지는 않으며, istio를 이해하는데 있어 필수적인 부분에 대해서만 살펴보겠습니다. 이번 포스팅은 envoy 관련 첫번째 포스팅으로 envoy 구조와 내부 컴포넌트 동작 원리에 대해서 알아보도록 하겠습니다.

2. Envoy 컴포넌트

Envoy는 Proxy 프로그램으로 사용자와 Service 중간에서 Proxy 역할을 수행합니다. 이때 Client로부터 전달받는 트래픽은 Downstream, 전달받은 요청을 Service로 전달하는 트래픽을 Upstream이라고 부릅니다. 즉 Envoy를 기준으로 상위 서비스 전달은 Upstream Envoy로 흘러 들어오는 스트림은 Downstream입니다.

그렇다면 Downstream을 통해 전달되는 트래픽이 Envoy의 어떤 과정을 거쳐서 Upstream으로 Service에 전달될까요?

먼저 Envoy의 주요 컴포넌트에 대해서 먼저 알아보겠습니다.

Envoy 내부에서 가장 핵심이 되는 컴포넌트는 위 그림과 같습니다. 도식화된 그림을 살펴보면 여러개 Listener 그리고 요청을 전달하기 위한 Route 과정 그리고 해당 Route 과정을 통해서 Cluster에 전달되고 Cluster는 Load Balancing 정책에 따라서 자신이 보유하고 있는 Endpoint 중 하나를 선정합니다. 결과적으로는 해당 Endpoint에 매칭되는 Service에 트래픽이 전달됩니다.

갑자기 여러가지 컴포넌트가 등장했는데요. 지금부터 하나하나씩 살펴보겠습니다.

2-1 Endpoint

먼저 살펴볼 것은 Endpoint입니다. Endpoint는 위 그림과 같이 Proxy를 통해 연결해야하는 최종 목적지 주소와 Port 번호를 의미합니다. 위와 같이 address는 IP일 수도 있고 혹은 도메인 네임일 수도 있습니다. 그 밖에 health check를 위한 설정 및 Load Balancing을 수행할 때 가중치 와 우선순위 등을 설정할 수 있습니다. 자세한 내용은 Envoy 공식 문서를 통해서 확인하시기 바랍니다.

2-2 Cluster

Service는 가용성 혹은 성능 향상의 목적으로 여러 서버에 동일한 Service를 배포합니다. 따라서 단일 Endpoint를 통해 여러개 Service를 관리할 수 있는 논리적인 집합 단위가 필요합니다.

Envoy Proxy에서는 Cluster 컴포넌트를 통해 Endpoint들을 그룹핑하여 관리할 수 있습니다. 해당 컴포넌트를 통해서 Endpoint 중에서 어디로 트래픽을 보낼지 결정하는 Load Balancing을 결정할 수 있습니다.

  clusters:
  - name: some_service
    connect_timeout: 0.25s
    type: STATIC
    lb_policy: ROUND_ROBIN
    load_assignment:
      cluster_name: some_service
      endpoints:
      - lb_endpoints:
        - endpoint:
            address:
              socket_address:
                address: 127.0.0.1
                port_value: 1234

위 설정은 Envoy proxy 공식 문서의 설정 예시입니다. Cluster 하위에 Endpoint 목록을 지정하도록 되어 있는 것을 확인할 수 있습니다. 달리 말하면 Cluster와 Endpoint 간에는 의존성이 존재함을 확인할 수 있습니다. 위 설정에는 Endpoint 지정외에도 다양한 설정을 지정할 수 있습니다. 가령 Circuit Breaker 설정 HTTP Connection과 DNS refresh와 Resolving 정책 등의 부가적인 옵션을 해당 컴포넌트를 통해서 설정할 수 있습니다. 자세한 옵션 설정은 Envoy 공식 문서를 통해서 확인하시기 바랍니다.

2-3 Listener

Listener는 Envoy Proxy가 어떤 address의 어떤 port로 접속하는 요청에 대해서 Proxy 처리를 수행할 것인지를 설정합니다. 가령 위와같이 지정했다면, 해당 Envoy Proxy가 위치한 서버로 접속하는 80 Port 요청에 대해서 Envoy Proxy가 트래픽을 전달받고 후속 작업을 처리하게됩니다. 즉 Listener는 Envoy Proxy로 흐름을 전달하는 문지기 역할이라고 볼 수 있습니다.

Listener를 통해 트래픽이 전달되었다면, 이를 Cluster에 전달하기 위해서는 여러 내부 과정을 거쳐야합니다. Listener에는 Listener Filters와 Filter Chains(Network Filters)를 지니고 있습니다. 따라서 실제 트래픽이 전달되었을 때 Listener 내부에 위치한 Filter들을 통과하면서 사용자 요청을 분석하고 어떤 Cluster로 전달해야할지 등을 결정합니다. 그렇다면 Listener Filter와 Filter Chains는 무엇이 다를까요?

Listener Filters는 Connection에 대한 Metadata를 조작하거나 추가하는 데 사용되며, 변경된 정보를 토대로 Filter Chains에 존재하는 무수한 Filter 중에서 해당 요청을 처리하는데 적합한 Filter를 선정하는데 사용됩니다. 즉 실제 사용자 요청을 처리하는 것은 FIlter Chains에 존재하는 Filter이지만 해당 Filter를 사용하기 위해서 사전에 보조적인 작업을 담당하는 것이 Listener FIlter라고 볼 수 있습니다.

참고로 Envoy에서 제공하는 Listener Filter 목록은 위와 같으며, 개별 Filter의 역할은 다음과 같습니다.

Filter	역할
HTTP Inspector	Application에서 전달한 Traffic을 분석하여 해당 네트워크 요청이 HTTP인지 확인합니다. 또한 HTTP 요청이 맞다면, HTTP 1.1 요청인지 혹은 HTTP 2 요청인지를 분석합니다. 이를 토대로 추후 네트워크 요청에 적합한 Filter Chain을 찾는데 사용됩니다.
Original Destination	IpTable에 의해서 redirect된 소켓의 원래 목적지 값 주소를 알기 위해 SO_ORIGINAL_DST 값을 읽는 역할을 수행합니다. 해당 값은 Envoy 처리 이후 Connection Local address로 설정하는데 사용됩니다.
Original Source	Client가 Envoy의 주소로 Downstream 연결을 시도하면, Envoy는 Upstream과 통신을 위해서는 Source IP를 Envoy의 주소로 변경이 필요합니다. 따라서 해당 과정을 통해 연결의 목적지 주소를 Source 주소로 복제하는데 사용합니다.
Proxy Protocol	해당 Listener Filter는 HA Proxy Protocol을 지원하기 위한 역할을 수행합니다.
TLS Inspector	HTTP Inspector와 유사하게 해당 요청이 TLS 요청인지를 확인합니다. 이를 토대로 추후 네트워크 요청에 적합한 Filter Chain을 찾는데 사용됩니다.

Listener Filter를 통해서 Connection 요청 Metadata를 조작하거나 어떤 요청인지를 분석하고난 이후에는 Filter Chains(Network Filters)에 위치한 FIlter들을 통과하면서 사용자의 요청에 적합한 Filter를 찾아서 수행합니다.

기본적으로 제공하는 FIlter Chains 목록은 위와 같습니다. 해당 항목들은 L3/L4 Filter 기능을 담당하며, 사용자 요청에 적합한 Filter를 찾아서 처리하고 목적지로 전달하는데 사용합니다. 만약 위 Filters 중 사용자 요청을 처리할 수 없는 경우에는 Envoy에서 제공하는 Default Chain이 사용되며, 만약 Default Chain 설정을 하지 않았다면 해당 Connection은 종료됩니다. 참고로 envoy proxy 기동시 위와 같이 모든 Filter가 등록되는 것은 아니며 순서 또한 다를 수 있습니다. 위 Filter 목록 중 필요한 Filter만 선별적으로 등록 가능합니다. 이에 대해서는 추후 살펴보겠습니다.

개별 FIlter의 기능 설명은 공식 문서를 참고하기 바라며, 여기서는 HTTP connection manager에 대해 중점으로 다루어 보고자 합니다.

2-3-1 HTTP Connection manager

Envoy에서 HTTP를 담당하는 Network Level의 Filter로써 Filter Chain의 가장 마지막에 위치합니다. 해당 Filter의 주요 기능은 raw byte를 HTTP 메시지 convert를 담당하며, 내부적으로 HTTP L7 Filter들이 존재하여 부가적인 작업을 수행합니다. 따라서 HTTP 요청이 전달되었을 때, Listener Filters 이후 Filter Chain을 수행하는 과정에서 HTTP Connection manager가 요청을 처리할 경우 내부적으로 sub filters를 적용하여 부가작업을 수행합니다.

HTTP Connection manager가 담당하는 기능에 대해서 몇 가지 살펴보도록 하겠습니다.

1) HTTP header 조작

- 여러가지 Security 이유로 인해 Envoy를 통해서 특정 header를 삭제하거나 값을 변경할 수 있습니다. 가령 use_remote_address 옵션을 true로 변경했을 경우 connection manager는 실제 전달되는 remote address를 x-forwared-for http header에 사용합니다. 그밖에 다양한 header에 대해서 조작이 가능합니다.

2) Retry 설정

- HTTP 요청에 대해서 내부적으로 연결이 실패했을 때 얼만큼 Retry할 것인지를 설정할 수 있습니다.

3) Redirect

- 요청 서비스에서 Redirect 응답이 왔을 때 Proxy 내부에서 해당 3xx 응답을 기반으로 Redirect를 수행할 수 있습니다.

4) Timeout

- HTTP 요청에 대해서 응답이 지정 시간동안 없을 경우 요청을 취소할 수 있습니다.

위와 같은 기능 외 HTTP Connection manager에는 L7 Filters들이 있어서 해당 Filters를 통해 부가적인 작업을 수행할 수 있다고 말했습니다. 여기에는 다음과 같은 Filter들이 해당됩니다.

각 Filter에 대한 설명은 Envoy 공식 문서를 참고하시기 바라며, 참고로 위 Filter 중에 Router Filter의 경우는 사용자가 지정한 router 규칙에 일치하는 URL로 접근하였을 경우 지정된 Cluster로 Forwarding을 담당하는 Filter입니다.

그렇다면, 지금까지 설명을 바탕으로 HTTP 요청에 대한 Envoy Proxy 내부의 네트워크 흐름을 다시 한번 짚어보겠습니다.

1) Listener에 구성된 address와 port에 상응하는 요청이 들어오면, Listener 내부적으로 Listener Filters로 전달합니다.

2) Listener Filters를 순회하면서 Connection Metadata를 조작하고 이후 Network Filters로 전달합니다.

3) Filter Chains(Network Filters)를 순회하면서 사용자 요청을 처리하는데 적합한 Filter를 찾고 해당 Filter가 요청을 처리합니다.

(※ 위 예제에서는 HTTP 요청이 들어왔음을 가정했으므로 HTTP Connection Manager가 이를 담당합니다.)

4) HTTP Connection Manager 내부에 있는 Sub Filters를 순회합니다.

5) L7 필터 마지막에 위치한 Router Filter는 사용자의 Routing Path 요청과 적합한 Cluster를 찾고 해당 Cluster에게 트래픽을 Forwarding 하는 역할을 수행합니다.

6) Cluster는 내부에 설정된 로드밸런싱 정책등을 고려하여 적합한 Endpoint를 선정하며, 해당 Endpoint에 매칭되는 Service로 트래픽이 전달됩니다.

2-4 Envoy 컴포넌트 등록 방법

지금까지 Envoy 내부에 존재하는 컴포넌트를 기반으로 Envoy 네트워크 흐름에 대해서 살펴봤습니다. 그렇다면 Cluster, Listener, Endpoint 등은 어떻게 등록할 수 있을까요?

Envoy에서는 2가지 방식으로 컴포넌트 정보를 등록하거나 수정할 수 있습니다. 첫 번째 방식은 Static 방식이고 두 번째 방식은 Dynamic 방식입니다.

2-4-1 Static 등록 방식

Static 방식은 말 그대로 Envoy 기동 시점에 사용자가 지정한 Config 파일 정보를 기반으로 내부 컴포넌트를 등록하는 방식입니다. 따라서 Envoy가 이해할 수 있는 형태로 내부 컴포넌트 설정을 기술해야합니다. Envoy에서는 YAML 형태로 이를 지정할 수 있으며, 아래 예제를 통해서 간단히 살펴보겠습니다.

static_resources:
  listeners:
  - name: listener_0
    address:
      socket_address: { address: 127.0.0.1, port_value: 10000 }
    filter_chains:
    - filters:
      - name: envoy.filters.network.http_connection_manager
        typed_config:
          "@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
          stat_prefix: ingress_http
          codec_type: AUTO
          route_config:
            name: local_route
            virtual_hosts:
            - name: local_service
              domains: ["*"]
              routes:
              - match: { prefix: "/" }
                route: { cluster: some_service }
          http_filters:
          - name: envoy.filters.http.router
            typed_config:
              "@type": type.googleapis.com/envoy.extensions.filters.http.router.v3.Router
  clusters:
  - name: some_service
    connect_timeout: 0.25s
    type: STATIC
    lb_policy: ROUND_ROBIN
    load_assignment:
      cluster_name: some_service
      endpoints:
      - lb_endpoints:
        - endpoint:
            address:
              socket_address:
                address: 127.0.0.1
                port_value: 1234

해당 설정은 Envoy 공식 문서에 존재하는 예제입니다. 지금까지 살펴본 Envoy 컴포넌트에 대한 개념을 잘 숙지했다면, 위 예제의 큰 구조를 쉽게 파악할 수 있습니다.

먼저 Listener를 보면 listener_0이라는 이름으로 1개의 Listener가 등록되어있고, 내부에는 filter_chains 항목을 통해 Network Filter인 HTTP Connection Manager를 등록하는 것을 확인할 수 있습니다. 또한 Routes 설정을 통해 /으로 들어오는 모든 prefix에 대해서 some_service라는 Cluster로 전달하도록 지정했음을 확인할 수 있습니다. 이를 토대로 Listener로 들어오는 모든 HTTP 설정에 대해서 some_service Cluster로 트래픽이 전달되도록 Router Filter가 지정될 것임을 알 수 있습니다.

Clusters 항목을 보면, 이전에 Route에서 지정한 some_service 이름으로 등록되어있음을 확인할 수 있고 내부적으로 endpoint를 등록하여 Cluster로 트래픽이 전달되었을 때 내부적으로 어떤 endpoint로 전달할 수 있는지를 알 수 있습니다. 추가적으로 ROUND_ROBIN 정책을 적용하여 트래픽 부하를 고르게 분산하도록 지정되어있음을 확인할 수 있습니다.

2-4-2 Dynamic 등록 방식

Static 등록 방식은 Config 파일에 직접 기술하여 해당 정보를 토대로 envoy proxy를 구성하는 방법입니다. 하지만 Listener, Endpoint와 Cluster 정보가 수시로 바뀌는 상황에서는 Static 등록 방식을 사용하기에 적합하지 않습니다. 그 이유는 변경할 때마다 해당 Config 파일 수정이 필요하며, envoy proxy 또한 reload 해야하기 때문입니다.

따라서 envoy proxy에서는 Static 등록 방식 이외에 Dynamic 방식을 제공하여 envoy proxy 기동 중에도 내부 컴포넌트 설정을 변경할 수 있도록 인터페이스를 제공하였습니다. 이를 xDS API라고 부르며, FIle 동기화, REST 혹은 gRPC 방식이 존재합니다. 참고로 아직 살펴보지는 않았지만 istio에서는 gRPC 통신을 이용하여 envoy proxy의 정보를 동적으로 변경합니다.

그렇다면 xDS는 어떠한 종류가 있으며, 어떤 컴포넌트와 매칭되어 변경을 수행할 수 있을까요? 이에 대해서 간단히 알아보도록 하겠습니다.

이전에 살펴봤던 주요 컴포넌트 Listener, Cluster, Endpoint를 갱신할 수 있는 Discovery Service가 제공됩니다. 따라서 envoy proxy에서 요구하는 spec에 맞게 gRPC 혹은 REST 호출을 보내면 개별 컴포넌트에 해당하는 Discovery Service를 통해서 내부 컴포넌트 설정을 변경할 수 있습니다.

참고로 istio에서는 위와 같이 중앙에 envoy를 관리하는 Management Server가 있으며, Envoy의 xDS를 통해서 중앙에서 Configuration을 등록과 수정등을 자유롭게 할 수 있습니다.

위와 같은 Discovery Service외에도 VHDS, SRDS, LDS, SDS, RTDS, ECDS등 다양한 Discovery Service가 존재하며, 이는 envoy 공식 문서를 통해서 참고하시기 바랍니다.

이번에는 xDS 관련하여 또 하나 살펴볼 주요 내용 중 하나인 ADS(Aggregated xDS)에 대해서 살펴보겠습니다. 먼저 ADS는 무엇이고 왜 사용할까요?

Envoy 내부 동작 구조에 대해서 자세히 살펴보지 않았지만, 우선 가볍게 짚고 넘어가자면 Envoy 내부의 쓰레딩 모델은 기본적으로 Lock 없이 데이터를 주고 받으며, 데이터 동기화는 Eventually Consistency를 전제로 설계되어있습니다. 즉 이말은 데이터를 전달한다고 해서 바로 반영하는 것은 아니고 완벽한 동기화가 일시에 이루어지지 않음을 의미합니다.

그리고 이러한 구조는 다음과 같은 상황을 맞이할 수 있습니다.

이전에 살펴봤듯이 Endpoint와 Cluster는 의존 관계를 맺고 있음을 확인했습니다. 즉 Cluster는 Endpoint의 논리적 집합이었음을 이전 내용을 통해 확인했습니다.

그리고 이러한 상황에서 만약 위와 같이 Endpoint와 Cluster가 추가되어서 이를 갱신하는 상황이 발생한다고 가정했을 때, EDS를 통한 갱신이 CDS보다 먼저 이루어진다면 어떻게 될까요?

Envoy 입장에서는 EDS를 통해서 전달된 Endpoint의 대상이 Cluster-A라고 전달받았지만, 아직 CDS를 통해 Cluster 정보를 전달받지 못한 상황이므로 일정 기간 동안에는 Cluster 정보에 대한 동기화가 진행되지 않는 이상현상이 발생됩니다.

따라서 이러한 이슈를 해결하고자 등장한 것이 Aggregated Discovery Service입니다.

ADS는 Single gRPC 스트림으로 구성된 서비스로써 envoy에 전달되는 resource의 순서를 적용하려는 사용자를 위해 집계된 xDS를 단일 gRPC 스트림으로 전달할 수 있습니다. 따라서 위의 경우 ADS와 CDS의 의존 관계에 있을 때에도 이를 집계한 결과를 단일 스트림 형태로 envoy 전달하기 때문에 일관성을 달성할 수 있는 특징을 지니고 있습니다.

  "dynamic_resources": {
    "lds_config": {
      "ads": {},
      "initial_fetch_timeout": "0s",
      "resource_api_version": "V3"
    },
    "cds_config": {
      "ads": {},
      "initial_fetch_timeout": "0s",
      "resource_api_version": "V3"
    },
    "ads_config": {
      "api_type": "GRPC",
      "set_node_on_first_message_only": true,
      "transport_api_version": "V3",
      "grpc_services": [
        {
          "envoy_grpc": {
            "cluster_name": "xds-grpc"
          }
        }
      ]
    }
  },

dynamic_resources는 위와 같이 기존 Config yaml에 위와 같이 설정할 수 있습니다. 예를들어 위와 같이 설정을 지정할 수 있습니다. 내용을 살펴보면 lds와 cds는 ads를 통해서 해당 내용을 전달받을 수 있으며, ads는 xds-grpc 클러스터를 통해서 해당 정보를 가져오도록 지정되어 있습니다.

참고로 위 설정은 istio를 통해 배포된 Pod에 속한 envoy proxy의 설정 파일 중 일부를 발췌한 내용이며, 해당 설정에 대한 자세한 내역은 차후 포스팅을 통해 다루어보겠습니다.

3. xDS API

xDS API는 istio와 연계하여 Service Discovery를 수행하는데 있어 주요하게 사용됩니다. 따라서 xDS API의 종류와 동작 방법에 대해서 보다 자세히 살펴보고자 합니다.

먼저 xDS 지원 방식 부터 살펴보겠습니다. xDS 지원 방식은 총 3가지(File 동기화, HTTP, gRPC)입니다.

File 동기화 방식은 위와 같이 envoy에서 File의 상태를 관찰하고 설정이 적용된 File에서 변경이 일어났을 경우 envoy에서 이를 인지하여 내부 컴포넌트의 설정을 동기화하는 방식입니다.

반면 gRPC와 HTTP 방식은 config 정보를 전달하는 Management Server가 중앙에 존재합니다. 따라서 envoy에서는 Management Server에 요청하여 config 정보를 전달받고 전달받은 정보를 토대로 자신의 내부 컴포넌트 설정을 동기화합니다.

HTTP 방식은 주기적인 polling을 통해서 Management Server로부터 변경된 데이터 항목을 전달받아 갱신합니다. 반면 gRPC는 bidirectional streaming 통신을 통해 데이터를 주고 받는 차이점이 존재합니다. 해당 통신 방법에 대해서 궁금하신 분은 제 블로그 아래 내용을 참고 부탁드립니다.

https://cla9.tistory.com/177?category=993774

3. gRPC는 왜 빠를까? (통신 방식) - 2

서론 지난 포스팅에서는 gRPC에서 사용되는 protobuf와 REST 통신에서 사용되는 JSON 크기와 Serialization/Deserialization 관점에서 성능을 비교해봤습니다. 이번에는 gRPC에서 제공하는 통신 방법에 대해서

cla9.tistory.com

envoy에서 널리 사용하는 방식은 gRPC 방식이며, istio 또한 gRPC 방식을 통해 xDS 정보를 전달받습니다. 따라서 본 포스팅에서는 gRPC 방식에 보다 초점을 맞추어 살펴보겠습니다.

3-1 xDS gRPC

앞서 envoy에서 gRPC를 활용한 xDS 방식은 envoy와 config를 전달하는 Management Server 사이에 bidirectional streaming 통신을 사용한다고 설명했습니다. 따라서 해당 방식은 Connection이 끊기지 않고 지속 연결된 상태라고 봐도 무방합니다.

이러한 상황에서 처음 Management Server에 envoy가 연결되면, 위와 같이 Discovery Request를 Management Server에 전달합니다. 그러면 Management Server에서는 envoy가 요청하는 Config에 대해서 전체 목록을 전달하게되고, envoy는 해당 설정을 전달받아 Config 업데이트를 수행합니다.

이후 Config 업데이트가 완료되면, envoy는 이전에 Management Server로부터 전달받은 Config 항목에 대한 응답을 전달합니다. 만약 Config 내용을 정상적으로 업데이트를 수행했을 경우에는 ACK를 응답하고 그렇지 않을 경우에는 NACK를 응답합니다. (※ ACK와 NACK의 구조와 동작방식에 대해서는 envoy 공식 문서에서 자세히 다루고 있으니 참고바랍니다.)

이때 응답 메시지는 별개의 포맷을 활용하지 않고 다음 Discovery Request를 전달할 때, 응답을 포함하여 전달됩니다. 해당 Discovery Request 메시지는 Config 업데이트 완료 이후 Management Server에 Config가 변경되었을 때, 동기화된 Config 내역을 다시 전달받기 위해 요청하는 메시지입니다. 따라서 Management Server에 Config가 변경되거나 새로운 Resource가 추가되었을 경우 envoy에게 Discovery Response를 전달함으로써 동기화 작업이 이루어집니다.

3-2 SotW(State of the world), Delta xDS

지금까지 envoy gRPC 동작 과정에 대해서 가볍게 살펴봤는데, 이번에는 Management Server에서 Discovery Response를 응답 메시지를 전달하는데 있어서 선택할 수 있는 2가지 방법에 대해서 살펴보겠습니다.

첫 번째 방법은 SotW(State of the world) 방식입니다.

가령 envoy가 Cluster 정보를 동기화 하기 위해 xDS로 연결되었으며 이미 한차례 Cluster 동기화되었다고 가정해봅시다. 이때 SotW 방식은 동기화된 Cluster 정보 중 하나가 변경되었을 경우에 전체 Cluster 정보를 전달하는 방식을 의미합니다. 해당 방식은 구현이 간단한 반면에 전체 데이터 중 일부만 변경되었음에도 불구하고 전체 정보를 전달하기 때문에 많은 Network overhead가 발생할 수 있습니다.

참고로 이때 DiscoveryResponse 응답 포맷은 위와같으며, 여기서 resources를 통해서 전체 resource 정보가 전달됩니다.

두 번째 방법은 Delta 방식입니다.

해당 방식은 변경된 Config 정보만을 선별하여 전체를 전달하는 것이 아니라 변경분 (Delta 혹은 incremental)만 전달하는 방식을 의미합니다.

이때 Delta Discovery Response 응답 포맷은 위와 같으며, resources 항목은 변경된 항목만 추가됩니다. 또한 기존에 존재하는 Resource가 삭제되었을 경우에는 removed_resources를 통해서 이를 envoy에게 전달합니다.

지금까지 SotW, Delta 두 가지 방식에 대해서 살펴봤습니다. 그렇다면 두 방식은 어떻게 지정할 수 있을까요?

위 설정과 같이 envoy configuration에서 api_type을 지정할 때, GRPC로 지정 혹은 DELTA_GRPC로 지정하면 입력 값에 따라서 동작 방식이 결정됩니다.

지금까지 gRPC 방식에서 Config 정보를 전달하는 두 가지 방법에 대해서 살펴봤습니다. 그렇다면 istio에서는 어떤 방식을 기본적으로 사용할까요? istio에서는 기본적으로는 SotW 방식을 사용하고 있으며, 사이드카 컨테이너를 주입할 때 사용자가 지정한 ISTIO_DELTA_XDS 값을 통해서 Delta 방식으로 변경할 수 있습니다. 하지만 현재는 값을 변경한다고 할지라도 실제 데이터를 전달할 때 Delta 값만을 전달하지 않습니다.

4. 마무리

지금까지 Envoy 내부 주요 컴포넌트 및 설정 방식에 대해 살펴봤습니다. istio는 envoy를 얼만큼 잘 이해하고 있느냐에 따라서 istio에 대한 전문성을 확보한다고 생각합니다. 또한 istio가 문제가 생겼을 때 트러블 슈팅할 때는 envoy 설정에 대한 이해를 기반으로 진행되어야합니다. 따라서 이번 포스팅의 내용은 간략하지만 중요한 부분을 다루고 있습니다.

다음 포스팅에서는 Envoy 내부 구조에 대해서 조금 더 자세히 알아보도록 하겠습니다.

4. kotlin 환경에서 gRPC 설정하기

cla9 — Thu, 10 Mar 2022 19:45:54 +0900

서론

지금까지 gRPC에 대한 소개 및 해당 기술이 가진 이점에 대해서 살펴봤습니다. 이번 포스팅에서는 kotlin 환경에서 gRPC 관련 기본 설정 셋업하는 방법에 대해서 다루어보도록 하겠습니다. 프로젝트 설정은 gradle 기반의 기본 Kotlin 빈 프로젝트는 생성되었음을 가정하고 진행하겠습니다.

1. gradle 설정 추가

build.gradle.kts

import com.google.protobuf.gradle.*

plugins {
    ...(중략)...
    id("com.google.protobuf") version "0.8.13"
}

가장 먼저 설정할 것은 protobuf 관련 plugin을 설정하는 것입니다. 위 내용을 gradle.kts 파일 plugins 항목에 추가합니다.

build.gradle.kts

...(중략)...

val grpcVersion = "3.19.4"
val grpcKotlinVersion = "1.2.1"
val grpcProtoVersion = "1.44.1"

dependencies{
    implementation("io.grpc:grpc-kotlin-stub:$grpcKotlinVersion")
    implementation("io.grpc:grpc-protobuf:$grpcProtoVersion")
    implementation("com.google.protobuf:protobuf-kotlin:$grpcVersion")
}

그 다음에는 protobuf 관리와 stub을 자동으로 생성해주는 라이브러리 의존성을 위와같이 추가합니다.

build.gradle.kts

...(중략)...
sourceSets{
    getByName("main"){
        java {
            srcDirs(
                "build/generated/source/proto/main/java",
                "build/generated/source/proto/main/kotlin"
            )
        }
    }
}

위 내용은 build 이후에 Stub 클래스가 생성되는 directory에 대해서 target으로 추가하기 위한 설정입니다. 해당 설정을 통해 소스 내에서 Stub 클래스 참조가 가능합니다.

build.gradle.kts

...(중략)...

protobuf {
    protoc {
        artifact = "com.google.protobuf:protoc:$grpcVersion"
    }
    plugins {
        id("grpc") {
            artifact = "io.grpc:protoc-gen-grpc-java:$grpcProtoVersion"
        }
        id("grpckt") {
            artifact = "io.grpc:protoc-gen-grpc-kotlin:$grpcKotlinVersion:jdk7@jar"
        }
    }
    generateProtoTasks {
        all().forEach {
            it.plugins {
                id("grpc")
                id("grpckt")
            }
            it.builtins {
                id("kotlin")
            }
        }
    }
}

마지막으로 설정할 내용은 build 시점에 protobuf를 생성하기 위한 task를 추가하는 작업입니다. 해당 설정을 통해 Java Stub 파일과 Kotlin Stub파일을 생성할 수 있습니다.

기본 설정이 모두 끝났으면 gradle refresh를 통해서 설정을 마무리합니다.

2. 임시 Protobuf 생성 테스트

설정이 완료되었으면, Protobuf를 만들어보고 정상적으로 Stub 클래스가 생성되는지 확인해보도록 하겠습니다.

먼저 main 디렉토리 하위에 proto 디렉토리를 생성합니다.

생성된 proto 디렉토리 하위에 test.proto를 생성합니다.

간단한 테스트를 위해 위 내용을 기입합니다.

gradle 탭에서 build 버튼을 클릭합니다.

build가 정상적으로 완료되면, 위 그림과 같이 build 폴더가 생깁니다. 이를 확인해봅시다.

Stub 클래스가 정상 생성되었는지 확인을 위해 build > generated > source > proto > main 하위에 java와 kotlin 패키지를 열어봅니다. 만약 정상적으로 build가 완료되었으면, 위 그림과 같이 Test Stub 클래스가 생성된 것을 확인할 수 있습니다.

생성된 Stub 클래스를 프로그램내에서 정상 사용할 수 있는지 여부를 테스트하기 위해 위와 같이 별도 main 함수를 만들어 생성 가능 여부를 확인해봅니다.

만약 클래스 참조가 불가하다면, build.gradle.kts 파일에 sourceSets 내 경로가 일치하는지 확인 후 수정합니다.

지금까지 과정이 모두 정상적이라면, proto 파일을 만들고 이를 build하고 Stub 클래스를 생성 후 프로그램 참조하는 모든 과정을 가볍게 훑어볼 수 있었습니다. 테스트를 위해 사용되었던 test.proto 파일은 더 이상 필요하지 않으므로 제거해도 좋습니다.

3. 마치며

이번 포스팅은 Kotlin 기반에서 gRPC 설정 하는 방법에 대해서 알아봤습니다. 다음 포스팅부터는 본격적으로 protobuf 사용법에 대해서 알아보겠습니다.

3. gRPC는 왜 빠를까? (통신 방식) - 2

cla9 — Thu, 10 Mar 2022 09:16:54 +0900

서론

지난 포스팅에서는 gRPC에서 사용되는 protobuf와 REST 통신에서 사용되는 JSON 크기와 Serialization/Deserialization 관점에서 성능을 비교해봤습니다. 이번에는 gRPC에서 제공하는 통신 방법에 대해서 살펴보고 REST 단건 통신과 비교하여 송/수신 시간을 비교해보겠습니다.

1. gRPC 통신 방법

gRPC는 HTTP 2.0을 기반으로 구성되어있기 때문에 Multiplexing으로 연결을 구성할 수 있습니다. 따라서 단일 Connection으로 순서의 상관없이 여러 응답을 전달받을 수 있는 Streaming 처리가 가능합니다. gRPC는 총 4가지의 통신 방법을 지원하며 그 중 3가지 방식은 Streaming 처리 방식입니다. 지금부터 하나씩 살펴보겠습니다.

2. Unary

첫 번째 방식은 Unary 통신 방식입니다.

이는 가장 단순한 서비스 형태로써 클라이언트가 단일 요청 메시지를 보내고 서버는 이에 단일 응답을 내려보내주는 방식입니다. 일반적으로 사용하는 REST API를 통해 주고 받는 Stateless 방식과 동일하다고 볼 수 있으며, 개념적으로 이해하기 쉽습니다.

그렇다면 gRPC의 Unary 통신과 REST의 성능을 비교해보면 어떤차이를 보일까요? 테스트 시나리오를 기반으로 두 통신방법을 비교해보록 하겠습니다.

1. 사용자를 등록하는 서비스가 있다고 가정한다.
2. 10, 100 등 10만까지 10의 거듭 제곱 형태로 delay없이 요청 횟수를 늘리면서 REST와 gRPC의 응답 총 시간을 구한다.
3. 테스트 시작전 warm up을 위해 50회의 요청 수행 후 테스트를 진행한다.

위 시나리오를 기반으로 Unary 통신을 구현해보겠습니다.

syntax = "proto3";

import "google/protobuf/empty.proto";

option java_multiple_files = true;
option java_package = "grpc.polar.penguin";

message Address{
    string city = 1;
    string zip_code = 2;
}

message Person{
    string name = 2;
    int32 age = 3;
    repeated string hobbies = 4;
    optional Address address = 5;
}

service PersonService {
    rpc register(Person) returns (google.protobuf.Empty);
}

Protobuf는 위와 같이 디자인했습니다. message 포맷은 이전 포스팅에서 설계 내용과 동일합니다. 여기서 새로 추가된 항목은 service 부분입니다. 추가된 내용을 살펴보면 인자로 Person 타입을 입력받고 반환 값은 없으므로 Empty를 지정하였습니다.

이번 포스팅 내용은 통신 방법에 대한 설명이므로 syntax 설명은 향후 다른 포스팅 내용으로 다루겠습니다.

class PersonGrpcService : PersonServiceGrpcKt.PersonServiceCoroutineImplBase() {
    override suspend fun register(request: Person): Empty {
        //TODO : request 처리
        return Empty.getDefaultInstance()
    }
}

Proto 파일 디자인 후 Build하면 Stub 클래스가 자동 생성됩니다. 위 코드는 gRPC 서비스 처리를 구현하기 위해 Stub 클래스인 PersonServiceCoroutineImplBase을 상속받아 구현한 코드입니다. 테스트 시나리오에서는 전달받은 Person 객체를 따로 저장하거나 처리하지 않고 Empty 객체를 반환하도록 구현하였습니다.

fun main() {
    val server = ServerBuilder.forPort(6565)
        .addService(PersonGrpcService())
        .build()

    server.start()
    server.awaitTermination()
}

Server 기동 시에 Service를 등록 시켜서 Client의 요청이 들어왔을 경우에 해당 Service로 Routing 하도록 설정합니다. 이후 Server를 기동합니다.

fun main() {
    val channel = ManagedChannelBuilder.forAddress("localhost", 6565)
        .usePlaintext()
        .build()

    val stub = PersonServiceGrpc.newBlockingStub(channel)

    execute(stub, 50) //warm up phase

    val base = 10.0
    val dec = DecimalFormat("#,###")
    for (exponent in 1..5) {
        val iterCount = base.pow(exponent).toInt()
        val time = measureTimeMillis {
            execute(stub, iterCount)
            println("count : ${dec.format(iterCount)}")
        }
        println("elapsed time $time ms")
        println("------------------------------------")
    }
    
    channel.shutdown()
}

Unary 테스트를 위한 client 코드는 위와같습니다. Server를 localhost의 6565 포트에서 기동중이므로 해당 요청에 대한 Channel을 생성합니다.

이후 proto 파일 Build 과정에서 생성된 PersonServiceGrpc 내에 있는 BlockingStub 객체를 생성 해서 해당 Channel에 Binding 합니다. Channel에 Binding 한 다음에는 Stub 객체의 메소드를 호출하면 Server와 통신을 수행할 수 있습니다.

stub 객체까지 만들고 나면, 10 ~ 10만번까지 10의 거듭제곱 형태로 늘려가면서 gRPC Unary 통신을 수행 후 총 수행 시간을 출력합니다.

위 코드에서 실질적으로 gRPC를 호출하는 부분은 execute 함수입니다.

fun execute(stub: PersonServiceGrpc.PersonServiceBlockingStub, count: Int) {
    repeat(IntRange(1, count).count()) {
        stub.register(
            person {
                name = "kevin"
                age = (1..50).random()
                address = address {
                    city = "seoul"
                    zipCode = "123456"
                }
                hobbies.addAll(listOf("foot ball", "basket ball"))
            }
        )
    }
}

execute 함수를 살펴보면 위와 같이 iteration count를 인자로 전달받고 그 횟수만큼 gRPC 요청을 보내는 것을 확인할 수 있습니다.

프로그램을 실행하면 위와 같이 Unary 요청 수행 결과를 확인할 수 있습니다.

이번에는 REST 통신을 통해 같은 횟수를 반복했을 때 Unary 통신과 비교하여 총 수행시간이 얼만큼의 차이가 있는지를 비교해보도록 하겠습니다. 이때 Unary 테스트 또한 단일 Channel에서 Blocking 방식으로 수행시간을 측정하였으므로 REST 통신 또한 같은 방법으로 테스트를 진행하겠습니다.

data class PersonDto(
    val name : String,
    val age : Int,
    val hobbies : List<String>? = null,
    val address : AddressDto? = null
)

data class AddressDto(
    val city : String,
    val zipCode : String
)

JSON으로 입력받을 DTO를 위와 같이 디자인합니다.

@RestController
class PersonController(private val service: PersonService) {
    @PostMapping("/person")
    suspend fun register(@RequestBody person : PersonDto) {
        //TODO : request 처리
    }
}

REST Controller 코드는 위와 같습니다. gRPC 서비스 코드에서도 인자를 전달받아 아무런 처리를 하지 않았기 때문에 마찬가지로 요청만 전달받고 아무 처리를 수행하지 않도록 구성하였습니다.

@Component
class RegisterTest : CommandLineRunner {
    override fun run(vararg args: String?) {
        val client = WebClient.builder()
            .build()

        execute(client, 50) // warm up phase

        val base = 10.0
        val dec = DecimalFormat("#,###")
        for (exponent in 1..5) {
            val iterCount = base.pow(exponent).toInt()
            val time = measureTimeMillis {
                execute(client, iterCount)
                println("count : ${dec.format(iterCount)}")
            }
            println("elapsed time $time ms")
            println("------------------------------------")
        }
    }

    private fun execute(client: WebClient, count: Int) {
        repeat(IntRange(1, count).count()) {
            client.post().uri("localhost:8080/person")
                .bodyValue(
                    PersonDto(
                        name = "kevin",
                        age = (1..50).random(),
                        address = AddressDto(city = "seoul", zipCode = "123456"),
                        hobbies = listOf("foot ball", "basket ball")
                    )
                )
                .retrieve()
                .bodyToMono(Void::class.java)
                .block()
        }
    }
}

Client 수행 프로그램은 위와 같습니다. gRPC 테스트 코드와 크게 다르지 않으며, 차이점이 있다면 Stub 객체를 사용한 것이 아닌 Webclient를 사용한 부분입니다.

Client 코드를 수행하면 위와 같은 결과를 얻을 수 있습니다.

횟수	REST	gRPC(Unary)	성능
10	23 ms	14 ms	1.64배
100	165 ms	101 ms	1.63배
1,000	1,000 ms	694 ms	1.44배
10,000	4,109 ms	2,132 ms	1.92배
100,000	41,491 ms	13,768 ms	3.01배

결과를 살펴보면, Iteration 횟수가 증가할 수록 그 차이가 벌어지는 것을 확인할 수 있습니다. 격차가 벌어진 이유는 다양한 이유가 있지만 Protobuf의 Serialization & Deserialization이 가장 큰 영향을 미치지 않았을까 생각합니다.

이번에는 네트워크 패킷을 통해서 REST와 gRPC의 통신 과정을 비교 해보겠습니다. 비교를 위해서 사용자 등록을 5회만 수행 후 종료한 내용을 확인해보도록 하겠습니다.

REST 통신을 5회 수행하였을 때, 네트워크 흐름을 표시하면 위 그림과 같습니다. 자세히보면 REST 통신은 HTTP 1.1을 사용한 것을 알 수 있고 SYN, ACK와 FIN, ACK가 매 요청마다 보이지 않는 것으로 보아 Connection을 매번 요청하지 않았음을 확인할 수 있습니다.

이번에는 gRPC Unary 통신 결과입니다. REST에서는 HTTP 1.1 방식이었던 것과 달리 예상대로 HTTP 2.0으로 통신을 수행한 것을 확인할 수 있습니다.

gRPC에서 Unary 통신은 HTTP 2.0 Stream으로 데이터를 전송합니다. 따라서 위 패킷 내용을 살펴보면, Stream 통신에 있어서 필요한 데이터 흐름을 파악할 수 있습니다.

가령 WINDOW_UPDATE를 통해서 Client가 수신할 수 있는 Byte 수를 Server에 알려줘 해당 정보를 기반으로 Flow control이 가능하도록 사전 설정하는 것을 확인할 수 있습니다. 또한 PING 패킷의 경우는 연결된 Channel 에서 사용중인 Connection liveness를 체크합니다. 만약 PING 단계에서 정상 응답을 수신 받지 못하면, Connection을 끊습니다. 이후 Connection 재생성을 통해 다시 연결할 수 있습니다.

이번에는 데이터 패킷을 상세하게 살펴보도록 하겠습니다.

위 그림은 요청 패킷을 구조화한 모습입니다.

Header를 살펴보면, Header의 길이 그리고 Header의 종류 flag가 보입니다. 그리고 Stream ID가 표시된 것을 볼 수 있는데, 이는 HTTP Stream 내에서 사용되는 Stream 메시지 별 Unique ID 입니다. Client에서 보내는 메시지는 Stream ID가 홀수개로 증가합니다.

Header에는 그 밖에 요청 Path 정보 및 Schema, Content-type이 표시됩니다. 내부적으로 요청은 POST로 요청되는 것을 확인할 수 있습니다.

Data 영역에는 실제 전달되는 데이터와 Flag등을 전달합니다. Unary 통신의 경우 gRPC Stream 요청은 아니므로 Flag에는 End Stream으로 지정된 것을 확인할 수 있습니다.

응답 패킷은 크게 3가지 부분으로 이루어져있습니다. 첫번째는 요청에 대한 응답헤더이고, 두 번째는 응답에 대한 데이터 마지막으로는 trailer 헤더로 구성되어있습니다.

그렇다면 위 5개의 데이터 전송 흐름에서 gRPC 패킷은 어떤 특징을 지니고 있을까요?

요청 패킷을 살펴보면, Header 길이가 최초 메시지를 보낼 때보다 크기가 줄어든 것을 확인할 수 있습니다. 또한 Stream ID는 홀수 번호로 순차 증가한 것을 확인할 수 있습니다.

마찬가지로 응답 패킷을 살펴보면, 최초 응답 헤더에 비해 이후 응답 메시지의 Header 크기가 줄어든 것을 확인할 수 있습니다.

위와 같이 gRPC는 기반에 HTTP 2.0을 기반으로 하여 메시지 전송간 데이터 Payload가 줄어드는 장점이 존재하기 때문에 이전 REST 방식에 통신에 있어서 조금 더 빠른 결과를 나타낼 수 있습니다.

3. Streaming

이번에는 Streaming 처리 방법에 대해서 살펴보도록 하겠습니다. Stream은 데이터를 한번만 전송하는 것이 아니라 연속적인 흐름으로 전달하는 것을 의미합니다.

gRPC에서는 총 3가지 종류의 Streaming이 존재합니다.

1) Client Stream

Client는 Stream 형태로 전달하고 Client의 요청이 끝나면 Server에서 한번에 응답을 내려주는 경우는 Client Stream이라고 부릅니다.

2) Server Stream

Client의 요청은 한번만 전달하고 Server에서 응답은 여러 번에 걸쳐 전송하는 경우는 Server Stream이라고 부릅니다.

3) Bidirectional Stream

양방향 모두 Stream으로 데이터를 전송하는 경우는 Bidirectional Stream 이라고 부릅니다.

Stream 처리 방법은 개념적으로 어렵지 않고 이번 포스팅에서는 사용 방법 보다는 성능 비교가 주 목적이므로 모든 Stream 방식에 대한 구현을 다루지는 않겠습니다.

Stream 처리 관련해서 다루어볼 내용은 Client Stream 방식을 활용해서 Unary, REST 방식의 테스트 시나리오를 동일하게 적용하여 어떤 차이점이 있는지를 살펴보도록 하겠습니다.

...(중략)...
service PersonService {
    ...(중략)...
    rpc registerBatch(stream Person) returns (google.protobuf.Empty);
}

먼저 Stream 처리를 위해 서비스에 RPC를 등록합니다. 이후 Build를 수행합니다.

class PersonGrpcService : PersonServiceGrpcKt.PersonServiceCoroutineImplBase() {
    ...(중략)...
    override suspend fun registerBatch(requests: Flow<Person>): Empty {
        val start = System.currentTimeMillis()
        requests
            .catch {
                //TODO : Error 처리
            }
            .onCompletion {
                println("${System.currentTimeMillis() - start} ms elapsed. ")
            }
            .collect {
                //TODO : request 처리
            }
        return Empty.getDefaultInstance()
    }

    
}

Build 이후 해당 Stub 메소드 구현을 위해서 PersonServiceCoroutineImplBase Stub 클래스에서 RPC 관련 메소드를 override 합니다. 이때 Stream으로 전달받은 데이터를 기반으로 비즈니스 로직 처리는 수행하지 않기 때문에 collect 부분은 아무런 작업을 수행하지 않도록 구성했습니다.

fun main() {
    val channel = ManagedChannelBuilder.forAddress("localhost", 6565)
        .usePlaintext()
        .build()

    val stub = PersonServiceGrpcKt.PersonServiceCoroutineStub(channel)

    runBlocking { execute(stub, 50) } // warm up phase

    val base = 10.0
    val dec = DecimalFormat("#,###")

    runBlocking {
        for (exponent in 1..5) {
            val iterCount = base.pow(exponent).toInt()
            val time = measureTimeMillis {
                execute(stub, iterCount)
                println("count : ${dec.format(iterCount)}")
            }
            println("elapsed time $time ms")
            println("------------------------------------")
        }
    }
}

suspend fun execute(stub: PersonServiceGrpcKt.PersonServiceCoroutineStub, count: Int) {
    try {
        stub.registerBatch(
            IntRange(1, count)
                .map {
                    person {
                        name = "kevin"
                        age = (1..50).random()
                        address = address {
                            city = "seoul"
                            zipCode = "123456"
                        }
                        hobbies.addAll(listOf("foot ball", "basket ball"))
                    }
                }
                .asFlow()
        )
    } catch (e: StatusException) {
        println(e)
    }
}

Client 프로그램은 위와 같이 구성했습니다. gRPC의 Stream 처리를 구현하기 위해서 StreamObserver를 활용해서 구현하는 방식과 Kotlin의 Coroutine 방식 두 가지 방식으로 구현 가능한데, 위 코드는 Coroutine 방식으로 구현하였습니다.

내용을 살펴보면 이전 Unary 코드와 크게 다르지는 않으며, 데이터 전달시 Flow로 변환하여 전달하는 것을 확인할 수 있습니다.

코드 구현이 완료되었으면 실행 후 결과를 비교해보겠습니다.

실행 결과를 살펴보면, REST와 gRPC(Unary)와 비교했을 때 엄청난 개선이 이루어진 것을 확인할 수 있습니다.

이를 표로 나타내면 다음과 같습니다.

횟수	REST	gRPC(Unary)	gRPC(Client Stream)
10	23 ms	14 ms	9 ms
100	165 ms	101 ms	20 ms
1,000	1,000 ms	694 ms	106 ms
10,000	4,109 ms	2,132 ms	468 ms
100,000	41,491 ms	13,768 ms	2,880 ms

요청 횟수가 적을 때보다 횟수가 늘어감에 따라 차이가 더 커지는 것을 확인할 수 있습니다. 가령 10만번 데이터 전송의 경우 REST 방식보다 14.4배 Unary 방식에 비교하면 4.78배 효율이 좋은 것을 확인할 수 있습니다.

그렇다면 Stream 처리 방식은 왜 이리 많은 차이를 보이는 것일까요? 이전과 마찬가지로 패킷의 흐름을 살펴보겠습니다.

위 내용은 Stream 형식으로 Person 데이터를 50회 전송했을 때 네트워크 흐름입니다.

Unary와 REST 방식은 5회만 전송했는데도 많은 Network 요청이 있었던 것과 비교하여 50회 데이터를 전송했는데도 패킷의 횟수가 그리 많지 않습니다.

데이터 전송 부분만 살펴보면, 요청을 전달할 때 Header는 한번만 전송한 것을 확인할 수 있고, 응답 또한 한번만 전달받은 것을 확인할 수 있습니다.

그리고 데이터는 여러번 전달한 것이 아니라 한 Packet안에 여러개의 요청이 포함되어 전달된 것을 확인할 수 있습니다.

위 패킷 흐름에는 총 2번 전달하는 과정에서 50개의 요청이 담겨있는 것을 확인할 수 있습니다.

한번에 동일 요청 다수를 함께 전달할 경우, Stream 방식이 매번 요청을 수행하는 Unary 방법보다 효율적인 데이터 전송이 가능합니다. 따라서 네트워크 전달 과정에서 많은 비용을 감소하여 성능이 더욱 좋다고 볼 수 있습니다.

4. 마치며

지난 포스팅과 이번 포스팅을 통해서 gRPC의 성능 이점에 대해서 다양한 각도로 살펴봤습니다. 다음 포스팅부터는 gRPC를 사용하는 방법에 대해서 차차 알아보도록 하겠습니다.

2. gRPC는 왜 빠를까? (Payload) - 1

cla9 — Thu, 10 Mar 2022 09:15:37 +0900

서론

이전 포스팅에서는 gRPC에 대한 기본적인 소개를 다루어 봤습니다. 이번에는 gRPC에서 사용하는 Protocol Buffer(aka Protobuf)와 보편적으로 사용하는 JSON 메시지 포맷에 대한 비교를 통해 어떤 부분에서 Protobuf가 이점이 있는지를 살펴보겠습니다.

1. JSON, Protobuf 변환 속도 비교

이전 포스팅에서 살펴봤듯이 REST 통신에서는 JSON 규격으로 메시지를 주고 받았고 이때 발생하는 Serialization & Deserialization 과정은 비용이 소모되는 작업임을 살펴봤습니다. 반면 gRPC에서는 binary 포맷으로 데이터를 주고받기 때문에 변환 과정에 따른 비용이 JSON에 비해서 적다고 설명했습니다.

그렇다면 실제 Protobuf 변환 과정과 JSON 변환 과정을 측정해보면 얼마나 유의미한 결과를 나타낼까요? 테스트를 통해 차이가 얼마나 발생하는지 살펴봅시다.

data class PersonDto(
    val name : String,
    val age : Int,
    val hobbies : List<String>? = null,
    val address : AddressDto? = null
)

data class AddressDto(
    val city : String,
    val zipCode : String
)

JSON 변환 테스트를 위해 Sample 객체를 위와 같이 디자인합니다. 위 데이터 구조는 Person이라는 객체를 생성함에 있어 이름, 나이, 주소 정보를 입력받으며 취미의 경우 다수가 존재하므로 List로 입력받도록 디자인 했습니다.

syntax = "proto3";

option java_multiple_files = true;
option java_package = "grpc.polar.penguin";

message Address{
    string city = 1;
    string zip_code = 2;
}

message Person{
    string name = 1;
    int32 age = 2;
    repeated string hobbies = 3;
    optional Address address = 4;
}

앞서 구현한 data class에 대응되는 Proto 파일은 위와 같이 구현합니다. 아직 Protobuf에 대해서 본격적으로 다루어보지 않은만큼 syntax가 이해되지 않더라도 좋습니다.

기본 Spec을 정의하였으면 이제 변환 과정 테스트 시나리오를 정의해봅시다.

1. 10, 100 ... 천만번까지 10의 거듭제곱 횟수만큼 변환 과정을 수행하면서 각 단계에서 걸린 총 시간을 측정한다.

2. 단계별 warm up 과정을 추가하고 해당 단계에서의 결과는 제외한다. 따라서 단계별 50회 변환 과정을 추가한다.

3. JSON, Proto 변환 측정 과정은 다음과 같다.
- JSON : DTO를 JSON Byte 배열로 변환한 다음 해당 Byte을 다시 DTO로 변환하는데 걸린 시간
- Proto : Stub을 Byte 배열로 변환한 다음 해당 Byte 배열을 다시 Stub 객체로 변환하는데 걸린 시간

테스트 시나리오를 위해 작성한 메인 프로그램의 흐름은 위와 같습니다. 10 부터 천만번까지 각각 변환과정을 수행한 결과를 출력하도록 구성했습니다.

측정 과정은 앞서 시나리오대로 단계별 변환 횟수에 맞추어 변환 작업을 수행하며, 단계별 최초 50회는 warm up 단계로 구성하여 결과에서 제외한 총 수행시간을 반환하도록 작성했습니다.

Stub 객체를 Byte 배열로 변환하고 이를 다시 Stub 객체로 변환하는 코드는 위와 같습니다.

DTO 객체를 JSON Byte 배열로 저장한 다음 이를 다시 Person DTO 객체로 변환하는 코드는 위와 같습니다. 이 과정에서 Parser로는 Jackson을 사용했습니다.

코드 작성은 모두 마무리되었습니다. 이제 프로그램을 수행시킨 결과를 확인해봅시다.

측정 결과는 위와 같습니다. 살펴보면 변환 횟수가 증가하면서 두 방식의 변환 시간의 차가 크게 벌어지는 것을 확인할 수 있습니다. 가령 천만번 변환의 경우 7배 빠른 것으로 확인되었습니다.

그렇다면 위 측정결과를 gRPC가 REST 방식에 비해 7배 빠르다고 말할 수 있을까요?

요청에 대해서 응답을 처리하는 전체 flow를 아주 간략하게 표현한다면, 위와 같이 표현할 수 있을 것입니다. 위 과정에서 오래걸리는 영역은 당연히 Business Logic 처리를 위한 수행시간일 것입니다. 따라서 Business Logic 수행 시간이 오래 걸릴 수록 격차는 현격히 줄어들 것입니다.

하지만 TPS가 높은 시스템에서는 1ms라도 응답 속도를 줄이는 것이 중요하기 때문에 이런 경우 매우 유의미한 결과라고 볼 수 있습니다.

2. JSON, Protobuf 크기 비교

이번에는 기존에 사용했던 DTO, Stub 인스턴스를 byte 배열로 변환하였을 때 크기에 대해서 비교해보고 차이점을 통해 Protobuf의 특징을 확인해보겠습니다.

사이즈 크기 비교를 위해 작성한 프로그램은 위와 같습니다. 이전 내용과 같이 PersonDTO와 Stub 객체를 생성 후 둘 다 byte 배열로 변환한 크기를 출력하도록 구성했습니다.

실행 결과를 보면, 동일한 데이터 입력에 있어 JSON 방식과 Proto 방식간의 결과물 크기가 상당히 차이나는 것을 확인할 수 있습니다.

이러한 차이가 발생하는 이유는 Proto 메시지 정의에 따라서 Binary 데이터를 만드는 encoding 과정에서 데이터가 압축되기 때문입니다. 이와 관련하여 자세한 기술적인 내용은 아래 네이버 기술 블로그와 구글 Protocol Encoding 공식문서를 살펴보시면 도움 되실 것 같습니다.

네이버 기술 블로그 grpc 깊게 파고들기

[NBP 기술&경험] 시대의 흐름, gRPC 깊게 파고들기 #2

google에서 개발한 오픈소스 RPC(Remote Procedure Call) 프레임워크, gRPC를 알아봅니다.

medium.com

구글 Protocol Buffer Encoding 공식 문서

Encoding | Protocol Buffers | Google Developers

Encoding This document describes the binary wire format for protocol buffer messages. You don't need to understand this to use protocol buffers in your applications, but it can be very useful to know how different protocol buffer formats affect the size of

developers.google.com

이번에는 address와 hobbies를 제거한 다음의 수행 결과를 비교해보도록 하겠습니다.

결과를 측정해보면 값이 모두 들어있을 때보다 일부 필드에 값이 입력되지 않았을 경우 Stub 객체의 Byte 배열 크기와 JSON의 결과값이 더욱 차이가 나며, 이는 전체 값을 입력했을 때 보다 압축률이 더 좋음을 의미합니다.

그렇다면 필드에 데이터가 없을 때 어떻게 압축 효율이 더 좋을 수 있을까요? 이에 대해서 한번 살펴봅시다.

{"name":"polar penguin","age":20,"hobbies":null,"address":null}

위 결과는 DTO를 JSON으로 변환한 결과입니다. 길이를 살펴보면 63바이트인 것을 확인할 수 있습니다.

결과를 통해 살펴본 흥미로운 사실은 hobbies와 address는 실질적으로 아무런 값을 입력하지 않았음에도 불구하고 JSON에서는 Key와 value를 포함시킨다는 사실입니다. 이로인해 불필요한 overhead가 추가됩니다.

반면 Protobuf의 경우는 무엇이 다를까요?

message Person{
    string name = 1;
    int32 age = 2;
    repeated string hobbies = 3;
    optional Address address = 4;
}

이전에 살펴본 Person의 proto 정의는 위와 같습니다. 그리고 테스트 프로그램에서 수행한 실제 Stub 객체에는 hobbies와 address가 포함되지 않았음을 확인할 수 있습니다.

proto 파일에서 눈여겨 볼 점은 실제 Property 옆에 표시된 field 번호가 존재하는 점입니다. 가령 name에는 1이 age에는 2가 지정되어있습니다.

해당 번호는 Protobuf의 필드를 인식하게 만들어주는 Key를 구성하는 요소입니다. 참고로 이전에 첨부한 Naver 기술 블로그나 Google 공식 문서에서는 해당 Field 번호와 Wiretype가 조합된 Key를 이용하여 Encoding 및 Decoding을 수행하여 필드 값을 Parsing 함을 자세히 확인할 수 있습니다.

그렇다면 hobbies와 address가 입력되지 않았을 때 개념적으로 어떤 변화가 발생했을까요? 먼저 개념적으로 이해하기 위해 추상적으로 어떻게 표현되었는지 살펴봅시다.

protobuf에서는 field 번호가 해당 객체 내에서 필드 값을 식별하는데 있어 주요 역할을 수행합니다. 따라서 protobuf를 설계할 때 field 별로 부여하는 field 번호는 unique 해야합니다.

결과물을 살펴보면, JSON 표현 방식에 비해서 2가지 특징을 지닌 것을 확인할 수 있습니다.

1. 해당 객체 값에 값이 입력되지 않았을 경우 결과물에 포함시키지 않습니다. 따라서 JSON에 비해서 Byte 배열 크기가 줄어들 수 있습니다.

2. 실제 필드명의 길이가 어떻든 관계없이 field 번호를 기반으로 Binary 데이터가 만들어지기 때문에 payload 크기가 감소됩니다. 이는 field 명이 길어질 수록 payload 크기가 커지는 JSON과 대비하여 공간을 절약할 수 있습니다.

이번에는 패킷 수준에서 메시지 내용을 자세하게 살펴보겠습니다. 내용을 보면 방금전 설명했던 설명과 유사함을 확인할 수 있습니다.

데이터 구조를 살펴보면 Field Number와 Wire Type을 기반으로 ( (Field Number << 3) | Wire Type ) 형태로 Hex 값으로 구성되어 있습니다. 또한 모든 Field 내용이 저장되어있지 않고 사용자가 기입한 내용만 저장되어있는 것을 확인할 수 있습니다.

더 자세히 확인하기 위해 실제 Stub 객체에서 생성되는 Binary 내용을 해석해보도록 하겠습니다.

0A : name의 field 번호 1, wire type 2이므로 ( (1 << 3) | 2 ) 수행하면 10입니다. 따라서 이는 Hex 값으로 0A입니다.

0D : value의 길이를 의미합니다. 여기서 name에 저장된 값은 polar penguin 총 13자이므로 이는 Hex 값으로 0D입니다.

70 6F 6C 61 72 20 70 65 6E 67 75 69 6E : "polar penguin" 문자열의 Hex 값입니다.

10 : age의 field 번호 2, wire type 0이므로 ( (2 << 3) | 0 ) 수행하면 16입니다. 따라서 이는 Hex 값으로 10입니다.

14 : age의 값인 20입니다. 이는 Hex 값으로 14입니다.

지금까지 Proto에 저장되는 결과를 알아보기 위해 실제 저장된 Binary 구조까지 살펴봤습니다. 모든 기술이 장점이 있으면 단점이 존재하듯이 Protobuf는 결과물이 Binary 포맷이기 때문에 결과 값을 유추하기 쉽지 않은 점은 단점이라고 볼 수 있습니다. 하지만 성능이 더 중요시되는 환경에서는 짧은 Payload는 전송 속도에 있어 강점입니다.

마치며

이번 포스팅에서는 Protobuf와 JSON을 비교하여 변환 속도와 Payload 크기 차이점을 비교해봤습니다. Protobuf는 gRPC의 핵심 요소로써 gRPC가 가지는 성능 이점의 주요 부분 중 하나라고 생각합니다. 다음 포스팅에서는 HTTP 2.0 기반으로 gRPC의 통신 방법에 대해서 살펴보겠습니다.

1. gRPC 개요

cla9 — Sat, 5 Mar 2022 14:49:28 +0900

1. 서론

최근 MSA가 각광받으면서 많은 회사에서 Monolithic 구조를 여러개의 마이크로 서비스로 분리하려고 시도하고 있습니다.

MSA 구성은 다양한 장점을 내포하고 있으나 그만큼 다양한 문제점 또한 상존합니다. 이 글에서는 MSA의 문제점 중 하나인 네트워크 통신 overhead에 초점을 맞추어 gRPC 기술이 어떤 부분을 해소해줄 수 있는지에 대해서 다루어보고 해당 기술은 어떻게 사용할 수 있는지에 대해서 설명해보고자 합니다.

2. 마이크로 서비스간 통신 이슈

Monolithic 구조에서는 하나의 프로그램으로 동작하기 때문에 그 안에서 구조적인 2개의 서비스간의 데이터는 공유 메모리를 통해서 주고받을 수 있습니다. 따라서 이 경우 서비스간 메시지 전송 성능은 큰 이슈가 되지 않습니다.

반면 MSA에서는 여러 모듈로 분리되어있고 동일 머신에 존재하지 않을 수 있습니다. 따라서 일반적으로는 보편화된 방식인 REST 통신을 통해 메시지를 주고 받습니다.

문제는 Frontend 요청에 대한 응답을 만들어내기 위해 여러 마이크로 서비스간의 협력이 필요하다면, 구간별 REST 통신에 따른 비효율로 인해 응답속도가 저하된다는 점입니다. 그렇다면 구체적으로 어떤 요인으로 인해 응답 속도 저하가 발생될까요? 이에 대해서 알아보기 전에 HTTP 1.1의 특징에 대해서 이해하고 HTTP 1.1의 또 다른 이슈를 확인해보도록 하겠습니다.

3. HTTP 1.1 통신 방법

HTTP는 TCP위에서 동작하므로 데이터 송수신에 앞서서 TCP 연결 시점에 3 way handshake 과정을 거치며, 연결을 종료할 때도 4 way handshake 방식으로 종료하게됩니다.

이러한 경우 만약 여러 데이터를 전송 응답을 반복해야하는 상황이라면, 매번 연결을 맺고 종료하는 과정으로 인한 비효율이 발생합니다.

앞서 살펴본 HTTP 1.0은 요청/응답을 하기에 앞서 매번 Connection을 맺고 끊어야했기 때문에 연결 요청/해제 비용이 상당히 높았습니다.

따라서 이러한 성능 이슈를 해결하고자 HTTP 1.0 기반의 브라우저와 서버에서는 자체적으로 Keep-alive 기능을 지원하기도 했습니다. 이 경우 Header에 Keep alive 관련 헤더를 포함해서 Connection을 유지하는 경우도 있었습니다. 하지만 해당 기능은 공식 Spec은 아니였습니다.

HTTP 1.1에서는 1.0의 문제점을 해결하고자 Persistent Connection과 Pipelining 기법을 제공하였습니다. 해당 기능이 무엇인지 알아봅시다.

Persistent Connection의 경우 Keep Alive와 같이 요청/응답을 위해 매번 Connection을 맺는 것이 아니라 연결을 일정시간 지속하는 것을 의미합니다.

다만 Persistent Connection만 적용했을 경우 왼쪽 그림과 같이 1개의 요청을 보내고 요청에 대한 응답이 와야 그 다음 요청을 보내기 위해 기다려야 합니다. 따라서 오른쪽과 같이 추가로 Pipelining을 적용하여 각 요청마다 응답을 기다리지 않고, 요청을 하나의 Packet에 담아 지속적으로 요청을 전달할 수 있도록 개선하였습니다.

Pipelining을 살펴보면 HTTP 1.0과 비교해서 많은 부분이 개선된 것으로 보입니다. 하지만 Pipelining에서도 성능 이슈는 존재합니다. 과연 무엇일까요?

4. HTTP 1.1 문제점

1. HOLB(Head Of Line Blocking)

Pipelining에서 요청 자체는 응답 여부와 관계없이 보낼 수 있습니다. 하지만 여전히 순차적으로 응답을 받아야합니다. 따라서 첫 번째 요청에 대한 응답이 오래걸리는 상황이라면, 두 번째 세번 째 요청 응답은 첫번째 요청이 응답처리가 완료되기 전까지 대기해야합니다. 이러한 문제를 Head Of Line Blocking(HOLB)라고 합니다.

만약 위 예시와 같이 B, C, D, E 자원의 경우 크기가 작아 빠르게 처리될 수 있다면, 사용자 응답성이 좋아질 수 있습니다. 하지만 HTTP 1.1의 경우에는 A 자원의 응답처리가 완료되지 않았기 때문에 결과적으로는 전체 응답의 대기가 발생합니다. 이는 곧 사용성이 나빠지는 원인이 됩니다.

이러한 이슈를 해소하기 위해 대개 브라우저에서는 도메인당 기본 6개(브라우저 별 상이)의 Connection을 맺어놓고 데이터를 병렬적으로 요청 및 응답을 통해서 응답성을 개선하고 있습니다.

또한 개발자 입장에서는 브라우저 특성을 활용하여 자원 다운로드 속도를 빠르게 하기 위해 여러 기법을 사용합니다. 그 중 대표적인 방법은 여러 도메인으로 데이터를 분산하여 저장하고 도메인마다 병렬적으로 Connection 맺어 빠르게 많은 자원을 다운로드하도록 개선하는 방법입니다. 이러한 기법을 도메인 샤딩(Domain Sharding)이라고 합니다.

2. Header 문제

HTTP 통신시 헤더에는 많은 메타 정보가 저장되어 있습니다. 이때 사용자가 특정 사이트를 접속하게되면 방문 시점에 다수의 HTTP 요청이 발생하게 될 것입니다. 그리고 매 요청마다 중복된 헤더 값을 전달하며, 쿠키 또한 매 정보 요청마다 포함되어 전송됩니다. 더욱이 Header 정보는 Plain text로 전달되고 이는 Binary에 비해 상대적으로 크기가 크기 때문에 전송시 많은 비효율이 발생한다고 볼 수 있습니다.

5. HTTP 2.0 등장

출처 : https://developers.google.com/web/fundamentals/performance/http2/?hl=ko

HTTP 2.0은 2014년에 표준안이 제안되고 15년에 공개된 프로토콜입니다. HTTP 1.x 버전의 성능 개선을 위해 Multiplexed Streams 기술을 사용합니다. 해당 기술은 이전에 살펴본 HTTP pepelining의 개선 버전으로 하나의 Connection으로 여러개의 데이터를 주고 받을 수 있도록 Stream 처리가 가능합니다.

또한 응답에 대해서 우선순위(Priority)가 주어져서 요청 순서와 관계없이 우선순위가 높을 수록 더 빨리 응답을 할 수 있는 것이 특징입니다.

출처 : https://developers.google.com/web/fundamentals/performance/http2/?hl=ko

세 번째 특징으로는 HTTP 1.1에서는 매 요청마다 동일한 Header 정보를 보내야하는데 반해서 HTTP 2.0 버전에서는 Header 압축을 통해서 지속적인 데이터 요청에 대한 Header 크기를 줄일 수 있습니다.

즉 HTTP 2.0을 사용하게되면 더 적은 Connection으로 더 적은 Header 크기를 전송할 수 있으며 Stream 통신으로 인해 여러 데이터를 주고 받을 수 있게 되었습니다.

그 밖에 여러 특징이 존재하며, HTTP 2.0에 대해서 더 자세한 내용은 구글 개발자 페이지를 참고하시기 바랍니다.

6. REST API 이슈

gRPC는 HTTP 2.0 기반위에서 동작하기 때문에 지금까지 HTTP 2.0의 특징에 대해서 살펴봤습니다. 짧게 정리하자면, Header 압축, Multiplexed Stream 처리 지원 등으로 인해 네트워크 비용을 많이 감소시켰습니다.

그렇다면 HTTP 2.0 특징을 제외한 gRPC만의 특징은 무엇이 있을까요? 먼저 REST API 통신의 문제점에 대해서 먼저 살펴본 다음 gRPC의 특징에 대해서 살펴보도록 하겠습니다.

1) JSON Payload 비효율

REST 구조에서는 JSON 형태로 데이터를 주고 받습니다. JSON은 데이터 구조를 쉽게 표현할 수 있으며, 사람이 읽기 좋은 표현 방식입니다. 하지만 사람이 읽기 좋은 방식이라는 의미는 머신 입장에서는 자신이 읽을 수 있는 형태로 변환이 필요하다는 것을 의미합니다.

따라서 Client와 Server간의 데이터 송수신간에 JSON 형태로 Serialization 그리고 Deserialization 과정이 수반되어야합니다. JSON 변환은 컴퓨터 CPU 및 메모리 리소스를 소모하므로 수많은 데이터를 빠르게 처리하는 과정에서는 효율이 떨어질 수 밖에 없습니다.

2) API Spec 정의 및 문서 표준화 부재

REST API를 사용할 때 가장 큰 고민은 API 개발자와 API를 사용자 간의 효율적인 커뮤니케이션 방법입니다. 가령 API가 어떻게 디자인 되었는지, 그리고 해당 속성은 어떤 값을 입력해야하는지에 대해 상호간의 이해가 필요합니다. REST를 사용한다면 이를 위해서 자체적인 문서나 Restdocs 혹은 Swagger를 통해서 API 문서를 공유합니다. 하지만 이러한 방식은 REST와 관련된 표준은 아닙니다.

두 번째 이슈는 JSON 구조는 값은 String으로 표현됩니다. 따라서 사전에 타입 제약 조건에 대한 명확한 합의가 없거나 문서를 보고 개발자가 인지하지 못한다면, Server에 전달전에 이를 검증할 수 없습니다. 가령 위 예시와 같이 Server에서 zipCode는 숫자 타입으로 처리되어야하지만 Client에서는 이에 대한 제약 없이 문자열을 포함시켜 전달할 수 있음을 의미합니다.

그렇다면 gRPC 기술은 위 두 가지 이슈를 어떻게 풀어내었을까요?

7. gRPC Protobuf

Client에서 Server측의 API를 호출하기 위해서 기존에는 어떤 Endpoint로 호출해야할 지 그리고 전달 Spec에 대해서 API 문서 작성 혹은 Client와 Server 개발자간의 커뮤니케이션을 통해 정의해야했습니다. 그리고 이는 별도의 문서 생성이나 커뮤니케이션 비용이 추가로 발생합니다.

이러한 문제를 감소시키기 위해 다양한 방법이 존재합니다. 그 중 한가지는 Server의 기능을 사용할 수 있는 전용 Library를 Client에게 제공하는 것입니다. 그러면 Client는 해당 Library에서 제공하는 Util 메소드를 활용해서 호출하면 내부적으로는 Server와 통신하여 올바른 결과를 제공할 수 있습니다. 또한 해당 방법은 Server에서 요구하는 Spec에 부합되는 데이터만 보낼 수 있게 강제화 할 수 있다는 측면에서 스키마에 대한 제약을 가할 수 있습니다.

출처 : gRPC 공식 문서(https://grpc.io/docs/what-is-grpc/introduction/)

gRPC에서는 위 그림과 같이 이와 유사한 형태인 Stub 클래스를 Client에게 제공하여 Client는 Stub을 통해서만 gRPC 서버와 통신을 수행하도록 강제화 했습니다.

그렇다면 Stub 클래스는 무엇이고 위 그림에서 보이는 Proto는 무엇일까요?

message Address{
    string city = 1;
    string zip_code = 2;
}

message Person{
    string name = 1;
    int32 age = 2;
    repeated string hobbies = 3;
    optional Address address = 4;
}

service PersonService {
    rpc register(Person) returns (google.protobuf.Empty);
    rpc registerBatch(stream Person) returns (google.protobuf.Empty);
}

Protocol Buffer는 Google이 공개한 데이터 구조로써, 특정 언어 혹은 특정 플랫폼에 종속적이지 않은 데이터 표현 방식입니다. 하지만 Protocol Buffer는 특정 언어에 속하지 않으므로 Java나 Kotlin, Golang 언어에서 직접적으로 사용할 수 없습니다.

따라서 Protocol Buffer를 언어에서 독립적으로 활용하기 위해서는 이를 기반으로 Client 혹은 Server에서 사용할 수 있는 Stub 클래스를 생성해야합니다. 이때 protoc 프로그램을 활용해서 다양한 언어에서 사용할 수 있는 Stub 클래스를 자동 생성할 수 있습니다.

만약 Server가 Java 혹은 Kotlin 기반으로 구성되어있고 Client도 Java 혹은 Kotlin이라면, 위와 같이 Stub 생성을 자동으로 해주는 Library를 활용할 수 있습니다.

위 그림은 Library를 활용해서 Build 시점에 Proto 파일을 찾고 컴파일 단계에서 이를 분석해서 Stub 클래스를 자동으로 생성된 모습입니다.

Stub 클래스를 생성하면, 해당 클래스 정보를 Server와 Client에 공유한 다음 Stub 클래스를 활용하여 서로 양방향 통신을 수행할 수 있습니다.

위 코드는 Stub 객체를 활용하여 Client에서 특정 RPC를 호출한 모습입니다. REST 방식을 활용한다면 RestTemplate 혹은 Webclient나 Retrofit2와 같은 도구 활용해서 JSON으로 데이터를 전송해야합니다. 반면 gRPC 방법에서는 위와같이 Stub 객체에 정의된 메소드 호출을 통해서 Client/Server간 데이터 송수신을 수행할 수 있어 편리합니다.

지금까지 학습한 Protocol Buffer 내용을 정리하면 다음과 같은 장점을 지닌 것을 확인할 수 있습니다.

1. 스키마 타입 제약이 가능하다

2. Protocol buffer가 API 문서를 대체할 수 있다.

위 두가지 특징은 이전에 REST에서 다룬 이슈 중 하나인 API Spec 정의 및 문서 표준화 부재의 문제를 어느정도 해소해줄 수 있습니다. 그렇다면 또 하나의 이슈인 JSON Payload 비효율 문제와 대비하여 gRPC는 어떠한 이점을 지니고 있을까요?

JSON 타입은 위와같이 사람이 읽기는 좋지만 데이터 전송 비용이 높으며, 해당 데이터 구조로 Serialization, Deserialization 하는 비용이 높음을 앞서 지적했습니다.

gRPC의 통신에서는 데이터를 송수신할 때 Binary로 데이터를 encoding 해서 보내고 이를 decoding 해서 매핑합니다. 따라서 JSON에 비해 payload 크기가 상당히 적습니다.

또한 JSON에서는 필드에 값을 입력하지 않아도 구조상에 해당 필드가 포함되어야하기 때문에 크기가 커집니다. 반면 gRPC에서는 입력된 값에 대해서만 Binary 데이터에 포함시키기 때문에 압축 효율이 JSON에 비해 상당히 좋습니다.

결론적으로 이러한 적은 데이터 크기 및 Serialization, Deserialization 과정의 적은 비용은 대규모 트래픽 환경에서 성능상 유리합니다.

8. gRPC 단점

지금까지 gRPC에서 사용되는 기반 기술에 대해서 살펴봤습니다. gRPC는 MSA 환경에서 문제점인 네트워크 지연 문제를 어느정도 해결해 줄 수 있는 기술로써 점차 많은 곳에서 도입을 진행하고 있지만 다음과 같은 문제점 또한 존재합니다.

1) 브라우저에서 gRPC를 직접 지원 안함

현재 gRPC-WEB을 사용해서 직접 브라우저에서 서버로 gRPC 통신을 수행할 수 없습니다. 따라서 Envoy와 같은 Proxy 서버를 통해 요청을 Forwarding 해야합니다.

또 다른 방법으로는 gRPC 서버와 브라우저 사이에 Aggregator 서버를 별도로 두어 Aggregator와 브라우저간에는 REST 통신을 수행하고 Aggregator와 gRPC 서버간에 gRPC 통신을 수행하는 방법을 사용해야합니다.

2) Stub 관리 비용 추가

Client와 Server는 Stub 클래스를 통해 서로 통신을 수행합니다. 하지만 요구사항 변경으로인해 Stub 클래스 변경이 필요할 때 Server에서 변경한 내용을 Client에서도 적용을 해야합니다. 이 경우 버전 차이로 인한 하위 호환성 문제가 발생할 수 있기 때문에 서비스간 Stub 관리 방법을 정의해야합니다.

가장 많이 사용하는 방법으로는 Proto 파일을 중앙에서 gitops 형식으로 관리하고 변경이 생겼을 때 이를 감지하고 언어별로 컴파일하여 Stub 클래스를 라이브러리 형태로 배포하는 방법을 많이 사용합니다.

마치며

이번 포스팅에서는 gRPC가 MSA 환경에서 왜 대두되었는지 기존의 방식과 어떠한 차이점이 있는지에 대해서 간략하게 알아봤습니다. 다음 포스팅에서는 gRPC와 REST를 다각도로 비교해보면서 gRPC가 어떠한 장점이 있는지를 분석해보겠습니다.

Spring Boot Excel 업로드 라이브러리 개발기

cla9 — Mon, 23 Nov 2020 22:07:04 +0900

서론

Excel Upload 기능이 필요하여 많이쓰는 POI 라이브러리를 살펴보았으나, 2가지 아쉬운점이 있었습니다.

1. 비즈니스 로직과 POI 라이브러리 코드의 강결합
2. DOM과 SAX 방식은 코드 작성 방법이 달라 둘 다 쓰는데 있어 유지보수의 어려움

DOM 방식

try {
    Workbook workbook = WorkbookFactory.create(file.getInputStream());
    Sheet sheet = workbook.getSheetAt(0);
    for(int i = 0 ; i < sheet.getPhysicalNumberOfRows() ; i++){
        final Row row = sheet.getRow(i);
        for(int j = 0; j < row.getPhysicalNumberOfCells(); j++){
            final Cell cell = row.getCell(j);
            //Business Code
        }
    }
} catch (IOException e) {
    e.printStackTrace();
}

SAX 방식

try {
    OPCPackage pkg = OPCPackage.open(file.getInputStream());
    XSSFReader r = new XSSFReader(pkg);
    SharedStringsTable sst = r.getSharedStringsTable();
    StylesTable styles = r.getStylesTable();
    XMLReader parser = XMLHelper.newXMLReader();


    SAXSheetHandler sheetHandler = //사용자가 정의한 SAXSheetHandler(? extends DefaultHandler)
    ContentHandler handler = new XSSFSheetXMLHandler(styles, sst, sheetHandler, false);
    SAXRowHandler rowHandler = new SAXRowHandler();


    parser.setContentHandler(handler);
    try (InputStream sheet = r.getSheetsData().next()) {
        parser.parse(new InputSource(sheet));
    }
}
catch (Exception e) {
     e.printStackTrace();
}

이러한 문제를 어떻게 해결할 수 있을까 고민하던 와중 우아한 형제들 Excel 기술 블로그를 보고 영감을 얻어 Excel 업로드 라이브러리를 개발하기로 했습니다. 이번 포스팅은 개인 프로젝트로 진행한 라이브러리 설계 과정과 적용 기술 및 개발 당시 어려움을 겪은 내용을 다루겠습니다.

라이브러리 사용법 및 공식 문서는 Github 및 Wiki 페이지를 참고하시기 바랍니다.

개발 과정

먼저 개발에 앞서 필요 기능을 리스트업 했습니다.

1. DOM과 SAX 방법에 대한 추상화된 API를 제공해야한다.

2. Streaming 방식과 Collection 방식을 제공해야한다.

3. 사용자 코드에서 POI 코드가 직접적으로 의존되지 않아야한다.

4. 학습비용이 낮아야한다.

5. 다국어 처리를 지원해야한다.

6. Validation 기능을 제공해야한다.

1. DOM 과 SAX 방식에 대한 공통 API 구현

POI에서 제공하는 DOM과 SAX 방식은 구현 방법이 완전히 다릅니다. 그 이유는 제공하는 API도 다를 뿐더러 DOM 방식은 Pull 방식, SAX 방식은 Push 방식으로 Parsing 결과를 제공하기 때문입니다.

따라서, 먼저 이러한 두 가지 방법에 대해서 공통으로 처리할 수 있는 API를 설계하고 이를 Interface 제공하도록 구상하였습니다.

위와 같이 interface를 정의하면 사용자는 구현의 Detail은 알 필요없이 API 호출만으로 SAX 방식 혹은 DOM 방식으로 결과를 얻을 수 있습니다.

두번째는 Excel 파일에서 데이터를 Parsing하기 위해서는 Sheet에 대한 처리, 각각의 Row에 대한 처리가 필요합니다. 따라서, 이전과 마찬가지로 Row와 Sheet에 대한 각각의 inteface를 정의한 다음 각각의 Reader는 interface에 의존함으로써, 공통화된 기능을 제공할 수 있도록 설계했습니다.

public class ReaderFactory {
    private final ExcelMetaModelMappingContext context;
    
    public ReaderFactory(ExcelMetaModelMappingContext context) {
        this.context = context;
    }
    
    public <T> Reader<T> createInstance(ReaderType type, Class<T> tClass)  {
        final boolean isCached = context.hasMetaModel(tClass);
        if (type == ReaderType.WORKBOOK) {
            return isCached ? new WorkBookReader<>(tClass, context.getMetaModel(tClass)) : new WorkBookReader<>(tClass);
        }
        return isCached ? new SAXReader<>(tClass, context.getMetaModel(tClass)) : new SAXReader<>(tClass);
    }

    public  <T> Reader<T> createInstance(Class<T> tClass){
        final ExcelBody entity = tClass.getAnnotation(ExcelBody.class);
        return createInstance(entity.type(), tClass);
    }
}

여기에, Factory 클래스를 추가하여 사용자가 Enum 값으로 SAX 혹은 DOM(WorkBook) 방식 중 하나를 지정하면, 그에 해당하는 Excel Reader를 생성하도록 추가하였습니다. 지금까지 설명한 내용을 도식화하면 위 그림과 같습니다.

2. Annotation 기반 메타 정보 작성

Excel로 읽는 각 Row 데이터는 결국 특정 Entity로 변환되어 DB에 저장되거나 비즈니스 로직에서 사용될 것입니다. 이러한 Entity를 POJO스럽게 유지하면서도 라이브러리에서 필요한 다양한 메타 정보를 기록할 수 있는 방법 중 하나는 @Annotation 활용입니다. Spring 환경에서 개발하면, 다양한 Annotation을 접하게 되는데, 라이브러리를 개발함에 있어서도 이러한 Annotation을 사용하여 Entity 클래스내에 라이브러리 코드가 직접 침투되지 않도록 설계하였습니다.

또한, Annotation을 사용함에 있어 JPA와 유사한 스타일을 적용하면, 학습곡선을 많이 낮출 수 있다고 생각하여 비슷하게 디자인했습니다.

@ExcelBody(dataRowPos = 3, 
           type = ReaderType.SAX,
           headerRowRange = @RowRange(start = 1, end = 2),
           messageSource = PersonMessageConverter.class)
@ExcelBody(dataRowPos = 2)
@ExcelMetaCachePut
@ExcelColumnOverrides({
        @ExcelColumnOverride(headerName = "생성일", index = 8, column = @ExcelColumn(headerName = "생성일자")),
        @ExcelColumnOverride(headerName = "수정일", index = 10, column = @ExcelColumn(headerName = "수정일자"))
})
public class Person extends BaseAuditEntity{
    @ExcelColumn(headerName = "이름")
    @NotNull
    private String name;
    
    @Merge(headerName = "전화번호")
    @ExcelColumnOverrides(@ExcelColumnOverride(headerName = "집전화번호", index = 5, column = @ExcelColumn(headerName = "휴대전화번호", index = 4)))
    private Phone phone;
    
    @ExcelEmbedded
    private Address address;
    
    @ExcelColumn(headerName = "생성일자")
    @DateTimeFormat(pattern = "yyyyMMdd")
    private LocalDate createdAt;
    
    @ExcelColumn(headerName = "성별")
    @ExcelConvert(converter = GenderConverter.class)
    private Gender gender;
}

결과적으로 위와 같이 Entity내 라이브러리 코드 작성 없이 메타 Annotation을 작성하게되면, 라이브러리 코드내에서 해당 Annotation 정보들을 참조하여 Entity 생성 및 데이터를 주입할 수 있도록 하였습니다.

(사용법은 Excel-Parser Wiki 페이지를 참고하시기 바랍니다)

3. Reflection 활용

사용자 코드에서 무엇을(What) 처리 해야할지 명시하고 어떻게(How) 처리해야할지는 기술하지 않았습니다. 즉 원하는 바만 선언하였으니, 라이브러리내에서 메타 정보를 읽어들여 사용자가 원하는대로 처리하고 반환 해야합니다.

Java에서는 Runtime 시점에 Reflection을 통해서 Instance 및 Class의 내부 정보를 알 수 있는 방법을 제공합니다. 따라서 이를 활용해서 라이브러리 내부에서 Annotation 분석 → 데이터 Parsing → Entity 생성 → 데이터 주입 → 데이터 Validation 검증 과정 순서대로 처리할 수 있도록 구상하였습니다.

위 4가지 단계에서 데이터 Parsing은 SAX Reader, WorkBook Reader가 담당하는 것을 이전 내용을 통해 확인했습니다.

따라서, Annotation 분석과, Entity 생성을 위해 이를 담당할 Class를 추가로 생성하였습니다.

ExcelEntityParser와 EntityInstantiator는 Reflection을 활용하여, Entity 내부를 탐색하는 과정을 담당합니다. Parser는 이 과정에서 Entity에 작성된 Annotation의 유효성 검증 및 헤더 정보 등을 취합하는 역할을 담당하고, Instantiator는 Entity를 생성하고, Parser에서 취합된 헤더 정보를 토대로 데이터를 주입하는 역할을 담당합니다.

public class ExcelEntityParser implements EntityParser {
    ...(중략)...
    private void doParse() {
        visited.add(tClass);
        findAllFields(tClass);
        final int annotatedFieldHeight = extractHeaderNames();

        calcHeaderRange(annotatedFieldHeight);
        validateHeaderRange();
        calcDataRowRange();
        validateOverlappedRange();
        extractOrder();
        validateOrder();
        validateHeaderNames();
    }
    
    ...(중략)...
    private void findAllFields(final Class<?> tClass) {
        ReflectionUtils.doWithFields(tClass, field -> {
            final Class<?> clazz = field.getType();

            if(field.isAnnotationPresent(ExcelConvert.class)){
                final Class<?> converterType = field.getAnnotation(ExcelConvert.class).converter();
                if(!converterType.getSuperclass().isAssignableFrom(ExcelColumnConverter.class)){
                    throw new InvalidHeaderException(String.format("Only ExcelColumnConverter is allowded. Entity : %s Converter: %s",this.tClass.getName(), converterType.getName()));
                }
            }
            else if(instantiatorSource.isSupportedDateType(clazz) && !field.isAnnotationPresent(DateTimeFormat.class)){
                throw new InvalidHeaderException(String.format("Date Type must be placed @DateTimeFormat Annotation. Entity : %s Field : %s ", this.tClass.getName(), clazz.getName()));
            }
            else if(!instantiatorSource.isSupportedInjectionClass(clazz) && visited.contains(clazz)){
                throw new UnsatisfiedDependencyException(String.format("Unsatisfied dependency expressed between class '%s' and '%s'", tClass.getName(), clazz.getName()));
            }

            if (instantiatorSource.isSupportedInjectionClass(clazz)) {
                declaredFields.add(field);
            } else {
                visited.add(clazz);
                findAllFields(clazz);
                visited.remove(clazz);
            }
        });
    }
    ...(중략)...
}

public class EntityInstantiator<T> {
    ...(중략)...
    public <R> EntityInjectionResult<T> createInstance(Class<? extends T> clazz, List<String> excelHeaderNames, ExcelMetaModel excelMetaModel, RowHandler<R> rowHandler) {
        resourceCleanUp();
        final T object = BeanUtils.instantiateClass(clazz);

        ReflectionUtils.doWithFields(clazz, f -> {
            if (!excelMetaModel.isPartialParseOperation()) {
                instantiateFullInjectionObject(object, excelHeaderNames, excelMetaModel, f, rowHandler);
            } else if (excelMetaModel.getInstantiatorSource().isCandidate(f)) {
                instantiatePartialInjectionObject(object, excelHeaderNames, excelMetaModel, f);
            }
        });

        if (excelMetaModel.isPartialParseOperation()) {
            setupInstance(excelHeaderNames, excelMetaModel.getInstantiatorSource(), rowHandler);
        }

        return new EntityInjectionResult<>(object, List.copyOf(exceptions));
    }
    
    ...(중략)...
    private <U> void setupInstance(final List<? extends String> headers, EntitySource entitySource, final RowHandler<U> rowHandler) {
        for (int i = 0; i < instances.size(); i++) {
            if (Objects.isNull(instances.get(i))) continue;

            Field field = instances.get(i).field;
            Class<?> type = field.getType();
            field.setAccessible(true);
            String value = rowHandler.getValue(i);

            try {
                final Object instance = instances.get(i).instance;
                if (!StringUtils.isEmpty(value)) {
                    inject(entitySource, field, type, value, instance);
                }
                validate(instance, headers.get(i), value, field.getName()).ifPresent(exceptions::add);
            } catch (IllegalAccessException | ParseException e) {
                addException(headers, field, value, e.getLocalizedMessage());
            }

        }
    }    
    ...(중략)...
}

Entity Parser와 Instantiator까지 적용되면, 라이브러리로 Excel Parsing 요청시, 위 흐름대로 처리되는 것을 이해할 수 있습니다.

삽질의 시작

이전 내용을 토대로 기본적인 구현을 마친 이후 테스트를 해보자 몇가지 추가 고민이 생겼습니다. 그리고 이것은 이후 시작되는 삽질의 첫삽을 푼 순간이었습니다.

고민거리

Entity에 지정된 Annotation 유효성 검증을 런타임에 수행하는데, Spring Boot 기동시점인 로드 타임에 검증하는 것이 더 좋지 않을까?
Maven Central에 배포해보자!!!

삽질 1. 대상 Entity 클래스 Scanning

Spring Boot 기동 시점에 검증을 하려면, Excel Parser 라이브러리의 대상 Entity를 모두 찾을 수 있어야 합니다. 따라서, Spring에서 Bean Scanning 하는 코드 및 관련 클래스를 사용해야겠다고 생각했지만 검색 능력의 부족으로 인해 찾는데 많은 어려움을 겪었습니다. 많은 시행착오 끝에 ClassPathScanningCandidateComponentProvider 클래스가 해당 기능을 제공하는 것을 확인할 수 있었습니다.

ClassPathScanningCandidateComponentProvider provider = new ClassPathScanningCandidateComponentProvider(false);
provider.findCandidateComponents("base 패키지명");

삽질 2. Default base 패키지명은 어떻게 알 수 있을까?

ClassPathScanningCandidateComponentProvider 클래스를 통해 base 패키지명을 String 타입으로 전달하면, 하위 패키지내 클래스를 탐색하는 기능을 제공해줌을 알 수 있습니다.

여기서 한가지 의문이 들었습니다.

'Spring Data JPA에서는 @EnableJpaRepositories Annotation을 통해 basePackages를 입력하지 않아도 Repository Bean을 만들 수 있었는데, 어떤 원리로 그런것일까? '

이것을 알기위해 구글링을 해봤지만, 어떠한 keyword로 검색해야할지 몰라 정확한 정보를 찾을 수 없었습니다.

(대부분 @EnableJpaRepositories 설정 방법이나 basePackage를 지정하는 방법 관련된 검색결과가 대다수였습니다.)

결국, 선택한 방법은 코드내 EnableJpaRepositories 부터 시작해서 관련된 클래스 Debugger를 걸어놓고 코드를 따라 거슬러 오르는 방법이었습니다.

EnableJpaRepositores 검색결과

추적끝에 찾은 결과는 위와 같습니다. @EnableJpaRepositories 어노테이션을 Configuration 클래스에 선언하면, JpaRepositoriesRegistrar 클래스 정보가 같이 Import 됩니다. 이때, JpaRepositoryConfigExtension 클래스가 Bean으로 등록됩니다. 그리고 RepositoryConfigurationDelegate에게 Bean 탐색을 위임합니다.

이때, basePackages를 설정하게 되는데, 사용자가 지정한 @EnableRepositories Package 정보를 가져와서 지정합니다.

JpaRepositoriesAutoConfiguration은 JpaRepository 관련 자동설정을 하는데, JpaRepositoryConfigExtension 클래스가 Bean으로 등록되어있으면, 관련 자동설정을 하지 않습니다. @EnableJpaRepositories Annotation을 사용자가 지정했다면, 이전에 설명했듯이, JpaRepositoryConfigExtension가 Bean으로 등록되었기 때문에 자동설정을 하지 않습니다.

반면 @EnableJpaRepositories Annotation이 존재하지 않는다면, 마찬가지로 RepositoryConfigurationDelegate에게 Bean 탐색을 위임합니다. 이때 사용되는 basePackges는 AutoConfigurationPackages.get 메소드를 통해 얻을 수 있습니다. 그리고 해당 메소드가 바로 Spring Boot에서 사용되는 기본 basePackges 정보임을 알 수 있었습니다.

삽질 3. JPA는 되는데 난 안돼!!!

Spring Data JPA에서 사용되는 자동설정 Idea를 토대로 개발중인 라이브러리에 적용하기로 했습니다.

@EnableExcelEntityScan Annotation과 AutoConfiguration 클래스를 만들어서 사용자가 Annotation을 지정하여 basePackage를 지정하지 않으면 AutoConfiguration의 설정을 따르도록 했습니다.

하지만 아무리 AutoConfigurationPackages.get 메소드를 호출해도 Bean 정보가 없다는 Exception이 발생하였습니다.

처음에는 AutoConfigurationPackages.get가 아니라 혹시 다른 메소드가 이를 대신하나 싶어서 샅샅히 찾아봤지만 코드상에서는 찾을 수 없었습니다.

그렇게 한참을 삽질하다 문득 spring.factories에 EnableAutoConfiguration 설정을 하지 않았음을 알게 되었고, 설마 이것때문에? 라는 생각으로 관련 AutoConfiguration 클래스를 등록시켰습니다.

그 결과, 설정 이후에 정상적으로 basePackage 정보를 가져오는 것을 확인하고 많이 부족함을 재차 느꼈습니다.

삽질 4. Gradle기반 Spring Boot Starter 만들기

Spring Boot Starter 관련하여, Maven 기반으로 Starter를 작성하는 방법에 대해서는 다수 있지만, Gradle로 만드는 방법은 찾기 어려웠습니다. 다만 Spring Boot Starter 개념은 아래 링크에 참고된 블로그를 통해서 학습할 수 있었습니다. 한참의 삽질끝에 완성할 수 있었습니다.

참고 블로그

- nevercaution.github.io/spring-boot-starter-custom/

삽질 5. Maven Central 배포하기

운이 좋게 저보다 앞서 고생하시고 그 기록을 남겨주신 siyoon210님 블로그를 통해서 다른 과정과 비교했을 때 큰 문제 없이 업로드할 수 있었습니다.

마치며

숲을 제대로 모른 상태에서 나무만 보면서 만들다보니 삽질이 많았습니다. 하지만 그런 시행착오를 겪으면서 배워서 그런지 학습한 내용이 보다 오랫동안 기억에 남을 것같습니다. 공식 문서에 사용법에 대해서 작성했으나 나중에 기회가된다면 튜토리얼 포스팅을 작성해볼까 합니다. 관련된 자료는 아래 링크를 참고하시기 바랍니다.

마지막으로 해당 라이브러리에 대한 코드기여는 언제나 환영입니다.

GitHub : Excel-Parser

Documentation : Excel-Parser Wiki

2. Redis 샤딩

cla9 — Tue, 11 Aug 2020 22:03:46 +0900

서론

이전 포스팅에서 Redis의 기본적인 구조와 복제(Replication)에 대해서 살펴봤습니다.

잠시 복기해보자면, 복제는 Master의 데이터를 Replica에 모두 저장하여 가용성과 읽기 작업의 성능을 높일 수 있습니다.

하지만 데이터 양이 폭발적으로 증가한다면 어떻게 될까요?

Replication은 모든 데이터를 복제해야하기 때문에 단일 서버에서 저장 가능한 Memory를 초과하면 이를 복제할 수 없습니다. 따라서 메모리 증설등을 통한 Scale-Up 만으로 데이터 저장 공간을 확보할 수 없다면 다른 방법이 필요합니다.

이번 포스팅에서는 데이터 분산을 통해 고가용성을 확보할 수 있는 파티셔닝 개념과 Redis에서 사용되는 샤딩전략 그리고 Cluster에 대해 다루도록 하겠습니다.

1. 파티셔닝 개념

파티셔닝은 DB의 관리 용이성 및 읽기 최적화를 위해 논리적인 테이블의 물리 구조를 여러개의 파티션(Partition)으로 분할하여 분산 저장하는 기법을 말합니다. 파티셔닝 개념에 대한 이해를 돕기위해 잠시 RDBMS에서의 파티셔닝에 대해서 간략하게 알아보겠습니다.

위 그림과 같은 회원 테이블이 존재한다고 가정해봅시다. 이때 가입자가 매일 증가하여 테이블 크기가 점점 커진다면, 해당 테이블에 조회 성능을 높이기 위해 인덱스 추가등의 작업이 쉽지 않을 뿐더러 점차 조회 성능도 떨어지게 됩니다.

가령 수십억건의 데이터가 존재하는 테이블에서 매월마다 가입일이 5년지난 데이터를 삭제해야 한다면 어떻게 해야할까요?

데이터를 지우기 위해서 수십억건의 테이블을 탐색하면서 조건에 해당하는 데이터를 삭제해야합니다. 이렇게 되면 오랜시간동안 Lock으로 인해 동시성 저하가 발생할 수 있으며, 테이블 크기가 점점 더 커질 수록 해당 작업은 어려워질 것입니다.

설령 가입일에 인덱스가 생성되어있다 할지라도 디스크 Random I/O로 인해 좋은 성능이 나오지 않을 뿐더러 데이터 지속 삭제로 인해 인덱스 Sparse 현상이 발생할 수 있습니다.

따라서, 이러한 경우 사용자에게 논리적으로 보여지는 테이블은 하나이지만 기저에 물리적으로는 여러 파티션에 데이터를 나누어 저장한다면, 조회 성능 향상 및 관리가 용이해집니다.

위 그림은 가입일 기준으로 20년 1월에 발생한 데이터는 202001 파티션에 저장하도록 하였고, 2월에 가입한 회원들은 202002 파티션에 저장되도록 파티션을 구성하였습니다.

이와같이 가입일 기준으로 파티션을 구성하면 다음과 같은 이점이 있습니다.

만약 매월 가입일 기준으로 사용자를 삭제한다면, 기존에는 테이블내 모든 데이터를 탐색해야했지만 지금은 특정 월에 해당하는 파티션만 Drop(DDL 작업) 하면 되므로 작업 부담이 줄어듭니다.

그리고 특정 월에 해당하는 데이터를 조회할 때, 해당 파티션에 속한 데이터에 대해서만 Multi block I/O를 실시할 수 있기 때문에 인덱스를 사용하는 방법보다 빠른 조회가 가능할 수 있습니다.

정리하자면 파티셔닝은 위 사례와 같이 대용량의 논리적 구조를 여러 물리적인 파티션으로 분할하여 조회 및 관리 용이성을 위해 사용됩니다.

2. 파티셔닝 종류

이번에는 파티셔닝 종류에 대해서 알아보겠습니다. 파티셔닝은 수직적 파티셔닝과 수평적 파티셔닝 2가지 종류가 있습니다.

수평적 파티셔닝은 이전 파티셔닝 개념에서 살펴보았듯이, 특정 데이터(가입일) 기준으로 데이터를 다른 파티션에 저장하는 방법을 말합니다.

반면, 수직적 파티셔닝은 특정 컬럼을 기준으로 데이터를 분할하는 방법을 말합니다. 위 그림과 같이 기존 회원 테이블을 특정 컬럼을 기준으로 2개의 파티션으로 분할한 경우가 이에 해당됩니다.

수직적 파티셔닝의 이점은 한쪽 세그먼트에서 발생하는 DML이 다른쪽에 영향을 끼치지 않습니다. 반면, 레코드 전체 데이터를 읽어야할 경우에는 데이터가 물리적으로 분산되었으므로 I/O에서 다소 비효율이 발생합니다.

그렇다면, NoSQL 제품군에서 주로 사용되는 샤딩(Sharding)은 무엇일까요?

샤딩이란 수평적 파티셔닝의 한 종류입니다. 수평적 파티셔닝과 비교하여 다른점은 파티셔닝은 단일 DBMS내에서의 데이터 분할 정책이고, 샤딩은 분할된 여러 데이터베이스 서버로 데이터를 분할하는 방법입니다.

따라서, 샤딩을 구성하게되면 샤드의 수만큼 노드가 존재하며, 서버가 여러대 존재하므로 부하를 적절히 분산할 수 있는 장점이 있습니다.

지금까지 파티셔닝 종류에 대해서 알아봤습니다. 용량을 고려하여 데이터 크기를 분할할 때, 수직적 파티션보다는 수평적 파티션이 분배에 용이하므로 이후 내용은 수평적 파티셔닝 전략을 기준으로 작성하였음을 참고바랍니다.

3. 파티셔닝 전략

이전에 살펴본 예제는 가입일 컬럼 대상 특정 월을 기준으로 데이터 파티션을 나누었습니다. 이때 특정 범위를 기준으로 데이터를 분할한 파티션을 Range 파티션이라고 합니다.

Range 파티셔닝의 장점은 논리적인 범위의 분산에 효율적입니다. 또한, 원하는 데이터가 특정 파티션에 모여있어 관리하기가 용이합니다.

이렇듯 사용자가 원하는대로 데이터를 분산시킬 수 있는 장점이 있지만 다음과 같은 문제점을 지니고 있습니다. 사례를 통해 Range 파티션의 문제점을 알아보겠습니다.

만약 대한민국 전체 국민의 개인정보를 관리하는 시스템 테이블에서 사람들의 나이 10살 범위 기준으로 Range 파티셔닝 했다고 가정해보겠습니다.

출처 : 국가 통계 포털 20년 7월 기준 대한민국 인구 통계

차트를 통해 알 수 있듯이 50대 파티션에 가장 많은 데이터가 적재되며 파티션별로 데이터 편차가 크게 나는 것을 확인할 수 있습니다.

이를 통해 알 수 있는 사실은 Range 파티셔닝의 가장 큰 문제점은 데이터 분포도가 고르지 못할 경우 데이터 배분을 균등하게 할 수 없습니다.

지금까지 RDBMS 테이블 구조로 Range 파티션 구조를 살펴보았습니다. 만약 Redis로 회원 데이터를 샤딩하면 어떤 모습일까요?

대략 위 그림과 같이 전체 데이터를 특정 범위로 나뉘어 각각의 Master 서버에게 할당할 것입니다. 그리고 범위에 따른 파티션 지정의 책임은 Client에게 있는 것을 확인할 수 있습니다.

이처럼 Redis에서의 샤딩 전략은 RDMBS 파티셔닝과 차이가 존재합니다.

RDBMS의 경우에는 테이블 생성시, 파티션 전략을 지정하면, 이후 데이터 입력이나 조회가 필요할 경우에는 테이블을 대상으로 입력/조회 작업을 수행합니다. 그러면 옵티마이저가 적당한 파티션으로 분배할 것입니다.

하지만 Redis에서 파티셔닝 전략을 사용하려면 데이터 분배 책임은 Client에게 있습니다. 다시말해 이는 Client에서 데이터를 어디에 저장할지 혹은 데이터를 어디서 찾아야할지를 정해야함을 의미합니다.

Range 파티셔닝의 경우에는 특정 범위와 이에 해당하는 Master 노드를 매핑시키는 Mapping 테이블이나 Client 로직에 범위를 지정하여 분배하는 로직이 들어가야 합니다. 또한 데이터를 균등하게 분배하기 위해서는 철저한 전략 수립이 필요합니다.

결론적으로 Range 파티셔닝을 구현하는 것은 꽤 번거로운 일입니다. 공식 홈페이지에서 해당 내용에 대해서 다루고 있으며, 데이터 균등 분배를 위해 다음에 설명할 해시 파티셔닝 전략을 사용하는 것을 권하고 있습니다.

해시 파티셔닝

Redis에서 샤딩을 구현하기 위해서는 데이터를 서버별로 균등하게 분포해야 부하를 고르게 분산할 수 있습니다. 따라서 Range 파티셔닝은 데이터가 고르게 분포되지 못하므로 적절하지 못합니다. 이번에는 해시 파티셔닝을 통해서 데이터를 균등분배 하는 방법에 대해서 알아보겠습니다.

해시 파티셔닝은 Redis의 Key 값에 대하여 해시함수를 적용한 결과를 Redis Master의 개수만큼 나머지 연산을 토대로 데이터를 저장할 Master 서버를 지정하는 방법입니다.

다음과 같이 hash 함수를 적용한 다음 Modulo 연산을 통해서 데이터를 저장하거나 찾아야할 Redis 노드를 지정할 수 있습니다.

var hosts = {Master1, Master2, Master3, ... }
var index = hash(key) % hosts.length;

예를들어 Master 서버가 3대가 있고, 이를 배열로써 담았다고 가정합시다.

그러면 master1번은 0번 인덱스, master2는 1번 인덱스, master3은 2번 인덱스가 될 것입니다.

이때, Redis Key에 대하여 hash 함수를 적용한 결과가 1934라면 1934 % 3(서버 개수) 의 결과인 2에 해당하는 Master 3노드가 해당 Key의 저장소가 되며, 데이터를 조회할 때도 Client는 해당 저장소에서 데이터를 찾으려고 할 것입니다.

해시파티셔닝의 경우에는 Modulo 연산을 통해 데이터의 분포여부와 상관없이 고르게 분포시킬 수 있는 장점이 있어 주로 사용되는 전략입니다.

Rebalancing 문제

지금까지 Redis의 샤딩, Range 파티셔닝의 문제점 및 해시 파티셔닝을 통한 데이터 균등 분배 방법에 대해서 살펴봤습니다.

만약 해시 파티셔닝이 적용된 상황에서 데이터 용량이 더욱 커져 Master 서버 추가를 해야한다면, 어떤 이슈가 존재할까요? 사례를 통해서 알아보겠습니다.

위 그림과 같이 현재 총 12개의 데이터가 3개의 Master 서버에 고르게 분배되어있다고 가정해봅시다. 위와 같은 상황에서 Hash 함수 결과가 9를 저장하고 있는 Master는 9 % 3(서버 대수)에 의하여 Master 1번이 선택될 것이고 Client는 해당 연산을 통해서 Master1번에게 질의할 것입니다.

이러한 상황에서 Master4를 새롭게 추가한다고 가정해봅시다.

위와 같은 상황에서 기존과 같이 Hash 함수 9의 결과를 가지고 있는 Redis 서버를 찾고자하면 어떤일이 발생할까요?

서버의 개수가 증가하였으므로 9 % 4 = 1이되어 엉뚱한 서버에 질의 하는 결과를 낳게 됩니다.

따라서, 서버를 추가할 경우에는 그에 맞게 데이터의 재분배(Rebalancing) 작업이 필요합니다.

그럼 데이터 재분배를 진행한 결과를 살펴보겠습니다.

위 그림에서 초록색으로 표기된 데이터는 원래 노드에서 새로운 노드로 재분배된 데이터를 의미합니다.

이를 통해서 알 수 있는 사실은 Master 노드 추가 이후 75%의 데이터가 재분배 작업을 통해 다른 노드로 이전하였음을 확인할 수 있습니다. 이는 데이터를 재분배하는 과정에서 굉장히 많은 부하가 발생할 수 있으며, 운영중에 노드 추가 작업이 자유롭지 못함을 의미합니다.

따라서 단순 Modulo를 적용한 해시파티셔닝 전략으로는 신규 노드 추가/삭제 작업으로부터 자유롭지 못합니다.

그렇다면 어떻게 하면 데이터 재분배 작업을 최소화할 수 있을까요?

Consistent Hashing

이전에 살펴보았듯이, 노드 추가에 따른 Rebalancing 부하를 줄이기 위해서는 재분배되는 데이터 양이 적어야 합니다.

Consistent Hashing 기법은 데이터와 더불어 Master 서버에 대하여 동일한 해시 함수를 적용하고, Master 서버 해시값 구간에 해당되는 데이터를 저장하는 방법입니다.

예를 들어 설명하겠습니다.

위 그림과 같이 Redis Master 노드에 대하여 해시함수를 적용합니다.

그리고 해시함수 결과를 기준으로 데이터를 처리할 Master 노드를 결정합니다.

노드	데이터 담당 범위
Master1	해시값 <= 10724 OR 해시값 > 12345
Master2	10725 < 해시값 <= 11224
Master3	11224 < 해시값 <= 11965
Master4	11965 < 해시값 <= 12345

Case 1. 해시값 10756 데이터 입력시

Redis Master 서버에 대하여 해시 함수가 적용된 상황에서 해시 값이 10756인 데이터가 입력되었다고 가정해봅시다.

이는 10724보다는 크고 11224보다는 작으므로 Master2 노드가 해당 데이터의 저장소로 선정됩니다.

Case 2. 12086 해시값 데이터 입력시

12086 해시값 데이터가 입력되면, 12345 보다 작고 11965보다 크므로 Master4 노드가 해당 데이터의 저장소가 됩니다.

Case 3. 13567 해시값 데이터 입력시

12345보다 큰 값이 입력되었으므로, 해당 데이터의 저장소는 Master 1번이 됩니다.

Case 4. 5576 해시값 데이터 입력시

10724보다 작은 데이터가 입력되었으므로 해당 데이터의 저장소는 Master 1번이 됩니다.

이렇듯 Consistent Hashing 기법에서는 서버를 추가하면 해시 함수를 적용하여 Hash Ring 형태로 만듭니다. 이후 입력되는 데이터는 해시 값 결과에 따라 저장소가 결정됩니다.

그렇다면 위와 같은 상황에서 노드가 삭제되거나 추가될 때 효율적인 Rebalancing이 일어날까요? Master 1 노드를 제거하는 상황을 가정해보겠습니다.

Master1 노드 삭제로 인해 Master1 노드가 가지고 있던 데이터를 재분배 해야하는 상황입니다. 따라서, 지금 상황에서는 Master2 노드가 Master1 노드의 데이터를 전부 이관 받아야하는 상황이며, 이는 효율적으로 데이터 재분배가 일어났다고 보기 힘듭니다.

그렇다면, 어떻게 해야 데이터를 효율적으로 나눌 수 있을까요?

가상 노드 추가

Hash Ring에 단일 노드만 배치하니까 발생한 문제는, 노드를 제거했을 때, 인접해있는 다른 노드 하나에 모든 데이터를 이관해야하는 문제점이 있습니다. 따라서 이를 해소하는 방법은 Hash Ring에 여러 가상 노드를 배치하는 것입니다.

위와 같이 하나의 노드가 아니라 여러개의 가상 노드를 Hash Ring에 배치하면, 노드와 데이터사이 해시 값 범위가 좁아집니다. 따라서 이런 상황에서 Master1 노드를 제거하면, 해당 노드의 데이터가 다른 노드로 적절히 분배될 수 있습니다.

위 사례는 Master1번 노드가 삭제된 이후 Master1번 노드가 가지고 있었던 데이터(빨간색 음영)가 다른 노드로 적절히 분산되었음을 확인할 수 있습니다.

만약, 노드를 추가할 경우에는 특정 노드가 담당하고 있던 적은 범위의 데이터 영역을 재분배합니다.

정리하자면, 해시 파티셔닝을 사용함으로 인하여 데이터를 균등하게 분포하면서, 데이터 재분배에 대한 영향도를 최소화 하기 위해서 Consistent Hashing 알고리즘을 이용할 수 있습니다. Consistent Hashing 알고리즘을 사용시 고려 사항은 Hash Ring에 가상 노드를 촘촘하게 그리고 노드가 간격을 균일하게 배치할 수 있도록 Hash 알고리즘이 적용되야 합니다. 특정 노드간의 범위가 벌어지게된다면, 그만큼 재분배해야할 데이터 양이 많아지므로 이를 유의해야 합니다.

참고

- 강대명님 블로그

- Play Joinc님 블로그

마치며

이번 포스팅에서는 Redis 샤딩에 대해서 알아봤습니다. 처음 작성할 때 계획은 Redis Cluster까지 다루려고 했지만, 내용이 길어 여기서 마무리하도록 하겠습니다.

1. Redis 구조

cla9 — Sun, 9 Aug 2020 16:14:06 +0900

서론

지금부터 다룰 Redis 시리즈는 개인 공부 내용 정리 목적으로 작성하였습니다. 주요 포스팅 내용은 redis-cli 명령어 학습과 Spring Data Redis를 활용해서 해당 명령어 적용방법에 대해서 살펴보겠습니다.

이번 포스팅은 Redis를 다루는 첫 포스팅으로 Redis 구조에 대해서 개략적으로 살펴보겠습니다. 전문지식을 기반으로 작성한 내용이 아닌만큼 틀린 부분이 있다면 피드백 부탁드립니다.

1. Redis 접속

DBMS을 사용하기 위해서는 명령어 처리를 위한 별도 프로그램이 필요합니다. 이를 위해 각 DBMS 벤더사에서 DB와 통신을 위한 CLI(Command Line Interface) 프로그램을 제공합니다. 가령 oracle 사용한다면, oracle에서 기본적으로 제공하는 sql * plus 프로그램을 사용해서 DB에 접속할 수 있습니다.

마찬가지로 Redis를 사용하기 위해서는 Redis에 접속할 수 있는 프로그램이 필요합니다.

redis 접속화면

Redis에서는 이를 위해 redis-cli를 제공하며, Redis가 설치된 환경에서 사용자가 Redis를 사용하기 위해 가장 처음 접하게 되는 프로그램이 redis-cli입니다.

출처 : https://github.com/redis/redis

typedef struct redisObject {
    unsigned type:4;
    unsigned encoding:4;
    unsigned lru:LRU_BITS; /* lru time (relative to server.lruclock) */
    int refcount;
    void *ptr;
} robj;

Redis에 접속하게되면, redis-server는 Client 구조체로 저장하여 linked list 형식으로 관리합니다. 여기서 주목할 점은 Client 명령을 처리하기 위해 필요한 인자는 argc와 argv 멤버 변수를 통해 전달되며, 해당 구조는 redisObject 구조체로 정의되어있습니다.

해당 구조체에서 type 멤버 변수는 Redis에서 지원하는 데이터 타입을 의미합니다. 지원하는 타입 종류로는 String, List, Set, Sorted Set, Hash, Bitmap, HyperLogLogs 등이 있습니다. 각 데이터 타입에 대한 소개는 차후 포스팅을 통해 살펴보겠습니다.

그외 redisObject 구조체 각 멤버 변수에 대한 설명은 redisgate 홈페이지에 자세히 소개되어있으니 참고 바랍니다.

2. Redis 구조

출처 : 빅데이터 저장 및 분석을 위한 NoSQL & Redis 책 5.1절 Redis 아키텍처

인스턴스에 정상적으로 접속했다면, 명령어 전달을 통해 데이터를 저장하거나 조작할 수 있습니다. Redis는 In Memory 데이터 구조 저장소로써 위 그림에서 해당되는 데이터 구조는 모두 메모리에 상주합니다.

위 구조에서 Resident Area는 명령어를 통해 실제 데이터가 저장 및 작업이 수행되는 공간입니다. 초록색 영역은 내부적으로 서버 상태를 저장하고 관리하기 위한 메모리 공간으로 사용되며, Data Structure 영역으로 불립니다.

Data Structure 영역에 대한 설명은 차후 데이터 타입 포스팅을 진행할 때 다루어보겠습니다.

출처 : 빅데이터 저장 및 분석을 위한 NoSQL & Redis 책 5.1절 Redis 아키텍처

앞서 Redis는 In Memory 데이터 구조 저장소라고 설명했습니다. 하지만 Memory는 휘발성이기 때문에, 프로세스를 종료하게되면 데이터는 모두 유실됩니다. 따라서 단순 캐시용도가 아닌 Persistence 저장소로 활용을 위해서는 Disk에 저장하여 데이터 유실이 발생되지 않도록 해야합니다. 이를 위해 AOF(Append Only File)기능과 RDB(Snapshot) 기능이 존재합니다.

AOF는 전달된 명령을 별도에 파일에 기록하는 방법으로 RDBMS의 Redo 메커니즘과 유사합니다. AOF의 역할은 재기동시 파일에 기록된 명령어를 일괄 수행하여 데이터를 복구하는데 사용됩니다.

AOF의 장점으로는 데이터 유실이 발생하지 않습니다. 하지만 매 명령어마다 File과의 동기화가 필요하기 때문에 처리속도가 현격히 줄어듭니다. 따라서 이를 해소하기위해 File Sync 옵션(appendfsync)이 존재하며, 해당 옵션에 따라 Sync 주기를 조절할 수 있으나 그만큼 데이터 유실이 발생할 수 있습니다.

반면 RDB는 특정 시점의 메모리 내용을 복사하여 파일에 기록하는 방법으로 RDBMS Full Backup에 해당합니다. 따라서, 정기적 혹은 비정기적으로 저장이 필요할 시점에 데이터를 저장이 가능합니다.

RDB의 장점으로는 AOF에 비해 부하가 적으며, LZF 압축을 통해 파일 압축이 가능합니다. 또한 덤프파일을 그대로 메모리에 복원(Restore)하므로 AOF에 비해 빠릅니다. 반면 덤프를 기록한 시점이후 데이터는 저장되지 않으므로 복구시에 데이터 유실이 발생할 수 있는 문제점이 있습니다.

AOF와 RDB를 사용할 때는 유의해야할 점이 있습니다. 바로 Copy On Write입니다. AOF를 백그라운드로 수행하거나 RDB를 수행할때 redis-server에서 자식 프로세스를 fork하여 처리를 위임합니다. 만약 이과정에서 redis-server의 데이터에 쓰기 작업을 수행한다면, 기존 페이지를 수정하는 것이 아닌 이를 별도 공간에 저장 후 처리합니다. 따라서 해당 작업을 수행도중에 쓰기 작업이 증가한다면, 메모리 사용량이 급격히 증가될 수 있습니다.(최대 2배) 따라서 이를 유의해야합니다.

3. Redis 복제(Replication)

이번에는 Redis 복제에 대해서 알아보겠습니다. 먼저 복제가 필요한 이유에 대해서 먼저 알아봅시다.

Redis는 충분히 빠르고 안정적입니다. 하지만 서비스가 갑자기 잘되어 트래픽이 몰린다면 어떻게 될까요?

서버의 한계점을 넘어간다면, 인스턴스 장애가 발생할 수 있습니다. 이때 만약 단일 인스턴스로만 구성되었다면, Redis의 장애가 모든 Application에 영향을 미칩니다.

한편, Redis를 운영하는 입장에서 버전 업그레이드 혹은 서버 PM 작업이 필요하나 Application 영향도로 인해 섯불리 작업할 수 없는 문제가 생깁니다.

마지막으로, 캐시 목적으로 사용하는 Redis는 쓰기 작업보다는 읽기 작업이 주로 발생합니다. 따라서 읽기 작업 성능을 높힐 수 있는 아키텍처 구성이 필요할 수 있습니다.

이를 위해 Redis에서는 어느정도 고가용성을 확보 및 쓰기/읽기 작업 성능을 개선할 수 있는 Master/Replica 토폴로지를 제공합니다.

1. Master/Replica 구조

위 그림은 Master/Replica의 구조를 나타냅니다.

최초 Master/Replica 구성시 Master의 데이터는 모든 Replica에 복사합니다. 따라서 어느 Redis 인스턴스에서 데이터를 조회해도 원하는 결과를 얻을 수 있습니다.

만약 데이터의 변경이 발생한다면, 변경 작업은 Master에서만 가능합니다. 이후 변경된 데이터는 비동기적으로 모든 Replica에게 전달되어 반영됩니다.

(※ replica-read-only 옵션을 no로 설정하면, Replica 상태를 변경할 수 있으나 전체 동기화가 발생하면 모두 유실되므로 추천하지 않습니다.)

이러한 과정은 Oracle Data Guard의 SQL Apply 서비스와 유사합니다. 데이터가 아닌 문장(Statement)이 전달되므로 LuaScript가 적용된 문장이라면 Master와 Replica의 결과가 다를 수 있습니다.

2. Master/Replica 동기화 과정

이번에는 Master/Replica 동기화 과정에 대해서 살펴보겠습니다.

Replica에는 Master 노드에 적재된 데이터가 하나도 존재하지 않으므로 최초 구성시에는 전체 동기화가 발생합니다.

전체 동기화 과정은 다음과 같습니다.

1. Master와 Replica 인스턴스를 별도로 구성합니다.

2. Replica 인스턴스에서 ReplicaOf 명령어를 통해 Master 인스턴스와의 동기화 명령을 수행합니다.

3. Master에서는 fork를 통해 자식 프로세스를 생성합니다.

4. 자식 프로세스에서는 Master 메모리에 있는 모든 데이터를 Disk로 dump 합니다.

5. dump가 완료되면, 이를 Replica에 전달하여 반영합니다.

6. Master에서는 복제가 진행되는 동안 변경 데이터를 Replication Buffer에 저장합니다.

7. Dump 전송이 완료되면, Replication Buffer의 내용을 Replica에게 전달하여 데이터를 최신상태로 만듭니다.

8. 작업이 완료되면, 이후에는 데이터 변경발생분만 비동기방식으로 전달됩니다.

최초 구성시에는 전체 동기화(Full Syncronization)이 발생하고, 이때 fork가 발생하므로 메모리 사용량이 증가할 수 있습니다. 따라서 이를 유의해야 합니다.

만약 Master/Replica 구성이 완료된 이후에 네트워크 지연이 발생되면 동기화는 어떻게 처리가 될까요?

ReplicaOf 명령어를 통해 Master/Replica 구조가되면, Master 인스턴스에서는 내부적으로 repl-backlog-size 옵션 만큼의 Backlog Buffer가 만들어집니다. 이후 Replica와의 단절이 발생하게 되면, Master 인스턴스에서는 변경 데이터를 Backlog Buffer에 저장합니다. Backlog Buffer는 유한한 크기를 지녔으므로, 지연이 오랫동안 발생한다면 Buffer가 넘칠 수 있습니다.

단절 이후 다시 재연결 되었을 때 과정은 다음과 같습니다.

1. Replica에서 Master와 동기화를 위해 부분 동기화를 시도합니다.

2. 만약 Backlog Buffer에 네트워크 단절 이후의 데이터가 모두 존재하면, Buffer에있는 데이터를 전달받아 최신 상태를 만듭니다.

3. 만약 오랜 시간 네트워크 단절로 인해 Backlog Buffer에 데이터가 유실되었을 경우에는 전체 동기화 과정을 진행합니다.

ADB, RDB를 설명할때도 살펴봤지만, 프로세스 fork가 일어나게되면 메모리 사용율이 급격하게 증가할 수 있으므로 전체 동기화 작업 혹은 Replica 추가 작업시에는 모니터링과 메모리 조정등이 필요합니다.

참고 :

- Redis 공식 문서

- 우아한 테크 세미나 by 강대명님

- Redis Lab

3. Master/Replica 장단점

지금까지 Master/Replica 구조에 대해서 살펴보았습니다. 해당 구조의 장점은 무엇이 있을까요?

우선 Master 인스턴스와 Replica 인스턴스간 데이터가 공유되어있습니다. 따라서 Replica 중 어느 인스턴스가 다운되더라도 Application의 영향을 최소화할 수 있습니다.

또한, 데이터 조회를 위해 굳이 Master에게 요청하지 않아도 되므로 Read 작업에 대한 부하를 여러 인스턴스로 분산시킬 수 있는 장점이 있습니다.

이번에는 Master/Replica 구성했을 경우 발생되는 문제점에 대해서 살펴보겠습니다.

Master 인스턴스에 장애가 발생하여도 다른 Replica에 데이터가 모두 복제되어있으므로 읽기 연산은 문제가 없습니다. 하지만 쓰기 작업은 Master를 통해 이루어지므로 더이상 쓰기 작업 수행될 수 없는 문제가 있습니다.

따라서 단순 Master/Replica 구성을 했을 경우에는 관리자가 모니터링을 통해 장애 여부를 감지하고, 수동으로 Replica 인스턴스 중 하나를 Master로 선정하고, 나머지 Replica에서 새로 변경한 Master를 바라보도록 설정을 변경해야합니다.

즉 다시말해 Master 인스턴스 Crash 발생 시, 자동으로 Failover 해주지 않습니다. Master/Replica를 구성하는 이유 중 하나는 고가용성을 달성하기 위함인데, Failover를 자동으로 해주지 않는 것은 운영자 입장에서는 많이 불편할 수 밖에 없습니다.

따라서 이러한 이슈를 해결하기 위해 Redis Sentinel 기능을 제공하였습니다. Sentinel은 별도의 프로세스로 Master 인스턴스 다운시, 이를 감지하여 Replica 중 하나를 Master 인스턴스로 Failover 및 이를 Application에게 통지하는 기능을 포함하고 있습니다.

참고:

- Redis 공식 홈페이지 Sentinel 소개 자료

4. Master/Replica/Sentinel 구조

위 그림은 Master/Replica/Sentinel의 구조입니다. 여기서 녹색으로 연결된 선이 Sentinel과 연결된 네트워크 Path를 의미합니다.

Sentinel은 다른 Sentinel을 포함한 모든 Redis 인스턴스와 연결합니다. 이후 1초마다 HeartBeat 통신을 통해 Master 및 Replica 서버가 정상적으로 작동중인지 여부 확인하고 이상 발생시 자동으로 Failover 및 Application에 알림을 전송합니다.

그렇다면, Sentinel을 통해 Failover는 어떤 방식으로 이루어질까요?

Sentinel과 연결된 노드 중 HeartBeat에 일정 시간동안 응답하지 않는 경우 해당 Sentinel은 장애가 발생한 것으로 간주하고 해당 노드를 주관적 다운(Subjectively Down)으로 인지합니다.

주관적 다운으로 별도 지정한 이유는 해당 Sentinel과의 일시적인 네트워크 연결이 끊긴 것일 수도 있기 때문에 정확한 장애 여부는 아직 확정할 수 없기 때문입니다.

만약 장애가 발생한 인스턴스가 Master일 경우에는 모든 Sentinel에게 Master Down 여부를 묻습니다. Master Down 여부를 전달받은 Sentinel 들은 실제 Master 인스턴스가 죽었는지를 확인 후 이를 응답합니다.

이때 Master 인스턴스에 장애가 발생했다고 응답하는 비율이 정족수(Quorum)를 넘게 되면 이를 객관적 다운(Objectively Down)이라고 인지하게됩니다. 위 구조에서는 2개의 Sentinel 인스턴스가 Master 장애를 인지하게되면, 정족수를 넘게되는 것이므로 객관적 다운으로 인지하게 됩니다.

객관적 다운이 발생하게 되면, 다른 Sentinel 인스턴스와 통신하여 장애 조치 작업을 시작합니다.

Master 장애가 발생하게 되면 더이상 쓰기 작업이 안되므로 가장 먼저 해야할 작업은 새로운 Master를 선출하는 일입니다. 이를 위해서 Sentinel 프로세스는 새로운 Master 선출 권한이 있는 Sentinel 리더를 뽑는 작업을 합니다.

Sentinel 리더가 선출되면, 리더는 Replica 인스턴스 중 하나를 Master로 승격합니다. 이후 나머지 Replica에서 Master 인스턴스를 모니터링할 수 있도록 명령을 수행하고 장애 복구 작업을 종료합니다.

만약 기존 Master 인스턴스가 다시 살아난다면, 이미 Master가 바뀌었으므로 기존 Master는 Replica로 자동으로 변경됩니다.

이로써, 운영자의 개입없이 자동으로 Failover 하여 고가용성을 어느정도 확보할 수 있게 되었습니다.

여기서 어느정도라는 말을 쓰는 이유는 Master/Replica/Sentinel 구조에서도 데이터 유실이 발생할 수 있기 때문입니다.

예를 위해 다음과 같은 상황을 가정해보겠습니다.

위 그림은 기존 Master 인스턴스와 나머지 Redis 인스턴스 사이 네트워크가 단절된 모습입니다. 네트워크 이슈이므로 Master 인스턴스는 현재 정상적으로 Client와 통신이 가능하며, 데이터 쓰기 작업이 발생하면 Master 인스턴스에 데이터가 저장됩니다.

하지만 Sentinel과 연결이 끊겼기 때문에 Sentinel은 Master가 죽은 것으로 판단하고 Replica 중 하나를 Master로 선출하게됩니다.

만약 이러한 상황에서 네트워크 단절 이슈가 해결된다면 기존 Master 인스턴스는 Sentinel에 의하여 Replica로 변경이 될 것이고, 이때 기존 Master 인스턴스에 새롭게 수정된 데이터는 유실됩니다.

참고:

- https://aphyr.com/posts/287-acynchronous-replication-with-failover

- http://antirez.com/news/56

마치며

이번 포스팅에서는 Redis의 기본 구조와 복제에 대해서 살펴봤습니다. 다음 포스팅에서는 Redis 파티셔닝에 대해서 다루도록 하겠습니다.

4. JPA Cache 적용하기

cla9 — Wed, 5 Aug 2020 23:43:47 +0900

서론

이번 포스팅에서는 JPA에 Cache 적용방법에 대해서 다루어보겠습니다. 먼저 Cache 선정 기준 및 패턴에 대한 소개 및 적용 방법을 설명합니다. Cache로는 Ehcache3을 적용하며, Spring Actuator를 통해서 캐시 Metric 변화도 함께 살펴보겠습니다.

1. Cache 적용 기준

캐시란 간단하게 말해서 Key와 Value로 이루어진 Map이라고 볼 수 있습니다.

하지만 일반 Map과는 다르게 만료 시간을 통해 freshness 조절 및 캐시 제거 등을 통해서 공간을 조절할 수 있는 특징이 있습니다.

그렇다면 캐시 적용을 위해 고려해야할 척도는 무엇이 있을까요?

1. 얼마나 자주 사용하는가?

출처 : https://ko.wikipedia.org/wiki/%EA%B8%B4_%EA%BC%AC%EB%A6%AC

위 그림은 파레토 법칙을 표현합니다. 즉 시스템 리소스 20%가 전체 전체 시간의 80% 정도를 소요함을 의미합니다. 따라서 캐시 대상을 선정할 때에는 캐시 오브젝트가 얼마나 자주 사용하는지, 적용시 전체적인 성능을 대폭 개선할 수 있는지 등을 따져야합니다.

2. HitRatio

HitRatio는 캐시에 대하여 자원 요청과 비례하여 얼마나 캐시 정보를 획득했는지를 나타내며, 계산 식은 다음과 같습니다.

HitRatio = hits / (hits + misses) * 100

캐시공간은 한정된 공간이기 때문에, 만료시간을 설정하여 캐시 유지시간을 설정할 수 있습니다. misses가 높다는 것은 캐시공간의 여유가 없어 이미 캐시에서 밀려났거나, 혹은 자주 사용하지 않는 정보를 캐시하여 만료시간이 지난 오브젝트를 획득하고자할 때 발생할 수 있습니다. 따라서 캐시를 설정할 때는 캐시 공간의 크기 및 만료 시간을 고려해야합니다.

2. Cache 패턴

이번에는 캐시에 적용되는 패턴에 대해서 알아보도록 하겠습니다.

1. No Caching

말 그대로 캐시없이 Application에서 직접 DB로 요청하는 방식을 말합니다. 별도 캐시한 내역이 없으므로 매번 DB와의 통신이 필요하며, 부하가 유발되는 SQL이 지속 수행되면 DB I/O에 영향을 줍니다.

2. Cache-aside

Application 기동시 캐시에는 아무 데이터가 없으며, Application이 요청시에 Cache Miss가 발생하면, DB로부터 데이터를 읽어와 Cache에 적재합니다. 이후에 동일한 요청을 반복하면, 캐시에 데이터가 존재하므로 DB 조회 없이 바로 데이터를 전달받을 수 있습니다.

해당 패턴은 Application이 캐시 적재와 관련된 일을 처리하므로, Cache Miss가 발생했을 때 응답시간이 저하될 수 있습니다.

3. Cache-through

캐시에 데이터가 없는 상황에서 Miss가 발생했을 때, Application이 아닌 캐시제공자가 데이터를 처리한 다음 Application에게 데이터를 전달하는 방법입니다. 즉 기존에는 동기화의 책임이 Application에 있었다면, 해당 패턴은 캐시 제공자에게 책임이 위임됩니다.

Cache-through 패턴은 다음과 같이 세분화할 수 있습니다.

Read-through

데이터 읽기 요청시, 캐시 제공자가 DB와의 연계를 통해 데이터를 적재하고 이를 반환합니다.

Write-through

데이터 쓰기 요청시, Application은 캐시에만 적용을 요청하면, 캐시 제공자가 DB에 데이터를 저장하고, Application에게 응답하는 방식입니다. 모든 작업은 동기로 진행됩니다.

Write-behind

데이터 쓰기 요청시, Application은 데이터를 캐시에만 반영한 다음 요청을 종료합니다. 이후 일정 시간을 간격으로 비동기적으로 캐시에서 DB로 데이터를 저장요청합니다. 이 방식은 Application의 쓰기 요청 성능을 높일 수 있으나 만약 캐시에 DB에 저장하기 전에 다운된다면, 데이터 유실이 발생합니다.

3. EhCache

Ehcache는 Java에서 주로 사용하는 캐시 관련 오픈소스이며, Application에 Embedded되어 간편하게 사용할 수 있는 특징을 지니고 있습니다. EhCache3에서는 JSR-107에서 요구하는 표준을 준수하여 만들어졌기 때문에 2 버전과 3 버전 설정 방법이 다릅니다.

Ehcache에서는 이전에 설명한 캐시 패턴을 모두 적용할 수 있습니다. 그 중 Cache-through 전략은 CacheLoaderWriter 인터페이스 구현을 통해서 적용할 수 있으나 해당 내용에 대해서는 다루지 않겠습니다.

자세한 설명은 공식 홈페이지를 참고바랍니다.

출처 : https://www.ehcache.org/documentation/3.2/caching-concepts.html

공식 메뉴얼에 따르면, 캐시 중요도에 따라 세군데 영역으로 나뉘어 저장할 수 있습니다. 먼저 Heap Tier는 GC가 관여할 수 있는 JVM의 Heap영역을 말합니다. 반면, Off Heap은 GC에서 접근이 불가능하며 OS가 관리하는 영역입니다. 해당 영역에 데이터를 저장하려면, -XX:MaxDirectMemorySize 옵션 설정을 통해 충분한 메모리를 확보해야합니다. 마지막 영역은 Disk 영역으로 해당 설명은 Skip 하겠습니다.

그럼 지금부터 지금까지 JPA 포스팅하면서 다룬 예제를 확장하여 EhCache를 적용하겠습니다. 예제 프로그램은 Cache-Aside 패턴을 통해 구현하며, 그외 나머지 패턴은 다루지 않겠습니다.

1. EhCache3 적용

build.gradle

...(중략)...
dependencies {
    ...(중략)...
    
    //cache
    implementation 'org.springframework.boot:spring-boot-starter-cache'
    implementation group: 'javax.cache', name: 'cache-api', version: '1.1.1'
    implementation group: 'org.hibernate', name: 'hibernate-jcache', version: '5.4.19.Final'
    implementation group: 'org.ehcache', name: 'ehcache', version: '3.8.1'
}
...(중략)...

application.yaml

spring:
  jpa:
    properties:
      javax:
        persistence:
          sharedcache:
            mode: ENABLE_SELECTIVE
      hibernate:
        cache:
          use_second_level_cache: true
          region:
            factory_class: org.hibernate.cache.jcache.internal.JCacheRegionFactory
        temp:
          use_jdbc_metadata_defaults: false
        format_sql: true
        show_sql: true
        use_sql_comments: true
    hibernate:
      ddl-auto: none
    database-platform: org.hibernate.dialect.Oracle10gDialect

JPA와 관련된 캐시 설정을 합니다. 설정 내용 중 캐시와 관련된 옵션을 살펴보겠습니다.

먼저 SharedCache는 캐시모드를 설정할 수 있는 옵션으로 enable_selective는 @Cacheable이 설정된 엔티티에만 캐시를 적용함을 의미합니다. 만약 모든 엔티티에 적용하려면 all 옵션을 줄 수 있습니다.

use_second_level_cache는 2차 캐시 활성화 여부를 지정합니다. JPA에서 1차 캐시는 PersistentContext를 의미하며, 각 세션레벨에서 트랜잭션이 진행되는 동안에 캐시됩니다. 반면 2차 캐시는 SessionFactory 레벨에서의 캐시를 의미하며 모든 세션에게 공유되는 공간입니다. 해당 옵션을 통해서 2차 캐시 설정 여부를 지정합니다.

factory_class는 캐시를 구현한 Provider 정보를 지정합니다. Ehcache3는 JSR-107 표준을 준수하여 개발되었기 때문에 JCacheRegionFactory를 지정합니다.

2. Configuration 설정

@Configuration
public class CachingConfig {
    public static final String DB_CACHE = "db_cache";

    private final javax.cache.configuration.Configuration<Object, Object> jcacheConfiguration;

    public CachingConfig() {
        this.jcacheConfiguration = Eh107Configuration.fromEhcacheCacheConfiguration(CacheConfigurationBuilder.newCacheConfigurationBuilder(Object.class, Object.class,
                ResourcePoolsBuilder.newResourcePoolsBuilder()
                        .heap(10000, EntryUnit.ENTRIES))
                .withSizeOfMaxObjectSize(1000, MemoryUnit.B)
                .withExpiry(ExpiryPolicyBuilder.timeToIdleExpiration(Duration.ofSeconds(300)))
                .withExpiry(ExpiryPolicyBuilder.timeToLiveExpiration(Duration.ofSeconds(600))));
    }

    @Bean
    public HibernatePropertiesCustomizer hibernatePropertiesCustomizer(javax.cache.CacheManager cacheManager) {
        return hibernateProperties -> hibernateProperties.put(ConfigSettings.CACHE_MANAGER, cacheManager);
    }

    @Bean
    public JCacheManagerCustomizer cacheManagerCustomizer() {
        return cm -> {
            cm.createCache(DB_CACHE, jcacheConfiguration);
        };
    }
}

Cache Config 클래스를 작성합니다. 먼저 생성자를 통해 캐시의 기본 설정을 구성했습니다. 위 구성은 테스트를 위해 임의로 지정하였으며, 커스터마이징하여 작성 가능합니다.

지정된 옵션 설명은 다음과 같습니다.

총 10000개의 Entity를 저장할 수 있으며, 각 오브젝트 사이즈는 1000 Byte를 넘지 않도록 제한하였습니다. Object는 최초 캐시에 입력후 600초 동안 저장되며, 만약 마지막으로 캐시 요청이후에 300초동안 재요청이 없을 경우 만료되도록 지정하였습니다.

자세한 설정 방법은 공식 문서를 참고 바랍니다.

@Entity
@Table
@Getter
@Cacheable
@org.hibernate.annotations.Cache(region = CachingConfig.DB_CACHE, usage = CacheConcurrencyStrategy.READ_ONLY)
public class Customer {
    @Id
    @GeneratedValue
    @Column(name = "id")
    private Long customerId;
    @Column(name = "name")
    private String customerName;
}

SharedCache 모드를 enable_selective로 지정하였으므로, @Cacheable 어노테이션을 추가하여 해당 엔티티를 캐시할 수 있도록 설정하였습니다. 캐시 제공자내에는 여러 캐시가 존재할 수 있으며, 캐시마다 이름이 부여되어있으므로 region영역에는 캐시내에서 참조할 캐시이름을 지정합니다.

usage는 캐시와 관련된 동시성 전략을 지정할 수 있습니다. 지정할 수 있는 옵션으로는 NONE, READ_ONLY, NONSTRICT_READ_WRITE, READ_WRITE, TRANSACTIONAL 총 5가지 입니다. 예제 프로그램에서는 읽기 전용으로만 지정하기 위해서 READ_ONLY 옵션을 부여했습니다.

@Service
@Slf4j
public class CustomerService {
   ...(중략)...

    public CustomerDTO getCustomer(Long id) {
        log.info("getCustomer from db ");
        Customer customer = repository.findById(id).orElseThrow(IllegalAccessError::new);
        return CustomerDTO.of(customer);
    }
}

@RestController
@RequiredArgsConstructor
@RequestMapping("/customers")
public class CustomerController {
    ...(중략)...

    @GetMapping("/{id}")
    public CustomerDTO getCustomer(@PathVariable Long id) {
        return service.getCustomer(id);
    }
}

테스트를 위해 Service 및 Controller에 관련 메소드를 생성합니다.

2020-08-05 23:09:30.493  INFO 1872 --- [nio-8080-exec-1] c.e.paging_demo.service.CustomerService  : getCustomer from db 
Hibernate: 
    select
        customer0_.id as id1_0_0_,
        customer0_.name as name2_0_0_ 
    from
        customer customer0_ 
    where
        customer0_.id=?
2020-08-05 23:09:40.278  INFO 1872 --- [nio-8080-exec-2] c.e.paging_demo.service.CustomerService  : getCustomer from db 
2020-08-05 23:09:51.598  INFO 1872 --- [nio-8080-exec-3] c.e.paging_demo.service.CustomerService  : getCustomer from db 
2020-08-05 23:09:52.384  INFO 1872 --- [nio-8080-exec-4] c.e.paging_demo.service.CustomerService  : getCustomer from db

실행 후 로그 출력 결과입니다. 최초 요청시에는 SQL 수행결과가 로그에 기록되었지만, 그 이후에는 SQL이 수행되지 않고 2차 캐시에서 정상적으로 가져온 것을 확인할 수 있습니다.

3. DTO 레벨 캐시 추가 설정

이번에는 테스트 목적으로 Entitiy 뿐만 아니라 DTO에도 캐시를 적용해보겠습니다. 테스트를 위해 두 대상은 다른 캐시영역에 저장되며, 두 캐시영역간 설정에 차이를 두겠습니다.

@Configuration
public class CachingConfig {
    public static final String DB_CACHE = "db_cache";
    public static final String USER_CACHE = "user_cache";

    ...(중략)...

    @Bean
    public JCacheManagerCustomizer cacheManagerCustomizer() {
        return cm -> {
            cm.createCache(DB_CACHE, jcacheConfiguration);
            cm.createCache(USER_CACHE, Eh107Configuration.fromEhcacheCacheConfiguration(CacheConfigurationBuilder.newCacheConfigurationBuilder(Long.class, CustomerDTO.class,
                    ResourcePoolsBuilder.newResourcePoolsBuilder()
                            .heap(10000, EntryUnit.ENTRIES))
                    .withSizeOfMaxObjectSize(1000, MemoryUnit.B)
                    .withExpiry(ExpiryPolicyBuilder.timeToIdleExpiration(Duration.ofSeconds(10)))
                    .withExpiry(ExpiryPolicyBuilder.timeToLiveExpiration(Duration.ofSeconds(20)))));
        };
    }
}

새로운 캐시를 추가하기 위해서 위와같이 Configuration 클래스를 수정했습니다. 신규로 추가하는 USER_CACHE는 만료시간을 훨씬 짧게하여 최장 20초간만 캐시에 저장되도록 설정하였습니다.

@Service
@Slf4j
public class CustomerService {
    ...(중략)...

    @Cacheable(value = CachingConfig.USER_CACHE, key ="#id")
    public CustomerDTO getCustomer(Long id) {
        log.info("getCustomer from db ");
        Customer customer = repository.findById(id).orElseThrow(IllegalAccessError::new);
        return CustomerDTO.of(customer);
    }
}

@RestController
@RequiredArgsConstructor
@RequestMapping("/customers")
@Slf4j
public class CustomerController {
    ...(중략)...

    @GetMapping("/{id}")
    public CustomerDTO getCustomer(@PathVariable Long id) {
        log.info("Controller 영역");
        return service.getCustomer(id);
    }
}

Service 클래스에 @Cacheable 어노테이션을 추가하여 캐시를 지정합니다. 이때 key는 파라미터로 전달받은 id를 지정하며, SPEL을 사용할 수 있습니다.

Controller 클래스에는 별다른 로직 추가 없이 로그만 남기도록 수정했습니다. 이제 어플리케이션을 재기동 후 결과를 보겠습니다.

2020-08-05 23:18:53.012  INFO 13244 --- [nio-8080-exec-1] c.e.p.controller.CustomerController      : Controller 영역
2020-08-05 23:18:53.055  INFO 13244 --- [nio-8080-exec-1] c.e.paging_demo.service.CustomerService  : getCustomer from db 
Hibernate: 
    select
        customer0_.id as id1_0_0_,
        customer0_.name as name2_0_0_ 
    from
        customer customer0_ 
    where
        customer0_.id=?
2020-08-05 23:18:57.093  INFO 13244 --- [nio-8080-exec-2] c.e.p.controller.CustomerController      : Controller 영역
2020-08-05 23:18:57.821  INFO 13244 --- [nio-8080-exec-3] c.e.p.controller.CustomerController      : Controller 영역
2020-08-05 23:19:03.127  INFO 13244 --- [nio-8080-exec-4] c.e.p.controller.CustomerController      : Controller 영역
2020-08-05 23:19:29.327  INFO 13244 --- [nio-8080-exec-6] c.e.p.controller.CustomerController      : Controller 영역
2020-08-05 23:19:29.329  INFO 13244 --- [nio-8080-exec-6] c.e.paging_demo.service.CustomerService  : getCustomer from db

최초 기동 후에는 모든 캐시에 정보가 없으므로 Controller -> Service -> DB 순으로 호출되어 데이터가 캐싱되었음을 확인할 수 있습니다.

이후에는 Service Layer의 DTO 또한 캐시되었으므로 지속 호출시에 Controller 로그는 출력되나 Service 레벨 메소드는 호출되지 않습니다.

20초가 지난 이후에는 Service Layer에 지정된 DTO 캐시가 만료되므로 Entity에 접근하나 해당 캐시는 아직 유효하므로 별도 DB 통신 없이 캐시에서 데이터를 반환하는 것을 확인할 수 있습니다.

지금까지 캐시 적재에 대해서만 살펴봤는데, 만약 수정, 삭제등으로 인해 캐시를 삭제해야한다면 @CacheEvict 어노테이션을 통해 삭제할 수 있습니다.

4. Actuator 적용

Spring Actuator 프로젝트를 사용하게되면, 모니터링에 필요한 유용한 Metric 뿐만 아니라 HealthCheck 및 Dump 생성 그리고 Reload 등이 가능합니다. Spring Actuator를 통해서 Cache와 관련된 Metric을 활용해 Prometheus & Grafana 대시보드로 시각화 또한 가능합니다.

이번에는 Actuator 적용 후 URL 호출을 통해 Metric을 확인하는 방법에 대해서 살펴보겠습니다.

1. Actuator 설정

build.gradle

...(중략)...
dependencies {
    ...(중략)...
    implementation 'org.springframework.boot:spring-boot-starter-actuator'
}

먼저 actuator 관련 의존성을 추가합니다.

application.yaml

management:
  endpoints:
    health:
      show-details: always
    web:
      exposure:
        include: "*"
  metrics:
    cache:
      instrument: true

해당 설정을 통해 actuator 기능을 활성화합니다.

2. 적용 확인

프로그램 기동 후 ip:port/actuator URL을 호출하면 위와 같이 상세 정보를 볼 수 있는 URL이 제공됩니다.

Cache 관련 정보는 metrics 하위에 위 표시된 영역으로 정보를 확인할 수 있습니다.

위 그림은 gets과 관련된 metric 정보이며, 총 7번의 get 요청이 있었음을 확인할 수 있습니다. 그 밖에 다른 정보들도 제공되는 URL을 통해 정보 확인이 가능합니다.

마치며

이번 포스팅에서는 JPA 캐시 적용에 대해서 알아봤습니다. 일반적으로 코드성 데이터나 공지사항과 같이 수정/삭제가 거의 없고 자주 사용되는 데이터에 대해서 캐시를 적용하면, 좋은 효과를 볼 수 있습니다. 하지만 무턱대고 적용했다가는 오히려 성능 저하가 발생될 수 있으니 전략 수립이 필요합니다.

이번 포스팅에서는 각 Application 내부에서만 유효한 Local Cache에 대해서 다루었습니다. EhCache가 Clustering을 지원하지만, Application Scale Out에 영향을 주기때문에 개인적으로는 가급적 Local Cache로써 사용하고 캐시 무효화 시간을 짧게 가지는 것이 좋다고 생각합니다. 만약 캐시간의 동기화가 필요하다면 Clustering을 고려하거나 Redis와 같은 Third 캐시를 추가로 두는 것을 고려해볼 수 있습니다.

3. JPA Hateoas 적용하기

cla9 — Sat, 1 Aug 2020 17:13:05 +0900

서론

이번 포스팅에서 왜 Hateoas를 적용해야하는지에 대해서 다루지 않습니다. 이와 관련된 자세한 이응준님의 그런 REST API로 괜찮은가 발표 세션을 꼭 보시기를 권장드리며, 해당 내용을 알고 계시다는 전제하에 포스팅을 작성하겠습니다.

이번에 다룰 내용은 Rest API 작성을 위해 필요한 Hateoas를 기존에 생성한 Page 객체에 적용하는 방법과 PagedResourceAssembler를 Customizing하는 방법을 알아보겠습니다.

1. 기존 Page 객체 이슈

위 그림은 이전 포스팅에서 예제 프로그램 API 호출 결과입니다. 해당 API는 원하는 요청에 대한 결과를 확인할 수 있습니다. 하지만 데이터를 통해서 어떠한 행위들이 가능한지 혹은 메시지가 정확히 어떠한 의미를 포함하고 있는지는 API 결과를 통해 알 수 없습니다.

다시말해 해당 API 결과를 보고서는 customer_id를 통해 어떠한 API를 추가적으로 호출할 수 있는지 어떤 상태 변화가 가능한지 알 수 없습니다.

그렇다면 Hateoas가 적용된 API의 모습은 어떨까요?

[
  {
    "id": 1,
    "node_id": "MDU6SXNzdWUx",
    "url": "https://api.github.com/repos/octocat/Hello-World/issues/1347",
    "repository_url": "https://api.github.com/repos/octocat/Hello-World",
    "labels_url": "https://api.github.com/repos/octocat/Hello-World/issues/1347/labels{/name}",
    "comments_url": "https://api.github.com/repos/octocat/Hello-World/issues/1347/comments",
    "events_url": "https://api.github.com/repos/octocat/Hello-World/issues/1347/events",
    "html_url": "https://github.com/octocat/Hello-World/issues/1347",
    "number": 1347,
    "state": "open",
    "title": "Found a bug",
    "body": "I'm having a problem with this.",
    "user": {
      "login": "octocat",
      "id": 1,
      "node_id": "MDQ6VXNlcjE=",
      "avatar_url": "https://github.com/images/error/octocat_happy.gif",
      "gravatar_id": "",
      "url": "https://api.github.com/users/octocat",
      "html_url": "https://github.com/octocat",
      "followers_url": "https://api.github.com/users/octocat/followers",
      "following_url": "https://api.github.com/users/octocat/following{/other_user}",
      "gists_url": "https://api.github.com/users/octocat/gists{/gist_id}",
      "starred_url": "https://api.github.com/users/octocat/starred{/owner}{/repo}",
      "subscriptions_url": "https://api.github.com/users/octocat/subscriptions",
      "organizations_url": "https://api.github.com/users/octocat/orgs",
      "repos_url": "https://api.github.com/users/octocat/repos",
      "events_url": "https://api.github.com/users/octocat/events{/privacy}",
      "received_events_url": "https://api.github.com/users/octocat/received_events",
      "type": "User",
      "site_admin": false
    },
    "labels": [
      {
        "id": 208045946,
        "node_id": "MDU6TGFiZWwyMDgwNDU5NDY=",
        "url": "https://api.github.com/repos/octocat/Hello-World/labels/bug",
        "name": "bug",
        "description": "Something isn't working",
        "color": "f29513",
        "default": true
      }
    ],
    "assignee": {
      "login": "octocat",
      "id": 1,
      "node_id": "MDQ6VXNlcjE=",
      "avatar_url": "https://github.com/images/error/octocat_happy.gif",
      "gravatar_id": "",
      "url": "https://api.github.com/users/octocat",
      "html_url": "https://github.com/octocat",
      "followers_url": "https://api.github.com/users/octocat/followers",
      "following_url": "https://api.github.com/users/octocat/following{/other_user}",
      "gists_url": "https://api.github.com/users/octocat/gists{/gist_id}",
      "starred_url": "https://api.github.com/users/octocat/starred{/owner}{/repo}",
      "subscriptions_url": "https://api.github.com/users/octocat/subscriptions",
      "organizations_url": "https://api.github.com/users/octocat/orgs",
      "repos_url": "https://api.github.com/users/octocat/repos",
      "events_url": "https://api.github.com/users/octocat/events{/privacy}",
      "received_events_url": "https://api.github.com/users/octocat/received_events",
      "type": "User",
      "site_admin": false
    },
    "assignees": [
      {
        "login": "octocat",
        "id": 1,
        "node_id": "MDQ6VXNlcjE=",
        "avatar_url": "https://github.com/images/error/octocat_happy.gif",
        "gravatar_id": "",
        "url": "https://api.github.com/users/octocat",
        "html_url": "https://github.com/octocat",
        "followers_url": "https://api.github.com/users/octocat/followers",
        "following_url": "https://api.github.com/users/octocat/following{/other_user}",
        "gists_url": "https://api.github.com/users/octocat/gists{/gist_id}",
        "starred_url": "https://api.github.com/users/octocat/starred{/owner}{/repo}",
        "subscriptions_url": "https://api.github.com/users/octocat/subscriptions",
        "organizations_url": "https://api.github.com/users/octocat/orgs",
        "repos_url": "https://api.github.com/users/octocat/repos",
        "events_url": "https://api.github.com/users/octocat/events{/privacy}",
        "received_events_url": "https://api.github.com/users/octocat/received_events",
        "type": "User",
        "site_admin": false
      }
    ],
    "milestone": {
      "url": "https://api.github.com/repos/octocat/Hello-World/milestones/1",
      "html_url": "https://github.com/octocat/Hello-World/milestones/v1.0",
      "labels_url": "https://api.github.com/repos/octocat/Hello-World/milestones/1/labels",
      "id": 1002604,
      "node_id": "MDk6TWlsZXN0b25lMTAwMjYwNA==",
      "number": 1,
      "state": "open",
      "title": "v1.0",
      "description": "Tracking milestone for version 1.0",
      "creator": {
        "login": "octocat",
        "id": 1,
        "node_id": "MDQ6VXNlcjE=",
        "avatar_url": "https://github.com/images/error/octocat_happy.gif",
        "gravatar_id": "",
        "url": "https://api.github.com/users/octocat",
        "html_url": "https://github.com/octocat",
        "followers_url": "https://api.github.com/users/octocat/followers",
        "following_url": "https://api.github.com/users/octocat/following{/other_user}",
        "gists_url": "https://api.github.com/users/octocat/gists{/gist_id}",
        "starred_url": "https://api.github.com/users/octocat/starred{/owner}{/repo}",
        "subscriptions_url": "https://api.github.com/users/octocat/subscriptions",
        "organizations_url": "https://api.github.com/users/octocat/orgs",
        "repos_url": "https://api.github.com/users/octocat/repos",
        "events_url": "https://api.github.com/users/octocat/events{/privacy}",
        "received_events_url": "https://api.github.com/users/octocat/received_events",
        "type": "User",
        "site_admin": false
      },
      "open_issues": 4,
      "closed_issues": 8,
      "created_at": "2011-04-10T20:09:31Z",
      "updated_at": "2014-03-03T18:58:10Z",
      "closed_at": "2013-02-12T13:22:01Z",
      "due_on": "2012-10-09T23:39:01Z"
    },
    "locked": true,
    "active_lock_reason": "too heated",
    "comments": 0,
    "pull_request": {
      "url": "https://api.github.com/repos/octocat/Hello-World/pulls/1347",
      "html_url": "https://github.com/octocat/Hello-World/pull/1347",
      "diff_url": "https://github.com/octocat/Hello-World/pull/1347.diff",
      "patch_url": "https://github.com/octocat/Hello-World/pull/1347.patch"
    },
    "closed_at": null,
    "created_at": "2011-04-22T13:33:48Z",
    "updated_at": "2011-04-22T13:33:48Z",
    "repository": {
      "id": 1296269,
      "node_id": "MDEwOlJlcG9zaXRvcnkxMjk2MjY5",
      "name": "Hello-World",
      "full_name": "octocat/Hello-World",
      "owner": {
        "login": "octocat",
        "id": 1,
        "node_id": "MDQ6VXNlcjE=",
        "avatar_url": "https://github.com/images/error/octocat_happy.gif",
        "gravatar_id": "",
        "url": "https://api.github.com/users/octocat",
        "html_url": "https://github.com/octocat",
        "followers_url": "https://api.github.com/users/octocat/followers",
        "following_url": "https://api.github.com/users/octocat/following{/other_user}",
        "gists_url": "https://api.github.com/users/octocat/gists{/gist_id}",
        "starred_url": "https://api.github.com/users/octocat/starred{/owner}{/repo}",
        "subscriptions_url": "https://api.github.com/users/octocat/subscriptions",
        "organizations_url": "https://api.github.com/users/octocat/orgs",
        "repos_url": "https://api.github.com/users/octocat/repos",
        "events_url": "https://api.github.com/users/octocat/events{/privacy}",
        "received_events_url": "https://api.github.com/users/octocat/received_events",
        "type": "User",
        "site_admin": false
      },
      "private": false,
      "html_url": "https://github.com/octocat/Hello-World",
      "description": "This your first repo!",
      "fork": false,
      "url": "https://api.github.com/repos/octocat/Hello-World",
      "archive_url": "http://api.github.com/repos/octocat/Hello-World/{archive_format}{/ref}",
      "assignees_url": "http://api.github.com/repos/octocat/Hello-World/assignees{/user}",
      "blobs_url": "http://api.github.com/repos/octocat/Hello-World/git/blobs{/sha}",
      "branches_url": "http://api.github.com/repos/octocat/Hello-World/branches{/branch}",
      "collaborators_url": "http://api.github.com/repos/octocat/Hello-World/collaborators{/collaborator}",
      "comments_url": "http://api.github.com/repos/octocat/Hello-World/comments{/number}",
      "commits_url": "http://api.github.com/repos/octocat/Hello-World/commits{/sha}",
      "compare_url": "http://api.github.com/repos/octocat/Hello-World/compare/{base}...{head}",
      "contents_url": "http://api.github.com/repos/octocat/Hello-World/contents/{+path}",
      "contributors_url": "http://api.github.com/repos/octocat/Hello-World/contributors",
      "deployments_url": "http://api.github.com/repos/octocat/Hello-World/deployments",
      "downloads_url": "http://api.github.com/repos/octocat/Hello-World/downloads",
      "events_url": "http://api.github.com/repos/octocat/Hello-World/events",
      "forks_url": "http://api.github.com/repos/octocat/Hello-World/forks",
      "git_commits_url": "http://api.github.com/repos/octocat/Hello-World/git/commits{/sha}",
      "git_refs_url": "http://api.github.com/repos/octocat/Hello-World/git/refs{/sha}",
      "git_tags_url": "http://api.github.com/repos/octocat/Hello-World/git/tags{/sha}",
      "git_url": "git:github.com/octocat/Hello-World.git",
      "issue_comment_url": "http://api.github.com/repos/octocat/Hello-World/issues/comments{/number}",
      "issue_events_url": "http://api.github.com/repos/octocat/Hello-World/issues/events{/number}",
      "issues_url": "http://api.github.com/repos/octocat/Hello-World/issues{/number}",
      "keys_url": "http://api.github.com/repos/octocat/Hello-World/keys{/key_id}",
      "labels_url": "http://api.github.com/repos/octocat/Hello-World/labels{/name}",
      "languages_url": "http://api.github.com/repos/octocat/Hello-World/languages",
      "merges_url": "http://api.github.com/repos/octocat/Hello-World/merges",
      "milestones_url": "http://api.github.com/repos/octocat/Hello-World/milestones{/number}",
      "notifications_url": "http://api.github.com/repos/octocat/Hello-World/notifications{?since,all,participating}",
      "pulls_url": "http://api.github.com/repos/octocat/Hello-World/pulls{/number}",
      "releases_url": "http://api.github.com/repos/octocat/Hello-World/releases{/id}",
      "ssh_url": "git@github.com:octocat/Hello-World.git",
      "stargazers_url": "http://api.github.com/repos/octocat/Hello-World/stargazers",
      "statuses_url": "http://api.github.com/repos/octocat/Hello-World/statuses/{sha}",
      "subscribers_url": "http://api.github.com/repos/octocat/Hello-World/subscribers",
      "subscription_url": "http://api.github.com/repos/octocat/Hello-World/subscription",
      "tags_url": "http://api.github.com/repos/octocat/Hello-World/tags",
      "teams_url": "http://api.github.com/repos/octocat/Hello-World/teams",
      "trees_url": "http://api.github.com/repos/octocat/Hello-World/git/trees{/sha}",
      "clone_url": "https://github.com/octocat/Hello-World.git",
      "mirror_url": "git:git.example.com/octocat/Hello-World",
      "hooks_url": "http://api.github.com/repos/octocat/Hello-World/hooks",
      "svn_url": "https://svn.github.com/octocat/Hello-World",
      "homepage": "https://github.com",
      "language": null,
      "forks_count": 9,
      "stargazers_count": 80,
      "watchers_count": 80,
      "size": 108,
      "default_branch": "master",
      "open_issues_count": 0,
      "is_template": true,
      "topics": [
        "octocat",
        "atom",
        "electron",
        "api"
      ],
      "has_issues": true,
      "has_projects": true,
      "has_wiki": true,
      "has_pages": false,
      "has_downloads": true,
      "archived": false,
      "disabled": false,
      "visibility": "public",
      "pushed_at": "2011-01-26T19:06:43Z",
      "created_at": "2011-01-26T19:01:12Z",
      "updated_at": "2011-01-26T19:14:43Z",
      "permissions": {
        "admin": false,
        "push": false,
        "pull": true
      },
      "allow_rebase_merge": true,
      "template_repository": null,
      "temp_clone_token": "ABTLWHOULUVAXGTRYU7OC2876QJ2O",
      "allow_squash_merge": true,
      "delete_branch_on_merge": true,
      "allow_merge_commit": true,
      "subscribers_count": 42,
      "network_count": 0
    }
  }
]

위 API는 Github의 Issue API 결과입니다. 주요 데이터에 대하여 자신의 URL과 다음 상태 변이에 대한 URL 링크를 같이 제공하여 Hateoas를 준수하고 있습니다. 따라서 Client는 서버로부터 받은 링크를 통해 상태를 변화할 뿐 Client 소스에 하드코딩되어 있을 필요가 없습니다.

Spring에서는 Hateoas 기능을 손쉽게 적용가능하기 위한 Spring Hateoas 프로젝트가 있습니다. 해당 프로젝트를 적용하여, 기존 프로그램 예제를 확장해보도록 하겠습니다.

2. Hateoas 적용

build.gradle

(...중략...)
dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-hateoas'
    (...중략...)
}

위와같이 dependency에 hateoas를 추가합니다.

2-1. Controller

@RestController
@RequiredArgsConstructor
public class CustomerController {
    private final CustomerService service;
    private final PagedResourcesAssembler<CustomerDTO> assembler;

    @GetMapping("/customers")
    public ResponseEntity<PagedModel<EntityModel<CustomerDTO>>> getCustomer(PageableDTO pageableDTO){
        Page<CustomerDTO> customers = service.getCustomer(pageableDTO);
        PagedModel<EntityModel<CustomerDTO>> entityModels = assembler.toModel(customers);
        return ResponseEntity.ok(entityModels);
    }
}

Controller에서 Page 모델을 기본적으로 제공되는 PagedResourcesAssembler를 통해 PagedModel 객체로 변환하는 코드를 추가하였습니다.

2-2. 실행 결과

PagedResourcedAssembler 적용 후 결과를 보면, self 링크를 포함하여 다음 상태 전이를 위한 API가 기본적으로 제공되는 것을 확인할 수 있습니다.

하지만 위 API에서는 각각의 customerDTO 각 원소에 대한 상태 변이 URL은 제공되지 않았습니다. 이를 추가해보겠습니다.

3. PagedModelUtil

public class LinkResource<T> extends EntityModel<T> {
    public static <T> EntityModel<T> of(WebMvcLinkBuilder builder, T model, Function<T,?> resourceFunc){
        return EntityModel.of(model, getSelfLink(builder, model, resourceFunc));
    }

    private static<T> Link getSelfLink(WebMvcLinkBuilder builder, T data, Function<T, ?> resourceFunc){
        WebMvcLinkBuilder slash = builder.slash(resourceFunc.apply(data));
        return slash.withSelfRel();
    }
}

EntityModel을 생성할 때, Link를 주입하도록 LinkResource 클래스를 생성합니다.

public class PagedModelUtil {
    public static <T> PagedModel<EntityModel<T>> getEntityModels(PagedResourcesAssembler<T> assembler,
                                                                 Page<T> page,
                                                                 Class<?> clazz,
                                                                 Function<T, ?> selfLinkFunc ){
        WebMvcLinkBuilder webMvcLinkBuilder = linkTo(clazz);
        return assembler.toModel(page, model -> LinkResource.of(webMvcLinkBuilder, model, selfLinkFunc::apply));
    }

    public static <T> PagedModel<EntityModel<T>> getEntityModels(PagedResourcesAssembler<T> assembler,
                                                                 Page<T> page,
                                                                 WebMvcLinkBuilder builder,
                                                                 Function<T, ?> selfLinkFunc ){
        return assembler.toModel(page, model -> LinkResource.of(builder, model, selfLinkFunc::apply));
    }
}

LinkResource를 기반으로 전체 Page 모델을 순회하면서 Link를 주입하고, 이를 PagedModel 객체로 컨버팅하는 Util 클래스를 생성합니다.

@RestController
@RequiredArgsConstructor
public class CustomerController {
    private final CustomerService service;
    private final PagedResourcesAssembler<CustomerDTO> assembler;

    @GetMapping("/customers")
    public ResponseEntity<PagedModel<EntityModel<CustomerDTO>>> getCustomer(PageableDTO pageableDTO){
        Page<CustomerDTO> customers = service.getCustomer(pageableDTO);

        PagedModel<EntityModel<CustomerDTO>> entityModels = PagedModelUtil.getEntityModels(assembler, customers,
                linkTo(methodOn(this.getClass()).getCustomer(null)),
                CustomerDTO::getCustomerId);
        return ResponseEntity.ok(entityModels);
    }
}

Controller 클래스에서는 해당 Util 클래스 함수 호출을 통해 PagedModel로 변경하도록 코드를 변경헀습니다.

여기서 두번째 및 세번째 인자가 각 DTO별로 호출할 메소드 및 ID 값에 해당합니다.

위 예제에서는 getCustomer 메소드를 두번째 인자로 전달했기 때문에 @GetMapping 어노테이션으로 전달한 customers 가 URL에 추가가 될 것입니다. 또한, customers URL 뒤에올 ID 값으로 customerDTO에 속한 id 값을 넘겨줌으로써 URL이 완성될 것입니다.

따라서, 위 코드를 통해서 각 DTO 별로 추가되는 URL은 http://localhost:8080/customers/{id}가 될 것입니다.

@RestController
@RequiredArgsConstructor
public class CustomerController {
    private final CustomerService service;
    private final PagedResourcesAssembler<CustomerDTO> assembler;

    @GetMapping("/customers")
    public ResponseEntity<PagedModel<EntityModel<CustomerDTO>>> getCustomer(PageableDTO pageableDTO){
        Page<CustomerDTO> customers = service.getCustomer(pageableDTO);

        PagedModel<EntityModel<CustomerDTO>> entityModels = PagedModelUtil.getEntityModels(assembler, customers,
                linkTo(methodOn(this.getClass()).getCustomer(null)),
                v-> v.getCustomerName() + "/" + v.getCustomerId());
        return ResponseEntity.ok(entityModels);
    }
}

만약 URL을 변경하고 싶다면, 위와같이 두번째 인자 및 세번째 Function을 새로 정의하여 변경 가능합니다.

4. PagedResourceAssembler 커스터마이징

지금까지 Hateoas 적용과 각 DTO 별로 Self 링크를 적용하는 방법에 대해서 살펴봤습니다. 기본적으로 제공되는 PagedResourceAssembler에는 첫페이지, 이전 페이지, 현재 페이지, 다음 페이지 및 마지막 페이지 정보가 담겨있습니다.

이는 해당 API가 게시판에 노출되는 API라면 위와 같은 모습에 사용될 수 있는 Link 정보를 담고 있습니다.

만약 사용자가 원하는 게시판의 형태가 위와 같다면, 기본 제공되는 PagedResourcesAssembler는 이를 표현할 수 없습니다. 따라서 Customizing이 필요합니다.

4-1. CustomPagedResourceAssembler

public class CustomPagedResourceAssembler<T> extends PagedResourcesAssembler<T> {
    private final HateoasPageableHandlerMethodArgumentResolver pageableResolver;
    private final Optional<UriComponents> baseUri;
    private final int PAGE_SIZE;
    private final int DEFAULT_PAGE_SIZE = 10;

    public CustomPagedResourceAssembler(HateoasPageableHandlerMethodArgumentResolver pageableResolver, @Nullable  Integer pageSize) {
        super(pageableResolver,null);
        this.pageableResolver = pageableResolver;
        baseUri = Optional.empty();
        this.PAGE_SIZE = pageSize == null ? DEFAULT_PAGE_SIZE : pageSize;
    }

    @Override
    public PagedModel<EntityModel<T>> toModel(Page<T> entity) {
        return toModel(entity, EntityModel::of);
    }

    @Override
    public <R extends RepresentationModel<?>> PagedModel<R> toModel(Page<T> page, RepresentationModelAssembler<T, R> assembler) {
        Assert.notNull(page, "Page must not be null!");
        Assert.notNull(assembler, "ResourceAssembler must not be null!");

        List<R> resources = new ArrayList<>(page.getNumberOfElements());

        for (T element : page) {
            resources.add(assembler.toModel(element));
        }

        PagedModel<R> resource = createPagedModel(resources, asPageMetadata(page), page);
        return addPaginationLinks(resource, page, Optional.empty());
    }

    private PagedModel.PageMetadata asPageMetadata(Page<?> page) {

        Assert.notNull(page, "Page must not be null!");
        int number = page.getNumber();
        return new PagedModel.PageMetadata(page.getSize(), number, page.getTotalElements(), page.getTotalPages());
    }

    private <R> PagedModel<R> addPaginationLinks(PagedModel<R> resources, Page<?> page, Optional<Link> link) {

        UriTemplate base = getUriTemplate(link);
        boolean isNavigable = page.hasPrevious() || page.hasNext();

        int currIndex = page.getNumber();
        int lastIndex = page.getTotalPages() == 0 ? 0 : page.getTotalPages() - 1;
        int baseIndex = (currIndex / this.PAGE_SIZE) * this.PAGE_SIZE;
        int prevIndex = baseIndex - this.PAGE_SIZE;
        int nextIndex = baseIndex + this.PAGE_SIZE;
        int size = page.getSize();
        Sort sort = page.getSort();

        if(lastIndex < currIndex)
            throw new IndexOutOfBoundsException("Page total size must not be less than page size");

        if (isNavigable) {
            resources.add(createLink(base, PageRequest.of(0, size, sort), IanaLinkRelations.FIRST));
        }

        Link selfLink = link.map(it -> it.withSelfRel()).orElseGet(() -> createLink(base, page.getPageable(), IanaLinkRelations.SELF));

        resources.add(selfLink);

        if (prevIndex >= 0) {
            resources.add(createLink(base,
                    PageRequest.of(prevIndex, size, sort),
                    IanaLinkRelations.PREV));
        }

        for(int i = 0; i < this.PAGE_SIZE; i++){
            if(baseIndex + i <= lastIndex){
                resources.add(createLink(base, PageRequest.of(baseIndex + i, size, sort), LinkRelation.of("pagination")));
            }
        }

        if(nextIndex < lastIndex){
            resources.add(createLink(base, PageRequest.of(nextIndex, size, sort), IanaLinkRelations.NEXT));
        }

        if (isNavigable) {
            resources.add(createLink(base, PageRequest.of(lastIndex, size, sort), IanaLinkRelations.LAST));
        }

        return resources;
    }

    private UriTemplate getUriTemplate(Optional<Link> baseLink) {
        return UriTemplate.of(baseLink.map(Link::getHref).orElseGet(this::baseUriOrCurrentRequest));
    }

    private String baseUriOrCurrentRequest() {
        return baseUri.map(Object::toString).orElseGet(CustomPagedResourceAssembler::currentRequest);
    }

    private static String currentRequest() {
        return ServletUriComponentsBuilder.fromCurrentRequest().build().toString();
    }

    private Link createLink(UriTemplate base, Pageable pageable, LinkRelation relation) {
        UriComponentsBuilder builder = fromUri(base.expand());
        pageableResolver.enhance(builder, getMethodParameter(), pageable);
        return Link.of(UriTemplate.of(builder.build().toString()), relation);
    }
}

위 코드는 기존 PagedResourcesAssembler를 상속받아 구현하였습니다. 가장 핵심이 되는 부분은 addPaginationLinks 메소드이며, 해당 메소드를 통해 페이지의 인덱스 정보를 pagination 링크아래에 배치하도록 표현했습니다.

@Configuration
public class AppConfig implements WebMvcConfigurer {

    ...(중략)...

    @Bean
    public CustomPagedResourceAssembler<?> customPagedResourceAssembler(){
        return new CustomPagedResourceAssembler<>(new HateoasPageableHandlerMethodArgumentResolver(),10);
    }
}

이후 해당 클래스를 Bean으로 등록시켜 줍니다. 생성자의 두번째 파라미터는 Page 사이즈를 결정하며, 해당 값의 변경을 통해 노출되는 URL 크기가 달라집니다.

4-2 Controller

@RestController
@RequiredArgsConstructor
public class CustomerController {
    private final CustomerService service;
    private final CustomPagedResourceAssembler<CustomerDTO> assembler;

    @GetMapping("/customers")
    public ResponseEntity<PagedModel<EntityModel<CustomerDTO>>> getCustomer(PageableDTO pageableDTO){
        Page<CustomerDTO> customers = service.getCustomer(pageableDTO);

        PagedModel<EntityModel<CustomerDTO>> entityModels = PagedModelUtil.getEntityModels(assembler, customers,
                linkTo(methodOn(this.getClass()).getCustomer(null)),
                CustomerDTO::getCustomerId);
        return ResponseEntity.ok(entityModels);
    }
}

Bean으로 등록한 CustomPagedResourceAssembler로 주입받도록 코드를 수정했습니다.

4-3 결과

애플리케이션 구동 후 해당 URL을 호출하면, 정상적으로 페이지 URL이 표시되는 것을 확인할 수 있습니다.

마치며

Page 객체에 Hateoas를 적용하는 방법에 대해서 살펴봤습니다. Rest API 설계를 위해서는 Hateoas 적용뿐만 아니라 Self-descriptive-messages를 적용하기 위해 IANA 등록 혹은 Profile 링크를 추가해야합니다.

Profile 링크를 적용하기 위해서 RestDocs 혹은 Swagger 등을 활용할 수 있으니 참고 바랍니다.

2. JPA Sort 조건 개선

cla9 — Thu, 30 Jul 2020 21:25:45 +0900

서론

이전 포스팅에서 다룬 예제를 확장하여 진행하겠습니다. 이번 포스팅에서는 JPA Sort에 대해서 다루도록 하겠습니다.

문제상황

http://localhost:8080/customers?page=3&size=10&sort=customerId,asc

예제 프로그램 수행후 다음과 같은 URL을 호출하면 page, size, sort 파라미터가 Pageable 객체로 컨버팅 되어 정상적으로 프로그램이 페이징과 정렬이 수행되는 것을 확인할 수 있습니다.

http://localhost:8080/customers?page=3&size=10&sort=customerId,asc&sort=customerName,desc

만약 여러 Column의 정렬을 수행하고 싶다면, 위와 같이 여러개의 sort 파라미터를 추가하면 정상 수행되는 것을 확인할 수 있습니다.

하지만 위 sort 조건은 @Entity 클래스에 정의한 필드명과 정확히 동일해야합니다. 만약 예제와 같이 동일 컬럼에 대하여 리턴 값은 SnakeCase인 customer_id 일경우 Client 로직에서는 전달받은 값 이외에 @Entitiy 클래스 필드명을 관리해야합니다. 만약 Entitiy에 정의되어있지 않은 필드명을 전달하게된다면, 에러가 발생합니다.

Client 로직에서 도메인 객체 필드명에 의존하는 것은 바람직해 보이지 않습니다. 따라서 Enum과 DTO를 활용해서 Sort 조건이 도메인 객체와 직접연관되지 않도록 설정해봅시다.

Pageable 구현

기존에는 파라미터 객체를 Pageable로 Controller 파라미터로 주입받았습니다. 이때 도메인 객체 필드명을 Sort 인자에 정확히 명시해야하는 문제가 있었습니다. 따라서 방법을 바꾸어 별도 PageableDTO에 파라미터 인자를 주입받고 이를 처리하겠습니다.

1. Pair 클래스

@Getter
@Builder(access = AccessLevel.PRIVATE)
@ToString
public class Pair<T, U> {
    private T first;
    private U second;

    public static <T, U> Pair of(T first, U second) {
        return Pair.builder()
                .first(first)
                .second(second)
                .build();
    }
}

먼저 컬럼명과 정렬 상태를 담을 Pair 클래스를 생성합니다.

2. Sort 상태를 표현하는 Enum 구현

public enum SortOption {
    ASC,
    DESC
}

3. PageableDTO

@Getter
@Builder
@ToString
@NoArgsConstructor
@AllArgsConstructor
public class PageableDTO {
    private Integer page;
    private Integer size;
    private Integer totalElements;
    private List<Pair<String, SortOption>> sorts;
}

Page 관련 정보와 Sort 정보를 담을 DTO를 선언합니다.

4. HandlerMethodArgumentResolver 클래스 구현

public class PageableArgumentResolver implements HandlerMethodArgumentResolver {
    private final String PAGE = "page";
    private final String SIZE = "size";
    private final String TOTAL_ELEMENTS = "total_elements";

    @Override
    public boolean supportsParameter(MethodParameter parameter) {
        return parameter.getParameterType().equals(PageableDTO.class);
    }

    @Override
    public Object resolveArgument(MethodParameter parameter, ModelAndViewContainer mavContainer, NativeWebRequest webRequest, WebDataBinderFactory binderFactory) throws Exception {
        List<Pair<String, SortOption>> sorts = new ArrayList<>();
        final var sortArr = webRequest.getParameterMap().get("sort");

        if(sortArr != null){
            for(var v : sortArr){
                String[] keywords = v.split(",");
                sorts.add(Pair.of(keywords[0], (keywords.length < 2 || keywords[1].equals("asc")) ? SortOption.ASC : SortOption.DESC));
            }
        }

        return PageableDTO.builder()
                .page(getValue(webRequest.getParameter(PAGE)))
                .size(getValue(webRequest.getParameter(SIZE)))
                .totalElements(getValue(webRequest.getParameter(TOTAL_ELEMENTS)))
                .sorts(sorts)
                .build();
    }

    private Integer getValue(String param) {
        return param != null ? Integer.parseInt(param) : null;
    }
}

@Configuration
public class AppConfig implements WebMvcConfigurer {

    @Override
    public void addArgumentResolvers(List<HandlerMethodArgumentResolver> resolvers) {
        resolvers.add(new PageableArgumentResolver());
    }
}

위 클래스는 Custom HandlerMethodArgumentResolver입니다. 별도로 이를 구현한 이유는 PageableDTO에 정렬 정보를 담기 위해서는 배열형태로 넘어오는 Sort 정보를 @ModelAttribute를 통해 주입받을 수 없기 때문입니다.

따라서, 별도 HandlerMethodArgumentResolver를 구현하여 파라미터 값에서 관심있는 값들을 가져와 가공하여 DTO를 생성받아 주입할 수 있도록 구현하여 기존 resolver 목록에 추가했습니다.

만약 HandlerMethodArgumentResolver를 사용하고 싶지 않다면, MultiValueMap을 통해 주입받은 후 별도 Factory 메소드를 사용해 DTO를 코드상에서 변경시키는 것도 한 방법입니다.

5. 도메인 컬럼 매핑 Layer 구현

public class MetaModelUtil {
    public static String getColumn(Path<?> path){
        return path.getMetadata().getName();
    }
}

public enum CustomerMetaType {
    CUSTOMER_ID(getColumn(customer.customerId)),
    CUSTOMER_NAME(getColumn(customer.customerName));

    private String name;
    CustomerMetaType(String name) {
        this.name = name;
    }

    public String getName() {
        return name;
    }
}

Client에서 존재하는 SnakeCase의 컬럼명과 실제 @Entity 클래스 컬럼명을 매핑하기 위하여 Enum을 사용했습니다. @Entity로 부터 생성되는 컬럼명을 얻어오기 위해서는 QueryDsl의 Q클래스를 활용하거나 JPA Meta모델을 활용하는 방법이 있습니다.

대개 JPA를 쓰면서 QueryDsl을 같이 쓰기 때문에 별도 JPA Meta모델을 추출하기 보다는 QueryDsl의 MetaModel을 활용하여 매핑하였습니다.

6. DomainSpec 클래스 구현

6-1 Sort 전략 클래스 생성

public interface SortStrategy<T extends Enum<T>> {
    Sort.Order getSortOrder(T domainKey, SortOption order);
}

public class CustomerSortStrategy implements SortStrategy<CustomerMetaType> {
    @Override
    public Sort.Order getSortOrder(CustomerMetaType domainKey, SortOption order) {
        Sort.Order sortOrder = null;
        switch (domainKey){
            case CUSTOMER_ID:
            case CUSTOMER_NAME:
                final var column = domainKey.getName();
                sortOrder = (order == SortOption.ASC) ? Sort.Order.asc(column) : Sort.Order.desc(column);
        }
        return sortOrder;
    }
}

엔티티별로 정렬을 구현할 전략을 설정할 수 있는 객체를 생성합니다. 위 switch 구문에서 CUSTOMER_ID를 제거하면 Client로부터 넘어오는 customer_id는 해당되지 않으므로 Null이 반환되고 에러가 발생하게 될 것입니다. 따라서 Strategy에 지정한 구문여부에 따라서 정렬 대상을 한정할 수 있습니다.

6-2. DomainSpec 클래스 생성


public class DomainSpec<T extends Enum<T>, U> {
    private final Class<T> clazz;
    @Getter @Setter
    private int defaultPage = 0;
    @Getter @Setter
    private int defaultSize = 20;
    private SortStrategy<T> sortStrategy;

    public DomainSpec(Class<T> clazz, SortStrategy<T> sortStrategy) {
        this.clazz = clazz;
        this.sortStrategy = sortStrategy;
    }

    public DomainSpec(Class<T> clazz, SortStrategy<T> sortStrategy, int defaultPage, int defaultSize) {
        this.clazz = clazz;
        this.defaultPage = defaultPage;
        this.defaultSize = defaultSize;
        this.sortStrategy = sortStrategy;
    }

    public void changeSortStrategy(SortStrategy<T> sortStrategy) {
        this.sortStrategy = sortStrategy;
    }

    public Pageable getPageable(PageableDTO dto) {
        Integer page = dto.getPage();
        Integer size = dto.getSize();
        Pageable pageable;

        if (dto.getSorts().size() < 1) {
            pageable = PageRequest.of(page == null ? defaultPage : page, size == null ? defaultSize : size);
        } else {
            List<Sort.Order> sorts = getSortOrders(dto.getSorts());
            pageable = PageRequest.of(page == null ? defaultPage : page, size == null ? defaultSize : size, Sort.by(sorts));
        }

        return pageable;
    }

    private List<Sort.Order> getSortOrders(List<Pair<String, SortOption>> sorts) {
        Assert.notNull(this.sortStrategy,"There is no sort strategy");

        List<Sort.Order> orders = new ArrayList<>();
        for (var o : sorts) {
            T column;
            try {
                column = Enum.valueOf(this.clazz, o.getFirst().toUpperCase());
            } catch (IllegalArgumentException e) {
                throw new IllegalArgumentException("Sort option error");
            }

            final Sort.Order order = sortStrategy.getSortOrder(column, o.getSecond());
            Assert.notNull(order, "sort option error");

            orders.add(order);
        }
        return orders;
    }
}

정렬을 포함한 Pageable 객체를 얻어오기 위한 클래스입니다. SortStrategy를 통해 전달받은 구현체에 정렬 방법을 위임합니다.

7. Service 구현

@Service
public class CustomerService {
    private final CustomerRepository repository;
    private DomainSpec<CustomerMetaType, Customer> spec;

    public CustomerService(CustomerRepository repository) {
        this.repository = repository;
        this.spec = new DomainSpec<>(CustomerMetaType.class, new CustomerSortStrategy());
    }

    public Page<CustomerDTO> getCustomer(PageableDTO pageableDTO) {
        final var pageable = spec.getPageable(pageableDTO);

        final var customers = repository.findAll(pageable, pageableDTO.getTotalElements());
        return customers.map(CustomerDTO::of);
    }
}

정렬 조건을 포함한 Pageable 객체를 CustomerSpec에서 가져올 수 있도록 구성하였습니다.

8. Controller 구현

@RestController
@RequiredArgsConstructor
public class CustomerController {
    private final CustomerService service;

    @GetMapping("/customers")
    public ResponseEntity<Page<CustomerDTO>> getCustomer(PageableDTO pageableDTO){
        Page<CustomerDTO> customers = service.getCustomer(pageableDTO);
        return ResponseEntity.ok(customers);
    }
}

Pageable 객체를 바로 전달받는 것이 아니라, HandlerMethodArgumentResolver를 통해 PageableDTO를 주입받아 이를 서비스 객체로 넘기도록 코드를 수정하였습니다.

9. 실행 결과

프로그램을 실행시키면, 기존과는 다르게 customer_name과 같이 도메인 엔티티 컬럼명에 종속적이지 않고 컬럼명을 지정할 수 있습니다. 또한, 컬럼 정렬 대상을 제한하여 보다 무분별한 정렬이 발생되지 않도록 강제할 수 있습니다.

마치며

이번 포스팅에서는 JPA에서 정렬 조건을 제한하는 방법과 엔티티 컬럼명에 의존하지 않도록 매핑 Layer를 두는 방법에 대해서 알아봤습니다.

위 구조를 조금 확장하면, Specification이나 BooleanBuilder 등을 활용하여 SQL Where 조건절에 추가하는 도메인 코드 로직을 구성할 수 있습니다.

hellozin님 블로그님 포스팅에 이와 관련된 내용이 있으니 참고하면 좋을 것 같습니다.

JPA Specification으로 쿼리 조건 처리하기

해당 코드는 Github에서 확인할 수 있습니다. Spring Data에서 Specification은 DB 쿼리의 조건을 Spec으로 작성해 Repository method에 적용하거나 몇가지 Spec을 조합해서 사용할 수 있게 도와줍니다. 간단한 예

velog.io

1. JPA 페이징 쿼리 개선

cla9 — Wed, 29 Jul 2020 21:36:42 +0900

서론

Pageable 객체를 사용하면 JPA에서 손쉽게 페이징 처리를 할 수 있습니다. 하지만 기본적으로 제공되는 findAll 메소드를 통해 페이징 처리를 요청하면, 매 요청시마다 전체 갯수를 구하기 위한 Count SQL이 수행되는 것을 볼 수 있습니다.

조회 조건이 달라지지 않는 이상 매번 동일한 결과 건수가 보장될텐데, 매번 Count SQL이 수행되는 것은 꽤나 비효율 적입니다. 더불어 Count SQL을 수행하면, 페이징되는 데이터 뿐만 아니라 전체 데이터를 DBMS 메모리에 로딩해서 집계 해야하기 때문에 반복 수행시 성능 이슈가 발생할 수 있습니다.

물론 한번 메모리에 데이터가 로딩되면 그 이후에는 Count SQL 속도가 처음보다는 빠릅니다. 하지만 RDBMS(Oracle 기준)는 DMA(Direct Memorry Access)로 데이터에 즉시 접근할 수 없고 Latch를 획득해야하는 과정이 수반되기 때문에 여전히 Overhead가 존재합니다.

이번 포스팅에서는 CustomRepository 구현을 통해 전체 개수를 알고 있는 상황이라면, Count SQL을 요청하지 않도록 findAll 메소드를 구현하겠습니다.

1. Entity

@Entity
@Table
@Getter
public class Customer {
    @Id
    @GeneratedValue
    @Column(name = "id")
    private Long customerId;
    @Column(name = "name")
    private String customerName;
}

예제를 위해 엔티티는 위와같이 간단히 설정하였습니다. 조회를 위해 사전에 해당 테이블에 100건의 데이터 입력 하였다고 가정하고 진행하겠습니다.

2. 반환 DTO

@Builder(access = AccessLevel.PRIVATE)
@Getter
@JsonNaming(PropertyNamingStrategy.SnakeCaseStrategy.class)
public class CustomerDTO {
    private Long customerId;
    private String customerName;

    public static CustomerDTO of(Customer customer){
        return CustomerDTO.builder()
                .customerId(customer.getCustomerId())
                .customerName(customer.getCustomerName())
                .build();
    }
}

반환되는 DTO는 위와같이 구현했습니다.

3. Repository 구현

@NoRepositoryBean
public interface BaseRepository<T, ID extends Serializable> extends JpaRepository<T,ID> {
    Page<T> findAll(Pageable pageable, Integer totalElements);
    Page<T> findAll(Specification<T> spec, Pageable pageable, Integer totalElements);
    Page<T> findAll(Specification<T> spec, Pageable pageable, Integer totalElements, Sort sort);
}

CustomRepository 구현을 위해 JpaRepository를 상속받는 새로운 Repository를 생성합니다.

여기서 totalElements는 조건에 해당되는 전체 레코드 갯수로 Client가 전체 레코드 갯수를 파라미터로 전달하게 되면, 해당 값을 Page 객체에 삽입 후 Count SQL을 수행하지 않습니다. 반면 값이 전달되지 않으면 Count SQL을 수행합니다.

따라서, Count SQL 수행 여부는 파라미터로 전달되는 totalElements의 유무에 따라 결정됩니다.

public class BaseRepositoryImpl<T,ID extends Serializable> extends SimpleJpaRepository<T, ID> 
        implements BaseRepository<T,ID> {

    public BaseRepositoryImpl(JpaEntityInformation<T, ?> entityInformation, EntityManager entityManager) {
        super(entityInformation, entityManager);
    }

    @Override
    public Page<T> findAll(Pageable pageable, Integer totalElements) {
        return findAll(null, pageable, totalElements, Sort.unsorted());
    }

    @Override
    public Page<T> findAll(Specification<T> spec, Pageable pageable, Integer totalElements) {
       return findAll(spec, pageable, totalElements, Sort.unsorted());
    }

    @Override
    public Page<T> findAll(Specification<T> spec, Pageable pageable, Integer totalElements, Sort sort) {
        TypedQuery<T> query = getQuery(spec, sort);

        int pageNumber = pageable.getPageNumber();
        int pageSize = pageable.getPageSize();

        if(totalElements == null){
            return findAll(spec, pageable);
        }

        if(pageNumber < 0){
            throw new IllegalArgumentException("page number must not be less than zero");
        }

        if(pageSize < 1){
            throw new IllegalArgumentException("pageSize must not be less than one");
        }

        if(totalElements < pageNumber * pageSize){
            throw new IllegalArgumentException("totalElements must not be less than pageNumber * pageSize");
        }

        int offset = (int) pageable.getOffset();
        query.setFirstResult(offset);
        query.setMaxResults(pageable.getPageSize());

        return  new PageImpl<>(query.getResultList(), PageRequest.of(pageNumber, pageSize), totalElements);
    }
}

위 코드는 실제 Repository 구현 코드입니다. 전달받은 파라미터에 대하여 유효성 검증 후 로직에 따라 처리합니다.

만약 totalElements 값이 null이 아니라면 마지막 줄과 같이 Page 객체에 전달받은 값을 그대로 넣습니다.

public interface CustomerRepository extends BaseRepository<Customer, Long> {}

실제 사용하는 Repository에는 JpaRepository가 아닌 CustomRepository를 상속받도록 지정합니다.

@SpringBootApplication
@EnableJpaRepositories(repositoryBaseClass = BaseRepositoryImpl.class)
public class PagingDemoApplication {
    public static void main(String[] args) {
        SpringApplication.run(PagingDemoApplication.class, args);
    }
}

마지막으로 등록한 Repository를 사용하기 위해서는 Configuration 클래스에 @EnableJpaRepositories 어노테이션으로 CustomRepository를 등록합니다.

Service

@Service
@RequiredArgsConstructor
public class CustomerService {
    private final CustomerRepository repository;

    public Page<CustomerDTO> getCustomer(Pageable pageable, Integer totalElements) {
        Page<Customer> customers = repository.findAll(pageable, totalElements);
        return customers.map(CustomerDTO::of);
    }
}

CustomRepository의 메소드를 호출하며, 리턴된 페이지객체에 대해서 DTO로 변환하는 로직을 추가하였습니다.

Controller

@RestController
@RequiredArgsConstructor
public class CustomerController {
    private final CustomerService service;

    @GetMapping("/customers")
    public ResponseEntity<Page<CustomerDTO>> getCustomer(Pageable pageable,
                                                         @RequestParam(required = false, name = "total_elements")Integer totalElements){
        Page<CustomerDTO> customers = service.getCustomer(pageable, totalElements);
        return ResponseEntity.ok(customers);
    }
}

파라미터로 Pageable 객체이외에 totalElements를 전달받아 Service로 전달하는 역할을 수행합니다.

결과

1. totalElements 인자를 입력하지 않았을 경우

위와 같이 Count SQL이 수행되는 것을 확인할 수 있습니다.

2. totalElements 입력 결과

페이징 처리 SQL 수행 후 리턴받은 Page 객체에 전달받은 totalElements 값이 추가되었음을 확인할 수 있습니다.

마치며

이번 포스팅에서 JPA 페이징 수행시 Count SQL을 제거하는 방법에 대해서 살펴보았습니다. 기존에는 매번 Count SQL을 수행하여 Index가 벗어났는지 등을 Server에서 확인하였다면, 지금은 totalElements에 대한 책임이 Client 측에 일부 있습니다. 따라서 조회 조건이 달라진다면, totalElements 값을 전달하지 않는 처리가 Client에서 구현되어야 합니다.

약간의 복잡함은 있지만 비효율적인 Count SQL을 반복수행하는 것을 줄임으로 성능 향상을 꾀할 수 있습니다.

다음 포스팅에서는 Sort와 조회조건처리 관련하여 다루도록 하겠습니다.

5. 쿠버네티스 클러스터 구축 - MetalLB 설치

cla9 — Sat, 18 Jul 2020 21:35:23 +0900

서론

쿠버네티스 클러스터에 존재하는 Pod 서비스를 외부로 노출시키기 위한 가장 원시적인 방법은 NodePort를 이용하는 것입니다. 하지만 NodePort는 인스턴스의 IP가 변경되면 해당 서비스에도 이를 반영해야합니다. 따라서 Cloud 벤더에서는 LoadBalancer나 Ingress 타입을 통해 서비스를 노출할 수 있도록 지원합니다.

이번 포스팅에서는 온 프레미스 환경에서 LoadBalancer 타입을 지원하기 위한 MetalLB를 설치하는 방법을 다루고자 합니다.

문제 상황

1. nginx Deployment를 하나 생성합니다. (kubectl create deploy nginx --image=nginx)

2. 생성한 Deployment를 LoadBalancer 타입으로 서비스를 노출시킵니다.

( kubectl expose deploy nginx --port 80 --type LoadBalancer)

3. 서비스의 상태를 모니터링합니다. (watch kubectl get svc)

아무리 기다려도 해당 Service 오브젝트의 External-IP는 Pending 상태입니다. 이는 LoadBalancer가 존재하지 않기 때문입니다.

4. Service와 Deployment 오브젝트를 제거합니다.

- kubectl delete svc nginx

- kubectl delete depoly nginx

Metal LB 설치

MetalLB 공식 홈페이지 설치 가이드대로 차근차근 설치하겠습니다.

1. MetalLB를 위한 네임스페이스를 생성합니다.

(kubectl apply -f https://raw.githubusercontent.com/metallb/metallb/v0.9.3/manifests/namespace.yaml)

2. MetalLB Components를 생성합니다.

(kubectl apply -f https://raw.githubusercontent.com/metallb/metallb/v0.9.3/manifests/metallb.yaml)

3. Secret을 생성합니다.

(kubectl create secret generic -n metallb-system memberlist --from-literal=secretkey="$(openssl rand -base64 128)")

4. 라우팅 처리를 위한 ConfigMap을 생성합니다.

apiVersion: v1
kind: ConfigMap
metadata:
  namespace: metallb-system
  name: config
data:
  config: |
    address-pools:
    - name: default
      protocol: layer2
      addresses:
      - 192.168.72.102-192.168.72.103

5. 기존과 마찬가지로 nginx를 Deploy한 다음 LoadBalancer 타입으로 노출시킨 결과 이전과는 다르게 nginx Service 오브젝트의 External IP가 할당된 것을 확인할 수 있습니다.

4. 쿠버네티스 클러스터 구축 - NFS 설치

cla9 — Sat, 18 Jul 2020 20:32:54 +0900

서론

이전 포스팅을 통해 VirtualBox에서 쿠버네티스 클러스터를 구축하는 방법을 살펴봤습니다. 이번 포스팅에서는 클러스터내 Pod 끼리 디스크를 공유해야하는 경우 사용되는 Persistent Volume 유형 중 NFS를 구성하는 방법에 대해서 살펴보겠습니다.

쿠버네티스 Persistent Volume 지원 항목

GCEPersistentDisk
AWSElasticBlockStore
AzureFile
AzureDisk
CSI
FC (파이버 채널)
FlexVolume
Flocker
NFS
iSCSI
RBD (Ceph Block Device)
CephFS
Cinder (OpenStack 블록 스토리지)
Glusterfs
VsphereVolume
Quobyte Volumes
HostPath (단일 노드 테스트 전용 – 로컬 스토리지는 어떤 방식으로도 지원되지 않으며 다중-노드 클러스터에서 작동하지 않음)
Portworx Volumes
ScaleIO Volumes
StorageOS

1. NFS 서버 설치

NFS 구축을 위해서는 서버를 먼저 설치해야합니다. 보통 별도 서버를 띄운다음에 구축하는 것이 보편적이지만 편의상 Work1 노드에 NFS 서버를 구축하겠습니다.

1. Work1 노드에서 root 계정으로 접속합니다.

2. update를 수행합니다.

3. NFS 서버를 위한 패키지 프로그램을 설치합니다.

4. 공유 폴더를 새로 만듭니다. (mkdir /home/share/nfs -p)

5. 폴더 권한을 부여합니다. (chmod 777 /home/share/nfs)

6. exports 파일을 엽니다. (vi /etc/exports)

7. 공유폴더의 허용 host 및 권한을 설정합니다.

( /home/share/nfs 192.168.72.101(rw,sync,no_subtree_check) 192.168.72.102(rw,sync,no_subtree_check) 192.168.72.103(rw,sync,no_subtree_check) )

8. nfs-server를 재기동합니다.(service nfs-server restart)

9. nfs-server 상태를 확인합니다.(systemctl status nfs-server.service)

10. mount 목록을 확인하여 정상 반영되었는지 체크합니다. (showmount -e 127.0.0.1)

11. 공유 폴더를 /mnt로 마운트 시킵니다. (mount -t nfs 192.168.72.102:/home/share/nfs /mnt)

12. 정상적으로 마운트되었는지 확인하기 위해 공유 폴더에 테스트 파일을 만듭니다.

(echo test >> /home/share/nfs/test.txt)

13. 마운트 위치에있는 파일을 읽어 정상 동작 여부를 확인합니다. (cat /mnt/test.txt)

14. 임시 파일을 삭제합니다. (rm /mnt/test.txt)

15. Master 노드의 root 계정으로 접속합니다.

16. update를 수행합니다. (apt update)

17. NFS 관련 패키지 프로그램을 설치합니다.(apt install nfs-common nfs-kernel-server portmap)

18. Work2 노드에서 root 계정으로 접속합니다.

19. update를 수행합니다.

20. NFS 관련 패키지 프로그램을 설치합니다.(apt install nfs-common nfs-kernel-server portmap)

2. Persistent Volume 테스트

쿠버네티스 공식 홈페이지에 있는 예제를 활용하여 NFS를 활용한 공유디스크 설정 테스트를 진행합니다.

1. PersistentVolume 테스트를 위한 yaml 파일을 생성합니다.

2. 아래 내용을 복사 & 붙여넣기 합니다.

apiVersion: v1
kind: PersistentVolume
metadata:
  name: my-pv
spec:
  capacity:
    storage: 10Mi
  volumeMode: Filesystem
  accessModes:
    - ReadWriteOnce
  persistentVolumeReclaimPolicy: Recycle
  nfs:
    path: /home/share/nfs
    server: 192.168.72.102

3. PersistentVolume을 생성합니다. (kubectl create -f pv.yaml)

4. PersistentVolume 상태를 확인합니다.

위와같이 Status가 Available이면 정상입니다.

5. 초기화를 위해 PersistentVolume을 삭제합니다. (kubectl delete -f pv.yaml)

마치며

Stateful 애플리케이션을 사용하기 위해서는 Volume 설정이 필요합니다. NFS는 Persistent Volume을 지원하는 한 종류로서 공유 디스크 할당이 가능합니다.

다음 포스팅에서는 LoadBalancer를 위한 MetalLB 설치과정을 다루겠습니다.

3. 쿠버네티스 클러스터 구축 - Docker & 쿠버네티스 클러스터 설치

cla9 — Sat, 18 Jul 2020 17:39:25 +0900

서론

이전 포스팅에서 Ubuntu 설치 및 클러스터 구성을 위한 환경 설정을 진행했습니다. 이번 포스팅에서는 본격적으로 Docker 및 쿠버네티스를 설치하는 과정을 다루겠습니다.

1. Docker 설치

1. root 계정으로 접속합니다. (sudo -i)

2. Docker를 설치합니다. (apt install docker.io)

3. Docker 상태를 확인합니다. (docker ps)

4. nginx 이미지를 실행해서 정상적으로 동작하는지 확인해봅니다.

(docker run -d -p 80:80 --rm --name nginx nginx)

5. Safari를 실행하여 nginx 도커 이미지가 정상적으로 기동되었는지 확인합니다.

6. 생성한 Docker 컨테이너를 정리합니다. (docker stop nginx)

7. nginx 이미지를 삭제합니다. (docker rmi nginx)

2. 쿠버네티스 설치

쿠버네티스 공식 홈페이지에서 제공하는 방법으로 설치를 진행합니다.

설치에 앞서 공식홈페이지에서 요구하는 요구사항을 살펴봅시다.

2 GB or more of RAM per machine (any less will leave little room for your apps)
2 CPUs or more
Full network connectivity between all machines in the cluster (public or private network is fine)
Unique hostname, MAC address, and product_uuid for every node. See here for more details.
Certain ports are open on your machines. See here for more details.
Swap disabled. You MUST disable swap in order for the kubelet to work properly

여기서 마지막 줄을 보면, Swap을 비활성화 해야됩니다. 그 이유는 Swap 기능은 본래 가용된 메모리보다 더 큰 메모리 할당을 가능하도록 하기 위함인데, 쿠버네티스 철학은 주어진 인스턴스의 자원을 100% 가깝게 사용하는 것이 목표이기 때문에 부합되지 않습니다. 따라서 성능을 제대로 사용하기 위해서 Swap 기능을 비활성화 해야합니다.

1. Swap 중지하기 (swapoff -a)

2. 재부팅되면 초기화 되므로 완전하게 중지시킵니다. (sed -i '/ swap / s/^$.*$$/#\1/g' /etc/fstab)

3. 공식 홈페이지에 있는 Kubeadm 설치 명령어를 복사합니다.

명령어

sudo apt-get update && sudo apt-get install -y apt-transport-https curl
curl -s https://packages.cloud.google.com/apt/doc/apt-key.gpg | sudo apt-key add -
cat <<EOF | sudo tee /etc/apt/sources.list.d/kubernetes.list
deb https://apt.kubernetes.io/ kubernetes-xenial main
EOF
sudo apt-get update
sudo apt-get install -y kubelet kubeadm kubectl
sudo apt-mark hold kubelet kubeadm kubectl

4. 명령어 실행을 위하여 shell 파일을 만듭니다. (vi kubeadm-install.sh)

5. 공식 홈페이지에서 복사한 명령어를 붙여넣기 합니다.

위 명령어를 통해서 kubeadm kubelect kubectl이 설치됩니다.

6. Shell 파일을 실행합니다. (sh kubeadm-install.sh)

7. kubeadm이 정상적으로 설치되었는지 확인합니다. (kubeadm version)

8. 마스터 노드를 중지합니다. (halt)

3. 클러스터 구축

1. 쿠버네티스 VM 복사 전에 스냅샷을 찍습니다.( 나중에 문제생길 시 롤백 용도)

2. Worker 노드 복사를 위해 Master VM 선택 후 마우스 오른쪽 클릭 > 복제 버튼을 클릭합니다.

3. 복제할 가상머신의 이름과 저장 경로를 설정합니다.

4. MAC 주소 정책에서 모든 네트워크 어댑터의 새 MAC 주소 생성 버튼을 클릭합니다. 이후 다음 버튼을 클릭합니다.

5. 완전한 복제를 선택후 다음 버튼을 클릭합니다.

6. 복제 버튼을 클릭합니다.

7. 1~6 번과정을 동일하게 반복하여 Work2 가상 머신을 생성합니다.

8. work1 가상 머신을 기동 후 터미널을 엽니다.

9. root로 접속합니다. (sudo -i)

10. hostname을 변경합니다. (hostnamectl set-hostname node01)

11. 고정 IP 설정을 위해 설정 파일 위치로 이동합니다.

12. 설정 파일을 오픈합니다.

13. node01의 IP를 변경합니다. (AS-IS 192.168.72.101, TO-BE : 192.168.72.102)

14. reboot을 수행합니다. (reboot)

15. reboot 이후 hostname이 변경되었음을 확인합니다.

16. work1 가상머신과 동일한 작업을 위해 work2 머신을 기동합니다.

17. 터미널을 엽니다.

18. root로 접속합니다. (sudo -i)

19. hostname을 변경합니다. (hostnamectl set-hostname node02)

20. 고정 IP 설정을 위해 설정 파일 위치로 이동합니다.

21. 설정 파일을 오픈합니다.

22. node02의 IP를 변경합니다. (AS-IS 192.168.72.101, TO-BE : 192.168.72.103)

23. 재부팅을 수행합니다.

24. reboot 이후 hostname이 변경되었음을 확인합니다.

25. Master 가상 머신을 기동합니다.

26. Ping을 수행하여 정상적으로 수행되는지 확인합니다.

(※ Master 뿐만 아니라 Work1, Work2 가상 머신에서도 Ping을 수행하여 패킷이 정상 수신되는지 확인합니다.)

27. Master 노드에서 root 계정으로 접속합니다.

(※ 반드시 Master에서만 수행해야합니다.)

28. kubeadm init 명령어를 수행합니다.

(※ 해당 명령어를 통해 kube-apiserver, scheduler 등이 설치됩니다.)

29. 정상적으로 설치되었으면 아래와 같은 화면이 표시됩니다.

위 화면에서 두가지 작업이 추가됩니다.

먼저 mkdir 부터 시작하는 영역은 kubectl을 통해 Kube API Server와 통신하기 위한 클라이언트 설정입니다.

아래 kubeadm join에 해당하는 영역은 Worker 노드에서 Master 노드 클러스터에 합류하기 위한 명령어입니다.

30. 아래 영역을 드래그하여 복사합니다. 이후 터미널 상단에 위치한 새탭 버튼을 클릭합니다.

31. 새탭에서 복사한 명령어를 수행합니다.

(※ root가 아닌 admin 계정으로 kubectl을 수행할 것이므로 계정이 올바른지 확인합니다.)

32. 이전 탭에서 클러스터 조인 명령어를 복사합니다.

33. Work1 노드, Work2 노드에서 root 계정으로 접속합니다.

34. Work1 노드에서 복사한 명령어를 실행합니다.

35. 아래와 같은 메시지가 나오면 정상적으로 등록된 것입니다.

36. Work2 노드에서도 동일한 명령어를 수행하여 클러스터 Join을 수행합니다.

37. Work2 노드에서 Join이 정상적으로 등록되었는지 확인합니다.

38. Master 노드 kadmin 계정에서 cluster가 정상적으로 구축되었는지 확인합니다. (kubectl get nodes)

위와 같이 3개 노드와 메시지가 표시된다면 정상입니다.

다만 STATUS가 NotReady 상태인 이유는 Pod Network가 구성되지 않았기 때문입니다.

4. Overlay Network 설치

쿠버네티스 공식 홈페이지에 있는 CNI 중 Weave net을 설치하겠습니다.

1. 위 공식 문서 링크를 클릭하여 Weave Net 탭을 선택하여 명령어를 복사합니다.

2. Master 노드에서 해당 명령어를 실행시킵니다.

(kubectl apply -f "https://cloud.weave.works/k8s/net?k8s-version=$(kubectl version | base64 | tr -d '\n')")

3. node 상태를 살펴보면 STATUS가 Ready로 변경된 것을 확인할 수 있습니다. (kubectl get nodes)

4. 쿠버네티스 클러스터가 정상적으로 설치되었는지 확인하기 위해 nginx Deployment를 실행해봅니다.

(kubectl create deploy nginx-deploy --image=nginx)

5. Pod 상태를 확인하여 STATUS Running으로 되어있으면 정상적으로 동작하는 것입니다.

(kubectl get pods -o wide)

6. 실행시킨 Deployment를 종료시킵니다.

(kubectl delete deploy nginx-deploy)

마치며

지금까지 VirtualBox에서 쿠버네티스 클러스터를 구축하는 방법에 대해서 살펴봤습니다. 다음 포스팅에서는 공유 디스크 환경을 구성하는 NFS를 설정하여 PersistentVolume을 구성할 수 있도록 환경을 구성하는 방법을 살펴보겠습니다.

2. 쿠버네티스 클러스터 구축 - Ubuntu 설치 및 환경 구성

cla9 — Sat, 18 Jul 2020 16:28:03 +0900

서론

이전 포스팅을 통해 Ubuntu 이미지 다운로드 및 VirtualBox 기본 환경 설정을 구성하였습니다. 이번 포스팅에서는 K8S 클러스터 설치를 위한 기본 구성을 진행하겠습니다.

1. Ubuntu 설치

1. VM 기동을 위해 머신 선택 후 시작 버튼을 누릅니다.

2. 언어 설정 이후에 Ubuntu 설치 버튼을 클릭합니다.

3. 별다른 설정없이 계속하기 버튼을 클릭합니다.

4. 계속하기 버튼을 선택합니다.

5. 지금 설치 버튼을 클릭합니다.

6. 계속 하기 버튼을 누릅니다.

7. 지역 선택 후 계속 하기 버튼을 클릭합니다.

8. 컴퓨터 정보 입력 후 계속하기 버튼을 클릭합니다.

9. 설치가 완료될 때 까지 기다립니다.

10. 설치가 완료되면 지금 다시 시작 버튼을 누릅니다.

11. 아래와 같은 화면이 출력된다면, Enter키를 누르면 서버가 재시작됩니다.

Ubuntu 환경 설정

1. VM 재시작 이후 로그인합니다.

2. 건너뛰기 버튼을 클릭합니다.

3. 다음 버튼을 클릭합니다.

4. 완료 버튼을 눌러 최초 시작 환경 구성을 종료합니다.

5. 소프트웨어 업데이터 창이 뜬다면 지금 설치를 눌러 업데이트를 진행합니다.

6. 환경 구성을 위해 목록창을 열고 터미널을 입력하여 터미널 창을 띄웁니다.

7. root 계정으로 작업하기 위해 sudo -i 명령어를 입력합니다.

8. root 계정의 비밀번호를 변경합니다. (passwd)

9. update를 진행합니다. (apt update)

10. openssh-server를 설치합니다. (apt install openssh-server)

11. ifconfig 명령어를 보기 위해 net-tools를 설치합니다. (apt install net-tools)

12. 학습 목적이므로 모든 방화벽을 해제합니다. (ufw disable)

13. 방화벽 상태를 확인합니다. (ufw status verbose)

14. Vim을 설치합니다. (apt-get install vim)

15. 편의 기능인 클립보드 및 공유폴더 기능을 사용하기 위해 장치 > 게스트 확장 CD 이미지 삽입 버튼을 클릭합니다.

16. 실행 버튼을 클릭합니다.

17. 인증 필요시 비밀번호 입력 후 인증 버튼을 클릭합니다.

18. 클립보드 공유를 위해 장치 > 클립보드 공유 > 양방향 버튼을 클릭합니다.

19. 지금부터 네트워크 설정을 하겠습니다. 먼저 hosts 파일을 열어 master 노드와 worker 노드의 IP 목록을 입력한 다음 저장합니다.

20. hostname을 변경합니다. (hostnamectl set-hostname master)

21. ip 목록을 확인합니다. (ifconfig)

위 그림에서 enp0s3에 등록된 ip는 Bridge Adaptor로 등록된 IP이며, PC에서 SSH를 통해 접속 가능합니다.

확인을 위해 개인 PC에서 Putty를 통해 해당 IP로 접속시도하면 정상적으로 커넥션이 맺어지는 것을 확인할 수 있습니다.

22. Host Only Ethernet 설정을 위해 설정 파일이 있는 폴더로 이동합니다. (cd /etc/netplan/)

23. 설정 파일을 열어 고정 IP 설정을 진행합니다.

24. 고정 IP 설정을 적용합니다. (netplan apply)

25. IP 설정이 정상적으로 되었는지 확인합니다. (hostname -I)

26. hostname 변경 적용을 위해 reboot을 진행합니다.(reboot)

27. reboot 이후에 hostname이 변경되었음을 확인합니다.

마치며

Docker 및 쿠버네티스 설치를 위한 기초 설정 작업을 마쳤습니다. 다음 포스팅에서는 Docker & Kubernetes 설치 과정을 다루어보겠습니다.

1. 쿠버네티스 클러스터 구축 - Virtual Box 환경 설정

cla9 — Sat, 18 Jul 2020 13:15:13 +0900

서론

쿠버네티스를 처음 공부할 때 난해한 부분이 클러스터 설치라고 생각합니다. 물론 GCP, AWS와 같은 클라우드에서 제공하는 쿠버네티스 클러스터를 활용하거나 Katakoda와 같은 웹사이트를 통해 접할 수도 있지만, 직접 VM으로 클러스터를 구축하는 경험도 중요하다고 생각합니다.

향후 몇개의 포스팅을 통해 VirtualBox를 통해 3개(1 Master, 2 Worker)의 K8S 클러스터를 구축방법을 다루어보고자 합니다. 쿠버네티스는 Kubeadm을 활용하여 설치할 계획이며, 학습 목적이므로 Ansible이나 기타 자동화 툴 도입이나 상세 설정 없이 설치하는 과정을 설명합니다.

PC 환경은 램 16GB 이상을 권장드리며, 공유기가 있다는 전제하에 네트워크 구성은 Bridge Adaptor를 통해 구성하오니 내용 참고 바랍니다.

(※ 공유기가 없는 환경이라면 NAT 네트워크를 구성하여 진행 가능합니다.)

앞으로 다룰 내용

1. VirtualBox Ubuntu 설치

2. Docker 설치

3. 쿠버네티스 클러스터 구성

4. NFS 구성

5. metallb 설치

6. ingress-nginx 설치

이번 포스팅은 첫 번째로 VirtualBox를 사용하여 이미지 설치를 위한 기초 설정을 다루겠습니다.

1. VirtualBox 설치

VirtualBox 공식 홈페이지에 접속하여 프로그램을 다운로드 후 설치를 진행합니다.

설치시 특별한 설정 없이 다음버튼을 눌러 진행하면 되므로 설치 과정은 생략하겠습니다.

2. Ubuntu 이미지 다운로드

1. Ubuntu 공식 홈페이지에 접속하여 Desktop 다운로드 버튼을 누릅니다.

2. 이미지를 다운로드 받습니다. 만약 이미지 다운로드가 되지 않는다면, Download Now 링크를 클릭합니다.

3. VirtualBox 설정

1. VirtualBox를 실행시킵니다.

2. 상단의 머신 > 새로 만들기 버튼을 선택합니다.

3. 이미지의 이름을 지정합니다.

4. VM 이미지 설치 위치를 저장하기 위해 머신폴더 > 기타를 선택합니다.

5. 설치 위치를 선택한 다음 폴더 선택 버튼을 누릅니다.

6. 종류와 버전을 선택한 다음 다음 버튼을 누릅니다.

7. 컴퓨터 사양을 고려하여 메모리를 할당(2GB 이상) 후 다음버튼을 누릅니다.

8. 가상디스크를 만들기 위해 만들기 버튼을 클릭합니다.

9. 기본 설정을 유지한채 다음 버튼을 클릭합니다.

10. 동적 할당을 선택 후 다음 버튼을 클릭합니다.

11. PC 사양을 고려하여 이미지 할당 크기를 지정한 다음 저장 위치를 지정합니다. 완료 후 만들기 버튼을 클릭합니다.

12. Network 및 기타 설정을 위해 생성된 머신 선택 > 마우스 오른쪽 클릭 > 설정 버튼을 누릅니다.

13. CPU 설정을 위해 시스템 > 프로세서 탭에서 CPU 개수를 2개로 설정합니다.

14. Ubuntu 이미지를 설정하기 위해서 저장소 > 비어 있음 > 디스크 버튼 > Choose a disk file... 버튼을 클릭합니다.

15. 다운로드 받은 Ubuntu 이미지를 선택한 다음 열기 버튼을 누릅니다.

16. Ubuntu 이미지로 설정된 것을 확인합니다.

17. 네트워크 > 어댑터1에서 이름을 어댑터 브리지로 선택합니다.

18. Host 네트워크 설정을 위해 어댑터 2 > 네트워크 어댑터 사용하기 클릭 > 호스트 전용 어댑터를 선택합니다.

확인 버튼을 눌러 종료합니다.

마치며

Ubuntu 설치를 위한 기본적인 설정은 마무리 되었습니다.

다음 포스팅에서는 Ubuntu 설치 및 기본적인 환경 구성을 진행하겠습니다.

7. Reification

cla9 — Tue, 10 Mar 2020 23:18:16 +0900

지금까지 Generic 기초 및 동작 원리에 대해서 살펴봤습니다.

Generic을 활용한 Type erasure 동작 방법을 정리하면 다음과 같습니다.

경계가 표시된 Type은 경계로 컴파일시에 치환된다
Unbounded Wildcard(?) 타입은 Object 타입으로 치환된다
타입 안정성 보장을 위해서 캐스팅 연산을 수행한다.
Generic Type에 대한 다형성 지원을 위해서 Bridge 메소드를 추가한다.

개인적으로 Generic이 도입은 Java를 사용함에 있어 많은 편의성을 가져다 줬지만, 이에 못지않은 불편함 또한 주었다고 생각합니다. 즉 Type erasure로 인하여 하위 호환성을 유지할 순 있었지만, 한참이 지난 지금도 런타임시 타입을 알지 못하는 불편함으로 인해 개발자가 코드 작성시에 주의를 기울여야합니다.

이번 포스팅에는 Type erasure에 의해서 런타임시 표현되는 Unknown Type 불일치로 인해 주의해야할 점을 다루도록 하겠습니다.

Reifiable Type

Java에서 Runtime시에 완전하게 오브젝트 정보를 표현할 수 있는 타입을 가르켜 Reifiable 하다고 합니다.

즉 Compile 단계에서 Type erasure에 의해서 지워지지 않는 타입 정보를 말합니다.

Reifiable 가능한 타입 정보는 다음과 같습니다.

원시 타입(int, double, float, byte 등등)
Number, Integer와 같은 일반 클래스와 인터페이스 타입
Unbounded Wildcard가 포함된 Parameterized Type(List<?>, ArrayList<?> 등)
Raw Type(List, ArrayList, Map 등)

Unbounded Wildcard는 애초에 타입 정보를 전혀 명시하지 않았기 때문에, 컴파일시에 Type erasure 한다고 해도 잃을 정보가 없습니다. 따라서 Reifiable 하다고 볼 수 있으며, 컴파일시점에 Object로 치환됩니다.

그외 나머지는 Generic을 사용하지 않았기 때문에 타입 정보가 그대로 남습니다.

반면 아래 타입의 경우에는 Reifiable 하지 않습니다.

Generic Type(T)
Parameterized Type(List<Number, ArrayList<String> 등)
경계가 포함된 Parameterized Type(List<? extends Number>, List<? super String> 등)

Reifiable 하지 않은 경우에 대해서 차근차근 살펴보겠습니다.

우선 Generic Type은 Type erasure에 의하여 삭제되는 것은 이전의 포스팅들을 통해서 이해되셨을 것으로 생각합니다.

Parameterized Type의 경우에는 Type erasure에 의하여 컴파일시에 Raw Type으로 변경됩니다.

가령 List<String>, List<Integer>, List<List<String>>의 타입정보는 컴파일 시에 타입 안정성 검증 용도로 사용될 뿐 컴파일이 완료되면 Raw Type인 List로 치환됩니다. 따라서 Reifiable 하지 않습니다.

경계가 포함된 Parameterized Type 또한, 컴파일 시 타입 안정성 검증 용도로만 사용되므로 동일합니다.

그렇다면 위와같은 특성으로 인하여 주의해야할 점이 무엇이 있을까요?

Instance Test

public class Main {
    public static void main(String[] args) {
        Integer  a = 3;
        System.out.println(isIntegerType(a));
    }
    public static boolean isIntegerType(Object b){
        return b instanceof Integer;
    }
}

전달받은 타입이 Integer인지 확인하는 메소드를 구현한다고 가정합시다. 가장 심플한 방법은 instanceof 문법을 사용해서 Integer 임을 확인할 수 있습니다.

그럼 해당 메소드를 Generic 메소드로 변경해도 문제 없을까요?

public class Main {
    public static void main(String[] args) {
        Integer  a = 3;
        System.out.println(isIntegerType(a));
    }
    public static <T> boolean isIntegerType(T b){
        return b instanceof Integer;
    }
}

위 코드를 수행하면 문제없이 동작합니다. 그 이유는 Integer 타입은 런타임시에도 Integer 타입이기 때문입니다.

public class Main {
    public static void main(String[] args) {
        List<Integer> ints = Arrays.asList(1,2,3);
        System.out.println(isIntegerList(ints));
    }
    public static <T> boolean isIntegerList(T b){
        return b instanceof List<Integer>; //Compile 에러 발생
    }
}

이번에는 List<Integer> 타입임을 확인하는 메소드를 생성한다고 가정해봅시다. 위와같이 만들었을 때 정상적으로 동작할까요?

우리는 런타임시에 List의 Type Argument가 Integer임을 확인하고 싶으나 컴파일 이후에는 Raw Type으로 변경됩니다. 따라서 List<Integer> 임을 확인할 수 없기 때문에 애초에 컴파일 에러가 발생합니다.

public class Main {
    public static void main(String[] args) {
        List<Integer> ints = Arrays.asList(1,2,3);
        System.out.println(isList(ints));
    }
    public static <T> boolean isList(T b){
        return b instanceof List;
    }
}

물론 Raw Type 자체는 Reifiable 하기 때문에, 위와 같이 Raw type으로 명시하면 컴파일 에러도 발생하지 않고 정상적으로 동작합니다. 하지만 여전히 해당 List의 Element 타입이 Integer임은 알 수 없습니다.

public class Main {
    public static void main(String[] args) {
        List<Integer> ints = Arrays.asList(1,2,3);
        System.out.println(isList(ints));
    }
    public static <T> boolean isList(T b){
        return b instanceof List<?>;
    }
}

가급적이면 Raw type을 사용하는 것은 지양하는 것이 좋으므로 Reifiable한 Wildcard를 사용하여 동일한 구문을 표현할 수 있습니다.

일반적으로 instanceof 문법을 사용한 코드는 code smell로 표현하여 잘 사용하지는 않지만, 만약 사용한다 할지라도 반드시 Reifiable한 타입에만 사용할 수 있다는점을 유의합시다.

캐스팅

public class Main {
    public static void main(String[] args) {
        List objs = Arrays.asList(1, 2, 3);
        List<Integer> ints = (List<Integer>)objs;
    }
}

위와 같이 Raw Type의 List에 Integer 타입 원소만 있다고 가정할 때, 이를 List<Integer> 타입으로 캐스팅할 수 있을까요?

실제로 어플리케이션으로 실행하면, 정상적으로 수행되는 것으로 보입니다.

하지만 자세히 보면, cast 관련 Warning이 발생된 것을 확인할 수 있습니다.

그 이유는 마찬가지로 컴파일이 완료된 이후에는 타입정보가 없어지는데, List<Integer> 타입으로의 안전한 캐스팅을 보장할 수 없기 때문입니다.

그렇다면 Instance Test에서는 에러를 발생시켰는데, 캐스팅에서는 Warning을 발생시킨 것일까요?

다음 예제코드를 보며, 그 이유를 알아보도록 하겠습니다.

public static List<Integer> getAsIntegerList(List<?> objs){
    objs.forEach(o->{
        if(!(o instanceof Integer))
            throw new ClassCastException();
    });
    return (List<Integer>)objs;
}

List 오브젝트를 전달받아, 해당 List안에 있는 원소가 모두 Integer 일경우에는 List<Integer>로 캐스팅하여 반환하는 메소드를 구현한다고 가정해봅시다.

위 코드에는 이미 List 원소를 탐색하면서 Integer가 아닌 원소가 하나라도 존재한다면 ClassCastException이 발생합니다.

즉 List<Integer>로 캐스팅하는 코드에 도달한다면 이미 objs 리스트에는 모든 원소가 Integer 임이 반드시 보장됩니다.

따라서 java에서는 개발자가 의도적으로 위 코드와 같은 캐스팅을 수행할 수 있을 수도 있기때문에 에러가 아닌 Warning을 발생시킵니다.

따라서, 만약 위와같이 의도적으로 Non-Reifiable 타입에 대해서 캐스팅을 수행했다면 @SuppressWarnings("unchecked") 어노테이션을 붙여서 컴파일 시점에 Warning이 발생하지 않도록 처리해야합니다.

Exception

public class MyException<T> extends Exception{}


try {
   ....
}catch (MyException<Integer> e){
   ....   
}

Throwable을 상속받는다면 Generic 클래스를 생성할 수 없습니다. 또한 catch 구문에서 Parameterized Type을 사용할 수 없습니다. 이는 이전의 설명과 마찬가지로 런타임 시점에 타입확인이 불가하기 때문입니다.

6. Generic 메소드

cla9 — Tue, 10 Mar 2020 00:01:49 +0900

Integer 값이 들어있는 List 원소중 가장 큰 값을 리턴하는 함수를 만든다고 가정해봅시다.

public static int max(Collection<Integer> cols){
    return cols.stream().max((o1, o2) -> o1.compareTo(o2)).get();
}

대략 위와같이 구현할 수 있습니다. 그럼 Integer 타입이아닌 비교가 가능한 모든 클래스 타입이 사용될 수 있도록 하려면 어떻게 해야할까요?

그동안 학습한 내용을 적용하면서 이번 포스팅 주제를 다루어보겠습니다.

Step 1. Generic 사용

public static <T> T max(Collection<T> cols){
    return cols.stream().max((o1, o2) -> o1.compareTo(o2)).get(); //Compile 에러 발생
}

Get and Put 원리 고민없이 작성한다면 위와같이 작성할 수 있습니다. 여기서 첫번째 등장하는 <T>는 T 타입의 경계를 지정합니다. 이는 첫번째 포스팅에서 클래스 멤버 변수 타입의 경계 설정과 동일한 개념입니다.

하지만 이를 실행하면 두 원소의 대소 비교부분인 compareTo 메소드에서 컴파일 에러가 발생하게됩니다.

과연 무엇이 문제일까요?

첫번째 등장하는 <T> 구문은 T 타입의 경계를 지정한다고 했습니다.

위 코드는 Generic 타입이 존재한다는 것만 지정할 뿐, 해당 타입에 대한 경계를 지정하지 않았습니다.

이는 어떠한 타입이 지정되어도 상관없다는 의미입니다. 문제는 여기서 발생합니다.

compareTo 메소드를 사용하기 위해서는 해당 클래스에 Comparable 인터페이스가 구현되어있어야 합니다.

하지만 T 타입에는 어떠한 타입도 허용가능하므로 문제가 발생할 수 있습니다. 따라서 허용되지 않습니다.

이와 같은 문제를 해결하기 위해서는 Comparable 인터페이스가 구현된 타입만 지정되도록 경계를 정의해야합니다.

Step2. 타입 경계 적용

 public static <T extends Comparable<T>> T max(Collection<T> cols){
    return cols.stream().max((o1, o2) -> o1.compareTo(o2)).get();
 }

메소드 레벨에서 타입 경계를 Comparable로 지정하면, Comparable Subtype 만 지정될 수 있습니다. 따라서 메소드 내부에서 compareTo 사용이 가능합니다.

Step3. Get and Put 원리 적용

public static <T extends Comparable<? super T>> T max(Collection<? extends T> cols){
    return cols.stream().max((o1, o2) -> o1.compareTo(o2)).get();
}

Get and Put 원리를 적용하면 위와같이 변경 가능합니다. 그 이유는 Collection 내부에서 바깥으로 T의 Subtype 값을 꺼내며, Comparable 인터페이스 compareTo 메소드안으로 값을 넣기 때문입니다.

Step4. Method Reference 적용

public static <T extends Comparable<? super T>> T max(Collection<? extends T> cols){
    return cols.stream().max(T::compareTo).get();
}

추가로 Generic 타입에 메소드 레퍼런스를 적용하면 위와같이 작성할 수 있습니다.

Bridge 메소드

public interface Comparable{
	public int compareTo(Object o);
}

이번에는 Bridge 메소드에 대해서 알아보겠습니다. Java 1.4 버전 이하에서는 Generic 지원이 없었기 때문에 Comparable 인터페이스 구조는 위와 같습니다. 이때 파라미터는 모든 타입을 허용해야하므로 Object 타입인 것을 확인할 수 있습니다.

class Integer implements Comparable{
    private final int value;
    public Integer(int value) { this.value = value; }
    public int compareTo(Integer o){
        return (this.value < o.value) ? -1 : (value == o.value ? 0 : 1 );
    }
    @Override
    public int compareTo(Object o) {
        return compareTo((Integer)o);
    }
}

이를 구현해야하는 Integer, Double 등의 클래스에서는 올바른 비교 처리를 위해 Object를 자기 자신의 클래스 타입으로 치환하여 처리하도록 부가적인 메소드 구현이 필요했습니다.

public interface Comparable<T>{
	public int compareTo(T o);
}

class Integer implements Comparable<Integer>{
    private final int value;
    public Integer(int value) { this.value = value; }
    @Override
    public int compareTo(Integer o){
        return (this.value < o.value) ? -1 : (value == o.value ? 0 : 1 );
    }
}

Generic 등장 이후 compareTo 메소드에 Object가 아닌 명확한 타입 지정이 가능해졌습니다.

따라서 이를 구현하는 클래스에서도 Object 타입이 아닌 자신이 지정한 타입으로의 메소드 구현이 가능해졌습니다.

그 결과 Bridge 메소드 없이 1개의 메소드만 구현하면 됩니다.

하지만 여기서 한가지 의문이 발생합니다.

'Java는 하위 호환성을 중요시 여기는 언어인데, 위와 예시와 같이 Generic 도입에 따라서 메소드 수가 줄어들게 되면, 이는 Integer 클래스 구조가 변경되므로 하위 호환성을 유지할 수 있을까?'

실제 구조가 변경되었는지 확인을 위해 Reflection을 활용해서 런타임시 compareTo 메소드 정보를 출력해보겠습니다.

public class Main {
    public static void main(String[] args) {
        Stream.of(Integer.class.getDeclaredMethods())
                .filter(m -> "compareTo".equals(m.getName()))
                .map(Method::toGenericString)
                .forEach(System.out::println);
    }
}

public int java.lang.Integer.compareTo(java.lang.Object)
public int java.lang.Integer.compareTo(java.lang.Integer)

출력 결과 2개의 메소드가 존재함을 확인할 수 있습니다.

이를 통해 알 수 있는 사실은 Generic 타입 파라미터가 포함된 메소드를 오버로딩 할경우 Bridge 메소드를 자동으로 추가하여 레거시 코드와 호환성을 유지한다는 점입니다.

5. Wildcard

cla9 — Sun, 8 Mar 2020 18:35:37 +0900

Unbounded Wildcard

Collections 클래스에는 reverse API가 있습니다. 해당 API는 주어진 Collection내 원소들을 역순으로 뒤집어주는 기능을 수행합니다.

public class Collections {
    ....
    public static void reverse(List<?> list){}
    ....
}

위 파라미터 변수를 살펴보면 wildcard가 사용되었지만 그 어떠한 경계도 지정되지 않은 형태로 사용되었습니다.

이는 말 그대로 타입 변수가 어떠한 것이든 상관이 없음을 의미합니다.

자세히 보면 List<Object> 와 의미가 비슷하다고 생각할 수 있습니다.

하지만 List<?>와 List<Object>는 다릅니다.

public class Main{
   public void static main(int argc, String[] argv){
       List<Object> ints = new ArrayList<>();
       ints.add(1);
       ints.add(2);
       List<?> objs;
   }
}

List<Object>에는 Object 의 Subtype이 할당될 수 있지만, List<?>에는 오직 null 만이 할당될 수 있습니다. null만 할당이 가능하다는 점에서 List<? extends Object>와 같습니다.

Unbounded Wildcard 의미는 전달되는 변수의 타입이 무엇인지 정확히는 모르나 타입은 존재하며, 관심대상은 파라미터 타입이 아닌 객체가 제공하는 기능입니다.

즉 위 예시의 경우에는 관심대상은 List 인터페이스가 제공하는 기능이지 그 안에서 제공되는 타입들이 제공되는 기능은 관심대상은 아닙니다.

Unbounded Wildcard 내용을 정리하면 다음과 같습니다.

Object 클래스에 의하여 제공되는 기본적인 기능을 사용할 경우
타입 파라미터에 의존적이지 않은 Generic Class에서 제공되는 기능을 사용하는 경우
매개 변수로 전달되는 실제 타입은 관심 대상이 아니다.

Wildcard Capture

Get and Put 원리를 적용하여 reverse API를 직접 구현해봅시다. 메소드 수행 동작상에서 List의 원소가 제공하는 기능은 관심대상이 아니기에 다음과 같이 Spec을 정의할 수 있습니다.

public static void reverse(List<?> list)

메소드를 구현하면 대략 다음과 같습니다.

public static void reverse(List<?> list){
    List<Object> tmp = new ArrayList<>(list);
    for(int i =0;i < tmp.size();i++){
        list.set(i, tmp.get(i));
    }
}

Error:(12, 32) java: incompatible types: java.lang.Object cannot be converted to capture#1 of ?

위 메소드에서 tmp 리스트의 타입 인자가 Object인 이유는 전달받는 타입 정보를 모르기 때문에 모든 타입을 수용할 수 있도록 Object로 지정하였습니다.

하지만 메소드를 수행하면 에러가 발생하는 것을 볼 수 있습니다.

무엇이 문제였을까요?

public interface List<?> extends Collection<?>{
    ...
    ? get(int index);
    ? set(int index, ? element)
    ...
}

상위 경계 포스팅에서 다루었던 내용을 잠시 복습해보겠습니다.

Wildcard로 타입 인자가 지정되었을 때 타입에 대한 정보를 모르기때문에, 위 인터페이스에서 set 메소드를 호출할때마다 이를 지칭하기 위해 capture# of ?와 같은 형태로 컴파일러가 임의의 타입 변수를 할당합니다. 이를 Wildcard Capture라고 합니다.

문제는 알지 못하는 임의의 타입 T를 가르키는 capture# of ? 변수는 컴파일러가 내부적으로만 사용하고 타입 제약조건을 공식화하는데 사용하지 않는다는 점입니다.

따라서 Object 타입의 값을 알 수 없는 List에 집어넣으려고 하기 때문에 에러가 발생합니다.

public static void reverse(List<T> list){
    List<T> tmp = new ArrayList<>(list);
    for(int i =0;i < tmp.size();i++){
        list.set(i, tmp.get(i));
    }
}

가장 심플한 방법은 reverse API를 위와 같이 타입 파라미터를 명시하는 방법입니다.

하지만, 관심대상이 아닌 T 타입을 컴파일러 제약때문에 API에 넣는다는 것은 그다지 좋은 디자인이 아닙니다.

따라서 API 디자인 규칙을 잘 준수하면서도 기능 동작을 구현하기위해 일종의 컴파일러 트릭을 사용합니다.

위 코드는 Helper 메소드를 사용하여 문제를 해결하였습니다. 즉 reverse 메소드를 호출할 때는 Wildcard Capture 정보를 타입 제약 조건으로 사용되지 않았습니다. 하지만 내부적으로 reverseHelper 메소드를 호출할때, 파라미터 타입에 T 타입을 명시하였기 때문에, capture# of ?와 같은 정보를 타입으로써 지정할 수 있습니다.

이후 동일 타입내에서 값을 추출하고 넣음을 보장할 수 있기때문에 값 할당이 허용됩니다.

Wildcard 제한

public class Main {
    public static void main(String[] args)  {
        List<?> list = new ArrayList<?>(); //Compile 에러 발생
    }
}

Wildcard를 사용하면, 이를 기반으로 인스턴스 생성이 불가합니다.

만약, 타입 자동 추론을 이용하여 위 그림과 같이 list를 생성 할지라도, add 수행시 알 수 없는 타입이기 때문에 null외에 값 허용이 안됩니다.

이러한 제한을 둔 배경에는 Wildcard는 구체적인 타입 파라미터가 지정된 객체를 가르키는 것이기 때문에, 타입을 알 수 없는 Wildcard가 지정된 인스턴스 생성은 바람직하지 않기 때문입니다.

하지만 Wildcard가 쓰여있다고 해서 모든 객체가 생성 불가능한 것은 아닙니다.

Nested 형태로 Wildcard가 명시된 구조에서는 생성 가능합니다.

public class Main {
    public static void main(String[] args)  {
        List<List<?>> lists = new ArrayList<List<?>>();
        List<Integer> ints = Arrays.asList(1, 2, 3);
        List<Double> dbls = Arrays.asList(1.0, 2.0);
        lists.add(ints);
        lists.add(dbls);
    }
}

다만, 위에서도 볼 수 있듯이 Nested 형태 Wildcard가 포함된 인스턴스 또한 다른 List의 타입 파라미터를 가르키는 용도로 사용될 뿐 Wildcard 자체가 타입으로써 사용되지는 않습니다.

4. Wildcard with super(하위 경계)

cla9 — Fri, 6 Mar 2020 21:24:25 +0900

public class Collections {
    ....
    public static <T> void copy(List<? super T> dest, List<? extends T> src){}
    ....
}

Collections 클래스는 List와 관련된 여러 유용한 기능을 제공합니다. 그 중 copy API를 통해서 이번절 내용을 살펴보겠습니다.

copy는 src 변수가 가르키는 List의 데이터 값을 dest 변수가 가르키는 List에 저장하는 기능을 제공합니다.

여기서 우리는 지금까지 보지 못한 구문을 또 발견하게됩니다.

? super T
<T>

2번째 내용은 다음 포스팅에서 다루기로하며, 이번 절에서는 ? super T 구문에 대해서 살펴보겠습니다.

? super T는 무엇을 의미할까요?

이는 T 타입 뿐만 아니라 T 타입의 모든 Supertype까지 허용하겠다는 의미입니다.

즉 T 타입이 Integer라면 List<Integer> 외에 List<Number> 및 List<Object> 형태 할당을 허용하겠다는 의미입니다.

이러한 특성을 Contravariant 라고 합니다.

또한, Parameter Type을 T 타입 이상으로 제한한다고해서 하위 경계(Lower bound)라고 말합니다.

예제를 통해서 개념을 살펴보겠습니다.

public class Main {
    public static void main(String[] args)  {
        List<Object> objs = Arrays.asList(2, 3.14, "Penguin");
        List<Integer> ints = Arrays.asList(1, 2);
        Collections.copy(objs, ints);
        System.out.println(objs);
    }
}

위 코드는 Object List에 Integer List 값을 추가하는 코드입니다.

여기에서 Collections.copy 메소드는 objs 객체, ints 객체에도 속하지 않습니다. 따라서 메소드 호출 시에 어떠한 타입으로 호출될지 컴파일러가 추론하거나 개발자가 명시적로 호출시 타입을 지정해야합니다.

이때 지정될 수 있는 타입의 종류는 Integer, Number(Integer의 Supertype 이므로), Object입니다.

Collections.copy(objs, ints);
Collections.<Integer>copy(objs, ints);
Collections.<Number>copy(objs,ints);
Collections.<Object>copy(objs,ints);

public static <T> void copy(List<T> dest, List<? extends T> src){}

이러한 상황에서 만약 copy 메소드의 dst 변수 타입이 하위 경계가 아닌 T 타입으로 설계되어 있었다면 어떠한 타입으로 추론될까요?

public static <Object> void copy(List<Object> dest, List<? extends Object> src){}

위 코드를 만족시키기 위해서는 추론되는 타입이 Object 타입만 허용 가능합니다. 그 이유는 dest에 할당되는 Parameterized Type이 List<Object>이기 때문입니다.

따라서 위의 4가지 경우 중 1번과 4번 메소드 호출만 성공하고, 나머지 2개의 타입은 컴파일 오류가 발생합니다.

public static <T> void copy(List<? super T> dest, List<? extends T> src){}

이번에는 원래의 copy 메소드처럼 상위 경계와 하위 경계를 같이 쓰게되는 경우에는 어떻게 될까요? 결과는 위 4가지 어떠한 타입으로 추론되더라도 문제가 없습니다.

타입을 직접 명시하는 경우를 기준으로 하나하나씩 살펴볼까요?

1. Collections.<Integer>copy()

public static <Integer> void copy(List<? super Integer> dest, List<? extends Integer> src){}

Object는 Integer의 SuperType이고, Integer는 자기 자신에 대한 Subtype이므로 위와 같이 추론될 경우 할당 가능합니다.

2. Collections.<Number>copy()

public static <Number> void copy(List<? super Number> dest, List<? extends Number> src){}

Object는 Number Class의 SuperType이고, Integer <: Number 이므로 할당 가능합니다.

3. Collections.<Object>copy()

public static <Object> void copy(List<? super Object> dest, List<? extends Object> src){}

Object는 모든 Class의 SuperType이므로 할당 가능합니다.

위 사실들을 기반으로 사용될 수 있는 타입 파라미터 종류를 조합해보면 다음과 같은 결과를 얻을 수 있습니다.

1. copy(List<T> dst, List<T> src)
- 동일 타입만이 가능하므로, 위 예제에서는 해당 메소드를 사용할 수 없습니다.

2. copy(List<T> dst, List<? extends T> src)
  - dst가 Object 타입이므로 Object 타입 추론될 경우에만 허용 가능합니다.

3. copy(List<? super T> dst, List<T> src)
  - src가 Integer 이므로 Integer 타입 추론될 경우에만 허용 가능합니다.

4. copy(List<? suepr T> dst, List<? extends T> src)
  - Object, Number, Integer 타입 어떤 것이 오든지 허용 가능합니다.

이를 통해 알 수 있는 사실은 적절한 경계를 사용함으로서 메소드의 타입을 추론하는데 있어서 한정된 타입만 사용되지 않도록하여 유연한 API 설계를 가능하도록 지원합니다.

그렇다면 하위 경계는 언제 주로 활용될까요?

전달받은 구조 내부로 T나 T의 Subtype으로 값을 입력하는 경우 주로 사용됩니다.

public class Main {
    public static void main(String[] args)  {
        List<Integer> ints = new ArrayList<>();
        ints.add(1);
        ints.add(3);
        List<? super Integer> ints2 = ints;
        ints.add(4);
        
        for(Integer i : ints2){   //Compile 에러 발생
           System.out.println(i);
        }
    }
}

위 예제와 같이 ints2 객체에서는 Integer Subtype 값 입력이 가능합니다.

반면, 해당 구조체로부터 값을 가져오려는 경우에는 컴파일 에러가 발생합니다.

그 이유는, 컴파일러 입장에서 해당 객체는 Integer의 상위 타입은 모두 올 수 있는데, 그것을 Integer 타입 변수로 할당 받는 것은 적합하지 않기 때문입니다.

하지만 하위 경계에도 예외가 존재합니다. 즉 하위 경계는 주로 값 입력을 위해 사용되나, 특정 타입에 경우에는 값을 가져올 수 있습니다. 그것은 바로 Object 타입입니다.

public class Main {
    public static void main(String[] args)  {
        List<Integer> ints = new ArrayList<>();
        ints.add(1);
        ints.add(3);
        List<? super Integer> ints2 = ints;
        ints.add(4);
        
        for(Object i : ints2){  
           System.out.println(i);
        }
    }
}

그 이유는 Object는 모든 클래스의 부모 클래스이기 때문입니다.

아래 예시를 통해서 자세히 알아보겠습니다.

List<? super Integer> 변수 사용시, 어떠한 타입이 올지 모르므로 해당 타입을 임의의 타입 변수 X라고 가정해봅시다.

이때 Integer <: X이며, X <: Object 입니다.

public interface List<X> extends Collection<X>{
    ...
    X get(int index);
    void add(X element);
    ...
}

따라서 X의 Supertype인 Object의 반환은 허용됩니다.

Get and Put Principle

지금까지 상위, 하위 경계를 학습하였습니다.

이전의 예시들에서 확인하였듯이 Wildcard는 사용할 수 있을 때 가능하면 사용하는 것이 좋은 습관입니다.

그 이유는 WIldcard 사용을 통해서 해당 API 호출하는 입장에서 전달하는 파라미터 내용이 내부적으로 어떻게 사용될지 유추가 가능할 뿐더러 유연한 타입 제공이 가능하기 때문입니다.

그렇다면 언제, 어떤 Wildcard를 사용하는 것이 좋을까요?

이를 결정하기 위한 간단한 원칙이 있습니다.(Get and Put Principle)

하위 경계(? extends T) : 구조 바깥으로 T나 T의 Supertype으로 값을 읽어야 하는 경우 사용하자
상위 경계(? super T) : 구조 내부로 T나 T의 Subtype으로 값을 입력해야하는 경우 사용하자

이전에 살펴본 copy 메소드를 통해 해당 원칙이 어떻게 적용되었는지 확인해봅시다.

public static <T> void copy(List<? super T> dst, List<? extends T> src){}

Get and Put 원칙을 인지한 상태에서 위와 같은 API를 보면 다음과 같은 생각을 할 수 있습니다.

'src 변수에 전달하는 List 객체에서는 내부에서 값을 추출하기 위한 용도로 사용되며, dst 변수에 전달하는 객체에서는 값을 입력하는 용도로 사용되겠구나'

이번에는 Number 타입을 지닌 Collection의 합을 구하는 메소드를 직접 디자인한다면 어떻게 타입을 설계하는것이 좋을지 살펴보도록 하겠습니다.

public static double sum(Collection<Number> cols){
    double s = 0.0;
    for(Number col : cols)
    	s = s + col.doubleValue();
    return s;
}

먼저 위와 같이 Number 타입 지정을 고려해볼 수 있습니다. 하지만 이는 이전에 줄곧 얘기한 List<Number> 만 허용 가능한 메소드이기에 사용의 제약이 있습니다. 또한 Get and Put 원리에 따르면 해당 Collection에 별도 값 입력을 하지 않기 때문에 상위 경계(? extends Number)를 사용하는 것이 적합해보입니다.

이번에는 n을 입력하면 0부터 n-1까지 값을 채워주는 함수를 만들어 보겠습니다.

public static void assign(Collection<? super Integer> ints, int n){
    for(int i = 0 ; i < n; i++) ints.add(i);
}

위 경우에는 해당 Collection 안에 값을 채워넣는 작업이 수행되므로 하위 경계를 입력하는 것이 적합해보입니다.

3. Wildcard with extends(상위 경계)

cla9 — Fri, 6 Mar 2020 19:50:04 +0900

만약 Number 의 Subtype인 모든 List의 원소를 저장하는 메소드를 디자인 하려면 어떻게 해야할까요?

class Data{
    private List<Number> list;
    public void addAll(List<Number> cols){
        this.list.addAll(cols);
    }
}

public class Main {
    public static void main(String[] args)  {
        Data data = new Data();

        List<Integer> ints = Arrays.asList(1, 2, 3);
        List<Double> dbls = Arrays.asList(1.0, 2.8);
        List<Number> nums = Arrays.asList(5,4.5);
        
        data.addAll(ints); //Compile 에러 발생
        data.addAll(dbls); //Compile 에러 발생
        data.addAll(nums);
    }
}

지금까지 학습한 내용으로는 위와 같이 Data 클래스를 디자인 할 수 있습니다.

main 함수를 보면 Integer, Double, Number 관련 List 인스턴스를 생성했습니다.

과연 우리의 의도대로 Data 객체내 addAll 함수를 호출할 수 있을까요?

이전 포스팅에서 살펴보았듯이 Generic은 invariant 하기 때문에, 동일 타입의 Number 타입의 List를 제외하고 두 리스트에서의 메소드 호출은 컴파일 에러를 발생시킵니다.

그렇다면 이 경우에는 어떻게 메소드 디자인을 디자인할 수 있을까요?

Java에서는 이러한 요구를 충족되는 다양한 Wildcard 기법을 제공합니다.

이번 포스팅에서는 상위 경계 타입 파라미터(Upper-bound Type Parameter)를 알아보도록 하겠습니다.

class Data{
    private List<Number> list;
    public void addAll(List<? extends Number> cols){
        this.list.addAll(cols);
    }
}

위 코드에서 addAll 메소드는 상위 경계 타입 파라미터를 적용하였습니다.

이로써 이전에 발생했던 List<Integer>, List<Double> 변수를 addAll 메소드의 cols 변수에 할당할 수 있습니다.

그렇다면 List<? extends Number>는 무엇을 의미할까요?

전달되는 인자가 어떤 타입인지는 모르겠다. 이를 X 라고 하자
X <: Number 라면 List<X> <: List<? extends Number>이다.

위와 같은 의미로 인하여 List<Integer> <: List<? extends Number> 됩니다. 따라서 변수 할당이 가능합니다.

마찬가지로 List<Double> <: List<? extends Number>이므로 변수 할당 가능합니다.

이로써 일반 클래스 처럼 타입 파라미터 또한 Subtitution Principle 적용 가능해졌습니다. 위와 같은 특성을 Covariant 하다고 합니다. Covariant는 자기 자신 뿐만 아니라 자기 자신의 Subtype으로 타입 변환이 가능함을 말합니다.

Integer <: Number 일때, List<Integer>는 List<Number>의 Subtype이 아니다.

Integer <: Number 일때, List<? extends Integer> <: List<? extends Number> 이다!

public class Main {
    public static void main(String[] args)  {
        List<? extends Integer> ints = Arrays.asList(1, 2);
        List<? extends Number> nums = ints;
        nums.forEach(System.out::println);
    }
}

따라서 Corvariant 특성을 이용하면 위와 같은 사용 또한 가능합니다.

Heap Polution 이슈 방지

public class Main{
   public void static main(int argc, String[] argv){
       List<Integer> ints = new ArrayList<>();
       ints.add(1);
       ints.add(2);
       List<Number> nums = ints; //Compile 에러 발생
   }
}

public class Main{
   public void static main(int argc, String[] argv){
       List<Integer> ints = new ArrayList<>();
       ints.add(1);
       ints.add(2);
       List<? extends Number> nums = ints; //할당 허용
       nums.add(3.14); //Compile 에러 발생
   }
}

기존에 문제되었던 코드에 상위 경계 타입 파라미터를 사용하면 변수 할당이 가능함을 확인했습니다. 하지만 이때 상위 경계 타입 적용 변수에 Number의 Subtype 값을 할당하려고 하면 이전에 발생하였던 문제(List<Integer> 타입이 Integer가 아닌 Double 등의 다른 값 참조 현상)가 재발하게됩니다.

따라서 상위 경계를 사용한 객체에 대해서는 Subtype 값을 할당하려고 시도하면 컴파일 단계에서 에러를 발생시킵니다.

그렇다면 어떠한 과정으로 컴파일 단계에서 Subtype 값 할당이 실패하게 되는 것일까요?

Capture 변환 과정을 통해 이를 알아보도록 하겠습니다.

Capture 변환

List<Integer>와 같이 명시적으로 타입을 정의하면 List에서 제공되는 메소드가 호출되었을 때는 다음과 같이 논리적으로 생각해볼 수 있습니다.

public interface List<Integer> extends Collection<Ineteger>{
    ...
    Integer get(int index);
    void add(Integer element);
    ...
}

이 경우 add에 들어오는 값은 반드시 Integer 타입으로 지정되어있기 때문에 값 할당을 허용합니다.

그렇다면 List<? extends Number>로 타입이 지정되면 컴파일러는 어떤 타입으로 이를 추론할까요?

public interface List<?> extends Collection<?>{
    ...
    ? get(int index);
    void add(? element);
    ...
}

전달받는 파라미터 정보를 명시하지 않았기 때문에 타입을 추론할 수 없습니다. 따라서 컴파일시 내부적으로 임의의 타입 변수(capture of ?)으로 지정합니다.

public interface List<X> extends Collection<X>{
    ...
    X get(int index);
    void add(X element);
    ...
}

만약 컴파일러가 지정한 임의의 타입을 X라고 간단하게 정의하면 List 인터페이스는 다음과 같이 추론될 수 있습니다.

그리고 List<? extend Number> 구문을 통해서 컴파일러는 적어도 해당 타입이 Number의 Subtype임을 알 수는 있습니다.

결론적으로 위와 과정을 거쳐 컴파일러가 알 수 있는 사실은 다음과 같습니다.

Number의 Subtype이지만 무슨 타입인지는 모르겠다.

이러한 상황에서 만약 add 메소드를 호출하면 어떻게 될까요?

예시 코드를 통해 알아보도록 하겠습니다.

public class Main {
    public static void main(String[] args)  {
        List<Integer> ints = new ArrayList<>();
        ints.add(1);
        List<? extends  Number> nums = ints;
        Number number = nums.get(0);
        nums.add(number);
    }
}

X <: Number 이지만 무엇인지는 알 수 없습니다.

여기에 Number 값을 넣기 위해서는 Number <: X 이어야 합니다.

하지만 이는 성립되지 않습니다. 만약 X의 실제 타입이 Integer 였다면, Number <: Integer 라는 말인데 이는 성립되지 않기 때문입니다.

따라서, 아무리 입력하고자 하는 값이 Number의 Subtype일지라도 X 타입 변수내에서는 타입 정보를 정확히 알지 못하기 때문에 null 이외에 어떠한 값 입력을 허용하지 않습니다.

public class Main{
   public void static main(int argc, String[] argv){
       List<Integer> ints = new ArrayList<>();
       ints.add(1);
       ints.add(2);
       List<? extends Number> nums = ints;
       nums.add(null);
   }
}

null이 허용 가능한 이유는 null은 모든 타입과 호환되는 값이기 때문입니다.

그렇다면 해당 문법은 언제 사용해야 할까요?

일반적으로 상위 경계 타입 파라미터 타입은 구조 바깥으로 T나 T의 Supertype으로 값을 읽어야 하는 경우 사용하며, 추론되는 E의 Subtype 값을 집어 넣을 수 없습니다.

List<? extends Number>를 예로 내용 정리하면 다음과 같습니다.

관심대상은 List 클래스에서 제공되는 기능이다.(size 메소드, isEmpty 메소드 등)
관심대상은 Number 클래스에서 제공되는 기능이다.(실제 들어있는 값, equals 메소드 등)
Number 타입의 Subtype들은 관심대상이 아니다.
해당 변수에서는 구조체 내부 정보를 가져오기 위한 용도로 주로 사용된다.

개인적으로는 마지막 부분이 시사하는 바가 크다고 생각합니다.

이를 통해 앞으로 라이브러리 메소드를 사용할때 상위 한정자가 쓰여있다면, '메소드내에서 내가 전달한 구조에서 값을 꺼내는 용도로 사용하겠구나' 라는 의미를 파악하면 좋을 것 같습니다.

2. Subtyping, Substitution 원리

cla9 — Thu, 5 Mar 2020 18:24:43 +0900

Subtyping

이번 포스팅을 시작하기 앞서 Subtyping개념을 먼저 알아보겠습니다.

위와 같이 A 클래스가 가진 Spec이 요구되는 상황에서 B의 클래스가 A 역할을 대체하여 사용할 수 있을 때 B를 A의 Subtype, A는 B의 Supertype이라고 불립니다. 또한 모든 참조타입은 자기자신에 대해서 Subtype입니다.

(※ Subtype을 기호로 나타내면 <: 로 표현되며 A <: B 일 경우 A는 B의 Subtype 입니다.)

광의적인 의미에서 A 클래스의 Spec을 B 클래스에도 코드상에서 준수하고 있으면 이를 Subtype 관계로 보지만, Java에서는 상속 관계에 놓여있을 때만 교체가 가능하기에 이에 집중해서 살펴보겠습니다.

예를 통해서 알아보겠습니다.

ArrayList는 List의 인터페이스를 구현하였습니다. 따라서 List가 사용될 수 있는 영역에는 ArrayList로 대체가 가능합니다.

따라서, 이때 ArrayList는 List의 Subtype, List는 Supertype입니다.

Java에서 기본적으로 제공되는 라이브러리 예를 통해 해당 개념을 적용해보겠습니다.

Integer <: Number
Double <: Number
ArrayList<E> <: List<E>
Collection<E> <: Iterable<E>

Subtyping은 이행적인 특징을 지니고 있습니다.

즉 A <: B이고, B <: C 이면 A <: C입니다.

따라서, 위 예에서 List<E> <: Iterable<E> 라고 볼 수 있습니다.

Substitution Principle(치환 원리)

Wiki에는 해당 원리에 대하여 다음과 같이 정의하고 있습니다.

if S is a subtype of T, then objects of type T may be replcaed with objects of type S

요약하자면, 주어진 타입 변수는 해당 타입 어떠한 Subtype으로도 대체가 가능합니다.

Collection<E> 인터페이스에 정의된 add 메소드 사용예를 통해서 해당 원리을 적용해보겠습니다.

interface Collection<E>{
  ...
  public boolean add(E elt);
  ...
}

public class Main{
   public void static main(int argc, String[] argv){
       List<Number> nums = new ArrayList<>();
       nums.add(2);
       nums.add(3.14);
   }
}

nums 객체의 Type Argument는 Number 입니다.

따라서 add 메소드 파라미터 Type은 Number로 추론되므로 메소드 호출시, Integer나 Double 값을 할당할 수 있습니다.

이것이 가능한 이유는 Integer <: Number, Double <: Number 이기 때문입니다.

그렇기에 위 코드를 컴파일하면 아무런 문제 없이 완료됩니다.

그렇다면 해당 개념을 확장하여 다음과 같은 생각 또한 해볼 수 있습니다.

Integer <: Number이니까 List<Integer> <: List<Number> 라고 볼 수 있지 않을까?

위 문장만을 봐서는 가능할 것 같습니다.

예시 코드를 보면서 가능 여부를 확인해보겠습니다.

public class Main{
   public void static main(int argc, String[] argv){
       List<Integer> ints = Arrays.asList(1,2);
       List<Number> nums = ints; //Compile 에러 발생
   }
}

위 코드를 실행하면 컴파일 에러가 발생합니다. 과연 무엇이 문제였을까요?

위 코드가 정상적으로 컴파일된다면, 두 객체는 Heap 같은 메모리 영역을 바라보게 될 것입니다.

지금까지는 아무런 이상이 없는 것 처럼 보입니다.

public boolean add(Number elt){}

하지만 List<Number> 타입이 해당 메모리 영역을 가르킬 수 있으면 add 함수의 타입 파라미터는 Number로 추론됩니다. 따라서 Substitution Principle을 적용한다면 Number의 Subtype인 Double 값을 논리적으로 할당할 수 있습니다.

public class Main{
   public void static main(int argc, String[] argv){
       List<Integer> ints = new ArrayList<>();
       ints.add(1);
       ints.add(2);
       List<Number> nums = ints //Compile 에러 발생
       nums.add(3.14);
   }
}

실제로 Intellij 에서 위 코드를 입력하면 Compile 에러 발생라인은 컴파일전에 에러가 발생하고 있다고 highlight 표시해주지만 nums 객체의 add 함수호출부는 아무런 표시를 하지 않는 것을 확인할 수 있습니다.

위 구조에서의 문제는 해당 객체가 저장된 공간은 Parameterized Type이 List<Integer>인 ints 객체 또한 가르키는 영역이라는 점입니다.

만약 nums 객체에 ints를 할당할 수 있다면 자신이 가르키고 있는 영역에 int가 아닌 다른 타입이 존재할 수 있기 때문에 타입 안정성이 깨지게됩니다.

이러한 문제를 해결하기 위해서 Java에서는 해당 경우에 Substitution Principle을 적용하지 않습니다. 즉 List<Integer>는 List<Number>의 Subtype이 아닙니다.

이번에는 반대로 한번 생각해보겠습니다.

List<Number> <: List<Integer>일까?

public class Main{
   public void static main(int argc, String[] argv){
       List<Number> nums = new ArrayList<>();
       nums.add(2.78);
       nums.add(3.14);
       List<Integer> ints = nums; //Compile 에러 발생
   }
}

Number 타입은 Integer의 Supertype이지 Subtype이 아닙니다. 따라서 위 경우에 nums 객체 값을 ints에 할당 가능하다면 List<Integer> 타입인 ints 입장에서는 Number 타입의 다른 Subtype이 존재하는 영역을 가르키게 됩니다.

문제는 ints 객체가 가르키는 메모리 영역으로부터 데이터를 읽고자 한다면 Integer 타입이 아닌 Double 타입을 참조할 수 있습니다. 따라서 이러한 경우에는 타입 안정성이 깨지게 됩니다. 그러한 이유로 이 또한 허용되지 않습니다.

지금까지 살펴본 내용을 정리해보겠습니다.

List<Integer>는 List<Number>의 Subtype이 아니다.
List<Number>는 List<Integer>의 Subtype이 아니다.
List<Integer>는 자기 자신에 대하여 Subtype이다.
List<E>는 Collection<E>를 상속받으므로 List<Integer>는 Collection<Integer>의 Subtype이다.

위 정리를 살펴보면, 주어진 타입과 동일한 타입을 지닌 객체에 대해서만 변수 할당이 가능한 것을 확인할 수 있습니다. 일반화를 하면 Generic을 사용하면 타입의 상속 관계와 상관 없이 동일 타입만 가능한 Invariant 특성을 지니고 있습니다.

하지만 이렇게만 사용한다면, Generic을 사용함에 있어 많은 제약이 따를 수 밖에 없습니다.

이전에 살펴본 코드를 잠시 다시 살펴보겠습니다.

public class Main{
   public void static main(int argc, String[] argv){
       List<Integer> ints = new ArrayList<>();
       ints.add(1);
       ints.add(2);
       List<Number> nums = ints; //Compile 에러 발생
   }
}

위 코드는 nums 객체 할당이후 Number 타입의 다른 Subtype 할당이 가능했기 때문에 문제가 발생했습니다.

하지만 해당 nums 객체가 지정하는 타입에 대하여 Subtype 값 할당은 하지 않고 단순히 참조의 목적이라면, List<Number>에 List<Integer> 객체를 할당하는 것은 논리적으로 문제 없어 보입니다.

위와 같은 상황에서 사용할 수 있는 방법이 없을까요?

다음 포스팅에서 다룰 Wildcard를 통해서 해당 이슈를 다루어보도록 하겠습니다.

1. Generic 기초

cla9 — Wed, 4 Mar 2020 20:04:36 +0900

Java는 대표적인 정적 타입 언어입니다. 즉 컴파일 시점에 사용하는 변수의 타입이 결정되며, 따라서 명시적으로 변수의 타입을 지정하거나 추론이 가능해야합니다.

만약 클래스내 일부 변수에 대하여 int형 또는 String형으로 상황에 따라 각기 다른 데이터를 담고 싶다면 어떻게 해야할까요?

class IntegerData{
    int data;
    double var2;
    public IntegerData(int data) {this.data = data;}
    public int getData() {return data;}
    public void method1(){}
    public void method2(){}
}

class StringData {
    String data;
    double var2;
    public StringData(String data) {this.data = data;}
    public String getData() {return data;}
    public void method1(){}
    public void method2(){}
}

public class Main {
    public static void main(String[] args) {
        IntegerData a = new IntegerData(1);
        StringData b = new StringData("1");
        
        int c = a.getData();
        String d = b.getData();
    }
}

먼저 타입별 클래스를 만드는 방법을 먼저 떠올릴 수 있습니다.

하지만 일부 데이터 타입만 다름에도 불구하고 매번 클래스를 만드는 것은 매우 비효율적입니다.

그렇다면 어떻게 문제를 해결할 수 있을까요?

Idea) 모든 클래스는 Object를 상속받으니, Object 타입으로 변수를 지정하자

class Data{
    Object data;
    public Data(Object data) {this.data = data;}
    public Object getData() {return data;}
}

public class Main {
    public static void main(String[] args) {
        Data a = new Data(1);
        Data b = new Data("1");
        
        int c = (int) a.getData();
        String d = (String) b.getData();
    }
}

Object 타입으로 변수를 생성하면, Object 객체에 모든 변수 값을 저장할 수 있습니다. 따라서, 타입별로 클래스를 만들지 않아도되니 효율적입니다. 하지만 데이터를 가져올 때에는 원래 타입으로 캐스팅이 필요합니다.

음.. 캐스팅을 개발자가 명시적으로 지정해야한다는 약간의 불편함은 있지만 그런대로 괜찮아 보입니다.

하지만 정말 이대로 괜찮다고 말할 수 있을까요?

문제점

public class Main {
    public static void main(String[] args) {
        Data a = new Data(1);
        String b = (String) a.getData();
        System.out.println(b);
    }
}

개발자의 실수로 Data 객체에 들어있는 값의 타입이 String으로 착각하여 String 변수에 이를 담았다고 가정해봅시다.

실제로는 담겨져있는 int 타입의 변수에 대해서 String 타입으로 캐스팅을 수행하니 오류가 나야 정상입니다.

하지만 위 소스를 컴파일을 해보면 정상적으로 컴파일됩니다. 그 이유는 지정된 타입은 Object 이고, Object 타입은 String 타입의 부모 타입이기 때문입니다.

실행 결과 : Exception in thread "main" java.lang.ClassCastException: class java.lang.Integer cannot be cast to class java.lang.String

따라서, 에러가 발생하는 시점은 Application을 구동해서 데이터를 가져오는 코드가 실행되는 시점입니다. 즉 해당 방법은 TypeSafety 하지 않은 방법으로 Runtime 시점에 오류를 알 수 있는점은 잠재적인 오류를 내포하고 있으므로 좋지 못합니다.

public class Main {
    public static void main(String[] args) {
        List list = new ArrayList();
        list.add(1);
        String a = (String) list.get(0);
    }
}

java 1.4 doc ArrayList get 메소드

Generic이 지원되지 않는 Java 1.4 버전 이하에서는 우리가 흔히 사용하는 ArrayList 에서 여러 데이터 형을 담기 위하여 Object 타입으로 저장하였습니다. 또한 반환시에도 Object 타입으로 반환하였습니다. 따라서 Runtime 오류를 피하기 위해서 개발자가 조심해서 캐스팅을 수행해야했습니다.

Generic 등장

class Data<T>{
    T data;
    public Data(T data) { this.data = data; }
    public T getData() {return data; }
}

public class Main {
    public static void main(String[] args) {
        Data<Integer> a = new Data<>(1);
        Data<String> b = new Data<>("1");

        int c = a.getData();
        String d = b.getData();
    }
}

이전에 살펴보았듯이 Object 타입으로 저장하는 것은 개발자가 명시적으로 타입을 예측하여 캐스팅을 수행해야했기에 잠재적 코드 결함율이 발생할 수 있었습니다. 따라서 이를 해결하고자 Java 진영에서는 1.5 버전부터 Generic을 지원하였습니다. Generic은 특정 변수에 대하여 객체 생성시 원하는 타입으로 지정할 수 있도록 도와줍니다.

위 코드와 같이 Data 클래스에 대하여 객체 생성시 <> 안에 원하는 Reference 타입을 명시해주면, 컴파일러가 해당 객체의 data 타입은 명시적으로 지정된 타입이라는 것을 보장해줍니다.

기존에는 반환 값이 Object였기 때문에 명시적으로 캐스팅을 수행해야했지만, Generic을 사용하면 컴파일러가 타입을 보장해주기 때문에 명시적 캐스팅이 불필요합니다.

마치 위 그림과 같이 타입을 지정하게되면 각각의 클래스가 별도로 존재하는 것처럼 논리적으로 생각할 수 있습니다.

public class Main {
    public static void main(String[] args) {
        Data<Integer> a = new Data<>(1);
        String d = (String)a.getData();
    }
}

따라서 위와 같이 개발자의 실수로 Integer 데이터를 String 변수에 담으려고 해도 컴파일 단계에서 잘못된 타입임을 알고 에러를 표시하기 때문에 TypeSafety합니다.

도입부에 이해를 돕기 위해 논리적으로 Class 여러개가 생성된 그림을 보여드렸습니다. 그렇다면 실제 내부 구현도 위와 같이 되어있을까요? 지금부터 Generic 내부에 대해서 살펴보면서 원리를 알아보겠습니다.

용어

학습하기 전 관련 용어 일부를 알아보겠습니다.

Type Parameter : Generic 타입을 명시하기 위한 Placeholder 입니다. 즉 위 코드에서 Data 클래스의 T가 이에 해당됩니다.

Type Argument : 실제 Generic 타입에 명시된 타입을 의미합니다. 위 코드에서는 Integer가 해당됩니다.

Parameterized Type : Type argument에 의하여 Type Parameter가 치환된 전체 데이터 타입을 의미합니다. 위 코드에서는 Data<Integer>가 이에 해당됩니다.

위 세가지 용어가 혼동되지 않도록 주의하며, 본격적으로 Generic에 대해서 알아보겠습니다.

Type Erasure

class Data<T>{
    T data;
    public Data(T data) { this.data = data; }
    public T getData() {return data; }
}

public class Main {
    public static void main(String[] args) {
        Data<Integer> a = new Data<>(1);
        int c = a.getData();
    }
}

동작 원리를 이해하기 위해 컴파일된 바이트 코드를 보는 것이 가장 좋지만, 이해를 돕기위해 위와 같이 Generic 문법을 사용한 자바 코드를 컴파일 한다음 해당 class 파일을 다시 디컴파일 결과를 보겠습니다.

먼저 Data 클래스를 보겠습니다. 기존에 Type Parameter T로 선언되었던 부분이 전부 Object 클래스로 타입이 변경되었습니다.

main 호출부에서도 Parameterized Type이 Data<T>였던 클래스 정보가 Data와 같이 변경되었고, 값을 가져오는 부분에서 캐스팅이 발생되었음을 확인할 수 있습니다.

자세히 보면 이는 Generic이 사용되기 이전에 작성하던 방식과 동일한 결과입니다.

이를 통해 알 수 있는 사실은 Generic을 사용하더라도 사용자가 지정한 Type은 사라지고 기존과 같이 Object 타입으로 지정되며, 대신 명시적으로 값을 가져오는 코드에 컴파일러가 캐스팅하는 코드를 삽입하여 Type 안정성을 보장해준다는 점입니다.

또한, 컴파일러가 개발자가 지정한 Type을 알고 있기 때문에, 중간에 개발자가 실수로 잘못된 캐스팅을 시도하는 코드가 있다면 잘못 캐스팅 되었음을 알 수 있습니다.

public class Main {
    public static void main(String[] args) throws NoSuchFieldException {
        Data<Integer> a = new Data<>(1);
        System.out.println(a.getClass().getDeclaredField("data"));
    }
}

실행결과 : java.lang.Object Data.data

한 단계 더 나아가자면, 컴파일 시점에는 내가 지정한 Type 정보를 알 수 있지만 컴파일 이후에 생성된 바이트코드에서는 Object로 Type이 지정되므로 런타임 시점에는 Type 확인이 불가하다는 점입니다.

실제 위 코드와 같이 Reflection을 활용하여 런타임시 Data 인스턴스의 data 타입을 확인해보면 Object 타입임을 알 수 있습니다.

런타임 시점에 Type 정보를 알 수 없는 것은 꽤나 불편한 제약으로 느껴집니다. 그렇다면 Java는 왜 이러한 제약사항이 존재함에도 불구하고 Type Erasure를 통해서 명시된 Type을 삭제했을까요?

class Stub{
    List list;
}

예를들어 기존에 jdk 1.5 미만을 사용하던 라이브러리에서 Java Collection을 사용하려면 위와 같이 사용되었을 것입니다.

만약 Generic을 사용한 Collection 클래스에 대해 컴파일 하는 시점에 Type이 사용자가 지정한 Type으로 변경된다면, 그에 따른 바이트 코드 또한 변경될 것입니다.

따라서 낮은 버전(1.4 이하) Collection을 사용하는 라이브러리에서 상위 버전으로 업그레이드를 위해서는 변경에 따른 코드 수정이 필요합니다. 즉 New Feature 도입으로 인하여 하위 호환성 문제가 발생할 수 있습니다.

Java는 아주 대표적으로 하위 호환성을 중요시 여기는 언어입니다. 따라서 하위 버전의 호환성 유지를 위하여 Type Erasure를 통해 기존 코드와 상위 버전 코드간의 호환성이 잘 유지되도록 지원하였습니다.

그렇다면 Generic 프로그래밍을 지원하는 모든 언어가 Type erasure를 사용할까요?

정답은 그렇지 않습니다. 대표적으로 C++가 이에 해당합니다.

C++은 컴파일시에 실제 지정한 데이터타입에 대하여 코드를 생성합니다. 따라서 때로는 머신에 최적화된 코드를 생성하기 용이하기도 합니다. 하지만 타입만큼 코드가 생성되므로 Java에 비해 상대적으로 코드 크기가 커질 수 있는 단점 또한 존재합니다.

타입 경계

class Data<T>{
    T data;
    public Data(T data) { this.data = data; }
    public T getData() {return data; }
}

이전 내용을 통해 Type erasure에 의하여 T 타입이 Object 타입으로 변경됨을 확인하였습니다.

그렇다면 Generic으로 정의한 모든 타입이 컴파일시 Object로 타입이 변환될까요?

위 예제를 기반으로 T 타입이 Object로 변경된 이유를 다시 살펴보겠습니다.

위 코드에서 T 타입이 의미하는바는 우리가 지정한 어느 타입이여도 상관이 없음을 나타냅니다.

이는 Java를 통해 구현하는 모든 클래스 타입을 지정할 수 있음을 의미합니다. 즉 타입의 경계가 없습니다.

출처 : https://docs.oracle.com/javase/tutorial/java/IandI/subclasses.html

따라서, 런타임시 내가 지정한 어떠한 타입이라도 허용이 가능한 가장 최상위 클래스인 Object로 타입이 변경되는 것입니다.

만약 다음과 같은 요구사항이 있다고 가정해봅시다.

'Data 클래스에서 data 변수는 Integer, Double과 같은 Number 타입만 허용 가능하다.'

이 경우에는 어떻게 해야할까요?

방법1. 개발자끼리 명시적으로 합의하여 Number 타입이하로만 사용하게끔 조심한다.

방법2. T 타입으로 지정할 수 있는 범위를 설정하여, 잘못 지정시 컴파일 에러를 발생시킨다.

너무나 당연하게도, 방법 2로하는게 가장 안전할 것입니다.

Java에서는 이를 위해서 타입 경계 기능을 제공합니다.

class Data<T extends Number>{
    T data;
    public T getData() {
        return data;
    }
    public void setData(T data) {
        this.data = data;
    }
}

위 코드와 같이 T에 대한 경계(Number 타입 이하로만 설정)를 지정하면, 이를 사용하는 Data 클래스 사용시 타입을 Number 이하로만 설정할 수 있습니다.

public class Main {
    public static void main(String[] args)  {
        Data<Object> obj = new Data<>();
    }
}

Error:(14, 14) java: type argument java.lang.Object is not within bounds of type-variable T

Error:(14, 36) java: incompatible types: cannot infer type arguments for Data<>
    reason: inference variable T has incompatible bounds
      equality constraints: java.lang.Object
      lower bounds: java.lang.Number

만약 main 함수에서 Data 클래스 정의를 Number의 하위 타입이 아닌 다른 클래스로 지정하게되면 위와 같은 에러를 발생하게 됩니다.

그렇다면 위와 같이 경계를 지정한 다음 컴파일하게되면 타입은 무엇으로 지정되어있을까요?

이전과 마찬가지로 컴파일한 내용을 다시 디컴파일해서 확인해보겠습니다.

class Data
{

    Data()
    {
    }

    public Number getData()
    {
        return data;
    }

    public void setData(Number number)
    {
        data = number;
    }

    Number data;
}

아마 눈치를 채셨겠지만, 디컴파일을 하게되면 Data 클래스의 T 타입이 Object가 아닌 Number 타입으로 변경된 것을 확인할 수 있습니다.

그 이유는 타입 경계로 인하여 Number 이하의 타입만 허용가능하기 때문입니다.

정리하면 다음과 같습니다.

T 타입에 대한 경계를 지정하지 않으면 가장 최상위인 Object로 컴파일시 변경된다.
T 타입에 대한 경계를 지정하면, 해당 타입으로 컴파일시 변경된다.

그렇다면 타입의 경계를 여러개 지정이 필요한 경우에는 어떻게 할까요?

class Data<T extends Number & Comparable<T>>{
    private T data;

    public T getData() {
        return data;
    }
    public void setData(T data) {
        this.data = data;
    }
}

위와 같이 Number 타입이면서 Comparable 인터페이스를 구현한 타입만 지정하게끔 설정할 수 있습니다.

그리고 이때 컴파일 시에는 지정된 경계중에 가장 왼쪽에 위치한 Number 클래스로 타입이 지정됩니다.

이때 주의할 점은 경계를 구체적인 클래스 타입이 가장 첫 번째로 지정되어야합니다.

마치며

이번 포스팅에서는 Generic 기초와 Type erasure에 대해서 살펴보았습니다. 다음 포스팅에서는 Subtyping에 대해서 살펴보겠습니다.

20. Saga 패턴을 활용한 트랜잭션 관리 - 3

cla9 — Sat, 25 Jan 2020 14:58:45 +0900

1. 서론

이번 포스팅은 AxonFramework 관련 마지막 포스팅입니다. Saga 패턴 보상 트랜잭션 구현을 다루겠습니다.

2. Deadline

MSA 환경에서는 App이 여러개로 분산되어있으므로 하나의 App이 느려지거나 장애가 발생하면, 장애가 발생한 App을 호출하는 App에도 장애가 전파됩니다.

Axon에서 제공하는 Saga 패턴을 사용하면, 요청마다 Saga 인스턴스가 생성됩니다. 따라서 연관된 App의 장애로 인해 전체 트랜잭션에 Hang이 걸리게되면, 요청한 App 또한 안전하지 못합니다.

따라서 이를 완화하기 위해 Axon에서는 Deadline 기능을 제공합니다. Deadline은 App에서 지정한 시간동안 반응이 없으면, 이를 처리할 메소드를 Callback 형식으로 등록할 수 있는 기능입니다. 자세한 내용은 공식 문서를 참고 바라며, 데모 프로젝트에서는 CommandGateway 클래스에서 기본적으로 제공하는 sendAndWait 메소드를 통해서 일정 시간동안 응답이 없으면, 보상 트랜잭션을 발동하도록 구현하겠습니다.

1. Command 모듈 Saga 패키지내 있는 Saga 클래스를 엽니다.

2. Saga 클래스 코드를 수정합니다.

TransferManager.java

@Saga
@Slf4j
public class TransferManager {
    (...중략...)
    
    @StartSaga
    @SagaEventHandler(associationProperty = "transferID")
    protected void on(MoneyTransferEvent event) {
       (...중략...)
        try {
            log.info("계좌 이체 시작 : {} ", event);
            commandGateway.sendAndWait(comamndFactory.getTransferCommand(), 10, TimeUnit.SECONDS);
        } catch (CommandExecutionException e) {
            log.error("Failed transfer process. Start cancel transaction");
            //보상 트랜잭션 구현 로직
        }
    }
    (...중략...)

}

sendAndWait 두 번째, 세 번째 인자를 통해 TimeOut을 지정하며, 해당 기간동안 응답이 없을 경우 Exception을 통해 보상 트랜잭션을 발동할 수 있습니다.

3. 트랜잭션 프로세스 설계

일반적인 상황

일반적으로 계좌 이체 요청을하면, 해당 은행에서 보유한 잔고보다 요청액수가 클 경우에는 이체 거절을하며, 반대의 경우에는 이체 승인을 합니다. 따라서 요청자인 Command 모듈에서는 Jeju 은행의 승인 혹은 거절 이벤트 발생 여부에 따라서 결과를 처리하면 됩니다.

보상 트랜잭션 발동 상황

보상 트랜잭션은 연결된 App 사이에 트랜잭션 문제가 발생하였을 때, 이미 처리된 데이터를 원상복구를 위하여 추가적인 트랜잭션을 발동하는 것입니다.

예제에서는 Timeout이 발생하게 되면, Jeju 은행 App의 응답과 관계없이 트랜잭션 Rollback을 위하여 보상 트랜잭션을 요청하고, Command 모듈에서는 다음 로직을 수행합니다.

만약 위 그림과 같이 만약 Jeju 은행에 발생한 장애로 인하여 계좌 요청을 진행하였지만 응답이 오지 않는 상황이라고 가정해봅시다. Command 모듈에서는 장애 방지를 위해 Timeout을 설정했기 때문에 일정 시간이 지나면 보상 트랜잭션을 발동할 것입니다.

이후 Jeju 은행 App이 정상화된다면 이전 요청을 수행할 것입니다. 그 결과 요청이 적절하지 않으면, 이체 거절 이벤트를 발송합니다. 만약 이체 거절 상황에서 요청받은 보상 트랜잭션을 처리한다면, 잔고는 그대로인 상황에서 보상 트랜잭션에 의해 잔고가 늘어나는 기현상이 발생합니다.

이를 해결하기 위해 다양한 방법이 있겠지만, 예제 프로젝트에서는 Timeout이 발생된 상황에서 이체 거절 메시지를 받게되면, 보상 트랜잭션 취소 요청하여 정상 처리하겠습니다.

위 그림은 Command 모듈에서 트랜잭션 요청 이후 처리해야할 과정을 개략적으로 순서도로 나타냈습니다.

4. Common 모듈 구현

1. Common 모듈 command 패키지내 command 클래스를 추가합니다.

2. command 클래스를 구현합니다.

AbstractCancelTransferCommand.java

@ToString
@NoArgsConstructor
@AllArgsConstructor
@Getter
public abstract class AbstractCancelTransferCommand {
    @TargetAggregateIdentifier
    protected String srcAccountID;
    protected String dstAccountID;
    protected Long amount;
    protected String transferID;

    public AbortTransferCommand create(String srcAccountID, String dstAccountID, Long amount, String transferID) {
        this.srcAccountID = srcAccountID;
        this.dstAccountID = dstAccountID;
        this.transferID = srcAccountID;
        this.amount = amount;
        return this;
    }
}

JejuBankCancelTransferCommand.java

public class JejuBankCancelTransferCommand extends AbstractCancelTransferCommand {
    @Override
    public String toString() {
        return "JejuBankCancelTransferCommand{" +
                "srcAccountID='" + srcAccountID + '\'' +
                ", dstAccountID='" + dstAccountID + '\'' +
                ", amount=" + amount +
                ", transferID='" + transferID + '\'' +
                '}';
    }
}

SeoulBankCancelTransferCommand.java

public class SeoulBankCancelTransferCommand extends AbstractCancelTransferCommand {
    @Override
    public String toString() {
        return "SeoulBankCancelTransferCommand{" +
                "srcAccountID='" + srcAccountID + '\'' +
                ", dstAccountID='" + dstAccountID + '\'' +
                ", amount=" + amount +
                ", transferID='" + transferID + '\'' +
                '}';
    }
}

AbstractCompensationCancelCommand.java

@ToString
@NoArgsConstructor
@AllArgsConstructor
@Getter
public abstract class AbstractCompensationCancelCommand {
    @TargetAggregateIdentifier
    protected String srcAccountID;
    protected String dstAccountID;
    protected Long amount;
    protected String transferID;
    
    public AbstractCompensationCancelCommand create(String srcAccountID, String dstAccountID, Long amount, String transferID) {
        this.srcAccountID = srcAccountID;
        this.dstAccountID = dstAccountID;
        this.transferID = srcAccountID;
        this.amount = amount;
        return this;
    }
}

JejuBankCompensationCancelCommand.java

public class JejuBankCompensationCancelCommand extends AbstractCompensationCancelCommand {
    @Override
    public String toString() {
        return "JejuBankCompensationCancelCommand{" +
                "srcAccountID='" + srcAccountID + '\'' +
                ", dstAccountID='" + dstAccountID + '\'' +
                ", amount=" + amount +
                ", transferID='" + transferID + '\'' +
                '}';
    }
}

SeoulBankCompensationCancelCommand.java

public class SeoulBankCompensationCancelCommand extends AbstractCompensationCancelCommand {
    @Override
    public String toString() {
        return "SeoulBankCompensationCancelCommand{" +
                "srcAccountID='" + srcAccountID + '\'' +
                ", dstAccountID='" + dstAccountID + '\'' +
                ", amount=" + amount +
                ", transferID='" + transferID + '\'' +
                '}';
    }
}

TransferComamndFactory.java

@RequiredArgsConstructor
public class TransferComamndFactory {
    private final AbstractTransferCommand transferCommand;
    private final AbstractCancelTransferCommand abortTransferCommand;
    private final AbstractCompensationCancelCommand compensationAbortCommand;

    public void create(String srcAccountID, String dstAccountID, Long amount, String transferID){
        transferCommand.create(srcAccountID, dstAccountID, amount, transferID);
        abortTransferCommand.create(srcAccountID, dstAccountID, amount, transferID);
        compensationAbortCommand.create(srcAccountID, dstAccountID, amount, transferID);
    }

    public AbstractTransferCommand getTransferCommand(){
        return this.transferCommand;
    }
    public AbstractCancelTransferCommand getAbortTransferCommand(){
        return this.abortTransferCommand;
    }
    public AbstractCompensationCancelCommand getCompensationAbortCommand(){
        return this.compensationAbortCommand;
    }
}

3. Common 모듈 event 패키지내 event 클래스를 추가합니다.

4. event 클래스 내용을 구현합니다.

CompletedCancelTransferEvent.java

@Builder
@ToString
@Getter
public class CompletedCancelTransferEvent {
    private String srcAccountID;
    private String dstAccountID;
    private Long amount;
    private String transferID;
}

CompletedCompensationCancelEvent.java

@Builder
@ToString
@Getter
public class CompletedCompensationCancelEvent {
    private String srcAccountID;
    private String dstAccountID;
    private Long amount;
    private String transferID;
}

5. Jeju 모듈 수정

보상 트랜잭션 처리를 위한 Handler 메소드를 추가하기 위해 Aggregate 클래스를 수정합니다.

Account.java

@Entity
@Aggregate
@NoArgsConstructor
@AllArgsConstructor
@Slf4j
public class Account {
    @AggregateIdentifier
    @Id
    private String accountID;
    private Long balance;
    private final transient Random random = new Random();

    @CommandHandler
    public Account(AccountCreationCommand command) throws IllegalAccessException {
        log.debug("handling {}", command);
        if (command.getBalance() <= 0)
            throw new IllegalAccessException("유효하지 않은 입력입니다.");
        apply(new AccountCreationEvent(command.getAccountID(), command.getBalance()));
    }

    @EventSourcingHandler
    protected void on(AccountCreationEvent event) {
        log.debug("event {}", event);
        this.accountID = event.getAccountID();
        this.balance = event.getBalance();
    }

    @CommandHandler
    protected void on(JejuBankTransferCommand command) throws InterruptedException {
        if (random.nextBoolean())
            TimeUnit.SECONDS.sleep(15);

        log.debug("handling {}", command);
        if (this.balance < command.getAmount()) {
            apply(TransferDeniedEvent.builder()
                                        .srcAccountID(command.getSrcAccountID())
                                        .dstAccountID(command.getDstAccountID())
                                        .amount(command.getAmount())
                                        .description("잔고가 부족합니다.")
                                        .transferID(command.getTransferID())
                                     .build());
        } else {
            apply(TransferApprovedEvent.builder()
                                            .srcAccountID(command.getSrcAccountID())
                                            .dstAccountID(command.getDstAccountID())
                                            .transferID(command.getTransferID())
                                            .amount(command.getAmount())
                                        .build());
        }
    }

    @EventSourcingHandler
    protected void on(TransferApprovedEvent event) {
        log.debug("event {}", event);
        this.balance -= event.getAmount();
    }

    @CommandHandler
    protected void on(JejuBankCancelTransferCommand command) {
        log.debug("handling {}", command);
        apply(CompletedCancelTransferEvent.builder()
                                            .srcAccountID(command.getSrcAccountID())
                                            .dstAccountID(command.getDstAccountID())
                                            .transferID(command.getTransferID())
                                            .amount(command.getAmount())
                                          .build());
    }

    @EventSourcingHandler
    protected void on(CompletedCancelTransferEvent event) {
        log.debug("event {}", event);
        this.balance += event.getAmount();
    }

    @CommandHandler
    protected void on(JejuBankCompensationCancelCommand command) {
        log.debug("handling {}", command);
        apply(CompletedCompensationCancelEvent.builder()
                                                .srcAccountID(command.getSrcAccountID())
                                                .dstAccountID(command.getDstAccountID())
                                                .transferID(command.getTransferID())
                                                .amount(command.getAmount())
                                              .build());
    }

    @EventSourcingHandler
    protected void on(CompletedCompensationCancelEvent event) {
        log.debug("event {}", event);
        this.balance -= event.getAmount();
    }
}

위 클래스 구현 내용 중에서 Timeout 테스트를 위해 50% 확률로 Sleep 하도록 임의로 추가하였습니다.

if (random.nextBoolean())
	TimeUnit.SECONDS.sleep(15);

6. Command 모듈 수정

1. Command 클래스 수정을 위해 command 패키지 하위 MoneyTransferCommand 클래스 파일을 엽니다.

2. 클래스 파일을 수정합니다.

MoneyTransferCommand.java

@Builder
@ToString
@Getter
public class MoneyTransferCommand {
    private String srcAccountID;
    @TargetAggregateIdentifier
    private String dstAccountID;
    private Long amount;
    private String transferID;
    private BankType bankType;

    public enum BankType{
        JEJU(command -> new TransferComamndFactory(new JejuBankTransferCommand(),new JejuBankCancelTransferCommand(), new JejuBankCompensationCancelCommand())),
        SEOUL(command -> new TransferComamndFactory(new SeoulBankTransferCommand(), new SeoulBankCancelTransferCommand(), new SeoulBankCompensationCancelCommand()));

        private Function<MoneyTransferCommand, TransferComamndFactory> expression;
        BankType(Function<MoneyTransferCommand, TransferComamndFactory> expression){ this.expression = expression;}
        public TransferComamndFactory getCommandFactory(MoneyTransferCommand command){
            TransferComamndFactory factory = this.expression.apply(command);
            factory.create(command.getSrcAccountID(), command.getDstAccountID(), command.amount, command.getTransferID());
            return factory;
        }

    }

    public static MoneyTransferCommand of(TransferDTO dto){
        return MoneyTransferCommand.builder()
                .srcAccountID(dto.getSrcAccountID())
                .dstAccountID(dto.getDstAccountID())
                .amount(dto.getAmount())
                .bankType(dto.getBankType())
                .transferID(UUID.randomUUID().toString())
                .build();
    }
}

3. 보상 트랜잭션 구현을 위해 Saga 클래스를 엽니다.

4. Saga 클래스를 수정합니다.

TransferManager.java

@Saga
@Slf4j
public class TransferManager {
    @Autowired
    private transient CommandGateway commandGateway;
    private boolean isExecutingCompensation = false;
    private boolean isAbortingCompensation = false;
    private TransferComamndFactory comamndFactory;

    @StartSaga
    @SagaEventHandler(associationProperty = "transferID")
    protected void on(MoneyTransferEvent event) {

        log.debug("Created saga instance");
        log.debug("event : {}", event);
        comamndFactory = event.getComamndFactory();
        SagaLifecycle.associateWith("srcAccountID", event.getSrcAccountID());

        try {
            log.info("계좌 이체 시작 : {} ", event);
            commandGateway.sendAndWait(comamndFactory.getTransferCommand(), 10, TimeUnit.SECONDS);
        } catch (CommandExecutionException e) {
            log.error("Failed transfer process. Start cancel transaction");
            cancelTransfer();
        }
    }

    private void cancelTransfer() {
        isExecutingCompensation = true;
        log.info("보상 트랜잭션 요청");
        commandGateway.send(comamndFactory.getAbortTransferCommand());
    }

    @SagaEventHandler(associationProperty = "srcAccountID")
    protected void on(CompletedCancelTransferEvent event) {
        isExecutingCompensation = false;
        if (!isAbortingCompensation) {
            log.info("계좌 이체 취소 완료 : {} ", event);
            SagaLifecycle.end();
        }
    }

    @SagaEventHandler(associationProperty = "srcAccountID")
    protected void on(TransferDeniedEvent event) {
        log.info("계좌 이체 실패 : {}", event);
        log.info("실패 사유 : {}", event.getDescription());
        if(isExecutingCompensation){
            isAbortingCompensation = true;
            log.info("보상 트랜잭션 취소 요청 : {}", event);
            commandGateway.send(comamndFactory.getCompensationAbortCommand());
        }
        else {
            SagaLifecycle.end();
        }
    }

    @SagaEventHandler(associationProperty = "srcAccountID")
    @EndSaga
    protected void on(CompletedCompensationCancelEvent event){
        isAbortingCompensation = false;
        log.info("보상 트랜잭션 취소 완료 : {}",event);
    }

    @SagaEventHandler(associationProperty = "srcAccountID")
    protected void on(TransferApprovedEvent event) {
        if (!isExecutingCompensation && !isAbortingCompensation) {
            log.info("이체 금액 {} 계좌 반영 요청 : {}",event.getAmount(), event);
            SagaLifecycle.associateWith("accountID", event.getDstAccountID());
            commandGateway.send(TransferApprovedCommand.builder()
                                                            .accountID(event.getDstAccountID())
                                                            .amount(event.getAmount())
                                                            .transferID(event.getTransferID())
                                                       .build());
        }
    }

    @SagaEventHandler(associationProperty = "accountID")
    @EndSaga
    protected void on(DepositCompletedEvent event){
        log.info("계좌 이체 성공 : {}", event);
    }
}

5. 테스트 결과

정상

com.cqrs.command.saga.TransferManager    : event : MoneyTransferEvent(dstAccountID=a31faade-5b57-4435-85da-1de0ed1c55c4, srcAccountID=test, amount=1, transferID=30dbfa4a-ea98-4343-bcbd-00e906870090, comamndFactory=com.cqrs.command.transfer.factory.TransferComamndFactory@d713db5)
com.cqrs.command.saga.TransferManager    : 계좌 이체 시작 : MoneyTransferEvent(dstAccountID=a31faade-5b57-4435-85da-1de0ed1c55c4, srcAccountID=test, amount=1, transferID=30dbfa4a-ea98-4343-bcbd-00e906870090, comamndFactory=com.cqrs.command.transfer.factory.TransferComamndFactory@d713db5) 
com.cqrs.command.saga.TransferManager    : 이체 금액 1 계좌 반영 요청 : TransferApprovedEvent(srcAccountID=test, dstAccountID=a31faade-5b57-4435-85da-1de0ed1c55c4, transferID=30dbfa4a-ea98-4343-bcbd-00e906870090, amount=1)
c.c.command.aggregate.AccountAggregate   : handling TransferApprovedCommand(accountID=a31faade-5b57-4435-85da-1de0ed1c55c4, amount=1, transferID=30dbfa4a-ea98-4343-bcbd-00e906870090)
c.c.command.aggregate.AccountAggregate   : applying DepositMoneyEvent(holderID=b01fae84-e8a5-427d-a5f4-baa7376b7163, accountID=a31faade-5b57-4435-85da-1de0ed1c55c4, amount=1)
c.c.command.aggregate.AccountAggregate   : balance 31
com.cqrs.command.saga.TransferManager    : 계좌 이체 성공 : DepositCompletedEvent(accountID=a31faade-5b57-4435-85da-1de0ed1c55c4, transferID=30dbfa4a-ea98-4343-bcbd-00e906870090)

Timeout

com.cqrs.command.saga.TransferManager    : event : MoneyTransferEvent(dstAccountID=a31faade-5b57-4435-85da-1de0ed1c55c4, srcAccountID=test, amount=1, transferID=7a01bd7a-6ce0-43bd-93e9-ee0224dfd791, comamndFactory=com.cqrs.command.transfer.factory.TransferComamndFactory@3226f9ff)
com.cqrs.command.saga.TransferManager    : 계좌 이체 시작 : MoneyTransferEvent(dstAccountID=a31faade-5b57-4435-85da-1de0ed1c55c4, srcAccountID=test, amount=1, transferID=7a01bd7a-6ce0-43bd-93e9-ee0224dfd791, comamndFactory=com.cqrs.command.transfer.factory.TransferComamndFactory@3226f9ff) 
com.cqrs.command.saga.TransferManager    : Failed transfer process. Start cancel transaction
com.cqrs.command.saga.TransferManager    : 보상 트랜잭션 요청
com.cqrs.command.saga.TransferManager    : 계좌 이체 취소 완료 : CompletedAbortTransferEvent(srcAccountID=test, dstAccountID=a31faade-5b57-4435-85da-1de0ed1c55c4, amount=1, transferID=7a01bd7a-6ce0-43bd-93e9-ee0224dfd791)

잔고 부족

c.c.command.aggregate.AccountAggregate   : handling MoneyTransferCommand(srcAccountID=test, dstAccountID=a31faade-5b57-4435-85da-1de0ed1c55c4, amount=300, transferID=f73d08ba-004c-4e44-9929-2866f6ea02da, bankType=JEJU)
com.cqrs.command.saga.TransferManager    : Created saga instance
com.cqrs.command.saga.TransferManager    : event : MoneyTransferEvent(dstAccountID=a31faade-5b57-4435-85da-1de0ed1c55c4, srcAccountID=test, amount=300, transferID=f73d08ba-004c-4e44-9929-2866f6ea02da, comamndFactory=com.cqrs.command.transfer.factory.TransferComamndFactory@66a12a11)
com.cqrs.command.saga.TransferManager    : 계좌 이체 시작 : MoneyTransferEvent(dstAccountID=a31faade-5b57-4435-85da-1de0ed1c55c4, srcAccountID=test, amount=300, transferID=f73d08ba-004c-4e44-9929-2866f6ea02da, comamndFactory=com.cqrs.command.transfer.factory.TransferComamndFactory@66a12a11) 
com.cqrs.command.saga.TransferManager    : 계좌 이체 실패 : TransferDeniedEvent(srcAccountID=test, dstAccountID=a31faade-5b57-4435-85da-1de0ed1c55c4, transferID=f73d08ba-004c-4e44-9929-2866f6ea02da, amount=300, description=잔고가 부족합니다.)
com.cqrs.command.saga.TransferManager    : 실패 사유 : 잔고가 부족합니다.

잔고 부족 + Timeout

com.cqrs.command.saga.TransferManager    : event : MoneyTransferEvent(dstAccountID=a31faade-5b57-4435-85da-1de0ed1c55c4, srcAccountID=test, amount=300, transferID=b132f585-3be8-49b0-ab67-0293a05684ff, comamndFactory=com.cqrs.command.transfer.factory.TransferComamndFactory@3d4d8677)
com.cqrs.command.saga.TransferManager    : 계좌 이체 시작 : MoneyTransferEvent(dstAccountID=a31faade-5b57-4435-85da-1de0ed1c55c4, srcAccountID=test, amount=300, transferID=b132f585-3be8-49b0-ab67-0293a05684ff, comamndFactory=com.cqrs.command.transfer.factory.TransferComamndFactory@3d4d8677) 
com.cqrs.command.saga.TransferManager    : Failed transfer process. Start cancel transaction
com.cqrs.command.saga.TransferManager    : 보상 트랜잭션 요청
com.cqrs.command.saga.TransferManager    : 계좌 이체 실패 : TransferDeniedEvent(srcAccountID=test, dstAccountID=a31faade-5b57-4435-85da-1de0ed1c55c4, transferID=b132f585-3be8-49b0-ab67-0293a05684ff, amount=300, description=잔고가 부족합니다.)
com.cqrs.command.saga.TransferManager    : 실패 사유 : 잔고가 부족합니다.
com.cqrs.command.saga.TransferManager    : 보상 트랜잭션 취소 요청 : TransferDeniedEvent(srcAccountID=test, dstAccountID=a31faade-5b57-4435-85da-1de0ed1c55c4, transferID=b132f585-3be8-49b0-ab67-0293a05684ff, amount=300, description=잔고가 부족합니다.)
com.cqrs.command.saga.TransferManager    : 보상 트랜잭션 취소 완료 : CompletedCompensationAbortEvent(srcAccountID=test, dstAccountID=a31faade-5b57-4435-85da-1de0ed1c55c4, amount=300, transferID=b132f585-3be8-49b0-ab67-0293a05684ff)

테스트 결과 각기 다른 상황에서 정상적으로 수행되는 것을 확인할 수 있습니다.

6. 마치며

이상으로 AxonFramework에 대한 포스팅을 마치겠습니다. 테스팅에 대해서는 다루지 않았는데, 분산 App 환경에서 테스트 코드 작성은 반드시 필요하다고 생각합니다. 따라서 공식문서를 참고하여 테스트 코드 작성 방법을 익힌다면, 보다 안전한 프로그램이 될 것입니다.

그 외에 쿠버네티스 지원, Tracing에 대해서도 공식문서에 소개되어 있으니 참고바랍니다. 또한, 지금까지 구현한 프로젝트 내용은 깃헙에 업로드 했습니다.

포스팅 내용 중 개선사항에 대해서는 댓글로 남겨주시면, 확인 후 내용 반영하도록 하겠습니다.

19. Saga 패턴을 활용한 트랜잭션 관리 - 2

cla9 — Sat, 25 Jan 2020 12:32:01 +0900

1. 서론

이번 포스팅은 분산 트랜잭션 제어를 위한 Saga 패턴을 구현하겠습니다. 보상 트랜잭션까지 같이 구현하면 내용이 복잡하므로 보상 트랜잭션 및 Deadline 기능은 다음 포스팅에서 다루겠습니다.

Saga 패턴 사용을 위한 가상의 시나리오는 다음과 같습니다.

테스트 시나리오

1. Jeju 모듈에 계좌를 개설한다.(계좌명 : test, 잔고 : 100)

2. Command 모듈에 계정 & 계좌를 개설한다.

3. Jeju 모듈의 계좌에서 30원을 Command 모듈 계좌로 이체한다.

4. Jeju 모델 DB의 계좌와 Query 모델 DB를 통해서 이체금액을 확인한다.

이전 포스팅에서 구현한 Jeju 모듈을 활용하여 코드 구현을 진행하겠습니다. Saga 요청을 위한 API 및 Saga 인스턴스는 Command 모듈에 생성하도록 하겠습니다.

2. Common 모듈 구현

1. 공통으로 사용할 Command 및 Event 추가를 위해 Common 모듈 Command 패키지 및 Command 클래스를 생성합니다.

2. 생성한 Command 클래스를 구현합니다.

TransferComamndFactory.java

@RequiredArgsConstructor
public class TransferComamndFactory {
    private final AbstractTransferCommand transferCommand;

    public void create(String srcAccountID, String dstAccountID, Long amount, String transferID){
        transferCommand.create(srcAccountID, dstAccountID, amount, transferID);
    }

    public AbstractTransferCommand getTransferCommand(){
        return this.transferCommand;
    }
}

위 클래스는 계좌 이체와 연관된 Command를 생성하는 Factory 클래스입니다. 나중에 보상 트랜잭션을 위한 Command를 같이 관리하기 위하여 생성하였습니다.

AbstractTransferCommand.java

@ToString
@Getter
public abstract class AbstractTransferCommand {
    @TargetAggregateIdentifier
    protected String srcAccountID;
    protected String dstAccountID;
    protected Long amount;
    protected String transferID;

    public AbstractTransferCommand create(String srcAccountID, String dstAccountID, Long amount, String transferID) {
        this.srcAccountID = srcAccountID;
        this.dstAccountID = dstAccountID;
        this.transferID = transferID;
        this.amount = amount;
        return this;
    }
}

계좌 이체 요청을 위한 클래스입니다. srcAccountID는 인출할 계좌 ID이며, dstAccountID는 송금 대상 계좌 ID입니다.

JejuBankTransferCommand.java

public class JejuBankTransferCommand extends AbstractTransferCommand {
    @Override
    public String toString() {
        return "JejuBankTransferCommand{" +
                "srcAccountID='" + srcAccountID + '\'' +
                ", dstAccountID='" + dstAccountID + '\'' +
                ", amount=" + amount +
                ", transferID='" + transferID + '\'' +
                '}';
    }
}

SeoulBankTransferCommand.java

public class SeoulBankTransferCommand extends AbstractTransferCommand {
    @Override
    public String toString() {
        return "SeoulBankTransferCommand{" +
                "srcAccountID='" + srcAccountID + '\'' +
                ", dstAccountID='" + dstAccountID + '\'' +
                ", amount=" + amount +
                ", transferID='" + transferID + '\'' +
                '}';
    }
}

3. Common 모듈 event 패키지 하위에 Event 클래스를 생성합니다.

4. Event 클래스를 구현합니다.

MoneyTransferEvent.java

@Builder
@ToString
@Getter
public class MoneyTransferEvent {
    private String dstAccountID;
    private String srcAccountID;
    private Long amount;
    private String transferID;
    private TransferComamndFactory comamndFactory;
}

위 클래스는 Command 모듈로 계좌이체 요청이 들어오면, 인출할 대상 계좌번호(srcAccountID) 및 입금 계좌번호(dstAccountID), 그리고 이체 금액(amount)와 같은 기본정보와 트랜잭션간 고유 키(transferID) 및 요청 Command 구분 정보를 담고있습니다.

TransferApprovedEvent.java

@Builder
@ToString
@Getter
public class TransferApprovedEvent {
    private String srcAccountID;
    private String dstAccountID;
    private String transferID;
    private Long amount;
}

위 클래스는 계좌이체가 성공되었을 때, 금액을 반영하기 위한 Event입니다.

TransferDeniedEvent.java

@Getter
@Builder
@ToString
public class TransferDeniedEvent {
    private String srcAccountID;
    private String dstAccountID;
    private String transferID;
    private Long amount;
    private String description;
}

위 클래스는 계좌이체가 거절될 때, 요청 App에 거절 내역을 전달하기 위한 Event입니다.

3. Jeju 모듈 구현

1. Jeju 은행 모듈 build.gradle 파일을 엽니다.

2. Jeju 모듈에 State-Stored-Aggregate 구현을 위해 JPA 및 DB 의존성을 추가합니다.

build.gradle

ext{
    axonVersion = "4.2.1"
}
dependencies{
    implementation 'org.springframework.boot:spring-boot-starter-web'
    implementation 'org.springframework.boot:spring-boot-starter-data-jpa'
    compileOnly 'org.projectlombok:lombok'
    annotationProcessor 'org.projectlombok:lombok'
    implementation group: 'org.axonframework', name: 'axon-spring-boot-starter', version: "$axonVersion"
    implementation group: 'org.postgresql', name: 'postgresql', version: '42.2.6'
}

3. Jeju 모듈 resources 패키지 하위 application.yml 파일을 엽니다.

4. datasource 속성을 추가합니다.

application.yml

server:
  port: 9091

spring:
  application:
    name: eventsourcing-cqrs-jejuBank
  datasource:
    platform: postgres
    url: jdbc:postgresql://localhost:5432/jeju
    username: jeju
    password: jeju
  jpa:
    hibernate:
      ddl-auto: update

axon:
  serializer:
    general: xstream
  axonserver:
    servers: localhost:8124

logging.level.com.cqrs.jeju : debug

DB는 Command와 Query와 동일하게 Postgre를 사용하였으며, jeju 계정을 별도로 생성하였습니다.

5. 계좌 생성을 위해 Jeju 모듈 하위에 다음과 같은 패키지들을 생성합니다.

6. aggregate 패키지 내 aggregate 클래스부터 구현하겠습니다.

Account.java


@Entity
@Aggregate
@NoArgsConstructor
@AllArgsConstructor
@Slf4j
public class Account {
    @AggregateIdentifier
    @Id
    private String accountID;
    private Long balance;
    
    @CommandHandler
    public Account(AccountCreationCommand command) throws IllegalAccessException {
        log.debug("handling {}", command);
        if (command.getBalance() <= 0)
            throw new IllegalAccessException("유효하지 않은 입력입니다.");
        apply(new AccountCreationEvent(command.getAccountID(), command.getBalance()));
    }

    @EventSourcingHandler
    protected void on(AccountCreationEvent event) {
        log.debug("event {}", event);
        this.accountID = event.getAccountID();
        this.balance = event.getBalance();
    }

    @CommandHandler
    protected void on(JejuBankTransferCommand command) throws InterruptedException {

        log.debug("handling {}", command);
        if (this.balance < command.getAmount()) {
            apply(TransferDeniedEvent.builder()
                                        .srcAccountID(command.getSrcAccountID())
                                        .dstAccountID(command.getDstAccountID())
                                        .amount(command.getAmount())
                                        .description("잔고가 부족합니다.")
                                        .transferID(command.getTransferID())
                                     .build());
        } else {
            apply(TransferApprovedEvent.builder()
                                            .srcAccountID(command.getSrcAccountID())
                                            .dstAccountID(command.getDstAccountID())
                                            .transferID(command.getTransferID())
                                            .amount(command.getAmount())
                                        .build());
        }
    }

    @EventSourcingHandler
    protected void on(TransferApprovedEvent event) {
        log.debug("event {}", event);
        this.balance -= event.getAmount();
    }
}

트랜잭션 테스트 도중 Account 정보를 DB에서 바로 확인하기 위해 State-Stored Aggregate 형태로 구현하였습니다. 위 코드 내용은 Command 어플리케이션 구현파트에서 다룬 내용이 주이기에 별도 설명은 생략하겠습니다.

7. command 패키지내 Command 클래스 생성 및 이를 구현합니다.

AccountCreationCommand.java

@NoArgsConstructor
@AllArgsConstructor
@ToString
@Getter
public class AccountCreationCommand {
    @TargetAggregateIdentifier
    private String accountID;
    private Long balance;
}

8. dto 패키지내 dto 클래스 생성 및 이를 구현합니다.

AccountDTO.java

@NoArgsConstructor
@AllArgsConstructor
@ToString
@Getter
public class AccountDTO {
    private String accountID;
    private Long balance;
}

9. event 패키지내 event 클래스를 생성 및 이를 구현합니다.

AccountCreationEvent.java

@ToString
@RequiredArgsConstructor
@Getter
public class AccountCreationEvent {
    private final String accountID;
    private final Long balance;
}

해당 이벤트는 Jeju 모듈내에서만 유효하기 때문에 공통 모듈에 생성하지 않았습니다.

10. service 패키지내 service 클래스 생성 및 이를 구현합니다.

AccountService.java

public interface AccountService {
    String createAccount(AccountDTO accountDTO);
}

AccountServiceImpl.java

@Service
@RequiredArgsConstructor
public class AccountServiceImpl implements AccountService {
    private final CommandGateway commandGateway;

    @Override
    public String createAccount(AccountDTO accountDTO) {
        return commandGateway.sendAndWait(new AccountCreationCommand(accountDTO.getAccountID(), accountDTO.getBalance()));
    }
}

11. controller 패키지내 controller 클래스 생성 및 이를 구현합니다.

AccountController.java

@RestController
@RequiredArgsConstructor
public class AccountController {
    private final AccountService accountService;

    @PostMapping("/account")
    public ResponseEntity<String> createAccount(@RequestBody AccountDTO accountDTO){
        return ResponseEntity.ok().body(accountService.createAccount(accountDTO));
    }
}

4. Command 모듈 구현

1. Command 구현 포스팅 8번 항목에서 AxonServerCommandBus를 SimpleCommandBus로 대체했습니다. Saga 트랜잭션에서는 다른 모듈에 대하여 Command 요청이 필요하므로 기존에 SImpleCommandBus 설정을 해제해야합니다. 이를 위해 config 패키지내에 있는 AxonConfig 클래스를 엽니다.

2. AxonConfig 파일에서 commandBus Bean 로직을 주석처리하거나 삭제합니다.

AxonConfig.java

@Configuration
@AutoConfigureAfter(AxonAutoConfiguration.class)
public class AxonConfig {
	(...중략...)
//    @Bean
//    SimpleCommandBus commandBus(TransactionManager transactionManager){
//        return  SimpleCommandBus.builder().transactionManager(transactionManager).build();
//    }
	(...중략...)
}

3. 계좌이체 요청 및 반영을 위한 Command 요청을 위해 command 패키지 내 command 클래스를 생성합니다.

4. Command 클래스 내용을 구현합니다.

TransferApprovedCommand.java

@ToString
@Getter
@Builder
public class TransferApprovedCommand {
    @TargetAggregateIdentifier
    private String accountID;
    private Long amount;
    private String transferID;
}

위 클래스는 계좌이체가 정상적으로 수행되었을 때, 요청을 위한 Command 클래스입니다.

MoneyTransferCommand.java

@Builder
@ToString
@Getter
public class MoneyTransferCommand {
    private String srcAccountID;
    @TargetAggregateIdentifier
    private String dstAccountID;
    private Long amount;
    private String transferID;
    private BankType bankType;

    public enum BankType{
        JEJU(command -> new TransferComamndFactory(new JejuBankTransferCommand()),
        SEOUL(command -> new TransferComamndFactory(new SeoulBankTransferCommand());

        private Function<MoneyTransferCommand, TransferComamndFactory> expression;
        BankType(Function<MoneyTransferCommand, TransferComamndFactory> expression){ this.expression = expression;}
        public TransferComamndFactory getCommandFactory(MoneyTransferCommand command){
            TransferComamndFactory factory = this.expression.apply(command);
            factory.create(command.getSrcAccountID(), command.getDstAccountID(), command.amount, command.getTransferID());
            return factory;
        }

    }

    public static MoneyTransferCommand of(TransferDTO dto){
        return MoneyTransferCommand.builder()
                .srcAccountID(dto.getSrcAccountID())
                .dstAccountID(dto.getDstAccountID())
                .amount(dto.getAmount())
                .bankType(dto.getBankType())
                .transferID(UUID.randomUUID().toString())
                .build();
    }
}

계좌 이체 요청시, 은행구분에 따른 Command 생성을 달리 하기 위하여 enum을 사용했습니다. 또한, DTO 클래스를 Command 클래스로 변환하기 위한 Factory 메소드를 추가하였습니다.

5. DTO 추가를 위해 dto 패키지 내 dto 클래스를 생성합니다.

TransferDTO.java

@Getter
@ToString
@AllArgsConstructor
@NoArgsConstructor
public class TransferDTO {
    private String srcAccountID;
    private String dstAccountID;
    private Long amount;
    private MoneyTransferCommand.BankType bankType;
}

6. Service 메소드 추가를 위해서 service 패키지 하위 service 클래스를 수정합니다.

TransactionService.java

public interface TransactionService {
    (...중략...)
    String transferMoney(TransferDTO transferDTO);
}

TransactionServiceImpl.java

@Service
@RequiredArgsConstructor
public class TransactionServiceImpl implements TransactionService {
    private final CommandGateway commandGateway;
	(...중략...)

    @Override
    public String transferMoney(TransferDTO transferDTO) {
        return commandGateway.sendAndWait(MoneyTransferCommand.of(transferDTO));
    }
}

7. API 추가를 위해서 controller 패키지내 Controller에 메소드를 추가합니다.

TransactionController.java

@RestController
@RequiredArgsConstructor
public class TransactionController {
    private final TransactionService transactionService;

    (...중략...)

    @PostMapping("/transfer")
    public ResponseEntity<String> transfer(@RequestBody TransferDTO transferDTO){
        return ResponseEntity.ok().body(transactionService.transferMoney(transferDTO));
    }
}

8. Aggregate 수정을 위해 aggregate 패키지내 AccountAggregate 클래스를 엽니다.

9. Aggregate에 Command 및 EventSourcing 핸들러 로직을 추가합니다.

AccountAggregate.java

@NoArgsConstructor
@AllArgsConstructor
@Slf4j
@Aggregate
@EqualsAndHashCode
public class AccountAggregate {
    (...중략...)

    @CommandHandler
    protected void transferMoney(MoneyTransferCommand command) {
        log.debug("handling {}", command);
        apply(MoneyTransferEvent.builder()
                .srcAccountID(command.getSrcAccountID())
                .dstAccountID(command.getDstAccountID())
                .amount(command.getAmount())
                .comamndFactory(command.getBankType().getCommandFactory(command))
                .transferID(command.getTransferID())
                .build());
    }

    @CommandHandler
    protected void transferMoney(TransferApprovedCommand command) {
        log.debug("handling {}", command);
        apply(new DepositMoneyEvent(this.holderID, command.getAccountID(), command.getAmount()));
        apply(new DepositCompletedEvent(command.getAccountID(), command.getTransferID()));
    }
}

10. Saga 패키지 및 Saga 클래스를 생성합니다.

11. Saga 클래스를 구현합니다.

TransferManager.java

@Saga
@Slf4j
public class TransferManager {
    @Autowired
    private transient CommandGateway commandGateway;
    private TransferComamndFactory comamndFactory;

    @StartSaga
    @SagaEventHandler(associationProperty = "transferID")
    protected void on(MoneyTransferEvent event) {
        log.debug("Created saga instance");
        log.debug("event : {}", event);
        comamndFactory = event.getComamndFactory();
        SagaLifecycle.associateWith("srcAccountID", event.getSrcAccountID());

		log.info("계좌 이체 시작 : {} ", event);
		commandGateway.send(comamndFactory.getTransferCommand());
    }

    @SagaEventHandler(associationProperty = "srcAccountID")
    protected void on(TransferApprovedEvent event) {
		log.info("이체 금액 {} 계좌 반영 요청 : {}", event.getAmount(), event);
        SagaLifecycle.associateWith("accountID", event.getDstAccountID());
        commandGateway.send(TransferApprovedCommand.builder()
                .accountID(event.getDstAccountID())
                .amount(event.getAmount())
                .transferID(event.getTransferID())
                .build());
    }
    
    @SagaEventHandler(associationProperty = "srcAccountID")
    protected void on(TransferDeniedEvent event) {
        log.info("계좌 이체 실패 : {}", event);
        log.info("실패 사유 : {}", event.getDescription());
		SagaLifecycle.end();
    }

    @SagaEventHandler(associationProperty = "accountID")
    @EndSaga
    protected void on(DepositCompletedEvent event){
        log.info("계좌 이체 성공 : {}", event);
    }
}

구현 내용을 간략하게 소개하면 다음과 같습니다. 먼저 @Saga 어노테이션을 통해 해당 클래스가 Saga의 대상임을 지정합니다. 해당 클래스는 NoArgsConstructor로 생성이 되어야하므로 이를 주의합니다.

@StartSaga는 Saga 인스턴스의 시작점입니다. 여기에서 associationProperty는 해당 인스턴스를 유일하게 구별할 수 있는 속성이 무엇인지 지정합니다. 자세한 내용은 Axon 공식문서를 참고바랍니다.

생성된 Saga는 트랜잭션이 끝나면 종료되어야합니다. 위 예제에서는 DepositCompletedEvent 메시지를 수신받으면, 전체 트랜잭션이 끝난것으로 판단하여 Saga 인스턴스를 종료하도록 되어있습니다. Saga 인스턴스 종료방법은 크게 두가지입니다. 먼저 위 에제와 같이 명시적으로 end 메소드를 기입하거나 @EndSaga 어노테이션 지정할 수 있습니다.

5. 테스트

1. Command, Query, Jeju 모듈 App을 기동한 다음, Jeju 은행 계좌를 개설합니다.

POST localhost:9091/account
Content-Type: application/json

{
	"accountID" : "test",
	"balance" : 100
}

2. 생성된 계좌 내역을 DB에서 확인합니다.

3. Command 모듈에 계정을 생성합니다.

POST http://localhost:8080/holder
Content-Type: application/json

{
	"holderName" : "Kevin",
	"tel" : "02-2645-5678",
	"address" : "OO시 OO구",
    "company" : "Korea"
}

4. Command 모듈에 계좌를 개설합니다.

POST http://localhost:8080/account
Content-Type: application/json

{
  "holderID" : "b01fae84-e8a5-427d-a5f4-baa7376b7163"
}

5. Query 모듈 DB에서 계정 및 계좌 생성 내역을 확인합니다.

6. Jeju 은행 계좌에서 Command 모듈에 개설된 계좌로 30원 이체합니다.

POST http://localhost:8080/transfer
Content-Type: application/json
{
	"srcAccountID" : "test",
	"dstAccountID" : "a31faade-5b57-4435-85da-1de0ed1c55c4",
	"amount" : 30,
	"bankType" : "JEJU"
}

AccountAggregate   : handling MoneyTransferCommand(srcAccountID=test, dstAccountID=a31faade-5b57-4435-85da-1de0ed1c55c4, amount=30, transferID=3a6583e3-0288-4e07-87f0-c818644e009b, bankType=JEJU)
TransferManager    : Created saga instance
TransferManager    : event : MoneyTransferEvent(dstAccountID=a31faade-5b57-4435-85da-1de0ed1c55c4, srcAccountID=test, amount=30, transferID=3a6583e3-0288-4e07-87f0-c818644e009b, comamndFactory=com.cqrs.command.transfer.factory.TransferComamndFactory@5a65bed)
TransferManager    : 계좌 이체 시작 : MoneyTransferEvent(dstAccountID=a31faade-5b57-4435-85da-1de0ed1c55c4, srcAccountID=test, amount=30, transferID=3a6583e3-0288-4e07-87f0-c818644e009b, comamndFactory=com.cqrs.command.transfer.factory.TransferComamndFactory@5a65bed) 
TransferManager    : 이체 금액 30 계좌 반영 요청 : TransferApprovedEvent(srcAccountID=test, dstAccountID=a31faade-5b57-4435-85da-1de0ed1c55c4, transferID=3a6583e3-0288-4e07-87f0-c818644e009b, amount=30)
AccountAggregate   : handling TransferApprovedCommand(accountID=a31faade-5b57-4435-85da-1de0ed1c55c4, amount=30, transferID=3a6583e3-0288-4e07-87f0-c818644e009b)
AccountAggregate   : applying DepositMoneyEvent(holderID=b01fae84-e8a5-427d-a5f4-baa7376b7163, accountID=a31faade-5b57-4435-85da-1de0ed1c55c4, amount=30)
AccountAggregate   : balance 30
TransferManager    : 계좌 이체 성공 : DepositCompletedEvent(accountID=a31faade-5b57-4435-85da-1de0ed1c55c4, transferID=3a6583e3-0288-4e07-87f0-c818644e009b)

성공적으로 계좌이체가 완료되었으면 위와 비슷한 로그가 출력될 것입니다.

7. DB에서 계좌 상태를 확인합니다.

6. 마치며

serialized_sga 내용

<com.cqrs.command.saga.TransferManager>
    <comamndFactory>
        <transferCommand class="com.cqrs.command.transfer.JejuBankTransferCommand">
        <srcAccountID>test</srcAccountID>
        <dstAccountID>a31faade-5b57-4435-85da-1de0ed1c55c4</dstAccountID>
        <amount>30</amount>
        <transferID>test</transferID>
        </transferCommand>
        </compensationAbortCommand>
    </comamndFactory>
</com.cqrs.command.saga.TransferManager>

이번 포스팅에서는 Jeju, Command 모듈간에 일관성을 위하여 Saga 패턴을 사용했습니다. Command 모듈에서 MoneyTransferEvent Event가 발행되면, Saga 인스턴스가 생성됩니다. 이후 Application의 비즈니스 로직에 따라 모든 트랜잭션이 종료될 때까지 유지됩니다. Saga 인스턴스 정보는 동시에 SAGA_ENTRY 테이블에 적재되며, Saga 인스턴스가 종료되면 해당 데이터 또한 사라집니다.

다음 포스팅에서는 Deadline 기능, 보상 트랜잭션 로직이 적용된 Saga 패턴을 구현하겠습니다.

18. Saga 패턴을 활용한 트랜잭션 관리 - 1

cla9 — Thu, 23 Jan 2020 22:59:32 +0900

1. 서론

MSA 아키텍처를 구성하기 어려운 이유중 가장 큰 문제는 트랜잭션(Transaction)입니다. 기존 모놀로틱(Monolithic) 환경에서 DBMS가 기본적으로 제공해주는 트랜잭션 기능을 통해 데이터 Commit 혹은 Rollback을 통해 데이터를 일관성 있게 관리했습니다. 하지만 Application 및 DB가 분산되면서, 트랜잭션 처리를 단일 DBMS에서 제공하는 기능을 통해서 달성할 수 없습니다.

이번 포스팅에서는 분산 트랜잭션의 종류인 Two-Phase Commit, Saga 패턴 및 Axon에서 제공하는 Saga 기능에 대하여 소개하겠습니다.

2. Two Phase Commit

분산 DB 환경에서 쓰는 방법으로 주요 RDBMS에서 기능을 제공합니다. Two-Phase Commit은 말 그대로 2단계에 거쳐서 데이터를 영속화 하는 작업입니다. 위 그림과 같이 여러 DB가 분산 되었을 때, 트랜잭션을 조율하는 조정자(Coordinator)가 존재합니다. 조정자의 역할은 트랜잭션 요청이 들어왔을 때 두 단계를 거쳐 트랜잭션을 진행을 담당합니다. 이때 첫 번째 단계는 Prepare이며, 이는 쉽게말해 연관된 DB에게 데이터를 저장할 수 있는 상태인지 묻는 과정에 해당합니다.

메시지를 받은 DB에서는 Commit 작업을 위한 준비를 진행합니다. 이후 데이터를 영속할 수 있는 준비가 완료되면 조정자에게 준비가 완료되었음을 알리고, 반대로 Commit할 수 없다면 불가하다는 메시지를 전달합니다.

조정자는 첫 번째 단계에서 전달한 메시지에 대한 응답을 기다립니다. 모든 메시지 수신이 완료되면 두 번째 단계인 Commit을 진행합니다. Commit 단계에서는 조정자가 연관된 DB에게 데이터를 저장하라는 메시지를 송신하며, 수신받은 DB에서는 각자 DB에 데이터를 영속화 합니다.

모든 DB에서 트랜잭션 처리가 완료되면 전체 트랜잭션을 종료합니다.만약 두 단계를 거치는 과정에서 연관된 DB 중 하나의 DB라도 Commit을 할 수 없는 상황이라면, 모든 DB에게 Rollback을 요구합니다. 트랜잭션을 종료하는 동시에 모든 DB 데이터가 영속화됩니다. 따라서 트랜잭션의 범위는 데이터를 처리하는 DB 전체입니다.

MSA 환경에서 Two-Phase Commit 문제점

Two-Phase Commit은 DBMS 간 분산 트랜잭션을 지원해야 적용가능합니다. 하지만 NoSQL 제품군에는 이를 지원하지 않고, 함께 사용되는 DBMS가 동일 제품군(Oracle, MySQL, Postgres)이여야합니다. 따라서 DBMS polyglot 구성은 어렵습니다.

또한 Two-Phase Commit은 보통 하나의 API 엔드포인트를 통해 서비스 요청이 들어오고 내부적으로 DB가 분산되어있을 때 사용됩니다. 하지만 MSA 환경에서는 각기 다른 App에서 API간으로 통신을 통해 서비스 요청이 이루어지기 때문에 구현이 쉽지 않습니다.

3. Saga 패턴

Saga 패턴은 트랜잭션의 관리주체가 DBMS가 아닌 Application에 있습니다. App이 분산되어있을 때, 각 App 하위에 존재하는 DB는 Local 트랜잭션 처리만 담당합니다.

따라서 각각의 App에 대한 연속적인 트랜잭션 요청 및 실패할 경우에 Rollback 처리(보상 트랜잭션)를 Application에서 구현해야합니다.

Saga 패턴은 위 그림과 같이 연속적인 업데이트 연산으로 이루어져있으며, 전체가 동시에 데이터가 영속화되는 것이아니라 순차적인 단계로 트랜잭션이 이루어집니다. 따라서 Application 비즈니스 로직에서 요구되는 마지막 트랜잭션이 끝났을 때, 데이터가 완전히 영속되었음을 인지하고 이를 종료합니다.

Two-Phase Commit과 다르게 Saga를 활용한 트랜잭션은 데이터 격리성(Isolation)을 보장해주지 않습니다. 하지만 Application의 트랜잭션 관리를 통해 최종 일관성(Eventually Consistency)을 달성할 수 있기 때문에 분산되어있는 DB간에 정합성을 맞출 수 있습니다. 또한 트랜잭션 관리를 Application에서 하기 때문에 DBMS를 다른 제품군으로 구성할 수 있는 장점이 있습니다.

하지만 이러한 일관성을 달성하기 위해서는 프로세스 수행 과정상 누락되는 작업이 없는지 면밀히 살펴야하며, 실패할경우 에러 복구를 위한 보상 트랜잭션 처리 누락이 없도록 설계해야합니다.

4. Saga 패턴 종류

1. Choreography-Based Saga

Choreography-Based Saga는 자신이 보유한 서비스내 Local 트랜잭션을 관리하며, 트랜잭션이 종료되면 완료 Event를 발행합니다. 만약 그 다음에 수행되어야할 트랜잭션이 있다면, 해당 트랜잭션을 수행해야하는 App에서 완료 Event를 수신받고 다음 작업을 처리합니다. 이때 Event는 Kafka와 같은 메시지 큐를 이용해서 비동기 방식으로 전달할 수 있습니다.

Choreography-Based Saga 방식에서는 각 App별로 트랜잭션을 관리하는 로직이 있습니다. 따라서 중간에 트랜잭션이 실패하면, 해당 트랜잭션 취소처리를 실패한 App에서 보상 Event를 발행하여 Rollback 처리를 시도합니다.

위와 같은 구성은 구축하기 쉬운 장점이 있습니다. 하지만 운영자 입장에서 트랜잭션의 현재 상태를 알기 쉽지 않습니다.

2. Orchestration-Based Saga

Orchestration-Based Saga는 트랜잭션 처리를 위한 Saga 인스턴스(Manager)가 별도로 존재합니다. 트랜잭션에 관여하는 모든 App은 Manager에 의하여 점진적으로 트랜잭션을 수행하며 결과를 Manager에게 전달합니다. 비즈니스 로직상 마지막 트랜잭션이 끝나면 Manager를 종료하여 전체 트랜잭션 처리를 종료합니다. 만약 중간에 실패하게 되면 Manager에서 보상 트랜잭션을 발동하여 일관성을 유지하도록 합니다.

모든 관리를 Manager가 호출하기 때문에 분산트랜잭션의 중앙 집중화가 이루어집니다. 따라서 서비스간의 복잡성이 줄어들고 구현 및 테스트가 상대적으로 쉽습니다. 또한 트랜잭션의 현재 상태를 Manager가 알고 있기 때문에 롤백을 쉽게할 수 있는 것 또한 장점입니다. 하지만 이를 관리하기 위한 Orchestrator 서비스가 추가되어야 하기 때문에 인프라 구현의 복잡성이 증가되는 단점이 존재합니다.

5. Axon Saga 기능 소개

AxonFramework 에서는 Orchestration 방식의 Saga 패턴을 지원합니다. 즉 트랜잭션을 시작하는 시점에 Saga 인스턴스를 생성하며. Saga 인스턴스에서 트랜잭션을 관리합니다.

Saga 인스턴스는 Event를 처리하는 UnitOfWork 단계에서 생성되며, 전체 트랜잭션 처리가 완료되면 Saga 인스턴스를 종료합니다. Axon에서는 Annotation 기반으로 Saga 인스턴스를 간편하게 설정할 수 있습니다. 또한 DB에 Saga 정보를 저장하고 있어 복구가 가능합니다.

추가로 생성된 Saga에서 트랜잭션 요청시, Deadline 지정이 가능합니다. 이로인해 트랜잭션 수행 App으로부터 응답이 없을 경우 보상 트랜잭션을 수행할 수 있습니다.

6. 마치며

MSA를 구성하는 환경에서 Saga를 도입하기전에 비즈니스 로직상 트랜잭션처리가 반드시 필요한지에 대한 충분한 고려가 필요합니다. 이곳 저곳에 적용했다가는 트랜잭션 처리 지옥을 경험할 수 있기 때문입니다. 반드시 필요한 부분에만 일부 도입하는 것이 좋으며, 가장 좋은 상황은 MSA 환경에서 트랜잭션 처리를 하지 않도록 비즈니스 로직을 설계하는 것입니다.

다음 시간에는 예제 구현을 통해 Axon에서 제공하는 Saga 기능을 익혀보겠습니다.

17. Query 어플리케이션 구현(Query) - 3

cla9 — Mon, 20 Jan 2020 00:30:05 +0900

1. 서론

이번 포스팅에서는 Scatter-Gather Query를 구현하겠습니다. Scatter-Gather Query는 동일한 Query를 수행하는 Query Handler가 여러 App에 존재할 경우 모든 App에 Query를 요청하여 결과를 취합받아 최초 Query를 요청한 Application에서 결과를 처리합니다.

데모 프로젝트에 아래와 같은 요구사항이 추가되었음을 가정하여 Scatter-Gather Query 기능을 구현하도록 하겠습니다.

Axon Server에 Jeju 은행과 Seoul 은행 외부시스템이 연결되어있다고 가정해봅시다. 이때 소유주(HolderID)가 보유한 잔고에 대하여 각 은행에게 대출한도를 Query하면 은행별로 전달받은 답변을 Client 화면에 표시하는 요구사항을 코드를 통해 알아보겠습니다.

2. Jeju 은행 모듈 구현

1. Jeju 은행과, Seoul 은행에 Query를 요청하려면, Query 클래스 정보를 공유해야하므로, 공통 모듈(Common)에 Query 클래스를 생성해야합니다. 먼저 Common 모듈에 query > loan 패키지를 생성합니다. 이후 Query 및 결과를 저장할 클래스를 생성합니다.

2. 생성한 두 클래스를 구현합니다.

LoanLimitQuery.java

@AllArgsConstructor
@ToString
@Getter
public class LoanLimitQuery {
    private String holderID;
    private Long balance;
}

LoanLimitResult.java

@AllArgsConstructor
@ToString
@Getter
@Builder
public class LoanLimitResult {
    private String holderID;
    private String bankName;
    private Long balance;
    private Long loanLimit;
}

3. 새로운 은행 모듈 생성을 위하여 프로젝트 root 디렉토리에 위치한 settings.gradle 파일을 연다음 모듈 추가합니다.

settings.gradle

rootProject.name = 'demo'
include 'command'
include 'query'
include 'common'
include 'seoulBank'
include 'jejuBank'

4. 추가된 두 묘듈에서 공통 모듈을 사용하기 위해 빌드 설정을 추가해야 합니다. 프로젝트 root 디렉토리에 위치한 build.gradle 파일을 연다음 빌드 스크립트 내용을 추가합니다.

build.gradle

(...중략...)
project(':jejuBank') {
    dependencies {
        compile project(':common')
    }
}

project(':seoulBank') {
    dependencies {
        compile project(':common')
    }
}

이후 gradle build를 수행하면, jejuBank, seoulBank 모듈이 생성됩니다.

5. jejuBank 프로젝트 하위에 build.gradle 파일을 생성합니다.

6. build.gradle 파일에 의존성을 추가합니다.

build.gradle

ext{
    axonVersion = "4.2.1"
}
dependencies{
    implementation 'org.springframework.boot:spring-boot-starter-web'
    compileOnly 'org.projectlombok:lombok'
    annotationProcessor 'org.projectlombok:lombok'
    implementation group: 'org.axonframework', name: 'axon-spring-boot-starter', version: "$axonVersion"
}

7. resource 패키지 하위에 application.yml 파일을 생성합니다.

8. application.yml 파일에 설정 값을 기술합니다.

application.yml

server:
  port: 9091

spring:
  application:
    name: eventsourcing-cqrs-jejuBank

axon:
  serializer:
    general: xstream
  axonserver:
    servers: localhost:8124

9. 패키지 구조 설정 한다음 Component 패키지와 Main 클래스를 생성합니다.

9. Main 클래스 내용을 구현합니다.

jejuBankApp.java

@SpringBootApplication
public class JejuBankApp {
    public static void main(String[] args) {
        SpringApplication.run(JejuBankApp.class, args);
    }
}

10. component 패키지내에 Query를 처리할 Component 클래스를 생성합니다.

11. Component 클래스 내용을 구현합니다.

AccountLoanComponent.java

@Component
@Slf4j
public class AccountLoanComponent {

    @QueryHandler
    private LoanLimitResult on(LoanLimitQuery query) {
        log.debug("handling {}",query);
        return LoanLimitResult.builder()
                .holderID(query.getHolderID())
                .balance(query.getBalance())
                .bankName("JejuBank")
                .loanLimit(Double.valueOf(query.getBalance() * 1.2).longValue())
                .build();
    }
}

위 코드에서 jeju 은행의 대출한도는 일괄적으로 보유 잔고의 120%만 가능하도록 가정하였습니다.

3. Seoul 은행 모듈 구현

1. seoulBank 프로젝트 하위에 build.gradle 파일을 생성합니다.

2. build.gradle 파일에 의존성을 추가합니다.

build.gradle

ext{
    axonVersion = "4.2.1"
}
dependencies{
    implementation 'org.springframework.boot:spring-boot-starter-web'
    compileOnly 'org.projectlombok:lombok'
    annotationProcessor 'org.projectlombok:lombok'
    implementation group: 'org.axonframework', name: 'axon-spring-boot-starter', version: "$axonVersion"
}

3. resource 패키지 하위에 application.yml 파일을 생성합니다.

4. application.yml 파일에 설정 값을 기술합니다.

application.yml

server:
  port: 9092

spring:
  application:
    name: eventsourcing-cqrs-seoulBank

axon:
  serializer:
    general: xstream
  axonserver:
    servers: localhost:8124

5. 패키지 구조 설정 한다음 Component 패키지와 Main 클래스를 생성합니다.

6. Main 클래스 내용을 구현합니다.

SeoulBankApp.java

@SpringBootApplication
public class SeoulBankApp {
    public static void main(String[] args) {
        SpringApplication.run(SeoulBankApp.class, args);
    }
}

7. component 패키지내에 Query를 처리할 Component 클래스를 생성합니다.

8. Component 클래스 내용을 구현합니다.

AccountLoanComponent.java

@Component
@Slf4j
public class AccountLoanComponent {
    @QueryHandler
    private LoanLimitResult on(LoanLimitQuery query) {
        log.debug("handling {}",query);
        return LoanLimitResult.builder()
                .holderID(query.getHolderID())
                .balance(query.getBalance())
                .bankName("SeoulBank")
                .loanLimit(Double.valueOf(query.getBalance() * 1.5).longValue())
                .build();
    }
}

4. Query 인터페이스 구현

1. 화면 생성을 위해 Query 모듈 resources > templates 패키지내에 scatter-gather.html 파일을 생성합니다.

2. 화면 코드를 구현합니다.

scatter-gather.html

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Scatter-Gather Query Example</title>
</head>
<script>
    window.addEventListener("DOMContentLoaded", function (){
        (function () {
            let appendDiv = document.getElementById("layout");
            let text = document.getElementById("holderInput");
            let pElem = document.createElement("p");
            document.getElementById("wrapper").addEventListener("click", append);

            function append(e) {
                let target = e.target;
                let callbackFunction = callback[target.getAttribute("data-cb")];
                callbackFunction();
            }

            let callback = {
                "search": (function () {
                    let holderId = text.value;
                    if (holderId === undefined || holderId === null || holderId ==="") {
                        alert("소유주를 입력하시오.");
                    } else {
                        let xhr = new XMLHttpRequest();
                        xhr.open('GET','http://localhost:9090/account/info/scatter/gather/'+holderId, true);
                        xhr.send();
                        xhr.onload = function(){
                            if(xhr.status === 200){
                                let elem = pElem.cloneNode();
                                elem.innerText = xhr.responseText;
                                appendDiv.appendChild(elem);
                            }
                        }
                    }
                })
            }
        }());
    });
</script>
<body>
<div id="wrapper">
    <input type="button" data-cb="search" value="조회"/>
</div>
<input type="text" id="holderInput" placeholder="소유주 ID를 입력하시오.">
<div id="layout"/>
</body>
</html>

3. Scatter-Query를 요청할 서비스를 구현하기 위하여 먼저 메소드를 정의해야합니다. Query 모듈 service 패키지에 위치한 QueryService 클래스를 엽니다.

4. 인터페이스에 추상 메소드를 정의합니다.

QueryService.java

public interface QueryService {
    (...중략...)
    List<LoanLimitResult> getAccountInfoScatterGather(String holderId);
}

5. QueryServiceImpl 클래스를 열어 추가된 추상 메소드를 구현합니다.

QueryServiceImpl.java

@RequiredArgsConstructor
@Slf4j
@Service
public class QueryServiceImpl implements QueryService {
    (...중략...)
    private final AccountRepository repository;
    (...중략...)
    @Override
    public List<LoanLimitResult> getAccountInfoScatterGather(String holderId) {
        HolderAccountSummary accountSummary = repository.findByHolderId(holderId).orElseThrow();

        return queryGateway.scatterGather(new LoanLimitQuery(accountSummary.getHolderId(), accountSummary.getTotalBalance()),
                ResponseTypes.instanceOf(LoanLimitResult.class),
                30, TimeUnit.SECONDS)
                .collect(Collectors.toList());
    }
}

Scatter-Gather 쿼리는 단일 App에 요청하는 것이 아니므로, 만약 Handler 처리 App에 장애가 발생한다면 무한정 대기할 수 있습니다. 따라서 요청시, DeadLine을 정하여 요청시간 만큼만 대기할 수 있도록 지정이 필요합니다.

6. API End Point 지정 및 화면 호출을 위하여 Controller 클래스 수정이 필요합니다. Query 모듈내 Controller 패키지안에 있는 두개의 Controller 클래스에 관련 메소드를 추가합니다.

HolderAccountController.java

@RestController
@RequiredArgsConstructor
public class HolderAccountController {
    (...중략...)

    @GetMapping("account/info/scatter/gather/{id}")
    public ResponseEntity<List<LoanLimitResult>> getAccountInfoScatterGather(@PathVariable(value = "id") @NonNull @NotBlank String holderId){
        return ResponseEntity.ok()
                .body(queryService.getAccountInfoScatterGather(holderId));
    }

}

WebController.java

@Controller
public class WebController {
	(...중략...)
    @GetMapping("/scatter-gather")
    public void scatterGatherQueryView(){}
}

5. 테스트

1. jeju, seoul 은행 App과 Query App을 기동합니다.

2. 웹브라우저(Chrome)에서 http://localhost:9090/scatter-gather URL 입력합니다.

3. 임의의 소유주 ID를 입력후 조회 버튼을 눌러 결과를 확인합니다.

6. 마치며

이번 포스팅을 끝으로 EventSourcing에 필요한 기본적인 Command, Event 처리 및 Query 요청에 대한 필수 기능 구현을 완료했습니다. 각 기능별로 세부적인 기능은 Axon 공식 홈페이지에서 제공하는 Document나 Google Groups를 이용하여 검색하시면 많은 자료를 구할 수 있으니 참고 바랍니다.

16. Query 어플리케이션 구현(Query) - 2

cla9 — Sun, 19 Jan 2020 19:41:51 +0900

1. 서론

이번 시간에는 Query 기능 중 Point to Point, Subscription 기능을 구현합니다. 또한, Query 결과를 보기 위하여 Client 화면을 간략하게 만들겠습니다.

Client 화면은 크게 Point to Point Query와 Subsciprtion Query를 조회하는 화면 2개를 분할하였으며, 화면 호출 URL은 다음과 같습니다.

Point to Point : http://localhost:9090/p2p

Subscription : http://localhost:9090/subscription

Subscription 에서는 조회를 누르면 Server와의 Connection이 설정되므로 이를 해제하기 위한 종료 버튼을 추가하였습니다. 조회 버튼을 누르게되면, Server API를 호출합니다. 두 API 주소는 다음과 같습니다.

Point to Point : http://localhost:9090/account/info/{id}

Subscription : http://localhost:9090/account/info/subcription/{id}

이제 본격적으로 기능 구현을 진행하겠습니다.

2. Point to Point Query

Query를 처리하는 Handler가 하나만 존재하고, 한번만 질의만 하면되는 상황이라면 Point to Point Query가 적합합니다.

해당 기능 구현을 통해 사용방법을 알아보겠습니다.

1. Query 모듈 build.gradle 파일을 엽니다.

2. 화면 구현을 위하여 thymeleaf 의존성을 추가합니다.

build.gradle

dependencies{
    (...중략...)
    implementation 'org.springframework.boot:spring-boot-starter-thymeleaf'
}

3. 화면 호출을 위하여 Query 모듈 Controller 패키지에 WebController 클래스를 추가합니다.

4. 클래스 내용을 구현합니다.

WebController.java

@Controller
public class WebController {
    @GetMapping("/p2p")
    public void pointToPointQueryView(){}
}

Controller에서 http://localhost:9090/p2p URL 호출 시 p2p.html 파일을 전달하도록 지정합니다.

5. 화면 구현을 위해서 Query 모듈 resources 패키지 하위에 templates 패키지 및 p2p.html 파일을 생성합니다.

6. html 내용을을 구현합니다.

p2p.html

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>PointToPoint Query Example</title>
</head>
<script>
    window.addEventListener("DOMContentLoaded", function (){
        (function () {
            let appendDiv = document.getElementById("layout");
            let text = document.getElementById("holderInput");
            let pElem = document.createElement("p");
            document.getElementById("wrapper").addEventListener("click", append);

            function append(e) {
                let target = e.target;
                let callbackFunction = callback[target.getAttribute("data-cb")];
                callbackFunction();
            }

            let callback = {
                "search": (function () {
                    let holderId = text.value;
                    if (holderId === undefined || holderId === null || holderId ==="") {
                        alert("소유주를 입력하시오.");
                    } else {
                        let xhr = new XMLHttpRequest();
                        xhr.open('GET','http://localhost:9090/account/info/'+holderId, true);
                        xhr.send();
                        xhr.onload = function(){
                            if(xhr.status === 200){
                                let elem = pElem.cloneNode();
                                elem.innerText = xhr.responseText;
                                appendDiv.appendChild(elem);
                            }
                        }
                    }
                })
            }
        }());
    });
</script>
<body>
<div id="wrapper">
    <input type="button" data-cb="search" value="조회"/>
</div>
<input type="text" id="holderInput" placeholder="소유주 ID를 입력하시오.">
<div id="layout"/>
</body>
</html>

위 코드 내용 중 가장 핵심이 되는 로직은 callback 객체입니다. 구현 내용은 비동기로 Query를 수행하는 API에 소유주 정보를 인자로 요청하면, 해당 내용을 수신받아 화면에 표시합니다.

7. 화면이 정상적으로 출력되는지 확인하기 위하여, Query App을 기동합니다. 이후 웹브라우저(Chrome)을 열고 화면 호출 테스트를 수행합니다.(http://localhost:9090/p2p)

8. 테스트가 완료되었으면, Query를 수행할 API 내용을 구현하겠습니다. 먼저 Query 모듈 service 패키지내 QueryService 인터페이스를 엽니다.

9. Query 수행을 위한 메소드를 정의합니다.

QueryService.java

public interface QueryService {
    void reset();
    HolderAccountSummary getAccountInfo(String holderId);
}

10. Service 구현을 위하여 Query 모듈 service 패키지내 QueryServiceImpl 클래스를 엽니다.

11. Interface에 정의된 메소드를 구현합니다.

QueryServiceImpl.java

@RequiredArgsConstructor
@Slf4j
@Service
public class QueryServiceImpl implements QueryService {
	(...중략...)
    @Override
    public HolderAccountSummary getAccountInfo(String holderId) {
        AccountQuery accountQuery = new AccountQuery(holderId);
        log.debug("handling {}", accountQuery);
        return queryGateway.query(accountQuery, ResponseTypes.instanceOf(HolderAccountSummary.class)).join();
    }

}

12. API End Point 설정을 위해 controller 패키지내 위치한 HolderAccountController 클래스를 엽니다.

13. API End Point를 추가합니다.

HolderAccountController.java

@RestController
@RequiredArgsConstructor
public class HolderAccountController {
    private final QueryService queryService;

	(...중략...)
    @GetMapping("/account/info/{id}")
    public ResponseEntity<HolderAccountSummary> getAccountInfo(@PathVariable(value = "id") @NonNull @NotBlank String holderId){
        return ResponseEntity.ok()
                             .body(queryService.getAccountInfo(holderId));
    }

}

14. QueryGateway로 전달된 Query를 처리하는 Handler 작성을 위해 Query 모듈 projection 패키지 하위 HolderAccountProjection 클래스를 엽니다.

15. HolderAccountProjection 클래스에서 QueryHandler 메소드를 구현합니다.

HolderAccountProjection.java

@Component
@EnableRetry
@AllArgsConstructor
@Slf4j
@ProcessingGroup("accounts")
public class HolderAccountProjection {
    (...중략...)

    @QueryHandler
    public HolderAccountSummary on(AccountQuery query){
        log.debug("handling {}", query);
        return repository.findByHolderId(query.getHolderId()).orElse(null);
    }
}

16. Query App을 기동합니다. 이후 EventStore에 저장된 HolderID 중 하나를 선택하여 입력창에 기입합니다. 조회 버튼을 눌러 정상적으로 조회되는지 확인합니다.

테스트 결과, Read Model에 저장된 데이터가 정상적으로 출력되는 것을 확인할 수 있습니다.

3. Subscription Query

Subscription Query는 Client로부터 Connection을 연결하면, 이를 해제하지 않고 유지합니다. Query를 처리하는 Hanlder App에서는 초기 결과를 최초에 반환합니다. 이때 Flux 타입으로 반환하며, QueryUpdateEmitter를 통해서 Read Model의 변경이 있을 때마다 수신 받습니다.

데모 프로젝트에서는 SSE(Server Sent Event) 방식으로 구현하기 위해 Client 화면에서는 EventSource 객체를 사용하겠습니다.

1. Query 모듈 build.gradle 파일을 엽니다.

2. Flux 사용을 위하여 reactor-core 의존성을 추가합니다.

build.gradle

dependencies{
    (...중략...)
    implementation group: 'io.projectreactor', name: 'reactor-core'
}

3. 화면 호출을 위하여 Query 모듈 Controller 패키지에 WebController 클래스를 추가합니다.

4. 클래스 내용을 구현합니다.

WebController.java

@Controller
public class WebController {
   (...중략...)
    @GetMapping("/subscription")
    public void subscriptionQueryView(){}
}

Controller에서 http://localhost:9090/subscription URL 호출 시 subscription.html 파일을 전달하도록 지정합니다.

5. 화면 구현을 위해서 Query 모듈 resources 패키지 하위에 templates 패키지 및 subscription.html 파일을 생성합니다.

6. html 내용을을 구현합니다.

subscription.html

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Subscription Query Example</title>
</head>
<script>
    window.addEventListener("DOMContentLoaded", function (){
        (function () {
            let appendDiv = document.getElementById("layout");
            let text = document.getElementById("holderInput");
            let eventSource = undefined;
            let pElem = document.createElement("p");
            document.getElementById("wrapper").addEventListener("click", append);

            function append(e) {
                let target = e.target;
                let callbackFunction = callback[target.getAttribute("data-cb")];
                callbackFunction();
            }

            function closeEventSource() {
                eventSource.close();
                eventSource = undefined;
            }

            let callback = {
                "search": (function () {
                    let holderId = text.value;
                    if (eventSource !== undefined) {
                        closeEventSource();
                    }

                    if (holderId === undefined || holderId === null || holderId === "") {
                        alert("소유주를 입력하시오.");
                    } else {
                        eventSource = new EventSource('/account/info/subscription/' + holderId);
                        eventSource.onopen = function () {
                            console.log("connected");
                        };
                        eventSource.onmessage = function (event) {
                            let elem = pElem.cloneNode();
                            elem.innerText = event.data;
                            appendDiv.appendChild(elem);
                        };
                        eventSource.onerror = function () {
                            console.error("Connection error has occurred");
                            closeEventSource();
                        }
                    }
                }),
                "disconnect": (function () {
                    if (eventSource !== undefined) {
                        console.log("disconnected");
                        closeEventSource();
                    }
                })
            }
        }());
    });
</script>
<body>
<div id="wrapper">
    <input type="button" data-cb="search" value="조회"/>
    <input type="button" data-cb="disconnect" value="종료"/>
</div>
<input type="text" id="holderInput" placeholder="소유주 ID를 입력하시오.">
<div id="layout"/>
</body>
</html>

조회 버튼을 누르면, EventSource 객체를 생성하여 Server Sent Event를 수신받으며, 메시지가 전달되면 수신된 데이터를 화면에 출력하도록 구현하였습니다.

7. 화면이 정상적으로 출력되는지 확인하기 위하여, Query App을 기동합니다. 이후 웹브라우저(Chrome)을 열고 화면 호출 테스트를 수행합니다.(http://localhost:9090/usbscription)

8. 테스트가 완료되었으면, Query를 수행할 API 내용을 구현하겠습니다. 먼저 Query 모듈 service 패키지내 QueryService 인터페이스를 엽니다.

9. Query 수행을 위한 메소드를 정의합니다.

QueryService.java

public interface QueryService {
    (...중략...)
    Flux<HolderAccountSummary> getAccountInfoSubscription(String holderId);
}

10. Service 구현을 위하여 Query 모듈 service 패키지내 QueryServiceImpl 클래스를 엽니다.

11. Interface에 정의된 메소드를 구현합니다.

QueryServiceImpl.java

@RequiredArgsConstructor
@Slf4j
@Service
public class QueryServiceImpl implements QueryService {
    (...중략...)
    @Override
    public Flux<HolderAccountSummary> getAccountInfoSubscription(String holderId) {
        AccountQuery accountQuery = new AccountQuery(holderId);
        log.debug("handling {}", accountQuery);

        SubscriptionQueryResult<HolderAccountSummary, HolderAccountSummary> queryResult = queryGateway.subscriptionQuery(accountQuery,
                ResponseTypes.instanceOf(HolderAccountSummary.class),
                ResponseTypes.instanceOf(HolderAccountSummary.class)
        );

        return Flux.create(emitter -> {
            queryResult.initialResult().subscribe(emitter::next);
            queryResult.updates()
                    .doOnNext(holder -> {
                        log.debug("doOnNext : {}, isCanceled {}", holder, emitter.isCancelled());
                        if (emitter.isCancelled()) {
                            queryResult.close();
                        }
                    })
                    .doOnComplete(emitter::complete)
                    .subscribe(emitter::next);
        });
    }
}

위 코드 구현 내용은 최초에 initalResult 생성 후에, 지속적으로 updates 메소드를 통해 Stream 데이터를 전달받아 Client에게 전달합니다. 만약 중간에 Connection이 실패하게되면, 해당 Flux를 종료하도록 구현하였습니다.

12. API End Point 설정을 위해 controller 패키지내 위치한 HolderAccountController 클래스를 엽니다.

13. EndPoint를 추가합니다.

HolderAccountController.java

@RestController
@RequiredArgsConstructor
public class HolderAccountController {
    (...중략...)

    @GetMapping("account/info/subscription/{id}")
    public ResponseEntity<Flux<HolderAccountSummary>> getAccountInfoSubscription(@PathVariable(value = "id") @NonNull @NotBlank String holderId){
        return ResponseEntity.ok()
                             .body(queryService.getAccountInfoSubscription(holderId));
    }
}

14. Subscription에서는 Read Model에 변경이 발생되었을 때 이를 전파해야합니다. 따라서 이를 작성하기 위해 Query 모듈 projection 패키지 하위 HolderAccountProjection 클래스를 엽니다.

15. EventSourcingHandler를 통해 ReadModel의 변화가 발생하였을 때, QueryUpdateEmitter 클래스를 통해 이벤트 변경 내용을 전파하도록 클래스 내용을 수정합니다.

HolderAccountProjection.java

@Component
@EnableRetry
@AllArgsConstructor
@Slf4j
@ProcessingGroup("accounts")
public class HolderAccountProjection {
    private final AccountRepository repository;
    private final QueryUpdateEmitter queryUpdateEmitter;

    (...중략...)

    @EventHandler
    @AllowReplay
    protected void on(DepositMoneyEvent event, @Timestamp Instant instant){
        log.debug("projecting {} , timestamp : {}", event, instant.toString());
        HolderAccountSummary holderAccount = getHolderAccountSummary(event.getHolderID());
        holderAccount.setTotalBalance(holderAccount.getTotalBalance() + event.getAmount());

        queryUpdateEmitter.emit(AccountQuery.class,
                query -> query.getHolderId().equals(event.getHolderID()),
                holderAccount);

        repository.save(holderAccount);
    }
    @EventHandler
    @AllowReplay
    protected void on(WithdrawMoneyEvent event, @Timestamp Instant instant){
        log.debug("projecting {} , timestamp : {}", event, instant.toString());
        HolderAccountSummary holderAccount = getHolderAccountSummary(event.getHolderID());
        holderAccount.setTotalBalance(holderAccount.getTotalBalance() - event.getAmount());

        queryUpdateEmitter.emit(AccountQuery.class,
                query -> query.getHolderId().equals(event.getHolderID()),
                holderAccount);

        repository.save(holderAccount);
    }

	(...중략...)
}

각 Handler안에 queryUpdateEmitter를 통해 구독중인 Query와 동일한 ID의 Event가 들어오면, Query 결과에 전달되도록 처리하였습니다.

위 예제에서 holderId가 924eb0ab-c35f-4d3e-b753-a4ce35bd7c27인 계좌 전체의 잔고는 현재 290입니다. Update가 정상 수신되는지 확인하기 위하여, 해당 소유주가 보유한 계좌에서 5원을 인출하는 API를 호출합니다.

17. 5원 인출 후 Client 화면에서 변경된 데이터가 정상 수신되었는지 확인합니다.

확인 결과, 정상적으로 데이터 수신되었음을 확인할 수 있습니다.

18. 종료 버튼을 눌러 구독을 중지합니다. 이후 924eb0ab-c35f-4d3e-b753-a4ce35bd7c27 소유주가 보유한 계좌에서 추가로 5원 인출하였을 때, Query 결과가 화면에 표시되지 않음을 확인합니다. 화면의 변화가 없으면, 정상적으로 Connection이 종료된 것입니다.

4. 마치며

이번 시간에는 Point to Point, Subscription Query에 대해서 살펴보았습니다. Subscription Query는 반환 형태가 Flux 형태다보니 아무래도 Spring MVC에서는 사용하기 힘든 부분이 있을듯 합니다. 또한, 이를 지원하기 위해서는 Client에서도 SSE를 위한 구현이 필요하며, Server에서는 Client와 Connection 유지를 위해 Subscription Query가 증가할 수록 그에 상응하는 Thread 수가 증가합니다. 따라서 비즈니스 요건에 맞게 적절한 사용이 필요하며, Spring Webflux를 사용한다면 도입을 검토해볼 수 있을 것 같습니다.

15. Query 어플리케이션 구현(Query) - 1

cla9 — Tue, 14 Jan 2020 20:51:25 +0900

1. 서론

이번 포스팅부터 생성된 Read Model에 대하여 Query하는 방법에 대하여 소개하겠습니다. AxonServer를 통해서 수많은 MicroService App들이 연결되어 있을 수 있습니다. 이러한 환경에서 Query 요청을 했을때, 단순 1:1 요청 응답을 요구할 수 도 있고 때로는 Query 요청에 따라 2개 이상의 다른 App에서 데이터를 수신받는 경우도 있습니다. 따라서 각기 다른 경우에 따라 처리해야하는 방법이 다릅니다.

Axon Framework는 총 3가지 타입의 Query 기능을 제공합니다. 이번 포스팅에서는 Axon 에서 제공하는 Query 종류와 동작 원리를 알아보겠습니다.

2. Axon Server 라우팅 기능(Query)

Command 명령을 요청할 때는 CommandBus를 이용하였고, Event 발생시에는 EventBus를 이용하였습니다. 마찬가지로 Query는 QueryGateway를 통해 요청을 전달하며, 전달된 Query는 QueryBus를 통해서 해당 Query를 처리하는 Handler로 연결됩니다. 이때 QueryHandler가 속한 App에 Query를 전달하는 역할을 Axon Server가 수행합니다. Query 관련 Axon Server의 라우팅 기능 동작 흐름을 살펴보겠습니다.

1. Point to Point Query

Command Handler와 마찬가지로 Application 기동시 AxonServer와 연결을 시도합니다. 연결이 완료되면, 해당 App은 자신이 처리가능한 Query Handler 정보를 Server에 등록합니다. Point to Point Query는 해당 Query를 처리하는 Handler가 단 하나의 Application에만 존재할 경우 해당 처리할 수 있는 App으로 Query를 전달하여 결과를 전달합니다.

2. Scatter & Gatter Query

두번째는 Scatter-Gather Query입니다. 이는 동일한 Query를 처리하는 Handler가 여러 App에 등록되어있을 때, 이를 처리하는 방법입니다. Application 기동시 Query Handler 정보를 Axon Server에 등록하면, Application 정보가 라우팅 테이블에 해당 App 정보를 기록합니다. 이때는 Client 측에서 각기 다른 App에서 수신되는 결과를 수집하여 처리 방법(한쪽 결과만 수집, 둘다 수집 등)을 정해야합니다. Axon Server는 Query 요청이 들어오면 등록된 Application에게 Query를 전달하며, 수신받은 App에서는 결과를 취합하여 전송합니다. 이후 Client 측에서 결과를 수신받아 데이터 결과를 종합합니다.

3. Subscription Query

Point to Point Query를 요청하였을 때, 만약 Query를 수행하는 Read Model에 대한 변경이 발생한다면, 화면에 출력되는 결과와 Read Model 사이 데이터 정합성 불일치 문제가 발생합니다. 따라서 이를 해결하기 위해서는 주기적으로 Query를 재요청하는 방법이 있습니다. 하지만 데이터 변경이 발생하지 않아도 계속 Query를 요청해야하는 문제점이 있으므로 효율적이지 못합니다.

Subscription Query는 Client측에서 Query를 요청할 때, Query 결과를 전달받고 Connection을 끊는 것이 아니라 계속 지속합니다. 이후 Query Handler가 위치한 App의 Read Model 변경이 발생할 경우 변경분에 대한 데이터를 전달받아 이를 최신화합니다.

3. Query Handler 동작 과정

AxonFramework 관련 Bean 생성시 사용자가 지정한 QueryBus가 없으면, Default로 AxonServerQueryBus가 생성됩니다. 이때 내부적으로 QueryProcessor가 만들어지고, 해당 생성자 안에서 ExecuterService를 통해 요청시 최대 10개의 Thread를 Default로 생성하도록 Handler에 등록합니다.

ExecuterService에 의해서 만들어지는 Thread는 QueryProcessingTask이며, AxonServer로부터 Query를 전달받으면 해당 클래스의 run 메소드를 통해 QueryHandler 작업이 이어집니다.

Application 구동 이후, Query 요청이 발생되면, 내부적으로는 위와 같은 흐름을 거쳐 메시지가 전달됩니다.

QueryGateway로 Query를 전달합니다. 이때 전달하는 Query가 Scatter-Gather, Subsciprtion, Point to Point 중 하나임을 메소드를 통해 AxonServer에게 전달합니다.
사용자가 전달한 Query를 GenericQueryMessage로 변환한다음 QueryBus로 전달합니다. Default QueryBus는 AxonServerQueryBus이므로 AxonServer에 전달됩니다.
전달된 Query는 QueryHandler가 존재하는 App으로 라우팅됩니다. 이때 AxonServer로부터 gRPC를 통해 onMessage 메소드가 호출되면, AxonServerQueryBus 내부에 할당된 Handler들의 onNext 메소드를 호출합니다.
Bean 등록 당시 Handler 호출시 ExecutorService로부터 QueryProcessingTask 생성을 요청하였습니다. 따라서 Handler 호출과정에서 Thread 생성을 요청합니다.
QueryProcessingTask 내부에 있는 run 메소드가 수행되면서 QueryProcessor에게 Query 수행을 위임합니다.
QueryProcessor 내부 로직 수행중 Query 수행을 SimpleQueryBus에게 위임합니다.
내부적으로 UnitOfWork 과정을 거치면서, Reflection을 통해 QueryHandler 메소드를 찾아 수행후 결과를 돌려 받습니다.
최종 수행된 결과를 QueryProviderOutbound에게 전달합니다.
AxonServer에게 결과를 전달합니다.
Query를 요청한 Client에게 결과를 전달합니다.

4. 마치며

Query App 구현을 위해 기본적으로 알아야하는 내부 과정에 대해서 살펴봤습니다. 다음 포스팅에서는 코드 구현을 진행하겠습니다.

14. Query 어플리케이션 구현(Event) - 4

cla9 — Sat, 11 Jan 2020 22:14:00 +0900

1. 서론

Software 개발 및 유지보수 단계에서 요구사항에 의하여 데이터 모델은 변하기 마련입니다. 그리고 바뀌는 데이터모델에 맞춰 Event 또한 형태가 변합니다. 이때, 이전 발행된 Event와 앞으로 적재되는 Event의 형태는 다르게 됩니다. 따라서 Replay 과정에서 변경된 Event를 적용하는데 있어 문제가 발생되지 않도록 코드를 통한 중재가 필요합니다. Axon 에서는 이를 위해 Event Upcasting 기능을 제공합니다. 이번 포스팅에서는 코드를 통하여 Event Upcasting을 적용하는 방법을 알아보겠습니다.

2. Versioning

Application 개발 후 요구사항 변경으로 계정 가입시에 회사명 정보가 추가되며, Read Model MView(Materialized View)에도 회사명 정보가 포함되고, 회사명이 기입되지 않으면 N/A로 표시된다고 가정하겠습니다.

요구사항 변경 내용을 코드로 구현하면 다음과 같습니다.

1. Command 수정을 위해서 API 변경이 필요합니다. Command 모듈내 dto 패키지에 위치한 HolderDTO 파일을 엽니다.

2. DTO 클래스에 company 정보를 추가합니다.

HolderDTO.java

@Getter
@AllArgsConstructor
@NoArgsConstructor
public class HolderDTO {
    private String holderName;
    private String tel;
    private String address;
    private String company;
}

3. Common 모듈 commands 패키지내 HolderCreationCommand 파일을 엽니다.

4. Command 클래스에 company 정보를 추가합니다.

HolderCreationCommand.java

@AllArgsConstructor
@ToString
@Getter
public class HolderCreationCommand {
    @TargetAggregateIdentifier
    private String holderID;
    private String holderName;
    private String tel;
    private String address;
    private String company;
}

5. Command 모듈 service 패키지에 위치한 TransactionServiceImpl 파일을 엽니다.

6. Service 클래스에서 계정 생성 로직에 Company 정보를 넘기도록 수정합니다.

TransactionServiceImpl.java

@Service
@RequiredArgsConstructor
public class TransactionServiceImpl implements TransactionService {
	(...중략...)
    @Override
    public CompletableFuture<String> createHolder(HolderDTO holderDTO) {
        return commandGateway.send(new HolderCreationCommand(UUID.randomUUID().toString()
                , holderDTO.getHolderName()
                , holderDTO.getTel()
                , holderDTO.getAddress()
                , holderDTO.getCompany())
                );
    }
    (...중략...)
}

7. Common 모듈의 build.gradle 파일을 엽니다.

8. build.gradle 파일에 axon-messaging 의존성을 추가합니다.

build.gradle

ext{
    axonVersion = "4.2.1"
}
bootJar { 
    enabled = false 
}
jar {
    enabled = true
}
dependencies{
    compileOnly 'org.projectlombok:lombok'
    annotationProcessor 'org.projectlombok:lombok'
    implementation group: 'org.axonframework', name: 'axon-messaging', version: "$axonVersion"
}

9. Common 모듈 events 패키지 내 HolderCreationEvent 파일을 엽니다.

10. Event에 변경된 사항을 추가합니다. 이때 Event에는 변경이 발생하므로, Event의 변경이 발생했음을 알리는 마커가 필요합니다. 이때 사용되는 어노테이션이 @Revision입니다. Revision 표시를 통해서 실제 Event가 발생되었을 때 EventStore에는 해당 Event의 버전이 저장되며, 추후 Event Upcasting 시에 해당 정보가 사용됩니다.

HolderCreationEvent.java

@AllArgsConstructor
@ToString
@Getter
@Revision("1.0")
public class HolderCreationEvent {
    private String holderID;
    private String holderName;
    private String tel;
    private String address;
    private String company;
}

11. Command 모듈 aggregate 패키지내에 위치한 HolderAggregate 파일을 엽니다.

12. Aggregate 클래스 Event 발행 로직에 company 정보를 전달할 수 있도록 변경합니다.

HolderAggregate.java

@AllArgsConstructor
@NoArgsConstructor
@Aggregate
@Slf4j
public class HolderAggregate {
	(...중략...)
    @CommandHandler
    public HolderAggregate(HolderCreationCommand command) {
        log.debug("handling {}", command);

        apply(new HolderCreationEvent(command.getHolderID(), command.getHolderName(), command.getTel(), command.getAddress(), command.getCompany()));
    }
    (...중략...)
}

13. Query 모듈에 version 패키지를 생성한 다음 HolderCreationEventV1 클래스를 만듭니다. 해당 클래스는 변경 이전HolderCreationEvent에 대해서 변경 후에 어떻게 추가된 정보를 처리를 지정 용도로 사용됩니다.

14. HolderCreationEventV1 클래스 내용을 구현합니다.

HolderCreationEventV1.java

public class HolderCreationEventV1 extends SingleEventUpcaster {
    private static SimpleSerializedType targetType = new SimpleSerializedType(HolderCreationEvent.class.getTypeName(), null);

    @Override
    protected boolean canUpcast(IntermediateEventRepresentation intermediateRepresentation) {
        return intermediateRepresentation.getType().equals(targetType);
    }

    @Override
    protected IntermediateEventRepresentation doUpcast(IntermediateEventRepresentation intermediateRepresentation) {
        return intermediateRepresentation.upcastPayload(
                new SimpleSerializedType(targetType.getName(), "1.0"),
                org.dom4j.Document.class,
                document -> {
                    document.getRootElement()
                            .addElement("company")
                            .setText("N/A");
                    return document;
                }
        );
    }

코드 구현내역은 다음과 같습니다. 먼저 targetType에는 대상 Event를 지정합니다. 데모 프로젝트에서는 HolderCreationEvent가 변경되었으므로 해당 Class 타입을 지정합니다. 두번째 인자에 위치한 null 값은 최초에는 @Revision 정보를 명시하지 않았으므로 존재하는 값이 없기 때문에 null로 지정하였습니다.

doUpcast 메소드는 실제 Event Version을 확인하고 이전 버전의 Event가 들어왔을 때 행동해야할 내용을 기술합니다.

EventStore에 저장된 Event 내용이 XML로 지정되므로, XML로 되어있는 Payload 에서 신규 추가된 company 정보와 값이 없을 경우 입력될 Default 값 N/A를 setText 메소드를 통해 지정합니다. 또한 해당 작업을 수행할 대상을 Revision 정보가 null인 targetType으로 한정합니다. 따라서 해당 메소드를 통해서 확인할 수 있는 사실은 HolderCreationEvent에 수많은 Revision 정보가 존재하더라도, HolderEventCreationEventV1 클래스에서는 Revision 번호가 1.0과 null인 두 Event간의 속성값에만 영향을 미칩니다.

15. Query 모듈내 config 패키지에 존재하는 AxonConfig 파일을 엽니다.

14. AxonConfig 파일에 Event Chain을 등록합니다.

AxonConfig.java

@Configuration
public class AxonConfig {
	(...중략...)

    @Bean
    public EventUpcasterChain eventUpcasterChain(){
        return new EventUpcasterChain(
                new HolderCreationEventV1()
        );
    }
}

만약 Event의 버전이 여러개 생성되었다면, HolderCreationEventV1이외 여러개의 버전간 핸들러 클래스를 생성한 다음 Event Chain 생성 로직에 핸들러 인스턴스를 등록합니다.

15. 새로운 계정 등록 테스트를 진행한다음 Query Application을 Replay 시킵니다.

POST http://localhost:8080/holder
Content-Type: application/json

{
	"holderName" : "Kane",
	"tel" : "02-2645-5678",
	"address" : "OO시 OO구",
    "company" : "Korea"
}

c.c.q.p.HolderAccountProjection          : projecting HolderCreationEvent(holderID=0df539ed-2ee2-41be-af32-0f6724a75da3, holderName=kevin, tel=02-1234-5678, address=OO시 OO구, company=N/A) , timestamp : 2020-01-07T12:11:21.047Z
c.c.q.p.HolderAccountProjection          : projecting HolderCreationEvent(holderID=a5d267c6-fbd8-4f0d-b93b-03a8dbf09747, holderName=bruce, tel=02-5291-5678, address=OO시 OO구, company=N/A) , timestamp : 2020-01-07T12:12:14.238Z
c.c.q.p.HolderAccountProjection          : projecting HolderCreationEvent(holderID=1b77f5bc-73e6-4b7a-a1fd-d5453723b9c7, holderName=Kane, tel=02-2645-5678, address=OO시 OO구, company=Korea) , timestamp : 2020-01-11T13:00:10.487Z

위 내용은 Replay 이후 Application 로그 일부를 발췌한 내용입니다. 신규 생성한 Kane 사용자의 company는 입력값으로 정확히 등록이 되었으며, 기존에 발행된 Event는 N/A로 매핑된 것을 확인할 수 있습니다.

3. 마치며

이번 포스팅을 끝으로 Query Application에서 Event 처리와 관련된 내용을 마무리하겠습니다. 다음 포스팅에서는 Query Application에 저장된 Read Model을 기반으로 Query하는 방법에 대해서 다루도록 하겠습니다.

13. Query 어플리케이션 구현(Event) - 3

cla9 — Thu, 9 Jan 2020 00:22:52 +0900

1. 서론

이전 포스팅에서 Replay에 대해서 학습했습니다. Replay는 신규 Read Model이 추가되거나 기존 모델의 변경이 있을 때, EventStore에서 기존 내역을 전달받아 재수행하는 작업입니다. 따라서 EventSourcing & CQRS 모델을 사용한다면, Replay 성능 고민이 반드시 필요합니다. 이번 포스팅에서는 AxonIQ 블로그를 기반으로 Replay 성능 개선 방법에 대해서 소개하겠습니다.

본문 설명에 앞서 AxonIQ 벤치마크 테스트 환경 Spec은 다음과 같습니다.

DBMS : Postgres(9.6), MongoDB(3.6)
CPU : vCPU 8코어 (GCP)
RAM : 30G
OS : Ubuntu 18.10
DISK : SSD 1T

2. Replay 문제점

만약 EventStore에 저장된 Event 수가 10억개이고, Read Model에서 Replay 수행 시 초당 1000개의 Event를 재생할 수 있다고 가정한다면, Replay 작업에만 약 11일이 걸립니다. 이는 대부분의 상황에서는 적용하기 힘듭니다. 따라서 Replay 작업 최적화가 반드시 필요합니다.

앞선 포스팅에서 TrackingEventProcessor에 의하여 @EventHandler 메소드가 호출된다고 설명했습니다. 이때 별도 속성을 지정하지 않으면, TrackingEventProcessor는 Default 값으로 설정되며 기본값은 다음과 같습니다.

Thread 수 : 1개
Batch Size : 1
최대 Thread 수 : Segment 개수
TokenClaim 주기 : 5000ms

이를 통해 알 수 있는 사실은 Axon에서 Event 처리는 Batch 단위로 이루어지는데, 기본 설정 값은 Event 1개씩 단일 Thread로 처리됨을 확인할 수 있습니다.

AxonIQ에서 TrackingEventProcessor에 대한 기본값 설정으로 Event 처리에 대한 벤치마크 수행 결과, 초당 260개의 Event를 처리하였습니다. 이는 100만개 Event 기준 10시간의 처리 능력을 보여주어 좋지 않은 처리 능력을 나타냈습니다. 지금부터 Event 처리 능력을 강화하는 방법에 대해서 하나씩 살펴보겠습니다.

3. Replay 개선 전략

3-1. Batch Size 조정

이전 설명에서 Axon Framework에서 Event를 Batch 단위로 처리한다고 했습니다. Batch 작업 시, 개별적인 Event를 다루는 것 외에 부가적인 기능은 다음과 같습니다.

Tracking Token을 갱신하여 최신의 Event Stream 위치를 기억하도록 함.
Transactional Store를 사용했을 때 DB의 Transaction Commit 작업 수행.

사용자의 별도 설정이 없다면, 기본 Batch Size는 1입니다. 이는 Replay 작업을 수행하기에는 너무 적은 수치입니다. 따라서 적절한 PoC를 통해 최적의 Size를 맞추어야 합니다. Axon에서는 TrackingEventProcessorConfiguration을 통해서 Size 조정이 가능합니다. 설정 방법은 다음과 같습니다.

1. Query 모듈내 config 패키지 생성 후 AxonConfig 파일을 생성합니다.

2. AxonConfig 클래스를 구현합니다.

AxonConfig.java

@Configuration
public class AxonConfig {
    @Autowired
    public void configure(EventProcessingConfigurer configurer) {
        configurer.registerTrackingEventProcessor(
                "accounts",
                org.axonframework.config.Configuration::eventStore,
                c -> TrackingEventProcessorConfiguration.forSingleThreadedProcessing()
                        .andBatchSize(100)
        );
    }
}

코드 구현 내용은 accounts ProcessingGroup을 처리하는 TrackingEventProcessor의 Batch Size를 100으로 설정하였습니다.

출처 : https://axoniq.io/blog-overview/cqrs-replay-performance-tuning

위 그림은 Batch Size 조정에 따른 초당 Event 처리량을 그래프로 표시한 결과입니다. Size를 1부터 500까지 늘렸을 때 초당 260개의 이벤트 처리량에서 4000개로 15배의 성능 개선이 나타났습니다. 대략 500개 이상부터는 Size 증가에 따른 개선폭이 크지 않으므로 해당 예제에서는 500개가 적정선입니다. Batch Size 크기에 대한 적절한 가이드는 없으며, 이는 각 Application 환경에 맞게 테스트 이후 찾는 것이 좋습니다.

Batch Size를 늘려서 Transaction을 처리할 때 주의점이 있습니다. 이는 Read Model에 사용되는 DB가 Non-Transactional 하다면, 만약 Batch 중간에 실패했을 때 데이터가 자동 Rollback되지 않습니다. 따라서 이후 다시 Replay를 시도하게되면, 이미 처리된 Event가 다시 수행되므로 유의해야합니다.

3-2. 병렬 처리

출처 : https://axoniq.io/blog-overview/cqrs-replay-performance-tuning

TrackingEventProcessor의 Thread 수 기본 값은 1입니다. 즉 하나의 Thread로 모든 작업을 순차처리합니다. 따라서 Event Replay 성능을 높이기 위해서는 병렬도 증가가 필요합니다.

위 그림은 Batch Size는 500으로 설정한 상태에서 Thread 개수를 1에서 8개로 점차 늘렸을 때 초당 Event 처리량을 나타낸 것입니다. 병렬도를 8로 지정했을 때 초당 15000개의 Event를 처리할 수 있으므로 단일 Thread 대비 대략 4배정도의 개선이 이루어졌습니다.

하지만 Thread 개수를 늘릴 때는 고려해야할 사항이 많습니다. 그 이유는 병렬로 처리하게되면 처리되는 Event의 순서가 뒤바뀔 수 있기 때문입니다. 따라서 병렬 처리를 수행시, 순서가 보장될 수 있도록 처리해야합니다. Axon에서는 이러한 문제를 해결 하기 위해 Sequencing 정책을 제공합니다. Sequencing 정책이란 동일 Thread 내에서 Event는 반드시 처리 순서 보장에 대한 결정을 의미합니다.

기본적으로 Axon에서는 동일 Aggregate에 속한 Event는 동일 Thread에서 처리될 수 있도록 SequentialPerAggregatePolicy 클래스를 제공합니다. 이를 적용하여 AxonConfig 클래스 수정을 통해 병렬도를 변경하도록 하겠습니다.

AxonConfig.java

@Configuration
public class AxonConfig {
    @Autowired
    public void configure(EventProcessingConfigurer configurer) {
        configurer.registerTrackingEventProcessor(
                "accounts",
                org.axonframework.config.Configuration::eventStore,
                c -> TrackingEventProcessorConfiguration.forParallelProcessing(3)
                        .andBatchSize(100)
        );

        configurer.registerSequencingPolicy("accounts",
                configuration -> SequentialPerAggregatePolicy.instance());
    }
}

이전 대비 변경된 내용은 TrackingEventProcessor에 대해서 병렬도를 3으로 지정하였습니다. 또한 accounts ProcessingGroup을 대상으로 SequentialPerAggregatePolicy를 적용하여, 단일 Thread 내에서 동일 Aggregate Event가 순서대로 처리되도록 정책 설정하였습니다.

코드 변경 후 실제 Application을 구동한다음 Token Store에 TrackingEventProcessor 별로 Token이 생긴 것을 확인할 수 있습니다.

하지만 데모 프로젝트에서 단순히 위와같이 병렬도를 지정하고 Application을 수행하면, 소유주가 존재하지 않습니다 Error가 발생할 수도 있습니다. 이유는 아래와 같습니다.

데모 프로젝트 Aggregate 종류

Command App에서 구현된 Aggregate는 Holder와 Account 두개 입니다. 비즈니스 로직상 Account Aggregate는 반드시 Holder Aggregate가 존재해야지만 생성이 가능하며, Event Stream에도 순차적으로 생성되어 있습니다. 하지만 Read Model을 반영하는 과정에서 Thread를 분리시키면, 근본적으로 두 개의 Aggregate는 다릅니다. 따라서 SequentialPerAggregatePolicy 설정했어도 다른 Thread에 생성되어 처리될 가능성이 높습니다.

HolderAccountProjection.java

@Component
@EnableRetry
@AllArgsConstructor
@Slf4j
@ProcessingGroup("accounts")
public class HolderAccountProjection {
	(...중략...)
	private HolderAccountSummary getHolderAccountSummary(String holderID) {
        log.debug("getHolder : {} ",holderID);
        return repository.findByHolderId(holderID)
                .orElseThrow(() -> new NoSuchElementException("소유주가 존재하지 않습니다." + holderID));
    }
}

위 코드는 Account 생성 Event를 처리하기 위해 Repository 에서 Holder를 찾는 로직을 일부 발췌하였습니다. 이때 두 Aggregate가 다르므로 Account 생성 시점 Thread 1번에서 수행중인 Holder Aggregate가 DB에 반영되어있지 않을 수 있습니다. 그 결과 NoSuchElementException이 발생할 수 있습니다.

Replay를 수행할 때 의도적으로 @DisallowReplay 어노테이션을 추가하지 않는 이상 EventHandler에서 Event 누락이 발생되어서는 안됩니다. 따라서 문제점 해결을 위해 데모 프로젝트에서는 저장소 검색 과정에서 위와 같은 에러를 만나게 되었을 때 약간의 시차를 두고 다시 시도하게끔 지정하고자 합니다. 이를 위해 spring-retry 기능을 사용하도록 하겠습니다.

1. Query 모듈 build.gradle 파일을 열어 dependencies를 추가합니다.

build.gradle

dependencies{
 (...중략...)
 implementation group: 'org.springframework.retry', name: 'spring-retry'
}

2. projection 패키지 HolderAccountProjection 클래스 파일을 엽니다.

3. HolderAccountProjection 클래스 상단에 @EnableRetry 어노테이션을 추가합니다.

HolderAccountProjection.java

@Component
@EnableRetry
@AllArgsConstructor
@Slf4j
@ProcessingGroup("accounts")
public class HolderAccountProjection {
	(...중략...)
}

4. Account 생성 이벤트를 처리하는 Event Handler 메소드에 @Retryable 어노테이션을 추가합니다.

HolderAccountProjection.java

@Component
@EnableRetry
@AllArgsConstructor
@Slf4j
@ProcessingGroup("accounts")
public class HolderAccountProjection {
	(...중략...)
    
    @EventHandler
    @Retryable(value = {NoSuchElementException.class}, maxAttempts = 5, backoff = @Backoff(delay = 1000))
    @AllowReplay
    protected void on(AccountCreationEvent event, @Timestamp Instant instant)  {
        log.debug("projecting {} , timestamp : {}", event, instant.toString());
        HolderAccountSummary holderAccount = getHolderAccountSummary(event.getHolderID());
        holderAccount.setAccountCnt(holderAccount.getAccountCnt()+1);
        repository.save(holderAccount);
    }
    
    (...중략...)
}

위 코드의 내용은 Repository로부터 NoSuchElementException이 발생하면 1초 대기후에 다시 시도하며, 최대 5번까지 재수행을 시도하도록 설정하였습니다.

위 4단계를 거친 다음 Query App을 기동하여 Reset을 수행하면, 발생하였던 문제가 정상적으로 수행됨을 확인할 수 있습니다.

3-3. Batch 최적화

Read Model 구현에 있어 JPA를 사용한다면 Batch Update를 수행할 때 자동으로 최적화를 수행합니다. 가령 동일한 Record에 대하여 Update가 연속 두번 발생하면, 실제로는 Entitiy 로딩하기 위한 1번의 DBMS Call과 JPA 내부 Persistence Context에서 2번의 수정 작업을 거쳐 최종 1번의 Update DBMS Call이 발생합니다.

또한 다량의 Insert 작업이 중간에 Update 작업 없이 발생한다면, DBMS에 Insert를 반영할 때 SQL 단건씩 DBMS Call을 발생시키는 것이 아니라 Bulk Insert를 수행하여 최적화를 달성합니다.

하지만 JPA를 통한 Model 이외에도 적용할 수 있는 최적화 방법은 여러가지가 있습니다. 그 중 2가지 방법을 소개하겠습니다.

Entitiy에 대해서 Update를 수행하기 위해서는 기본적으로 데이터를 Persistence Context에 Load 이후에 변경을 실시하는데, Replay 과정에서는 굳이 데이터를 Load할 필요없이 바로 Update 구문을 수행함으로써 DBMS Call을 줄일 수 있습니다.
동일 Aggregate에 대해서 발생하는 Insert, Update, delete Event 순서를 결과에 어긋나지 않게 재배치하여 Bulk 작업을 수행한다면, 획기적으로 DBMS Call을 줄일 수 있습니다.

방금 소개시켜드린 2가지 방법은 단순히 Configuration 설정 변경으로는 적용할 수 없습니다. 따라서 이를 해결 하기위해서는 DBMS 최적화에 대한 기술적인 고민과 이를 적용하는 내용을 프로그래밍해야 합니다. Axon 에서는 이를 보조하기 위하여 다양한 API를 제공합니다. 또한 각각의 Batch 마다 하나씩 UnitOfWork가 존재합니다. 따라서 EventHandler 메소드 파라미터에 UnitOfWork 인자를 추가하면 UnitOfWork에서 처리되는 자원에 접근할 수 있습니다. 이를 통해 메시징 처리를 사용자가 효율적으로 Customizing 처리할 수 있도록 도움을 줍니다.

위 소개드린 2가지 기법들을 활용하여 Axon 에서 벤치마크 테스트한 결과, 기존 초당 15000개의 처리량에서 30000개로 2배의 성능 향상을 이룰 수 있었습니다. 이는 최초대비 115배의 성능 개선을 달성한 것입니다.

4. Mongo DB 테스트 결과

Read Model을 Mongo DB를 사용햇을 때 이전 Replay 최적화 방식을 도입함에 있어 AxonIQ 벤치마크 테스트 결과는 다음과 같습니다.

최적화 없음 : 초당 12000개
Batch 최적화 : 초당 30000개

AxonIQ 벤치마크 결과 Postgresql과 크게 다르지 않은 처리량을 볼 수 있습니다.

5. 마치며

이번 시간에는 Replay 성능 개선에 대하여 다루었습니다. 개인적으로 EventSourcing & CQRS를 도입하는데 있어 기술적으로 가장 고민을 많이해야하는 부분이 이번 포스팅 내용인 것 같습니다. Replay 수행에 있어 Application 개선 뿐만 아니라 DBMS 최적화 기법을 같이 고려한다면 더 큰 성능개선이 이루어질 수 있으므로 Read Model DB에 대한 지식은 큰 도움이 될 것입니다. 다음 시간에는 요구사항 변경에 따른 Event 모델 수정 및 Versioning에 대하여 다루겠습니다.

12. Query 어플리케이션 구현(Event) - 2

cla9 — Tue, 7 Jan 2020 22:13:25 +0900

1. 서론

이번 시간에는 Query App의 EventHandler 로직을 구현하도록 하겠습니다. Query App의 Read Model은 이전 포스팅에서 도출한 구조를 사용하도록 하겠습니다.

2. Projection 구현

Command에서 발생된 Event를 적용하는 과정을 Projection이라 합니다. 먼저 설계 단계에서 도출한 Entity 구현 이후 Projection을 구현하겠습니다.

1. Query 모듈내 entity 패키지를 생성후 Entity 클래스를 생성합니다.

2. Entity 클래스를 구현합니다.

HolderAccountSummary.java

@Entity
@Table(name = "MV_ACCOUNT")
@NoArgsConstructor
@AllArgsConstructor
@Builder
@Getter @Setter
public class HolderAccountSummary {
    @Id
    @Column(name = "holder_id", nullable = false)
    private String holderId;
    @Column(nullable = false)
    private String name;
    @Column(nullable = false)
    private String tel;
    @Column(nullable = false)
    private String address;
    @Column(name = "total_balance", nullable = false)
    private Long totalBalance;
    @Column(name = "account_cnt", nullable = false)
    private Long accountCnt;
}

3. repository 패키지를 생성 후 entitiy repository 인터페이스를 생성합니다.

4. repository 인터페이스 메소드를 정의합니다.

AccountRepository.java

public interface AccountRepository extends JpaRepository<HolderAccountSummary,String> {
    Optional<HolderAccountSummary> findByHolderId(String holderId);
}

5. projection 패키지 생성 후 projection 클래스를 생성합니다.

6. Projection 클래스를 구현합니다.

HolderAccountProjection.java

@Component
@AllArgsConstructor
@Slf4j
public class HolderAccountProjection {
    private final AccountRepository repository;

    @EventHandler
    protected void on(HolderCreationEvent event, @Timestamp Instant instant) {
        log.debug("projecting {} , timestamp : {}", event, instant.toString());
        HolderAccountSummary accountSummary = HolderAccountSummary.builder()
                                                                        .holderId(event.getHolderID())
                                                                        .name(event.getHolderName())
                                                                        .address(event.getAddress())
                                                                        .tel(event.getTel())
                                                                        .totalBalance(0L)
                                                                        .accountCnt(0L)
                                                                    .build();
        repository.save(accountSummary);
    }
    
    @EventHandler
    protected void on(AccountCreationEvent event, @Timestamp Instant instant){
        log.debug("projecting {} , timestamp : {}", event, instant.toString());
        HolderAccountSummary holderAccount = getHolderAccountSummary(event.getHolderID());
        holderAccount.setAccountCnt(holderAccount.getAccountCnt()+1);
        repository.save(holderAccount);
    }
    
    @EventHandler
    protected void on(DepositMoneyEvent event, @Timestamp Instant instant){
        log.debug("projecting {} , timestamp : {}", event, instant.toString());
        HolderAccountSummary holderAccount = getHolderAccountSummary(event.getHolderID());
        holderAccount.setTotalBalance(holderAccount.getTotalBalance() + event.getAmount());
        repository.save(holderAccount);
    }
    
    @EventHandler
    protected void on(WithdrawMoneyEvent event, @Timestamp Instant instant){
        log.debug("projecting {} , timestamp : {}", event, instant.toString());
        HolderAccountSummary holderAccount = getHolderAccountSummary(event.getHolderID());
        holderAccount.setTotalBalance(holderAccount.getTotalBalance() - event.getAmount());
        repository.save(holderAccount);
    }

    private HolderAccountSummary getHolderAccountSummary(String holderID) {
        return repository.findByHolderId(holderID)
                .orElseThrow(() -> new NoSuchElementException("소유주가 존재하지 않습니다."));
    }
}

위 코드는 Projection 로직을 담고 있습니다. EventHandler 메소드 파라미터에는 @Timestamp 외 @SequenceNumber, ReplayStatus 등이 추가로 전달될 수 있으며, 자세한 내용은 Axon 공식 문서를 참고 바랍니다.

3. 테스트

API 테스트를 통해 발행된 Command가 Read Model에 제대로 반영되는지 테스트 하겠습니다.

1. reousrces 하위 application.yml 파일을 오픈 후에 로깅 정보를 입력합니다.

2. AxonServer 기동 후에 Query App을 수행합니다. 기동이 완료되면 DB에 테이블이 정상 생성되었는지 확인합니다.

3. Command App을 기동합니다. 이후 계정 생성, 계좌 생성, 입금, 출금 Command 명령을 수차례 반복 수행합니다.

4. 테스트 이후 Query App Read Model 갱신 여부를 확인합니다. 또한 Application Log를 통해서 Event 정상 처리를 확인합니다.

c.c.q.p.HolderAccountProjection          : projecting HolderCreationEvent(holderID=0df539ed-2ee2-41be-af32-0f6724a75da3, holderName=kevin, tel=02-1234-5678, address=OO시 OO구) , timestamp : 2020-01-07T12:11:21.047Z
c.c.q.p.HolderAccountProjection          : projecting HolderCreationEvent(holderID=a5d267c6-fbd8-4f0d-b93b-03a8dbf09747, holderName=bruce, tel=02-5291-5678, address=OO시 OO구) , timestamp : 2020-01-07T12:12:14.238Z
c.c.q.p.HolderAccountProjection          : projecting AccountCreationEvent(holderID=0df539ed-2ee2-41be-af32-0f6724a75da3, accountID=0e6d3546-4163-4083-bf2f-50f1289d8c25) , timestamp : 2020-01-07T12:12:27.633Z
c.c.q.p.HolderAccountProjection          : projecting AccountCreationEvent(holderID=0df539ed-2ee2-41be-af32-0f6724a75da3, accountID=042937fb-e658-441d-b23a-fd56be237563) , timestamp : 2020-01-07T12:12:33.961Z
c.c.q.p.HolderAccountProjection          : projecting AccountCreationEvent(holderID=a5d267c6-fbd8-4f0d-b93b-03a8dbf09747, accountID=9eb1f188-c38f-401d-b212-3c26ea84acfa) , timestamp : 2020-01-07T12:12:45.193Z
c.c.q.p.HolderAccountProjection          : projecting AccountCreationEvent(holderID=0df539ed-2ee2-41be-af32-0f6724a75da3, accountID=40d52cac-20d0-49c2-b973-049bd585108f) , timestamp : 2020-01-07T12:13:28.542Z
c.c.q.p.HolderAccountProjection          : projecting DepositMoneyEvent(holderID=0df539ed-2ee2-41be-af32-0f6724a75da3, accountID=40d52cac-20d0-49c2-b973-049bd585108f, amount=300) , timestamp : 2020-01-07T12:15:02.059Z
c.c.q.p.HolderAccountProjection          : projecting WithdrawMoneyEvent(holderID=0df539ed-2ee2-41be-af32-0f6724a75da3, accountID=40d52cac-20d0-49c2-b973-049bd585108f, amount=30) , timestamp : 2020-01-07T12:15:08.242Z
c.c.q.p.HolderAccountProjection          : projecting WithdrawMoneyEvent(holderID=0df539ed-2ee2-41be-af32-0f6724a75da3, accountID=40d52cac-20d0-49c2-b973-049bd585108f, amount=20) , timestamp : 2020-01-07T12:15:13.488Z
c.c.q.p.HolderAccountProjection          : projecting DepositMoneyEvent(holderID=a5d267c6-fbd8-4f0d-b93b-03a8dbf09747, accountID=9eb1f188-c38f-401d-b212-3c26ea84acfa, amount=300) , timestamp : 2020-01-07T12:15:29.451Z
c.c.q.p.HolderAccountProjection          : projecting WithdrawMoneyEvent(holderID=a5d267c6-fbd8-4f0d-b93b-03a8dbf09747, accountID=9eb1f188-c38f-401d-b212-3c26ea84acfa, amount=150) , timestamp : 2020-01-07T12:15:38.423Z

위 내역은 전체 로그중 일부만 발췌한 결과입니다. 확인 결과 Event가 정상적으로 반영된 것을 알 수 있습니다.

4. Replay

이전 포스팅에서 마지막 수신 Event Token 정보를 토대로 AxonSever으로부터 다음 목록을 수신받아 처리한다고 설명 했습니다. 하지만 때로는 Read Model 구조를 재구성하기 위해서 Event를 재생해야될 수 있습니다. Axon에서는 이를 위해 Replay 기능을 제공하며, 특정 시점부터 혹은 전체의 Event에 대한 Replay를 수행할 수 있습니다.

Replay 기능이 동작하면, 내부적으로는 Token 정보를 초기화하여, 특정 시점 혹은 처음부터 발행된 Event를 전달받아 재수행합니다.

이번 시간에는 전체 Event를 재생하는 방법에 대해서 설명하며, 특정 시점부터 이벤트 Replay는 Axon 공식 문서를 참고 바랍니다.

1. Replay를 수행하기 위해 Projection 클래스를 변경합니다. 먼저 ProcessingGroup을 지정하여 TrackingEventProcessor로 하여금 어떤 Group을 대상으로 Replay를 수행할지 지정합니다.

HolderAccountProjection.java

@Component
@AllArgsConstructor
@Slf4j
@ProcessingGroup("accounts")
public class HolderAccountProjection {
(...중략...)
}

2. Replay 수행시 Read Model 초기화 작업이 이루어지지 않으면, 남아있는 데이터에 이벤트가 적용되므로 데이터 정합성이 맞지 않습니다. 따라서 Replay가 수행되기전, 대상 테이블 또한 초기화가 선행 되어야합니다. 이를 위해 @ResetHandler 어노테이션을 추가한 메소드를 정의하여 초기화 작업을 처리합니다.

HolderAccountProjection.java

@Component
@AllArgsConstructor
@Slf4j
@ProcessingGroup("accounts")
public class HolderAccountProjection {
(...중략...)
    @ResetHandler
    private void resetHolderAccountInfo(){
        log.debug("reset triggered");
        repository.deleteAll();
    }
}

3. Replay시 적용 대상 Handler 메소드에 @AllowReplay 어노테이션을 추가합니다.(Optional) 만약 Replay 대상에서 해당 Event는 처리하고 싶지 않을 경우에는 @DisallowReplay를 추가합니다. 예제에서는 전체 Replay 재생을 위해 @AllowReplay 어노테이션만 추가했습니다.

1~3번 과정을 모두 적용한 Projection 클래스 코드는 다음과 같습니다.

HolderAccountProjection.java

@Component
@AllArgsConstructor
@Slf4j
@ProcessingGroup("accounts")
public class HolderAccountProjection {
    private final AccountRepository repository;

    @EventHandler
    @AllowReplay
    protected void on(HolderCreationEvent event, @Timestamp Instant instant) {
        log.debug("projecting {} , timestamp : {}", event, instant.toString());
        HolderAccountSummary accountSummary = HolderAccountSummary.builder()
                                                                        .holderId(event.getHolderID())
                                                                        .name(event.getHolderName())
                                                                        .address(event.getAddress())
                                                                        .tel(event.getTel())
                                                                        .totalBalance(0L)
                                                                        .accountCnt(0L)
                                                                    .build();
        repository.save(accountSummary);
    }
    @EventHandler
    @AllowReplay
    protected void on(AccountCreationEvent event, @Timestamp Instant instant){
        log.debug("projecting {} , timestamp : {}", event, instant.toString());
        HolderAccountSummary holderAccount = getHolderAccountSummary(event.getHolderID());
        holderAccount.setAccountCnt(holderAccount.getAccountCnt()+1);
        repository.save(holderAccount);
    }
    @EventHandler
    @AllowReplay
    protected void on(DepositMoneyEvent event, @Timestamp Instant instant){
        log.debug("projecting {} , timestamp : {}", event, instant.toString());
        HolderAccountSummary holderAccount = getHolderAccountSummary(event.getHolderID());
        holderAccount.setTotalBalance(holderAccount.getTotalBalance() + event.getAmount());
        repository.save(holderAccount);
    }
    @EventHandler
    @AllowReplay
    protected void on(WithdrawMoneyEvent event, @Timestamp Instant instant){
        log.debug("projecting {} , timestamp : {}", event, instant.toString());
        HolderAccountSummary holderAccount = getHolderAccountSummary(event.getHolderID());
        holderAccount.setTotalBalance(holderAccount.getTotalBalance() - event.getAmount());
        repository.save(holderAccount);
    }

    private HolderAccountSummary getHolderAccountSummary(String holderID) {
        return repository.findByHolderId(holderID)
                .orElseThrow(() -> new NoSuchElementException("소유주가 존재하지 않습니다."));
    }

    @ResetHandler
    private void resetHolderAccountInfo(){
        log.debug("reset triggered");
        repository.deleteAll();
    }
}

4. Reset 수행 EndPoint를 구현하기 위해 controller 패키지 및 클래스를 생성합니다.

5. controller 클래스를 구현합니다.

HolderAccountController.java

@RestController
@RequiredArgsConstructor
public class HolderAccountController {
    private final QueryService queryService;

    @PostMapping("/reset")
    public void reset() {
        queryService.reset();
    }
}

6. Service Package 및 Service 클래스를 생성합니다.

7. 서비스 클래스를 구현합니다.

QueryService.java

public interface QueryService {
    void reset();
}

QueryServiceImpl.java

@RequiredArgsConstructor
@Service
public class QueryServiceImpl implements QueryService{
    private final Configuration configuration;

    @Override
    public void reset() {
        configuration.eventProcessingConfiguration()
                .eventProcessorByProcessingGroup("accounts",
                        TrackingEventProcessor.class)
                .ifPresent(trackingEventProcessor -> {
                    trackingEventProcessor.shutDown();
                    trackingEventProcessor.resetTokens(); // (1)
                    trackingEventProcessor.start();
                });
    }
}

실제 Token 초기화는 resetTokens 메소드를 통해서 이루어집니다. 해당 작업을 위해서는 EventProcessor의 재시작이 필요합니다.

8. Query App 재기동 후 API 테스트(POST : http://localhost:9090/reset)를 수행합니다. Application 로그 및 DB를 확인하면 정상적으로 Replay가 이루어졌음을 확인할 수 있습니다.

5. 마치며

EventHandler 메소드 적용에 따른 Read Model 구현을 완성했습니다. 다음 포스팅에서는 Replay 성능 개선 방법에 대하여 다루도록 하겠습니다.

11. Query 어플리케이션 구현(Event) - 1

cla9 — Mon, 6 Jan 2020 00:46:50 +0900

1. 서론

이번 포스팅부터 Query App 구현을 다루겠습니다. Query App은 Event를 수신받아 Read Model에 반영하는 Projection 작업과 Read Model을 읽는 Query 2가지로 기능이 나뉩니다. 기능별로 실제 구현 코드량은 얼마되지 않지만 알아야 하는 개념이 많으므로 먼저 Event 처리 기능 관련하여 다루고 향후에 Query 기능을 다루겠습니다.

이번 내용은 EventHandler 구현 실습전 내부 처리 과정을 살펴보겠습니다.

2. Event 처리 과정

Token Store

이전 포스팅에서 확인 하였듯이 EventStore에는 EventStream의 내용을 순차적으로 적재합니다. 따라서 수신부에서 지금까지 수신된 Event는 어디까지이며, EvenStore에서 어디서부터 Event를 수신 받아야할지에 대한 정보를 가지고 있어야합니다. 해당 정보를 Token이라고 하며, Token은 Query App과 연관된 DB 내부에 저장하여 영구적으로 관리합니다.(Token Store)

Token 내용

<org.axonframework.eventhandling.GlobalSequenceTrackingToken>
  <globalIndex>13</globalIndex>
</org.axonframework.eventhandling.GlobalSequenceTrackingToken>

위 예시는 TokenStore에 저장된 내용입니다.Token 컬럼에는 지금까지 Tracking된 Event의 Global Sequence 값이 들어있으며, 예시를 통해 13번이 마지막으로 수신된 Event임을 알 수 있습니다.

Tracking Event Processor

TokenStore를 통해서 마지막 수신 Event 정보를 알 수 있다면, 해당 정보를 토대로 Event 수신 요청 및 처리를 담당하는 중계 역할이 필요합니다. Axon에서 제공하는 Event 처리기는 Subscribing Event Processor(SEP), Tracking Event Processor(TEP) 2가지가 있습니다. 두 Event 처리기 차이점은 이벤트 발행 쓰레드에서 Event 처리여부입니다. SEP는 Event 발행 쓰레드에서 Event 또한 처리하며, TEP는 별도 쓰레드에서 처리합니다. TEP를 이해하는 것이 중요하므로 이를 중점적으로 다루겠습니다.

3. Tracking Event Processor

위 그림은 Query App이 기동될 때 EventProcessor 생성 및 처리 과정 흐름을 간략하게 표현했습니다.

Spring DefaultLifecycleProcessor가 Start 명령을 내립니다.
Axon의 기본 설정을 담당하는 DefaultConfigurer 클래스 Start 메소드가 호출됩니다. 이후 등록된 Handler에게 수행 명령을 내립니다. 기본으로 등록된 Handler는 2개입니다.(EventProcessingModule, EventProcessorInfoConfiguration)
EventProcessingInfoConfiguration의 Start 메소드가 호출됩니다.
내부 로직을 거쳐 ProcessorInfoSource와 EventProcessorControlService를 구동합니다. ProcessorInfoSource는 AxonServer에게 EventProcessor의 현재 상태를 주기적(Default 500ms)으로 보내는 역할을 담당합니다. EventProcessorContolService는 AxonServer에서 요청시 EventProcessor를 제어하는 서비스 역할을 담당합니다. EventPRocessorControlService의 실제 로직 수행은 AxonServerConnectionManager 및 EventProcessorController가 담당합니다.
EventProcessingModule을 구동합니다. 이 과정에서 EventProcessor 생성을 요청합니다.
TrackingEventProcessor를 생성합니다. 사용자가 별도 속성 정의를 하지 않았으면, DefaultEventProcessor가 생성됩니다. (※ Thread 수 : 1개, 배치 사이즈 : 1, 최대 Thread 수 : Segment 개수, tokenClaim 주기 : 5000ms)
생성된 TrackingEventProcessor에게 구동을 요청합니다. 내부적으로 AxonThreadFactory에게 WorkerLauncher 인스턴스에 대한 Thread 생성을 요청합니다.
TrackingEventProcessor가 구동중이면 내부로직이 반복 수행될 수도록 무한 루프로 구성되어 있습니다. 만약 EventStore Segment에 변경된 내역을 확인하여 처리해야한다면, AxonThreadFactory에게 TrackingSegmentWorker 인스턴스 생성을 요청합니다.
Segment에 대한 Event 처리(ProcessingLoop)를 요청합니다.

9번 Segment Event 처리 과정을 자세히 확인하기 위해 순서도를 그리면 다음과 같습니다.

EventStream을 오픈합니다.
EventStream에서 최신 Event가 존재하는지 확인합니다. 존재하지 않는다면 Token 값을 갱신하고 작업을 종료합니다.
최신 Event를 수신받은 후 해당 App에서 처리가 가능한 Event인지 확인합니다. 만약 처리할 수 없다면 BlackList 등록이 가능한지 확인하고 이를 등록합니다. 이후 해당 Event는 MessageMonitor에 보고한 뒤 무시합니다.
처리가 가능한 Event라면 UnitOfWork를 수행합니다. 해당 과정에서 Token 값은 자동 갱신합니다. 이후 EventHandler를 찾아 메소드를 수행합니다.
Event 처리가 완료되면 작업을 종료합니다.

내부구조는 복잡하지만 이를 한줄로 요약하자면 "주기적으로 TrackingEventProcessor에서 처리가 가능한 Event가 존재하는지 확인 및 처리(UnitOfWork)하고 Token 갱신하는 작업"으로 정의할 수 있습니다.

4. Axon Server 라우팅기능(Event)

이번에는 Client가 아닌 AxonServer 입장에서 Event 전달 흐름을 살펴보도록 하겠습니다.

Query Application을 구동하면 Token 정보를 읽어옵니다. 이후 EventStore에게 자신이 보유한 Token 정보를 알려준 다음 EventStream을 오픈합니다. 위 예시에는 요청당시 EventStore에는 추가로 유입된 Event가 없으므로 Application의 Token값 변경 후 작업을 종료합니다.

만약 Command App으로부터 Event가 추가된다면, 다음 ProcessingLoop 작업에서 해당 Event를 Query App으로 전달합니다. 수신받은 App에서 해당 Event 처리 가능 여부를 확인하는데, 만약 처리하지 못할 경우는 AxonServer에게 BlackList 추가를 요청합니다. 따라서 이후 신규 적재되는 Event에 대해서는 수신받지 않습니다.

신규 App이 추가로 기동되어 AxonServer에 등록요청한 상태에서 마지막 수신 Event가 2번이라면, AxonServer에서 3번부터 해당 Event를 App으로 전달합니다.

4. 마치며

이번 포스팅에서는 EventHandler 메소드를 수행하기위해서 알아야할 내부 구조를 알아봤습니다. 다음 포스팅에서는 EventHandler 메소드 구현에 대해 다루어보겠습니다.

10. EventStore

cla9 — Thu, 2 Jan 2020 21:13:54 +0900

1. 서론

Query App 관련 포스팅을 진행하기 앞서 Event가 저장되는 EventStore에 대하여 알아보고자 합니다. 이번 포스팅에서 다룰 내용은 EventStore를 위한 필요조건, DB 종류에 따른 EventStore 역할 장·단점 그리고 AxonServer EventStore 저장 구조입니다.

2. EventStore 필요 조건

Event를 읽고 쓰는데 있어 EventStore가 기본적으로 갖춰야할 조건을 알아보겠습니다.

1. 이벤트는 추가만 가능하고 입력,삭제,수정이 불가능하다.
2. 여러 이벤트가 하나의 트랜잭션 처리가 되어야 한다면, 트랜잭션 단위로 Commit 혹은 Rollback 되어야한다.
3. Commit된 이벤트는 유실되어서는 안된다
4. 발행된 모든 Event 중 Aggregate 별로 데이터를 읽을 수 있어야한다.
5. 모든 이벤트는 삽입된 순서대로 읽기가 가능해야한다.

위 조건은 대부분의 DBMS라면 충족되는 요건입니다. 그 밖에 EventStore를 구성하는데 있어 요구되는 사항은 무엇이 있을까요?

1. SnapShot 저장소 지원

Command App을 구현하면서 Snapshot 필요성을 인지하였습니다. EventStore에서는 특정 시점에 Aggregate별 Sequence 번호에 해당하는 Snapshot을 별도 공간에 적재하며, Event 로드시에 해당 스냅샷 상태와 스냅샷 이후의 Sequence 번호에 해당되는 Event만을 읽을 수 있도록 지원해야 합니다.

2. Event Notification 기능

EvenetStore가 신규 추가된 Event를 희망하는 App에게 전파하는 역할을 수행하지 못한다면, Subscriber에서 주기적으로 Polling하여 Event 유입이 있는지 확인하는 작업이 필요합니다. 이는 DB 관점에서 I/O 및 Network 트래픽이 증가하는 요인입니다. 일반적인 RDBMS에서는 이벤트 전파기능이 없기 때문에 위 그림과 같이 메시징 처리를 수행해야합니다.

이러한 문제점을 해결하고자 메시지 큐를 사용해서 EventStore에 적재함과 동시에 큐에도 이벤트를 적재하여 전송하는 방법을 생각할 수 있습니다. 하지만 이는 EventStore에 저장과 큐를 통한 Event 전송 시점에 대한 동기화를 보장할 수 없습니다.

또한, 기타 이유로 EventStore에 이벤트 삽입이 실패하는 경우 메시지 큐를 통해 이미 전달된 이벤트와의 일관성이 깨지게 됩니다.

따라서 EventStore의 가장 이상적인 구조는 EventStore 자체가 Message Bus 역할을 담당하는 것입니다.

3. EventStore 적합성 비교

지금부터 소개드리는 내용은 AxonIQ Webinar를 참고하여 작성하였습니다.

1. RDBMS

RDBMS 사용의 장점으로는 Transaction에 대한 지원 및 기술적 성숙도가 높다는 점입니다. 또한 오랜시간동안 사용되었으므로 사용자들에게 친숙하며, 제공되는 Tool이 다양합니다.

하지만 가장 큰 문제점은 확장성입니다. 대량의 데이터 처리보다는 데이터 공간 효율화 및 관계를 통한 데이터 정합성 보장 등에 초점이 맞춰져 있습니다. AxonIQ에서 RDBMS를 EventStore로 사용했을 때의 벤치마크 테스트 결과는 다음과 같습니다.

출처 : https://youtu.be/zUSWsJteRfw

출처 : http://www.dbguide.net/db.db?cmd=view&boardUid=148209&boardConfigUid=9&boardIdx=136&boardStep=1

결과를 보면 데이터 양이 증가할 수록 처리량이 떨어지는 것을 확인할 수 있습니다. 다양한 요인이 있을 수 있겠지만, 대표적으로는 대용량 데이터를 기준으로 B-Tree 인덱스를 사용하면, 인덱스 Depth가 깊어지기 때문에 지속 발생하는 인덱스 Split과 더불어 수직적 탐색 비용이 증가합니다. 또한 데이터 특성상 인덱스 우측 Block에 Transaction이 집중적으로 몰리기 때문에 Oracle 기준 핫블록으로 인한 Latch 경합이 발생하여 동시성이 크게 저하될 수 있습니다.(Right Growing Index)

위 테스트 결과는 RDBMS 테이블 구조 변경 없이 일반적인 Heap 테이블과 B-Tree 인덱스를 기준으로 진행했습니다. 만약 DBMS가 Oracle이라면 Hash 파티셔닝, Reverse 인덱스, IOT(Index Organized Table) 등을 적절히 사용한다면 개선의 여지는 있습니다.

RDBMS는 Event Notification 기능이 없기 때문에 이를 고려해야합니다. 이전에 설명한 Polling 방식을 개선하기 위해서는 테이블 단위 Audit을 고려해볼 수 있습니다. 즉 Audit 결과를 File로 떨어트리고 해당 로그 tail 값을 AxonFramework에서 요구하는 포맷으로 변경한 다음 메시지 큐를 통해 보내는 방법이 있습니다. 혹은 Trigger를 이용하는 방법도 생각해볼 수 있으나 이는 추천하지 않습니다.

2. Mongo DB

Mongo DB는 대표적인 NoSQL로써 하나의 이벤트는 하나의 Document에 속하며, 대량의 데이터 처리에 적합합니다. 하지만 Transaction 지원 문제점이 있습니다. 최근에 4.2 버전이 Release되어 Multi Document에 대한 Transaction 기능이 추가되었지만, 단일 Node에서는 Transaction이 불가하는 등의 제약사항이 존재합니다.

참고자료

두 번째 문제점은 MongoDB 3.2 버전부터 Storage Engine으로 Wiredtiger를 기본적으로 사용하고 있습니다. Wiredtiger 저장 방식은 Btree, 컬럼스토어, LSM 방식이 있습니다. 이중 EventStore에 적합한 방식은 Write 작업에 최적화된 LSM 방식이나 MongoDB에는 LSM을 아직 지원하고 있지 않습니다.

세 번째 문제점은 RDBMS와 마찬가지로 Event Notification 기능이 없기 때문에, Commit 로그 결과 등을 AxonFramework에서 요구하는 포맷으로 변경한 다음 메시지 큐를 통해 보내는 방식을 고려해야 합니다.

마지막으로 모든 Document에 대하여 전역적인 Sequence 기능이 기본적으로 제공되지 않는다는 점입니다. 따라서 이를 해결하기 위해서는 직접 함수를 구현해야 합니다.

참고자료

Mongo DB 시퀀스 만들기

3. Kafka

카프카는 대용량 환경에서 Message 전달 역할로 좋은선택입니다. 하지만 EventSourcing에 있어서 좋은 도구는 아닙니다. 그 이유는 위 그림과 같이 Event Stream에서 특정 Aggregate를 추출하기 위해서는 해당 Stream 전체를 읽으면서 그 중 내가 원하는 Aggregate만 필터링하는 작업이 수반되어야 하기 때문입니다.

물론 Aggregate 별로 Topic을 생성하는 방법등도 고려할 수 있으나 이는 Aggregate 별로 디스크에 적재되는 용량과 I/O 밸런스 등을 고려해야하는 등의 관리 포인트가 급격하게 상승합니다.

참고자료

Apache Kafka is not for Event Sourcing

4. Axon Server(Event Store)

AxonServer 내부에는 Event 저장을위한 별도 DB가 없으며, File을 직접 다룹니다. 외부와의 연결은 Rest API 혹은 gRPC 방법을 통해 가능합니다.

EventStore는 오직 데이터 추가만이 가능하도록 설계되었습니다. 따라서 수정, 삭제와 관련된 그 어떠한 API도 제공되지 않습니다.

AxonServer에서는 EventStream을 일정 크기별로 잘라서 Segment로 매핑합니다. 각 Segment는 하나의 파일이며, 내부에는 Event가 연속적으로 할당되어 있습니다. 생성된 파일은 데이터 Corruption 확인을 위해 CRC 체크하여 파일 손상을 확인합니다.

만약 Segment에 Event Entry가 가득차게되면, 새로운 파일을 생성하고 이를 가르키도록 Index 정보를 추가합니다.

EventStore는 Snapshot 저장소를 제공합니다. Snapshot 저장소 또한 Segment 단위로 저장되며, Snapshot Entry는 동일한 Aggregate의 번호가 매핑된 파일을 가르킵니다. 따라서 위 그림에서 A Aggregate를 읽는다고 가정한다면 Snapshot이 가르키는 1번 Segment 이후부터 데이터를 읽기 시작합니다.

하지만 이때 2번 Segment에는 A Aggregate Event가 존재하지 않습니다. 따라서 해당 Segment는 읽는 것이 의미가 없습니다. 따라서 스캔 과정에서 2번은 읽지 않고 Skip할 수 있다면 최소한의 I/O로 성능을 높일 수 있을 것입니다. AxonServer에서는 이를 위해 Bloom Filter를 도입하였습니다.

Bloom Filter

Bloom Filter는 찾고자 하는 데이터가 해당 집합에 포함되는지를 판단하는 확률적 자료구조입니다. 주로 DBMS에서 많이 사용하며, 디스크에서 찾고자하는 값이 존재할 가능성이 있는 경우에만 블록을 읽기 위해 사용됩니다.

예를 들어 설명하겠습니다. Bloom Filter는 N개의 bit 배열에 대해서 찾고자하는 데이터를 대상으로 H개의 해시 함수를 적용한 결과를 1로 표시한다음, 대상 집합에도 동일하게 H개의 해시 함수를 적용해 결과가 동일한지를 판단합니다. 만약 동일하다면 찾고자 하는 존재할 수도 있으므로 해당 집합을 탐색합니다.

예를들어 1개의 Segment에는 1개의 Event만 존재하고, 4개 bit 배열 및 1개의 해 시함수(mod 10)을 적용한다고 가정하겠습니다. 이때 찾고자하는 Aggregate 식별자는 14라면 위 해시 함수를 적용했을 때 결과는 4가 나옵니다. 또한 저장된 값 또한 14라면 Bloom Filter 및 찾고자 하는 값이 동일하므로 해당 집합에는 원하는 결과가 존재합니다.

하지만 만약 집합속에 있는 값이 24라면, 해시 함수 결과 똑같이 4라는 결과가 나옵니다. 이때는 값이 다른데도 불구하고, 값이 있을 수도 있다고 판정하여 해당 집합을 읽습니다. 따라서 이러한 경우는 비효율적인 I/O가 존재하며 이를 false positive라고 합니다. 따라서 Bloom Filter에서는 false positive를 줄이기 위해서 bit 배열의 수를 늘리는 것과 해시 함수 개수를 늘려서 동일한 값이 발생하지 않도록해야 불필요한 I/O를 유발하지 않습니다.

참고자료

확률적 자료구조를 이용한 추정

Bloom Filter를 통해서 읽어야할 Segment를 알았다면, 해당 Segment에서 시작점을 찾는 것은 Segment 내부에 저장되어있는 인덱스를 통해서 Aggregate의 Sequence 번호를 찾아갑니다. 결론적으로 Axon Server의 EventStore에서 Aggregate 데이터를 검색할 때, 해당 Aggregate의 식별자와 Sequence 번호를 기준으로 Bloom Filter와 인덱스를 활용하여 이를 찾습니다.

5. 마치며

이번 시간에는 EventStore 역할 비교 및 Axon Server 저장소 구조에 대해서 알아보았습니다. 다음 포스팅부터 Query Application 구현에 대하여 다루도록 하겠습니다.

9. Command 어플리케이션 구현 - 4

cla9 — Tue, 31 Dec 2019 12:50:24 +0900

1. 서론

이번 포스팅은 데모 프로젝트 진행에 있어 필수적으로 구현해야하는 코드는 없습니다. 따라서 Skip해도 괜찮습니다. 이번 시간에는 상태를 저장하는 State-Stored Aggregate에 대해서 알아보겠습니다.

2. Aggregate 종류

AxonFramework 에서 Aggregate의 종류는 크게 두 가지로 분류할 수 있습니다.

EventSourced Aggregate
State-Stored Aggregate

EventSourced Aggregate는 기존 Command 어플리케이션을 제작하는 과정에서 구현한 모델 방식입니다. 즉 EventStore로부터 Event를 재생하면서 모델의 최신상태를 만듭니다.

출처 : https://altkomsoftware.pl/en/blog/cqrs-event-sourcing/

이와 반대로 State-Stored Aggregate는 위 그림과 같이 EventStore에 Event를 적재와 별개로 모델 자체에 최신 상태를 DB에 저장합니다. 데모 프로젝트 Aggregate 구조 변경을 통해 Command DB에 모델을 생성하는 방법에 대해서 알아봅시다.

3. State-Stored Aggregate

데모 프로젝트에는 Holder와 Account Entitiy가 존재합니다. Command 모델에서는 해당 Entitiy 관계를 분리하여 표현할 것이며 모델 구현은 JPA를 사용하겠습니다. 먼저 Command와 Query DB에 적재될 테이블 구조를 살펴보겠습니다.

ERD

Command 모델

Query 모델

3. Aggregate 구현

State-Stored Aggregate 구현을 위해 기존 코드를 단계적으로 변경하겠습니다.

1. HolderAggregate와 AccountAggregate 구조 변경을 통해 상태를 저장할 수 있도록 구현합니다.

HolderAggregate.java

@AllArgsConstructor
@NoArgsConstructor
@Aggregate
@Slf4j
@Entity(name = "holder")
@Table(name = "holder")
public class HolderAggregate {
    @AggregateIdentifier
    @Id
    @Column(name = "holder_id")
    @Getter
    private String holderID;
    @Column(name = "holder_name")
    private String holderName;
    private String tel;
    private String address;

    @OneToMany(mappedBy = "holder", orphanRemoval = true)
    private List<AccountAggregate> accounts = new ArrayList<>();

    public void registerAccount(AccountAggregate account){
        if(!this.accounts.contains(account))
            this.accounts.add(account);
    }
    public void unRegisterAccount(AccountAggregate account){
        this.accounts.remove(account);
    }

    @CommandHandler
    public HolderAggregate(HolderCreationCommand command) {
        log.debug("handling {}", command);

        this.holderID = command.getHolderID();
        this.holderName = command.getHolderName();
        this.tel = command.getTel();
        this.address = command.getAddress();

        apply(new HolderCreationEvent(command.getHolderID(), command.getHolderName(), command.getTel(), command.getAddress()));
    }
}

@Entity 어노테이션을 통해 대상 Aggregate가 JPA에서 관리되는 Entity임을 명시했습니다. 또한 Aggregate 식별자에 @Id 어노테이션을 추가하여 대상 속성이 PK임을 표시합니다.

HolderAggregate는 AccountAggregate와 1:N 관계를 맺고 있으므로 양방향 관계 설정 했으며, HolderAggregate가 삭제될 경우 AccountAggregate도 삭제되도록 orphanRemovel 옵션을 추가했습니다.

마지막으로 양방향 관계 설정 시 연관관계 편의 메소드 제공을 위해 registerAccount, unRegisterAccount 메소드를 추가했습니다.

(참고 : 양방향 연관관계 편의 메소드)

혹시 위 Aggregate 코드에서 JPA 코드 추가 외에 혹시 이상한 점을 눈치채셨나요?

바로 EventSourcingHandler 메소드가 사라졌습니다. State-Stored Aggregate 모델은 모델 자체가 최신 상태를 유지하고 있으므로 EventStore로부터 Replay를 할 필요가 없습니다. 따라서 CommandHandler 메소드 내에서 Command 상태를 저장하는 로직을 포함시켜야 합니다.

이번에는 AccountAggreagte 클래스를 변경하겠습니다.

AccountAggregate.java

@NoArgsConstructor
@AllArgsConstructor
@Slf4j
@Aggregate
@EqualsAndHashCode
@Entity(name = "account")
@Table(name = "account")
public class AccountAggregate {
    @AggregateIdentifier
    @Id
    @Column(name = "account_id")
    private String accountID;

    @ManyToOne
    @JoinColumn(name = "holder_id", foreignKey = @ForeignKey(name = "FK_HOLDER"))
    private HolderAggregate holder;
    private Long balance;

    public void registerHolder(HolderAggregate holder){
        if(this.holder != null)
            this.holder.unRegisterAccount(this);
        this.holder = holder;
        this.holder.registerAccount(this);
    }

    @CommandHandler
    public AccountAggregate(AccountCreationCommand command) {
        log.debug("handling {}", command);
        this.accountID = command.getAccountID();
        HolderAggregate holder = command.getHolder();
        registerHolder(holder);
        this.balance = 0L;
        apply(new AccountCreationEvent(holder.getHolderID(),command.getAccountID()));
    }
    @CommandHandler
    protected void depositMoney(DepositMoneyCommand command){
        log.debug("handling {}", command);
        if(command.getAmount() <= 0) throw new IllegalStateException("amount >= 0");
        this.balance += command.getAmount();
        log.debug("balance {}", this.balance);
        apply(new DepositMoneyEvent(command.getHolderID(), command.getAccountID(), command.getAmount()));
    }
    @CommandHandler
    protected void withdrawMoney(WithdrawMoneyCommand command){
        log.debug("handling {}", command);
        if(this.balance - command.getAmount() < 0) throw new IllegalStateException("잔고가 부족합니다.");
        else if(command.getAmount() <= 0 ) throw new IllegalStateException("amount >= 0");
        this.balance -= command.getAmount();
        log.debug("balance {}", this.balance);
        apply(new WithdrawMoneyEvent(command.getHolderID(), command.getAccountID(), command.getAmount()));
    }
}

HolderAggregate에서 설명한 부분은 제외하고 추가된 점은 Account 모델이 Holder 모델에 대하여 FK를 지니고 있으므로 관계상에서 FK를 명시하였습니다.

2. HolderAggregate 클래스 생성을 위한 Repository 패키지 및 클래스를 생성합니다.

3. HolderRepository 클래스를 구현합니다.

@Repository
public interface HolderRepository extends JpaRepository<HolderAggregate,String> {
    Optional<HolderAggregate> findHolderAggregateByHolderID(String id);
}

4. 객체 대상으로 연관관계를 변경하였기 때문에 AccountCreateCommand 클래스를 수정합니다.

5. Service 클래스를 수정합니다.

@Service
@RequiredArgsConstructor
public class TransactionServiceImpl implements TransactionService {
    private final CommandGateway commandGateway;
    private final HolderRepository holders;

...(중략)...

    @Override
    public CompletableFuture<String> createAccount(AccountDTO accountDTO) {
        HolderAggregate holder = holders.findHolderAggregateByHolderID(accountDTO.getHolderID())
                                       .orElseThrow( () -> new IllegalAccessError("계정 ID가 올바르지 않습니다."));
        return commandGateway.send(new AccountCreationCommand(UUID.randomUUID().toString(),holder));
    }

...(중략)...
}

6. Snapshot 설정을 위해 생성한 Configuration 속성을 적용하지 않도록 AxonConfig 클래스 @Configuration 어노테이션을 주석처리 합니다.

//@Configuration
//@AutoConfigureAfter(AxonAutoConfiguration.class)
public class AxonConfig {
...(중략)...
}

이로써 State-Stored Aggregate 구현에 대한 코드 변경은 끝났습니다.

4. 테스트

1. Application 실행 후 계정 생성 API 테스트를 진행합니다.

POST http://localhost:8080/holder
Content-Type: application/json

{
	"holderName" : "kevin",
	"tel" : "02-1234-5678",
	"address" : "OO시 OO구"
}

2. DB에서 계정 데이터 생성 여부를 확인합니다.

3. 계좌 생성 API를 호출합니다.

POST http://localhost:8080/account
Content-Type: application/json

{
  "holderID" : "486832c2-b606-470d-949a-9f9d8613b112"
}

4. DB에서 계좌 데이터 생성 여부를 확인합니다.

5. 입금 API를 호출합니다.

POST http://localhost:8080/deposit
Content-Type: application/json

{
  "accountID" : "9274bb43-ca87-4aa4-b1b4-0363382ad6fb",
  "holderID" : "486832c2-b606-470d-949a-9f9d8613b112",
  "amount" : 300
}

6. DB에서 해당 계정 잔고를 확인합니다.

정상적으로 입금된 것을 확인할 수 있습니다.

7. 출금 API를 4번 연속으로 호출합니다.

POST http://localhost:8080/withdrawal
Content-Type: application/json

{
  "accountID" : "9274bb43-ca87-4aa4-b1b4-0363382ad6fb",
  "holderID" : "486832c2-b606-470d-949a-9f9d8613b112",
  "amount" : 1
}

8. DB에서 출금 내역을 확인합니다.

정상적으로 출금된 것을 확인할 수 있습니다.

o.a.commandhandling.SimpleCommandBus     : Handling command [com.cqrs.command.commands.WithdrawMoneyCommand]
c.c.command.aggregate.AccountAggregate   : handling WithdrawMoneyCommand(accountID=9274bb43-ca87-4aa4-b1b4-0363382ad6fb, holderID=486832c2-b606-470d-949a-9f9d8613b112, amount=1)
c.c.command.aggregate.AccountAggregate   : balance 296
org.axonframework.messaging.Scope        : Clearing out ThreadLocal current Scope, as no Scopes are present

4번 연속 출금 후 Application의 로그를 일부 발췌하였습니다. 기존과 다른점은 EventSourced Aggregate의 경우에는 Replay를 위해 EventStore의 I/O 과정이 필요했지만 State-Stored Aggregate는 상태를 보관하므로 상태 복원 과정이 없습니다.

5. 마치며

State-Stored Aggreagte는 Command DB에 최신 상태를 보관합니다. 이로인해 매번 EventStore를 통해서 Replay를 하지 않아도 되는 점은 장점입니다.

하지만 만약에 테이블 데이터가 손실이 되어서 복구가 필요한 경우 Replay를 자동으로 수행되지 않으므로 별도로 EventSourcing 하는 작업을 구현해야 할 수 있습니다. 물론 DBMS 자체 복구 기능을 이용할 수도 있습니다. 하지만 Media Recovery가 불가피하다면 DB 서비스 중단이 발생합니다. 따라서 Aggregate별 사용 장단점을 인지한 다음 적절한 사용이 필요합니다.

이상으로 Command Application 구현 포스팅 마치도록 하겠습니다.

8. Command 어플리케이션 구현 - 3

cla9 — Sun, 29 Dec 2019 18:00:29 +0900

1. 서론

지난 포스팅에서 Command Application에 대한 전반적인 구현을 마무리했습니다. 하지만 해당 프로그램은 근본적인 문제점을 안고 있습니다. 이번 포스팅에서는 발생되는 문제점과 이를 해결하기 위한 방법에 대하여 살펴보겠습니다.

2. 문제점 도출

아래 테이블은 계정 생성 Command를 실행했을 때 EventStore에 저장되는 데이터 중 일부를 발췌한 것입니다.

글로벌 인덱스	Payload	Payload 종류	발생 시간	Aggregate 식별자	시퀀스 번호	타입
1		com.cqrs.events.HolderCreationEvent	2019-12-29T05:34:49.2527378Z	70f956e3-069c-4666-b0f4-324dfb0a807e	0	HolderAggregate

공간 부족으로 위 데이터에서 Payload 데이터만 따로 뽑아보면 다음과 같습니다.

<com.cqrs.events.HolderCreationEvent>
  <holderID>70f956e3-069c-4666-b0f4-324dfb0a807e</holderID>
  <holderName>kevin</holderName>
  <tel>02-1234-5678</tel>
  <address>OO시 OO구/address>
</com.cqrs.events.HolderCreationEvent>

Payload에는 Event 내용이 담겨있습니다. 따라서 EventSourcing 및 Event Handler에서는 Payload 내용을 기준으로 Event를 처리합니다.

계정 생성만 완료된 상황에서 추가로 계좌 생성 > 계좌 입금(300원) > 인출 5회(1원씩)을 진행한 후 EventStore를 살펴보면 다음과 같습니다.

글로벌 인덱스	Payload 종류	Aggregate 식별자	시퀀스 번호	타입
1	com.cqrs.events.HolderCreationEvent	70f956e3-069c-4666-b0f4-324dfb0a807e	0	HolderAggregate
2	com.cqrs.events.AccountCreationEvent	c65f80c3-9c44-4ca6-a977-72983a675203	0	AccountAggregate
3	com.cqrs.events.DepositMoneyEvent	c65f80c3-9c44-4ca6-a977-72983a675203	1	AccountAggregate
4	com.cqrs.events.WithdrawMoneyEvent	c65f80c3-9c44-4ca6-a977-72983a675203	2	AccountAggregate
5	com.cqrs.events.WithdrawMoneyEvent	c65f80c3-9c44-4ca6-a977-72983a675203	3	AccountAggregate
6	com.cqrs.events.WithdrawMoneyEvent	c65f80c3-9c44-4ca6-a977-72983a675203	4	AccountAggregate
7	com.cqrs.events.WithdrawMoneyEvent	c65f80c3-9c44-4ca6-a977-72983a675203	5	AccountAggregate
8	com.cqrs.events.WithdrawMoneyEvent	c65f80c3-9c44-4ca6-a977-72983a675203	6	AccountAggregate

(※ 공간 부족으로 Payload 및 이벤트 발생 시간 등은 제외하였습니다.)

만약 이러한 상황에서 c65f80c3-9c44-4ca6-a977-72983a675203 식별자를 지닌 AccountAggregate 에서 1원을 인출하는 명령이 발생된다면 내부적으로는 어떠한 과정을 거칠까요?

Command 어플리케이션 구현 - 1 포스팅에서 소개한 Command 이벤트 수행 내부 흐름도입니다. 당시 4번 과정에 대해서 다음과 같이 소개했습니다.

4. UnitOfWork 수행합니다. 이 과정에서 Chain으로 연결된 handler 들을 거치면서 대상 Aggregate에 대하여 EventStore로부터 과거 이벤트들을 Loading 하여 최신 상태로 만듭니다. 이후 해당 Command와 연결된 Handler 메소드를 Reflection을 활용하여 호출합니다.

즉 새로운 명령을 수행하기 위해서는 c65f80c3-9c44-4ca6-a977-72983a675203 식별자를 지닌 Aggregate를 대상으로 기존에 발행된 7개의 이벤트를 EventStore에서 읽어와 Loading하는 작업이 선행됩니다. 그 결과 최신 상태로 Aggregate를 만든 이후에 새 Command 적용 및 Event를 발생시킵니다.

o.a.commandhandling.SimpleCommandBus     : Handling command [com.cqrs.command.commands.WithdrawMoneyCommand]
c.c.command.aggregate.AccountAggregate   : applying AccountCreationEvent(holderID=70f956e3-069c-4666-b0f4-324dfb0a807e, accountID=c65f80c3-9c44-4ca6-a977-72983a675203)
c.c.command.aggregate.AccountAggregate   : applying DepositMoneyEvent(holderID=70f956e3-069c-4666-b0f4-324dfb0a807e, accountID=c65f80c3-9c44-4ca6-a977-72983a675203, amount=300)
c.c.command.aggregate.AccountAggregate   : balance 300
c.c.command.aggregate.AccountAggregate   : applying WithdrawMoneyEvent(holderID=70f956e3-069c-4666-b0f4-324dfb0a807e, accountID=c65f80c3-9c44-4ca6-a977-72983a675203, amount=1)
c.c.command.aggregate.AccountAggregate   : balance 299
c.c.command.aggregate.AccountAggregate   : applying WithdrawMoneyEvent(holderID=70f956e3-069c-4666-b0f4-324dfb0a807e, accountID=c65f80c3-9c44-4ca6-a977-72983a675203, amount=1)
c.c.command.aggregate.AccountAggregate   : balance 298
c.c.command.aggregate.AccountAggregate   : applying WithdrawMoneyEvent(holderID=70f956e3-069c-4666-b0f4-324dfb0a807e, accountID=c65f80c3-9c44-4ca6-a977-72983a675203, amount=1)
c.c.command.aggregate.AccountAggregate   : balance 297
c.c.command.aggregate.AccountAggregate   : applying WithdrawMoneyEvent(holderID=70f956e3-069c-4666-b0f4-324dfb0a807e, accountID=c65f80c3-9c44-4ca6-a977-72983a675203, amount=1)
c.c.command.aggregate.AccountAggregate   : balance 296
c.c.command.aggregate.AccountAggregate   : applying WithdrawMoneyEvent(holderID=70f956e3-069c-4666-b0f4-324dfb0a807e, accountID=c65f80c3-9c44-4ca6-a977-72983a675203, amount=1)
c.c.command.aggregate.AccountAggregate   : balance 295
org.axonframework.messaging.Scope        : Clearing out ThreadLocal current Scope, as no Scopes are present
c.c.command.aggregate.AccountAggregate   : handling WithdrawMoneyCommand(accountID=c65f80c3-9c44-4ca6-a977-72983a675203, holderID=70f956e3-069c-4666-b0f4-324dfb0a807e, amount=1)
c.c.command.aggregate.AccountAggregate   : applying WithdrawMoneyEvent(holderID=70f956e3-069c-4666-b0f4-324dfb0a807e, accountID=c65f80c3-9c44-4ca6-a977-72983a675203, amount=1)
c.c.command.aggregate.AccountAggregate   : balance 294

위 코드는 Application에서 수행된 로그 중 일부를 발췌한 내용입니다.

이를 통해 알 수 있는 사실은 동일 Aggregate에 대해서 Event 갯수가 늘어날 수록 새로운 Command를 적용하는데 오랜 시간이 소요된다는 점입니다.

3. 개선 방안(Snapshot)

EventSourcing 패턴을 적용하는 Application에는 이전 단계에서 확인한 근본적인 문제점을 안고 있습니다. 따라서 이를 완화하기 위해서 일정 주기별로 Aggregate에 대한 Snapshot을 생성해야합니다.

Snapshot이란 특정 시점의 Aggregate의 상태를 말합니다. 일반적으로 EventStore에는 Aggregate의 상태를 저장하지 않고 이벤트만 저장합니다. 하지만 특정 시점의 Aggregate의 상태를 저장하여 Loading 과정에서 Snapshot 이후 Event만 Replay하여 빠르게 Aggregate Loading이 가능합니다.

AxonFramework에서도 Configuration 설정을 통해서 Aggregate 별로 Snapshot 설정이 가능합니다. Snapshot 설정에는 특정 Threshold를 넘어가면 생성되며, Snapshot 적용 예제를 통해 문제점을 완화해보도록 하겠습니다.

1. Command 모듈 AxonConfig 파일을 오픈합니다.

2. AxonConfig 클래스에 내용을 추가합니다.

AxonConfig.java

@Configuration
@AutoConfigureAfter(AxonAutoConfiguration.class)
public class AxonConfig {
    @Bean
    SimpleCommandBus commandBus(TransactionManager transactionManager){
        return  SimpleCommandBus.builder().transactionManager(transactionManager).build();
    }
    @Bean
    public AggregateFactory<AccountAggregate> aggregateFactory(){
        return new GenericAggregateFactory<>(AccountAggregate.class);
    }
    @Bean
    public Snapshotter snapshotter(EventStore eventStore, TransactionManager transactionManager){
        return AggregateSnapshotter
                .builder()
                    .eventStore(eventStore)
                    .aggregateFactories(aggregateFactory())
                    .transactionManager(transactionManager)
                .build();
    }
    @Bean
    public SnapshotTriggerDefinition snapshotTriggerDefinition(EventStore eventStore, TransactionManager transactionManager){
        final int SNAPSHOT_TRHRESHOLD = 5;
        return new EventCountSnapshotTriggerDefinition(snapshotter(eventStore,transactionManager),SNAPSHOT_TRHRESHOLD);
    }

    @Bean
    public Repository<AccountAggregate> accountAggregateRepository(EventStore eventStore, SnapshotTriggerDefinition snapshotTriggerDefinition){
        return EventSourcingRepository
                .builder(AccountAggregate.class)
                    .eventStore(eventStore)
                    .snapshotTriggerDefinition(snapshotTriggerDefinition)
                .build();
    }
}

위 코드는 AccountAggregate 기준으로 Snapshot을 설정하도록 작성된 코드입니다. SnapshotTriggerDefinition을 통하여 Aggregate의 발행된 Event가 5개 이상일 경우 Snapshot을 생성하도록 지정하였습니다. Threshold 값에는 얼마를 지정 해야한다는 기준은 없으며, 비즈니스 로직에 따라 생성 주기를 조절하면 됩니다.

Snapshot 설정을 완료한 다음 Application을 재시작 한다음 다시 API 테스트를 하면 수행 당시에는 Snapshot이 존재하지 않기 때문에 전체를 Loading 합니다. 이때 Event를 적용하는 과정에서 Threshold 값을 넘었기 때문에 EventStore에 Snapshot을 새롭게 생성합니다.

Aggregate 식별자	시퀀스 번호	타입	Payload	Payload 타입
c65f80c3-9c44-4ca6-a977-72983a675203	8	AccountAggregate		com.cqrs.command.aggregate.AccountAggregate

생성된 Snapshot 데이터 중 일부를 발췌했습니다. 특정 시퀀스 번호에 해당되는 Aggregate에 대한 상태 정보가 기입되었으며, 상태정보는 Payload에 담겨있습니다.

Payload 내용

<com.cqrs.command.aggregate.AccountAggregate>
  <accountID>c65f80c3-9c44-4ca6-a977-72983a675203</accountID>
  <holderID>70f956e3-069c-4666-b0f4-324dfb0a807e</holderID>
  <balance>293</balance>
</com.cqrs.command.aggregate.AccountAggregate>

Snapshot 생성 이후 다시 1원을 인출하게되면, 이전 시퀀스 번호인 8번 Snaphot이 존재하므로 전체 Event를 읽어오지 않고 Snapshot정보를 읽어온 다음 Command 명령을 수행합니다.

o.a.commandhandling.SimpleCommandBus     : Handling command [com.cqrs.command.commands.WithdrawMoneyCommand]
org.axonframework.messaging.Scope        : Clearing out ThreadLocal current Scope, as no Scopes are present
c.c.command.aggregate.AccountAggregate   : handling WithdrawMoneyCommand(accountID=c65f80c3-9c44-4ca6-a977-72983a675203, holderID=70f956e3-069c-4666-b0f4-324dfb0a807e, amount=1)
c.c.command.aggregate.AccountAggregate   : applying WithdrawMoneyEvent(holderID=70f956e3-069c-4666-b0f4-324dfb0a807e, accountID=c65f80c3-9c44-4ca6-a977-72983a675203, amount=1)
c.c.command.aggregate.AccountAggregate   : balance 292
org.axonframework.messaging.Scope        : Clearing out ThreadLocal current Scope, as no Scopes are present

Snapshot 생성 이후 5번의 Event 발생까지는 Snapshot 시점 이전부터 생성된 Event가 재생됩니다. 만약 다시 Threshold를 넘어서게 되면 새로운 Snapshot이 생성되고 그 이후부터는 새로운 Snapshot 이후 Event가 재생됩니다.

4. 성능개선

Aggregate를 매번 로딩하면 이를 복원하는데 드는 비용이 지속 수반됩니다. 따라서 자주 사용하는 Aggregate는 Cache를 적용하면 Loading 비용이 줄어들 것입니다. Axon에서 이를 위해 기본적으로 WeakReferenceCache를 제공하며 이를 적용한 Configuration은 다음과 같습니다.

AxonConfig.java

@Configuration
@AutoConfigureAfter(AxonAutoConfiguration.class)
public class AxonConfig {
    @Bean
    public AggregateFactory<AccountAggregate> aggregateFactory(){
        return new GenericAggregateFactory<>(AccountAggregate.class);
    }
    @Bean
    public Snapshotter snapshotter(EventStore eventStore, TransactionManager transactionManager){
        return AggregateSnapshotter
                .builder()
                    .eventStore(eventStore)
                    .aggregateFactories(aggregateFactory())
                    .transactionManager(transactionManager)
                .build();
    }
    @Bean
    public SnapshotTriggerDefinition snapshotTriggerDefinition(EventStore eventStore, TransactionManager transactionManager){
        final int SNAPSHOT_TRHRESHOLD = 5;
        return new EventCountSnapshotTriggerDefinition(snapshotter(eventStore,transactionManager),SNAPSHOT_TRHRESHOLD);
    }

    @Bean
    public Cache cache(){
        return new WeakReferenceCache();
    }

    @Bean
    public Repository<AccountAggregate> accountAggregateRepository(EventStore eventStore, SnapshotTriggerDefinition snapshotTriggerDefinition, Cache cache){
        return CachingEventSourcingRepository
                .builder(AccountAggregate.class)
                    .eventStore(eventStore)
                    .snapshotTriggerDefinition(snapshotTriggerDefinition)
                    .cache(cache)
                .build();
    }
}

5. 마치며

3개의 포스팅을 통해 Command Application을 구현하는 방법에 대해서 살펴보았습니다. 다음 포스팅은 Aggregate 관련 번외편을 진행할 예정입니다. 따라서 데모 프로젝트를 위한 Application 구현은 이번 포스팅이 마지막입니다.