Hubble exporter 구성

Hubble exporter 구성 (Configuring Hubble exporter)

Hubble Exporter는 cilium-agent의 기능으로, Hubble 흐름(flow)을 파일로 기록해 나중에 로그로 활용할 수 있게 해줘요. 파일 회전, 크기 제한, 필터, 필드 마스킹을 지원합니다. 이 문서에서는 기본 구성과 동적(dynamic) 구성 방법을 다룹니다.

출처: Configuring Hubble exporter

본문

사전 준비 사항 (Prerequisites)

Helm 저장소를 설정하세요:

Helm Repository

helm repo add cilium https://helm.cilium.io/

OCI Registry

Cilium 차트는 OCI 레지스트리(Quay.io 및 Docker Hub)에서도 제공돼요. 별도 설정 없이 oci:// URL로 바로 설치할 수 있습니다.

차트 서명 검증과 다이제스트 기반 설치를 포함한 자세한 내용은 OCI Registry 섹션을 참고하세요.

기본 구성 (Basic Configuration)

설정 (Setup)

Hubble Exporter는 Config Map 속성으로 활성화돼요. hubble-export-file-path에 파일 경로 값을 설정하기 전까지는 비활성화 상태입니다.

hubble exporter를 활성화한 상태로 cilium을 helm으로 설치할 수 있어요:

Helm Repository

helm install cilium cilium/cilium --version 1.20.2 \
   --namespace kube-system \
   --set hubble.enabled=true \
   --set hubble.export.static.enabled=true \
   --set hubble.export.static.filePath=/var/run/cilium/hubble/events.log

OCI Registry

helm install cilium oci://quay.io/cilium/charts/cilium 1.20.2 \
   --namespace kube-system \
   --set hubble.enabled=true \
   --set hubble.export.static.enabled=true \
   --set hubble.export.static.filePath=/var/run/cilium/hubble/events.log

cilium 파드가 준비될 때까지 기다리세요:

kubectl -n kube-system rollout status ds/cilium

플로우 로그가 대상 파일에 저장되는지 확인하세요:

kubectl -n kube-system exec ds/cilium -- tail -f /var/run/cilium/hubble/events.log

Hubble Exporter를 구성했다면, 로깅 솔루션이 Hubble 내보내기 파일 경로에서 로그를 가져오도록 구성하면 돼요.

Hubble 흐름을 회전 파일에 쓰지 않고 로그로 직접 내보내려면, stdout을 hubble-export-file-path로 지정하면 됩니다.

정적 구성을 비활성화하려면 cilium-config ConfigMap에서 hubble-export-file-path 키를 제거하고, 컨테이너의 지정된 위치에 생성된 로그 파일을 수동으로 정리해야 해요. 아래 명령은 Cilium 파드를 재시작합니다. ConfigMap을 수동으로 편집했다면 Cilium 파드를 재시작해야 합니다.

cilium config delete hubble-export-file-path

구성 옵션 (Configuration options)

Helm 차트 구성 옵션은 다음과 같아요:

  • hubble.export.static.filePath: 대상 로그 파일의 경로. (기본값 /var/run/cilium/hubble/events.log)
  • hubble.export.static.fileMaxSizeMb: Hubble 내보내기 파일을 회전할 크기(MB). (기본값 10)
  • hubble.export.static.fileMaxBackups: 보관할 회전된 Hubble 내보내기 파일의 개수. (기본값 5)
  • hubble.export.static.fileCompress: 회전된 파일의 압축 활성화. (기본값 false)

성능 튜닝 (Performance tuning)

Hubble exporter의 성능에 영향을 주는 구성 옵션은 다음과 같아요:

  • hubble.export.static.allowList: Hubble exporter에 JSON 인코딩된 FlowFilters로 allowlist를 지정.
  • hubble.export.static.denyList: Hubble exporter에 JSON 인코딩된 FlowFilters로 denylist를 지정.
  • hubble.export.static.fieldMask: Hubble exporter에서 필드 마스킹에 사용할 필드 목록을 지정.

필터 (Filters)

hubble CLI를 사용해 필요한 필터를 생성할 수 있어요 (원시 흐름 필터 지정에서 더 많은 예제를 확인하세요).

예를 들어, verdict가 DENIED 또는 ERROR인 흐름을 필터링하려면 다음을 실행하세요:

$ hubble observe --verdict DROPPED --verdict ERROR --print-raw-filters
allowlist:
- '{"verdict":["DROPPED","ERROR"]}'

그런 다음 출력을 cilium-config Config Map의 hubble-export-allowlist에 붙여 넣으세요:

kubectl -n kube-system patch cm cilium-config --patch-file=/dev/stdin <<-EOF
data:
  hubble-export-allowlist: '{"verdict":["DROPPED","ERROR"]}'
EOF

