[cilium] Hubble Exporter

 

Hubble Exporter 는 cilium-agent 의 기능으로, 다른 로그 시스템에 통합할 수 있도록 Hubble 로그를 파일로 반출하는 도구입니다.

아래와 같은 주요 기능들을 제공합니다.

• 파일 회전 (File rotation)
• 크기 제한
• 필터링
• 필드 마스킹

static exporter 방식과 dynamic exporter 방식이 존재하며 아래와 같은 차이점이 있습니다.

	static exporter	dynamic exporter
필터 수	하나의 필터 세트만 허용	여러 필터 동시 설정 가능
출력 파일	단일 파일에 저장	다수 파일에 저장
설정 변경	Cilium 파드 재시작 필요	Cilium 파드 재시작 불필요 (60초 이내 반영)

 

dynamic exporter 가 static exporter 방식보다 더 유연하므로 실무에서는 dynamic exporter 를 사용할 것으로 생각합니다.

 

Static Exporter

활성화 과정

Hubble Exporter 는 Cilium 의 Config Map 속성으로 활성화됩니다. Helm 을 통해 Hubble Exporter 를 활성화합니다.

helm install cilium cilium/cilium --reuse-values \
  --set hubble.enabled=true \
  --set hubble.export.static.enabled=true \
  --set hubble.export.static.filePath=/var/run/cilium/hubble/events.log # 기본 경로

 

hubble.enabled=true 및 hubble.export.static.enabled=true(Static Exporter 사용 시)는 필수로 활성화해야 하는 옵션입니다.
다음 옵션들은 선택적으로 활용할 수 있습니다.

옵션	설명	기본 설정
hubble.export.static.filePath	로그 파일의 파일 경로	/var/run/cilium/hubble/events.log
hubble.export.fileMaxSizeMb	순환 주기 대상 hubble export 크기(MB)	10
hubble.export.fileMaxBackups	순환 주기 대상 hubble export 파일 수	5
hubble.export.fileCompress	hubble export 파일 압축 여부	false
hubble.export.static.allowList	hubble export 로그 내용에 포함해야 할 허용 규칙	[]
hubble.export.static.denyList	hubble export 로그 내용에 배제해야 할 거부 규칙	[]
hubble.export.static.fieldMask	hubble export 로그 내용에 표시해야 할 항목

 

hubble 로그를 filepath 옵션으로 파일형태로 저장하는데 hubble-export-file-path 를 stdout 으로 정의하여 로그를 직접 전송할 수도 있습니다.

hubble-export-file-path 에 파일 경로 값을 설정하기 전까지는 비활성화 상태이므로 아래 명령어를 통해 정상 설치 여부를 확인합니다.

cilium config view | grep hubble-export-file-path

 

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 로그를 아래 두 옵션으로 원하는 내용만 필터링할 수 있습니다.

• hubble.export.static.allowList: JSON 인코딩된 FlowFilters 를 allowlist 로 지정
• hubble.export.static.denyList: JSON 인코딩된 FlowFilters 를 denylist 로 지정

자주 사용하여 확인하는 hubble observe 필터 구문이 있다면, 아래처럼 --print--raw-filters 옵션을 통해 allowlist 와 denylist 항목들을 확인할 수 있습니다. 예를 들어, 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 차트를 업데이트하여 사용할 수도 있습니다.

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

 

예를 들어, kube-system namespace 의 모든 로그들을 수집에서 제외하고 싶다면, 아래와 같이 세팅합니다.

$ 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 사용 시에는 아래와 같이 세팅할 수 있습니다.

helm upgrade cilium cilium/cilium --version 1.17.5 \
  --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/"]}'

 

필드 마스킹 적용

필드 마스킹을 통해 hubble 로그에서 원하는 항목만 선택적으로 지정하여 노출을 제어할 수 있습니다.

cilium 이나 hubble 로 직접 생성할 수는 없고, flow proto 정의의 필드 이름 목록 중 선택해서 원하는 항목을 선택할 수 있습니다.

 

예를 들어 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

 

여기서 주의할 것이 Summary 의 S 는 대문자이다. 필자는 Summary 를 summary 로 세팅하다가 아래와 같은 오류를 만났었다.

k -n kube-system logs --timestamps cilium-6562v

...
2025-07-23T15:04:47.991450086+09:00 time="2025-07-23T06:04:47.991308086Z" level=error msg="Failed to apply flowlog for name all: failed to apply option: proto:\u00a0invalid path \"summary\" for message \"flow.Flow\"" subsys=hubble
...

 

타임스탬프, verdict, 포트, IP 주소, 노드 이름, 파드 이름, 네임스페이스만 출력하고 싶으면 다음과 같이 세팅한다.

hubble-export-fieldmask: time source.namespace source.pod_name destination.namespace destination.pod_name l4 IP node_name is_reply verdict

 

설정 예시

helm upgrade cilium cilium/cilium --reuse-values \
  --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}"

 

아래와 같이 /var/run/cilium/hubble/events.log 로그를 직접 확인해보자.

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

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

 

Dynamic Exporter

활성화 과정

Dynamic Exporter 도 Static Exporter 와 마찬가지로 hubble-flowlogs-config-path에 파일 경로 값을 설정할 때까지 비활성화됩니다. 파드 재시작 없이 플로우 로그 설정을 변경할 수 있습니다. (ConfigMap 전파 지연으로 60초 이내 반영)

helm install cilium cilium/cilium --reuse-values \
  --set hubble.enabled=true \
  --set hubble.export.dynamic.enabled=true

 

필수 옵션인 hubble.enable=true 옵션과 hubble.export.dynamic.enabled=true 옵션을 세팅하여 활성화합니다.

최대 출력 파일 크기와 백업 파일 수는 정적 설정과 동일한 설정과 동일합니다.

• hubble.export.fileMaxSizeMb
• hubble.export.fileMaxBackups

Dynamic Export 로그는 end 속성을 사용하여 지정된 날짜 시간 이후 자동으로 로깅을 중단하도록 설정할 수 있습니다.

 

설정 예시

helm upgrade cilium cilium/cilium --reuse-values \
  --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/'

 

아래와 같이 hubble-exporter-dynamic.yml 파일로 작성하고, helm upgrade 명령어를 통해 설정을 변경할 수 있습니다.

(사실 Static Exporter 도 yml 파일을 작성하여 적용할 수 있습니다.)

helm upgrade cilium cilium/cilium -n kube-system --reuse-values -f hubble-exporter-dynamic.yml

hubble:
  export:
    dynamic:
      enabled: true
      config:
        enabled: true
        content:
        - name: "all"
          filePath: "/var/run/cilium/hubble/testtest.log"
          fieldMask: ["time", "source.namespace", "source.pod_name", "destination.namespace", "destination.pod_name", "verdict", "summary"]
          includeFilters: []
          excludeFilters: []
        - name: "drop"
          filePath: "/var/run/cilium/hubble/test.log"
          fieldMask: ["time", "source.namespace", "source.pod_name", "destination.namespace", "destination.pod_name", "verdict", "summary"]
          includeFilters:
          - destination_pod: ["default/deathstar"]
          excludeFilters:
          - source_pod: ["kube-system/"]
          - destination_pod: ["kube-system/"]

 

static exporter 의 allowList 와 denyList 가 dynamic exporter 에서는 includeFilters 와 excludeFilters 옵션인 부분만 조심하면 나머지는 같습니다.

필자는 https://g-egg.tistory.com/174 이 network policy 를 적용하고 drop 된 패킷들을 확인해보려고 했지만, "all" dynamic exporter 에서도 나오지 않아 확인이 어려웠다.