ztunnel 연결 문제 트러블슈팅하기
ztunnel 연결 문제 트러블슈팅하기 (Troubleshoot connectivity issues with ztunnel)
이 가이드는 ztunnel 프록시 구성과 데이터 경로를 모니터링하는 몇 가지 옵션을 설명해요. 이 정보는 높은 수준의 트러블슈팅에도 도움이 되며, 문제가 있을 때 버그 리포트에서 수집해 제공하면 유용한 정보를 식별하는 데도 도움이 돼요.
출처: Istio 문서
본문
ztunnel 프록시 상태 보기 (Viewing ztunnel proxy state)
ztunnel 프록시는 xDS API를 통해 istiod 컨트롤 플레인에서 구성과 발견 정보를 받아요.
istioctl ztunnel-config 명령은 ztunnel 프록시가 본 발견된 워크로드를 볼 수 있게 해줘요.
첫 번째 예제에서, ztunnel이 현재 추적하는 모든 워크로드와 컨트롤 플레인 컴포넌트를 볼 수 있어요. 여기에는 IP 주소, 그 컴포넌트에 연결할 때 사용할 프로토콜 정보, 그 워크로드에 연관된 웨이포인트 프록시가 있는지 여부가 포함돼요.
$ istioctl ztunnel-config workloads
NAMESPACE POD NAME IP NODE WAYPOINT PROTOCOL
default bookinfo-gateway-istio-59dd7c96db-q9k6v 10.244.1.11 ambient-worker None TCP
default details-v1-cf74bb974-5sqkp 10.244.1.5 ambient-worker None HBONE
default productpage-v1-87d54dd59-fn6vw 10.244.1.10 ambient-worker None HBONE
default ratings-v1-7c4bbf97db-zvkdw 10.244.1.6 ambient-worker None HBONE
default reviews-v1-5fd6d4f8f8-knbht 10.244.1.16 ambient-worker None HBONE
default reviews-v2-6f9b55c5db-c94m2 10.244.1.17 ambient-worker None HBONE
default reviews-v3-7d99fd7978-7rgtd 10.244.1.18 ambient-worker None HBONE
default curl-7656cf8794-r7zb9 10.244.1.12 ambient-worker None HBONE
istio-system istiod-7ff4959459-qcpvp 10.244.2.5 ambient-worker2 None TCP
istio-system ztunnel-6hvcw 10.244.1.4 ambient-worker None TCP
istio-system ztunnel-mf476 10.244.2.6 ambient-worker2 None TCP
istio-system ztunnel-vqzf9 10.244.0.6 ambient-control-plane None TCP
kube-system coredns-76f75df574-2sms2 10.244.0.3 ambient-control-plane None TCP
kube-system coredns-76f75df574-5bf9c 10.244.0.2 ambient-control-plane None TCP
local-path-storage local-path-provisioner-7577fdbbfb-pslg6 10.244.0.4 ambient-control-plane None TCP
ztunnel-config 명령은 ztunnel 프록시가 mTLS에 사용하기 위해 istiod 컨트롤 플레인에서 받은 TLS 인증서를 담은 시크릿을 보는 데 사용할 수 있어요.
$ istioctl ztunnel-config certificates "$ZTUNNEL".istio-system
CERTIFICATE NAME TYPE STATUS VALID CERT SERIAL NUMBER NOT AFTER NOT BEFORE
spiffe://cluster.local/ns/default/sa/bookinfo-details Leaf Available true c198d859ee51556d0eae13b331b0c259 2024-05-05T09:17:47Z 2024-05-04T09:15:47Z
spiffe://cluster.local/ns/default/sa/bookinfo-details Root Available true bad086c516cce777645363cb8d731277 2034-04-24T03:31:05Z 2024-04-26T03:31:05Z
spiffe://cluster.local/ns/default/sa/bookinfo-productpage Leaf Available true 64c3828993c7df6f85a601a1615532cc 2024-05-05T09:17:47Z 2024-05-04T09:15:47Z
spiffe://cluster.local/ns/default/sa/bookinfo-productpage Root Available true bad086c516cce777645363cb8d731277 2034-04-24T03:31:05Z 2024-04-26T03:31:05Z
spiffe://cluster.local/ns/default/sa/bookinfo-ratings Leaf Available true 720479815bf6d81a05df8a64f384ebb0 2024-05-05T09:17:47Z 2024-05-04T09:15:47Z
spiffe://cluster.local/ns/default/sa/bookinfo-ratings Root Available true bad086c516cce777645363cb8d731277 2034-04-24T03:31:05Z 2024-04-26T03:31:05Z
spiffe://cluster.local/ns/default/sa/bookinfo-reviews Leaf Available true 285697fb2cf806852d3293298e300c86 2024-05-05T09:17:47Z 2024-05-04T09:15:47Z
spiffe://cluster.local/ns/default/sa/bookinfo-reviews Root Available true bad086c516cce777645363cb8d731277 2034-04-24T03:31:05Z 2024-04-26T03:31:05Z
spiffe://cluster.local/ns/default/sa/curl Leaf Available true fa33bbb783553a1704866842586e4c0b 2024-05-05T09:25:49Z 2024-05-04T09:23:49Z
spiffe://cluster.local/ns/default/sa/curl Root Available true bad086c516cce777645363cb8d731277 2034-04-24T03:31:05Z 2024-04-26T03:31:05Z
이 명령들을 사용해 ztunnel 프록시가 예상한 모든 워크로드와 TLS 인증서로 구성되어 있는지 확인할 수 있어요. 또한 누락된 정보는 네트워킹 오류를 트러블슈팅하는 데 사용할 수 있어요.
all 옵션을 사용해 단일 CLI 명령으로 ztunnel-config의 모든 부분을 볼 수 있어요:
$ istioctl ztunnel-config all -o json
ztunnel 프록시의 원시 구성 덤프는 그 파드 안의 엔드포인트에 대한 curl로 볼 수도 있어요:
$ kubectl debug -it $ZTUNNEL -n istio-system --image=curlimages/curl -- curl localhost:15000/config_dump
ztunnel xDS 리소스에 대한 Istiod 상태 보기 (Viewing Istiod state for ztunnel xDS resources)
때로는 istiod 컨트롤 플레인에 유지되는 ztunnel 프록시 구성 리소스의 상태를, ztunnel 프록시를 위해 특별히 정의된 xDS API 리소스 형식으로 보고 싶을 수 있어요. 이는 istiod 파드에 exec하여 아래 예제처럼 주어진 ztunnel 프록시에 대해 포트 15014에서 이 정보를 얻음으로써 할 수 있어요. 이 출력은 JSON 예쁜 프린트 포맷터 유틸리티로 저장하고 보기 좋게 볼 수도 있어요 (예제에는 표시되지 않음).
$ export ISTIOD=$(kubectl get pods -n istio-system -l app=istiod -o=jsonpath='{.items[0].metadata.name}')
$ kubectl debug -it $ISTIOD -n istio-system --image=curlimages/curl -- curl localhost:15014/debug/config_dump?proxyID="$ZTUNNEL".istio-system
로그를 통해 ztunnel 트래픽 확인하기 (Verifying ztunnel traffic through logs)
ztunnel의 트래픽 로그는 표준 쿠버네티스 로그 기능으로 조회할 수 있어요.
$ kubectl -n default exec deploy/curl -- sh -c 'for i in $(seq 1 10); do curl -s -I http://productpage:9080/; done'
HTTP/1.1 200 OK
Server: Werkzeug/3.0.1 Python/3.12.1
--snip--
표시된 응답은 클라이언트 파드가 서비스에서 응답을 받는다는 것을 확인해줘요. 이제 ztunnel 파드의 로그를 확인해 트래픽이 HBONE 터널을 통해 보내졌는지 확인할 수 있어요.
$ kubectl -n istio-system logs -l app=ztunnel | grep -E "inbound|outbound"
2024-05-04T09:59:05.028709Z info access connection complete src.addr=10.244.1.12:60059 src.workload="curl-7656cf8794-r7zb9" src.namespace="default" src.identity="spiffe://cluster.local/ns/default/sa/curl" dst.addr=10.244.1.10:9080 dst.hbone_addr="10.244.1.10:9080" dst.service="productpage.default.svc.cluster.local" dst.workload="productpage-v1-87d54dd59-fn6vw" dst.namespace="productpage" dst.identity="spiffe://cluster.local/ns/default/sa/bookinfo-productpage" direction="inbound" bytes_sent=175 bytes_recv=80 duration="1ms"
2024-05-04T09:59:05.028771Z info access connection complete src.addr=10.244.1.12:58508 src.workload="curl-7656cf8794-r7zb9" src.namespace="default" src.identity="spiffe://cluster.local/ns/default/sa/curl" dst.addr=10.244.1.10:15008 dst.hbone_addr="10.244.1.10:9080" dst.service="productpage.default.svc.cluster.local" dst.workload="productpage-v1-87d54dd59-fn6vw" dst.namespace="productpage" dst.identity="spiffe://cluster.local/ns/default/sa/bookinfo-productpage" direction="outbound" bytes_sent=80 bytes_recv=175 duration="1ms"
--snip--
이 로그 메시지는 트래픽이 ztunnel 프록시를 통해 보내졌다는 것을 확인해줘요. 트래픽의 소스·목적지 파드와 같은 노드에 있는 특정 ztunnel 프록시 인스턴스의 로그를 확인해 더 세밀한 모니터링을 할 수 있어요. 이 로그가 보이지 않는다면, 트래픽 리디렉션이 올바르게 동작하지 않을 가능성이 있어요.
ztunnel 로드 밸런싱 확인하기 (Verifying ztunnel load balancing)
ztunnel 프록시는 목적지가 여러 엔드포인트를 가진 서비스라면 클라이언트 측 로드 밸런싱을 자동으로 수행해요. 추가 구성이 필요 없어요. 로드 밸런싱 알고리즘은 내부적으로 고정된 L4 라운드 로빈 알고리즘으로, L4 연결 상태에 기반해 트래픽을 분산하며 사용자가 구성할 수 없어요.
여러 백엔드를 가진 서비스를 호출함으로써, 클라이언트 트래픽이 서비스 레플리카에 걸쳐 균형을 이루는지 검증할 수 있어요.
$ kubectl -n default exec deploy/curl -- sh -c 'for i in $(seq 1 10); do curl -s -I http://reviews:9080/; done'
$ kubectl -n istio-system logs -l app=ztunnel | grep -E "outbound"
--snip--
2024-05-04T10:11:04.964851Z info access connection complete src.addr=10.244.1.12:35520 src.workload="curl-7656cf8794-r7zb9" src.namespace="default" src.identity="spiffe://cluster.local/ns/default/sa/curl" dst.addr=10.244.1.9:15008 dst.hbone_addr="10.244.1.9:9080" dst.service="reviews.default.svc.cluster.local" dst.workload="reviews-v3-7d99fd7978-zznnq" dst.namespace="reviews" dst.identity="spiffe://cluster.local/ns/default/sa/bookinfo-reviews" direction="outbound" bytes_sent=84 bytes_recv=169 duration="2ms"
2024-05-04T10:11:04.969578Z info access connection complete src.addr=10.244.1.12:35526 src.workload="curl-7656cf8794-r7zb9" src.namespace="default" src.identity="spiffe://cluster.local/ns/default/sa/curl" dst.addr=10.244.1.9:15008 dst.hbone_addr="10.244.1.9:9080" dst.service="reviews.default.svc.cluster.local" dst.workload="reviews-v3-7d99fd7978-zznnq" dst.namespace="reviews" dst.identity="spiffe://cluster.local/ns/default/sa/bookinfo-reviews" direction="outbound" bytes_sent=84 bytes_recv=169 duration="2ms"
2024-05-04T10:11:04.974720Z info access connection complete src.addr=10.244.1.12:35536 src.workload="curl-7656cf8794-r7zb9" src.namespace="default" src.identity="spiffe://cluster.local/ns/default/sa/curl" dst.addr=10.244.1.7:15008 dst.hbone_addr="10.244.1.7:9080" dst.service="reviews.default.svc.cluster.local" dst.workload="reviews-v1-5fd6d4f8f8-26j92" dst.namespace="reviews" dst.identity="spiffe://cluster.local/ns/default/sa/bookinfo-reviews" direction="outbound" bytes_sent=84 bytes_recv=169 duration="2ms"
2024-05-04T10:11:04.979462Z info access connection complete src.addr=10.244.1.12:35552 src.workload="curl-7656cf8794-r7zb9" src.namespace="default" src.identity="spiffe://cluster.local/ns/default/sa/curl" dst.addr=10.244.1.8:15008 dst.hbone_addr="10.244.1.8:9080" dst.service="reviews.default.svc.cluster.local" dst.workload="reviews-v2-6f9b55c5db-c2dtw" dst.namespace="reviews" dst.identity="spiffe://cluster.local/ns/default/sa/bookinfo-reviews" direction="outbound" bytes_sent=84 bytes_recv=169 duration="2ms"
이것은 라운드 로빈 로드 밸런싱 알고리즘이며, VirtualService의 TrafficPolicy 필드에 구성될 수 있는 로드 밸런싱 알고리즘과는 분리되고 독립적이에요. 앞서 논의했듯이 VirtualService API 오브젝트의 모든 측면은 ztunnel 프록시가 아니라 웨이포인트 프록시에서 인스턴스화되기 때문이에요.
앰비언트 모드 트래픽의 가시성 (Observability of ambient mode traffic)
위에서 언급한 ztunnel 로그와 다른 모니터링 옵션을 확인하는 것 외에도, 정상적인 Istio 모니터링과 텔레메트리 기능을 사용해 앰비언트 데이터 플레인 모드를 이용하는 애플리케이션 트래픽을 모니터링할 수 있어요.
서비스가 ztunnel이 제공하는 보안 오버레이만 사용한다면, 보고되는 Istio 메트릭은 L4 TCP 메트릭(즉 istio_tcp_sent_bytes_total, istio_tcp_received_bytes_total, istio_tcp_connections_opened_total, istio_tcp_connections_closed_total)뿐이에요. 웨이포인트 프록시를 사용하면 전체 Istio 및 Envoy 메트릭 세트가 보고돼요.
IPv4 전용 클러스터의 IPv6 network is unreachable 경고 (IPv6 network is unreachable warnings on IPv4-only clusters)
자동 할당 주소가 있는 서비스(예: 명시적인 spec.addresses가 없는 ServiceEntry)는 IPv4와 IPv6 가상 IP를 모두 할당받아요. 단일 스택 IPv4 클러스터에서 파드는 사용 가능한 IPv6 주소가 없으므로, IPv6를 선호하는 클라이언트는 IPv6 VIP를 먼저 시도하고, 실패한 다음 IPv4 VIP로 폴백해요. 클라이언트나 ztunnel 로그에서 이런 반복적인 경고를 볼 수 있어요:
grpc: addrConn.createTransport failed to connect to {Addr: "[2001:2::2]:4317", ...}. Err: ... dial tcp [2001:2::2]:4317: connect: network is unreachable
이것은 예상된 것이며 그 자체로 실패가 아니에요. 연결이 IPv4로 폴백하고 트래픽이 정상적으로 흘러요. 일부 클라이언트(예: gRPC 기반)는 해석된 각 주소에 대한 연결 시도를 유지하며, IPv4로 데이터를 보내면서도 IPv6 시도를 반복해서 로그로 남겨요.
클러스터에 사용 가능한 IPv6가 없고 IPv6 시도와 경고를 피하고 싶다면, ztunnel에 IPV6_ENABLED 환경 변수를 false로 설정하세요(기본값은 true). IPv6이 비활성화되면 ztunnel이 IPv6(AAAA) 레코드를 반환하지 않으므로, 클라이언트는 IPv4 VIP만 받아요.