Hubble 관측성 설정
Hubble 관측성 설정 (Setting up Hubble Observability)
Hubble은 Cilium의 관측성 레이어로, Kubernetes 클러스터의 네트워크와 보안 레이어에 대한 클러스터 전역 가시성을 얻는 데 사용돼요. 이 가이드에서는 Hubble을 활성화하고 Hubble CLI를 설치해 API에 접근하는 방법을 다룹니다.
본문
Note
이 가이드는 Cilium이 Kubernetes 클러스터에 올바르게 설치되어 있다고 가정해요. 자세한 내용은 Cilium 빠른 설치를 참고하세요. 확실하지 않다면
cilium status를 실행해 Cilium이 실행 중인지 확인하세요.
Cilium에서 Hubble 활성화
Tip
Hubble을 활성화하려면 Cilium을 실행하는 모든 노드에서 TCP 포트 4244가 열려 있어야 해요. Relay가 올바르게 동작하기 위해 필요합니다.
Cilium CLI
Hubble을 활성화하고 Hubble relay를 설치하려면 아래와 같이 cilium hubble enable 명령을 실행하세요:
$ cilium hubble enable
🔑 Found existing CA in secret cilium-ca
✨ Patching ConfigMap cilium-config to enable Hubble...
♻️ Restarted Cilium pods
🔑 Generating certificates for Relay...
2021/04/13 17:11:23 [INFO] generate received request
2021/04/13 17:11:23 [INFO] received CSR
2021/04/13 17:11:23 [INFO] generating key: ecdsa-256
2021/04/13 17:11:23 [INFO] encoded CSR
2021/04/13 17:11:23 [INFO] signed certificate with serial number 365589302067830033295858933512588007090526050046
2021/04/13 17:11:24 [INFO] generate received request
2021/04/13 17:11:24 [INFO] received CSR
2021/04/13 17:11:24 [INFO] generating key: ecdsa-256
2021/04/13 17:11:24 [INFO] encoded CSR
2021/04/13 17:11:24 [INFO] signed certificate with serial number 644167683731852948186644541769558498727586273511
✨ Deploying Relay...
Helm
helm install로 Cilium을 설치했다면 Hubble은 기본적으로 활성화되어 있어요. 다음 명령으로 Hubble Relay를 활성화할 수 있습니다:
Helm Repository
helm upgrade cilium cilium/cilium --version 1.20.2 \
--namespace kube-system \
--reuse-values \
--set hubble.relay.enabled=true
OCI Registry
helm upgrade cilium oci://quay.io/cilium/charts/cilium 1.20.2 \
--namespace kube-system \
--reuse-values \
--set hubble.relay.enabled=true
Hubble이 활성화되어 실행 중인지 cilium status로 확인하세요:
$ cilium status
/¯¯\
/¯¯\__/¯¯\ Cilium: OK
\__/¯¯\__/ Operator: OK
/¯¯\__/¯¯\ Envoy DaemonSet: OK
\__/¯¯\__/ Hubble Relay: OK
\__/ ClusterMesh: disabled
DaemonSet cilium Desired: 1, Ready: 1/1, Available: 1/1
DaemonSet cilium-envoy Desired: 1, Ready: 1/1, Available: 1/1
Deployment cilium-operator Desired: 1, Ready: 1/1, Available: 1/1
Deployment hubble-relay Desired: 1, Ready: 1/1, Available: 1/1
Containers: cilium Running: 1
cilium-envoy Running: 1
cilium-operator Running: 1
clustermesh-apiserver
hubble-relay Running: 1
Cluster Pods: 8/8 managed by Cilium
Helm chart version: 1.17.0
Image versions cilium quay.io/cilium/cilium:latest: 1
cilium-envoy quay.io/cilium/cilium-envoy:v1.32.3-1739240299-e85e926b0fa4cec519cefff54b60bd7942d7871b@sha256:ced8a89d642d10d648471afc2d8737238f1479c368955e6f2553ded58029ac88: 1
cilium-operator quay.io/cilium/operator-generic-ci:latest: 1
hubble-relay quay.io/cilium/hubble-relay-ci:latest: 1
Hubble 클라이언트 설치
Hubble이 수집한 관측성 데이터에 접근하려면 먼저 Hubble CLI를 설치해야 해요.
아래에서 자신의 플랫폼에 맞는 탭을 선택하고 Hubble CLI 최신 릴리스를 설치하세요.
Linux
최신 hubble 릴리스를 다운로드하세요:
HUBBLE_VERSION=$(curl -s https://raw.githubusercontent.com/cilium/hubble/main/stable.txt)
HUBBLE_ARCH=amd64
if [ "$(uname -m)" = "aarch64" ]; then HUBBLE_ARCH=arm64; fi
curl -L --fail --remote-name-all https://github.com/cilium/hubble/releases/download/$HUBBLE_VERSION/hubble-linux-${HUBBLE_ARCH}.tar.gz{,.sha256sum}
sha256sum --check hubble-linux-${HUBBLE_ARCH}.tar.gz.sha256sum
sudo tar xzvfC hubble-linux-${HUBBLE_ARCH}.tar.gz /usr/local/bin
rm hubble-linux-${HUBBLE_ARCH}.tar.gz{,.sha256sum}
MacOS
최신 hubble 릴리스를 다운로드하세요:
HUBBLE_VERSION=$(curl -s https://raw.githubusercontent.com/cilium/hubble/main/stable.txt)
HUBBLE_ARCH=amd64
if [ "$(uname -m)" = "arm64" ]; then HUBBLE_ARCH=arm64; fi
curl -L --fail --remote-name-all https://github.com/cilium/hubble/releases/download/$HUBBLE_VERSION/hubble-darwin-${HUBBLE_ARCH}.tar.gz{,.sha256sum}
shasum -a 256 -c hubble-darwin-${HUBBLE_ARCH}.tar.gz.sha256sum
sudo tar xzvfC hubble-darwin-${HUBBLE_ARCH}.tar.gz /usr/local/bin
rm hubble-darwin-${HUBBLE_ARCH}.tar.gz{,.sha256sum}
Windows
최신 hubble 릴리스를 다운로드하세요:
curl -LO "https://raw.githubusercontent.com/cilium/hubble/main/stable.txt"
set /p HUBBLE_VERSION=<stable.txt
curl -L --fail -O "https://github.com/cilium/hubble/releases/download/%HUBBLE_VERSION%/hubble-windows-amd64.tar.gz"
curl -L --fail -O "https://github.com/cilium/hubble/releases/download/%HUBBLE_VERSION%/hubble-windows-amd64.tar.gz.sha256sum"
certutil -hashfile hubble-windows-amd64.tar.gz SHA256
type hubble-windows-amd64.tar.gz.sha256sum
:: verify that the checksum from the two commands above match
tar zxf hubble-windows-amd64.tar.gz
그리고 tarball에서 추출한 hubble.exe CLI를 %PATH% 환경변수에 있는 디렉터리로 이동하세요.
Hubble API 접근 검증
Note
다음 명령들은
-P(--port-forward) 플래그를 사용해 로컬 머신의4245포트에서 Hubble Relay 서비스를 자동으로 포트 포워딩해요.
플래그를 생략하고 Cilium CLI로 포트 포워딩을 직접 만들 수도 있어요:
$ cilium hubble port-forward
ℹ️ Hubble Relay is available at 127.0.0.1:4245
또는 kubectl을 사용할 수도 있어요:
$ kubectl -n kube-system port-forward service/hubble-relay 4245:80
Forwarding from 127.0.0.1:4245 -> 4245
Forwarding from [::1]:4245 -> 4245
이 방법에 대한 자세한 내용은 클러스터에서 애플리케이션에 접근하기 위해 포트 포워딩 사용하기 문서를 참고하세요.
이제 설치된 CLI로 Hubble API에 접근할 수 있는지 검증해 보세요:
$ hubble status -P
Healthcheck (via 127.0.0.1:4245): Ok
Current/Max Flows: 11917/12288 (96.98%)
Flows/s: 11.74
Connected Nodes: 3/3
플로우 API를 조회해서 플로우를 찾을 수도 있어요:
$ hubble observe -P
Feb 12 19:13:58.111: kube-system/hubble-relay-6467f4f4d-xrxfs:47550 (ID:95552) -> 172.18.0.2:4244 (host) to-stack FORWARDED (TCP Flags: ACK, PSH)
...
Note
4245이외의 포트로 포트 포워딩한다면(자동 포트 포워딩을 사용할 때--port-forward-port PORT),--server플래그나HUBBLE_SERVER환경변수를 사용해 Hubble 서버 주소를 설정해야 해요(기본값:localhost:4245).
자세한 내용은 hubble help status나 hubble help observe를 실행해 Hubble CLI 도움말을 확인하고, Hubble CLI 구성에는 hubble config를 사용하세요.
Note
TLS를 활성화했다면 Hubble API에 접근하기 위해 추가 플래그를 지정해야 해요.
Hubble 배포 트러블슈팅
cilium status를 실행해 Hubble 및/또는 Hubble Relay의 상태를 검증하세요:
$ cilium status
/¯¯\
/¯¯\__/¯¯\ Cilium: OK
\__/¯¯\__/ Operator: OK
/¯¯\__/¯¯\ Envoy DaemonSet: OK
\__/¯¯\__/ Hubble Relay: OK
\__/ ClusterMesh: disabled
DaemonSet cilium Desired: 1, Ready: 1/1, Available: 1/1
DaemonSet cilium-envoy Desired: 1, Ready: 1/1, Available: 1/1
Deployment cilium-operator Desired: 1, Ready: 1/1, Available: 1/1
Deployment hubble-relay Desired: 1, Ready: 1/1, Available: 1/1
Containers: cilium Running: 1
cilium-envoy Running: 1
cilium-operator Running: 1
clustermesh-apiserver
hubble-relay Running: 1
Cluster Pods: 8/8 managed by Cilium
Helm chart version: 1.17.0
Image versions cilium quay.io/cilium/cilium:latest: 1
cilium-envoy quay.io/cilium/cilium-envoy:v1.32.3-1739240299-e85e926b0fa4cec519cefff54b60bd7942d7871b@sha256:ced8a89d642d10d648471afc2d8737238f1479c368955e6f2553ded58029ac88: 1
cilium-operator quay.io/cilium/operator-generic-ci:latest: 1
hubble-relay quay.io/cilium/hubble-relay-ci:latest: 1
Hubble Relay
Hubble Relay가 활성화되어 있으면 cilium status에 OK가 표시되어야 해요. 그렇지 않다면 오류/경고가 보고되는 것을 볼 수 있어요:
$ cilium status
/¯¯\
/¯¯\__/¯¯\ Cilium: OK
\__/¯¯\__/ Operator: OK
/¯¯\__/¯¯\ Envoy DaemonSet: OK
\__/¯¯\__/ Hubble Relay: 1 errors, 2 warnings
\__/ ClusterMesh: disabled
DaemonSet cilium Desired: 1, Ready: 1/1, Available: 1/1
DaemonSet cilium-envoy Desired: 1, Ready: 1/1, Available: 1/1
Deployment cilium-operator Desired: 1, Ready: 1/1, Available: 1/1
Deployment hubble-relay Desired: 1, Unavailable: 1/1
Containers: cilium Running: 1
cilium-envoy Running: 1
cilium-operator Running: 1
clustermesh-apiserver
hubble-relay Pending: 1
Cluster Pods: 8/8 managed by Cilium
Helm chart version: 1.17.0
Image versions cilium quay.io/cilium/cilium:latest: 1
cilium-envoy quay.io/cilium/cilium-envoy:v1.32.3-1739240299-e85e926b0fa4cec519cefff54b60bd7942d7871b@sha256:ced8a89d642d10d648471afc2d8737238f1479c368955e6f2553ded58029ac88: 1
cilium-operator quay.io/cilium/operator-generic-ci:latest: 1
hubble-relay quay.io/cilium/hubble-relay-ci:latest-: 1
Errors: hubble-relay hubble-relay 1 pods of Deployment hubble-relay are not ready
Warnings: hubble-relay hubble-relay-85f98cc7df-s2lkq pod is pending
hubble-relay hubble-relay-85f98cc7df-s2lkq pod is pending
Tip
Cilium과Hubble Relay둘 다에 대해 경고나 오류가 보고된다면, 보통 Hubble 구성이 잘못되었거나 Hubble 시스템이 시작에 실패했음을 의미해요. Hubble은 Cilium Agent 안에서 실행되는 비핵심 시스템이므로, Hubble이 시작에 실패해도 Cilium 파드는 계속 실행되고 정상 상태를 유지하는 것이 정상이에요. Hubble 관련 트러블슈팅 단계는 아래의 Hubble 섹션을 참고하세요.
파드 상태를 다음으로 확인하세요:
$ kubectl -n kube-system get pods -l k8s-app=hubble-relay
NAME READY STATUS RESTARTS AGE
hubble-relay-6467f4f4d-x825b 0/1 CrashLoopBackOff 5 (19s ago) 7m28s
하나 이상의 파드가 Pending 상태라면 다음으로 파드를 describe 하세요:
$ kubectl describe -n kube-system pod/cilium-5bjkq
Name: hubble-relay-6467f4f4d-x825b
Namespace: kube-system
...
하나 이상의 파드가 Running 상태가 아니라면 파드 로그를 확인하세요:
$ kubectl -n kube-system logs hubble-relay-6467f4f4d-x825b
time="2025-02-12T21:21:40.246596435Z" level=info msg="Starting gRPC health server..." addr=":4222" subsys=hubble-relay
time="2025-02-12T21:21:40.246611018Z" level=info msg="Starting gRPC server..." options="{peerTarget:hubble-peer.kube-system.svc.cluster.local.:443 retryTimeout:30000000000 listenAddress::4245 healthListenAddress::4222 metricsListenAddress: log:0x400038fc00 serverTLSConfig:<nil> insecureServer:true clientTLSConfig:0x4000b12528 clusterName:cluster insecureClient:false observerOptions:[0x28cb1e0 0x28cb2e0] grpcMetrics:<nil> grpcUnaryInterceptors:[] grpcStreamInterceptors:[]}" subsys=hubble-relay
time="2025-02-12T21:21:40.251658493Z" level=info msg="Failed to create peer notify client for peers change notification; will try again after the timeout has expired" connection timeout=30s error="rpc error: code = Unavailable desc = connection error: desc = \"transport: Error while dialing: dial tcp 10.96.49.4:443: connect: connection refused\"" subsys=hubble-relay
time="2025-02-12T21:22:10.25956541Z" level=info msg="Failed to create peer notify client for peers change notification; will try again after the timeout has expired" connection timeout=30s error="rpc error: code = Unavailable desc = connection error: desc = \"transport: Error while dialing: dial tcp 10.96.49.4:443: connect: connection refused\"" subsys=hubble-relay
time="2025-02-12T21:22:40.265123839Z" level=info msg="Failed to create peer notify client for peers change notification; will try again after the timeout has expired" connection timeout=30s error="rpc error: code = Unavailable desc = connection error: desc = \"transport: Error while dialing: dial tcp 10.96.49.4:443: connect: connection refused\"" subsys=hubble-relay
time="2025-02-12T21:22:49.055746359Z" level=info msg="Stopping server..." subsys=hubble-relay
time="2025-02-12T21:22:49.056293486Z" level=info msg="Server stopped" subsys=hubble-relay
connection refused 오류가 발생하면 Hubble-Relay가 hubble-peer 서비스를 통해 Cilium 에이전트가 노출하는 Hubble API에 연결할 수 없다는 뜻이에요. Hubble 관련 트러블슈팅 단계는 아래의 Hubble 섹션을 참고하세요.
TLS 관련 오류는 Hubble TLS 트러블슈팅을 참고하세요.
Hubble
Hubble이 활성화되어 있으면 cilium status에 Cilium이 OK라고 표시되어야 해요. 그렇지 않다면 오류/경고가 보고되는 것을 볼 수 있어요:
$ cilium status
/¯¯\
/¯¯\__/¯¯\ Cilium: 1 warnings
\__/¯¯\__/ Operator: OK
/¯¯\__/¯¯\ Envoy DaemonSet: OK
\__/¯¯\__/ Hubble Relay: 1 errors
\__/ ClusterMesh: disabled
DaemonSet cilium Desired: 1, Ready: 1/1, Available: 1/1
DaemonSet cilium-envoy Desired: 1, Ready: 1/1, Available: 1/1
Deployment cilium-operator Desired: 1, Ready: 1/1, Available: 1/1
Deployment hubble-relay Desired: 1, Unavailable: 1/1
Containers: cilium Running: 1
cilium-envoy Running: 1
cilium-operator Running: 1
clustermesh-apiserver
hubble-relay Running: 1
Cluster Pods: 8/8 managed by Cilium
Helm chart version: 1.17.0
Image versions cilium quay.io/cilium/cilium:latest: 1
cilium-envoy quay.io/cilium/cilium-envoy:v1.32.3-1739240299-e85e926b0fa4cec519cefff54b60bd7942d7871b@sha256:ced8a89d642d10d648471afc2d8737238f1479c368955e6f2553ded58029ac88: 1
cilium-operator quay.io/cilium/operator-generic-ci:latest: 1
hubble-relay quay.io/cilium/hubble-relay-ci:latest: 1
Errors: hubble-relay hubble-relay 1 pods of Deployment hubble-relay are not ready
Warnings: cilium cilium-5bjkq Hubble: failed to setup metrics: metric 'unknown-metric' does not exist
파드 상태를 다음으로 확인하세요:
$ kubectl -n kube-system get pods -l k8s-app=cilium
NAME READY STATUS RESTARTS AGE
cilium-5bjkq 1/1 Running 1 (18m ago) 33m
하나 이상의 파드가 Pending 상태라면 다음으로 파드를 describe 하세요:
$ kubectl describe -n kube-system pod/cilium-5bjkq
Name: cilium-5bjkq
Namespace: kube-system
...
하나 이상의 파드가 Running 상태가 아니라면 파드 로그를 확인하세요:
$ kubectl logs -n kube-system -c cilium-agent -l k8s-app=cilium --tail=-1 | grep subsys=hubble
time="2025-02-12T22:12:01.227357082Z" level=info msg="Starting Hubble Metrics server" address=":9965" metrics=unknown-metric subsys=hubble tls=false
time="2025-02-12T22:12:01.22740229Z" level=error msg="Failed to launch hubble" error="failed to setup metrics: metric 'unknown-metric' does not exist" subsys=hubble