또는 helm 차트를 사용해 cilium 설치의 hubble.export.static.allowList 값 플래그를 업데이트할 수도 있어요.

Helm Repository

helm upgrade cilium cilium/cilium --version 1.20.2 \
   --namespace kube-system \
   --set hubble.enabled=true \
   --set hubble.export.static.enabled=true \
   --set hubble.export.static.allowList[0]='{"verdict":["DROPPED","ERROR"]}'

OCI Registry

helm upgrade cilium oci://quay.io/cilium/charts/cilium 1.20.2 \
   --namespace kube-system \
   --set hubble.enabled=true \
   --set hubble.export.static.enabled=true \
   --set hubble.export.static.allowList[0]='{"verdict":["DROPPED","ERROR"]}'

데이터를 선택적으로 필터링하려면 같은 방법을 사용할 수 있어요. 예를 들어 kube-system 네임스페이스의 모든 흐름을 필터링하려면 다음을 실행하세요:

$ hubble observe --not --namespace kube-system --print-raw-filters
denylist:
- '{"source_pod":["kube-system/"]}'
- '{"destination_pod":["kube-system/"]}'

그런 다음 출력을 cilium-config Config Map의 hubble-export-denylist에 붙여 넣으세요:

kubectl -n kube-system patch cm cilium-config --patch-file=/dev/stdin <<-EOF
data:
  hubble-export-denylist: '{"source_pod":["kube-system/"]},{"destination_pod":["kube-system/"]}'
EOF

또는 helm 차트를 사용해 cilium 설치의 hubble.export.static.denyList 값 플래그를 업데이트할 수도 있어요.

Helm Repository

helm upgrade cilium cilium/cilium --version 1.20.2 \
   --namespace kube-system \
   --set hubble.enabled=true \
   --set hubble.export.static.enabled=true \
   --set hubble.export.static.denyList[0]='{"source_pod":["kube-system/"]}' \
   --set hubble.export.static.denyList[1]='{"destination_pod":["kube-system/"]}'

OCI Registry

helm upgrade cilium oci://quay.io/cilium/charts/cilium 1.20.2 \
   --namespace kube-system \
   --set hubble.enabled=true \
   --set hubble.export.static.enabled=true \
   --set hubble.export.static.denyList[0]='{"source_pod":["kube-system/"]}' \
   --set hubble.export.static.denyList[1]='{"destination_pod":["kube-system/"]}'

필드 마스크 (Field mask)

필드 마스크는 hubble로 생성할 수 없어요. 필드 마스크는 flow proto 정의의 필드 이름 목록입니다.

예를 들면:

  • 파드 라벨을 제외한 모든 정보를 유지하려면: hubble-export-fieldmask: time source.identity source.namespace source.pod_name destination.identity destination.namespace destination.pod_name source_service destination_service l4 IP ethernet l7 Type node_name is_reply event_type verdict Summary
  • 타임스탬프, verdict, 포트, IP 주소, 노드 이름, 파드 이름, 네임스페이스만 유지하려면: hubble-export-fieldmask: time source.namespace source.pod_name destination.namespace destination.pod_name l4 IP node_name is_reply verdict

다음은 Hubble Exporter를 구성하는 완전한 예시예요.

  • Configuration: (Helm Repository)
helm upgrade cilium cilium/cilium --version 1.20.2 \
   --namespace kube-system \
   --set hubble.enabled=true \
   --set hubble.export.static.enabled=true \
   --set hubble.export.static.filePath=/var/run/cilium/hubble/events.log \
   --set hubble.export.static.allowList[0]='{"verdict":["DROPPED","ERROR"]}' \
   --set hubble.export.static.denyList[0]='{"source_pod":["kube-system/"]}' \
   --set hubble.export.static.denyList[1]='{"destination_pod":["kube-system/"]}' \
   --set "hubble.export.static.fieldMask={time,source.namespace,source.pod_name,destination.namespace,destination.pod_name,l4,IP,node_name,is_reply,verdict,drop_reason_desc}"
  • Command:
kubectl -n kube-system exec ds/cilium -- tail -f /var/run/cilium/hubble/events.log
  • Output:
{"flow":{"time":"2023-08-21T12:12:13.517394084Z","verdict":"DROPPED","IP":{"source":"fe80::64d8:8aff:fe72:fc14","destination":"ff02::2","ipVersion":"IPv6"},"l4":{"ICMPv6":{"type":133}},"source":{},"destination":{},"node_name":"kind-kind/kind-worker","drop_reason_desc":"INVALID_SOURCE_IP"},"node_name":"kind-kind/kind-worker","time":"2023-08-21T12:12:13.517394084Z"}
{"flow":{"time":"2023-08-21T12:12:18.510175415Z","verdict":"DROPPED","IP":{"source":"10.244.1.60","destination":"10.244.1.5","ipVersion":"IPv4"},"l4":{"TCP":{"source_port":44916,"destination_port":80,"flags":{"SYN":true}}},"source":{"namespace":"default","pod_name":"xwing"},"destination":{"namespace":"default","pod_name":"deathstar-7848d6c4d5-th9v2"},"node_name":"kind-kind/kind-worker","drop_reason_desc":"POLICY_DENIED"},"node_name":"kind-kind/kind-worker","time":"2023-08-21T12:12:18.510175415Z"}

동적 exporter 구성 (Dynamic exporter configuration)

표준 hubble exporter 구성은 한 세트의 필터만 받으며, 구성을 변경하려면 cilium 파드 재시작이 필요해요. 동적 흐름 로그(dynamic flow logs)는 여러 필터를 동시에 구성하고 출력을 별도의 파일에 저장할 수 있게 해줍니다. 또한 변경된 구성을 적용하기 위해 cilium 파드 재시작이 필요하지 않아요.

Dynamic Hubble Exporter는 Config Map 속성으로 활성화돼요. hubble-flowlogs-config-path에 파일 경로 값을 설정하기 전까지는 비활성화 상태입니다.

동적 exporter를 활성화한 상태로 cilium을 설치하세요:

Helm Repository

helm install cilium cilium/cilium --version 1.20.2 \
   --namespace kube-system \
   --set hubble.enabled=true \
   --set hubble.export.dynamic.enabled=true

OCI Registry

helm install cilium oci://quay.io/cilium/charts/cilium 1.20.2 \
   --namespace kube-system \
   --set hubble.enabled=true \
   --set hubble.export.dynamic.enabled=true

cilium 파드가 준비될 때까지 기다리세요:

kubectl -n kube-system rollout status ds/cilium

파드를 재시작하지 않고도 흐름 로그 설정을 변경할 수 있어요 (configmap 전파 지연 때문에 60초 이내에 변경 사항이 반영됩니다):

Helm Repository

helm upgrade cilium cilium/cilium --version 1.20.2 \
   --namespace kube-system \
   --set hubble.enabled=true \
   --set hubble.export.dynamic.enabled=true \
   --set hubble.export.dynamic.config.content[0].name=system \
   --set hubble.export.dynamic.config.content[0].filePath=/var/run/cilium/hubble/events-system.log \
   --set hubble.export.dynamic.config.content[0].includeFilters[0].source_pod[0]='kube_system/' \
   --set hubble.export.dynamic.config.content[0].includeFilters[1].destination_pod[0]='kube_system/'

OCI Registry

helm upgrade cilium oci://quay.io/cilium/charts/cilium 1.20.2 \
   --namespace kube-system \
   --set hubble.enabled=true \
   --set hubble.export.dynamic.enabled=true \
   --set hubble.export.dynamic.config.content[0].name=system \
   --set hubble.export.dynamic.config.content[0].filePath=/var/run/cilium/hubble/events-system.log \
   --set hubble.export.dynamic.config.content[0].includeFilters[0].source_pod[0]='kube_system/' \
   --set hubble.export.dynamic.config.content[0].includeFilters[1].destination_pod[0]='kube_system/'

동적 흐름 로그는 end 속성으로 구성할 수 있는데, 지정된 날짜·시간 이후에는 자동으로 로깅을 중단한다는 뜻이에요. 정적 hubble exporter와 동일한 필드 마스킹과 필터링을 지원합니다.

파일 회전은 흐름 로그 항목별로 구성돼요. 각 항목은 자신만의 fileMaxSizeMb, fileMaxBackups, fileCompress 설정을 받습니다. 항목이 이 설정을 생략하면 기본값이 사용돼요 (fileMaxSizeMb: 10, fileMaxBackups: 5, fileCompress: false).

샘플 동적 흐름 로그 구성:

hubble:
  export:
    dynamic:
      enabled: true
      config:
        enabled: true
        content:
        - name: "test001"
          filePath: "/var/run/cilium/hubble/test001.log"
          fieldMask: []
          includeFilters: []
          excludeFilters: []
          end: "2023-10-09T23:59:59-07:00"
        - name: "test002"
          filePath: "/var/run/cilium/hubble/test002.log"
          fieldMask: ["source.namespace", "source.pod_name", "destination.namespace", "destination.pod_name", "verdict"]
          fileMaxSizeMb: 100
          fileMaxBackups: 2
          fileCompress: true
          includeFilters:
          - source_pod: ["default/"]
            event_type:
            - type: 1
          - destination_pod: ["frontend/webserver-975996d4c-7hhgt"]
          excludeFilters: []
          end: "2023-10-09T23:59:59-07:00"
        - name: "test003"
          filePath: "/var/run/cilium/hubble/test003.log"
          fieldMask: ["source", "destination","verdict"]
          includeFilters: []
          excludeFilters:
          - destination_pod: ["ingress/"]

더 알아보기 (Learn more)