VirtualService ↔ DestinationRule
매핑 구조와 디버깅 플레이북

핵심 요약

리소스 역할 분담

Istio는 트래픽 제어를 라우팅 결정과 목적지 정책으로 분리함. 변경 주기·소유자가 다른 관심사를 리소스 단위로 나눈 설계임.

subset은 라우팅 대상 그룹의 "정의"만 담당하고, 그 그룹을 "선택"하는 것은 VS의 몫임. 정의(DR)와 선택(VS)이 분리되어 있어 이름 참조로만 연결됨 — 이 참조가 끊기는 것이 대부분의 장애 원인임.

spec.hosts는 무엇과 매칭되는가

spec.hosts는 "요청이 향하는 목적지 이름"과 매칭되어 이 VS의 발동 여부를 결정함. DR의 host와 비교되는 필드가 아님. 매칭은 두 단계로 일어남.

단계 1 — 컴파일 타임 (istiod)

istiod가 hosts:를 보고 이 VS의 규칙을 어느 Envoy virtualHost에 부착할지 결정함. sidecar(mesh) 트래픽의 경우 host는 service registry에 등록된 이름(K8s Service 또는 ServiceEntry)이어야 함. registry에 없는 이름을 쓰면 규칙이 어디에도 부착되지 않고 조용히 무시됨 — 에러가 나지 않아 발견이 늦어지는 유형임.

단계 2 — 런타임 (Envoy)

프로토콜에 따라 매칭 재료가 다름. L7 정보가 있는 프로토콜만 이름 기반 매칭이 가능함.

부착 위치에 따른 차이

매핑 키 — 무엇이 무엇과 연결되는가

VS와 DR을 잇는 키는 정확히 두 개임. 그 외 필드는 매핑에 관여하지 않음.

FQDN 정규화 규칙

host: reviews처럼 short name을 쓰면 그 리소스가 정의된 namespace 기준으로 reviews.<ns>.svc.cluster.local로 확장됨. 호출자 namespace 기준이 아님. VS와 DR이 서로 다른 namespace에 있으면 같은 short name이 다른 FQDN으로 확장되어 매핑이 조용히 끊어짐. 운영 환경에서는 FQDN 명시가 원칙임.

istiod → Envoy 변환 경로

디버깅 시 "어느 계층에서 끊겼는지"를 판단하려면 각 리소스가 어떤 xDS로 변환되는지 알아야 함. istioctl proxy-config의 서브커맨드가 이 계층과 1:1 대응임.

• RDS — VS의 hosts가 virtualHost의 domains가 되고, route 규칙이 cluster 이름 문자열을 가리킴.
• CDS — DR의 subset마다 outbound|<port>|<subset>|<FQDN> 이름의 cluster가 생성됨. subset 없는 기본 cluster는 subset 자리가 빈 문자열임.
• EDS — 해당 cluster의 endpoint 목록. Service endpoint 중 subset labels와 일치하는 Pod만 포함됨.
• 즉 VS→DR 연결의 실체는 "route가 참조하는 cluster 이름 문자열"이며, 이 문자열을 만드는 재료가 매핑 키 두 개임.

완전한 예제 — v1/v2 가중치 분배

# DestinationRule — subset 정의 + 목적지 정책
apiVersion: networking.istio.io/v1
kind: DestinationRule
metadata:
  name: reviews
  namespace: default
spec:
  host: reviews.default.svc.cluster.local   # KEY ①
  trafficPolicy:
    loadBalancer:
      simple: LEAST_REQUEST
  subsets:
  - name: v1                                # KEY ②
    labels:
      version: v1                            # Pod label과 일치 필요
  - name: v2
    labels:
      version: v2
---
# VirtualService — 라우팅 규칙
apiVersion: networking.istio.io/v1
kind: VirtualService
metadata:
  name: reviews
  namespace: default
spec:
  hosts:
  - reviews.default.svc.cluster.local        # 요청 매칭용 (DR과 무관)
  http:
  - route:
    - destination:
        host: reviews.default.svc.cluster.local  # KEY ① → DR.host
        subset: v1                                # KEY ② → subsets[].name
      weight: 90
    - destination:
        host: reviews.default.svc.cluster.local
        subset: v2
      weight: 10

검증 커맨드는 06 디버깅 플레이북의 각 단계에 포함함. 정상 상태 기준의 예상 출력도 함께 표기함.

디버깅 플레이북 — 설정이 꼬였을 때

원칙: 정적 검증 → 동기화 확인 → xDS 계층 순회(Route → Cluster → Endpoint) → 런타임 관측 순으로 내려감. 각 단계는 "여기까지는 정상"을 확정하고 다음 계층으로 넘어가는 이분 탐색임.

istioctl analyze -n default          # 또는 --all-namespaces
# 대표 경고:
#  IST0101 referenced DestinationRule subset not found → subset 이름 오타/DR 누락
#  IST0132 host not found in registry → hosts에 미등록 이름

istioctl proxy-status
# 모든 컬럼(CDS/LDS/EDS/RDS)이 SYNCED 여야 함. STALE → istiod 쪽 문제

istioctl experimental describe pod reviews-v2-abc -n default

istioctl proxy-config route deploy/productpage -n default --name 9080 -o json \
  | jq '.[0].virtualHosts[] | select(.name | startswith("reviews"))'
# 기대: weightedClusters에 outbound|9080|v1|... =90, |v2|... =10
# 규칙이 안 보임 → VS hosts가 registry 미등록이거나 exportTo로 가려짐

istioctl proxy-config cluster deploy/productpage -n default \
  --fqdn reviews.default.svc.cluster.local
# 기대: subset 컬럼에 v1, v2 행이 각각 존재
# subset 행 없음 → DR 미적용 (host FQDN 불일치, exportTo, namespace 확인)

istioctl proxy-config endpoint deploy/productpage -n default \
  --cluster "outbound|9080|v2|reviews.default.svc.cluster.local"
# 기대: version=v2 Pod IP들이 HEALTHY
# 0개 → subset labels와 Pod label 불일치. 아래로 교차 확인:
kubectl get pods -n default -l app=reviews --show-labels
kubectl get endpointslices -n default -l kubernetes.io/service-name=reviews

kubectl logs deploy/productpage -n default -c istio-proxy --tail=100 | grep -E ' 50[03] '
# "... 503 NC ..." → cluster 부재   "... 503 UH ..." → endpoint 부재

# Envoy 전체 설정 스냅샷 (istioctl 출력의 원본)
kubectl exec deploy/productpage -n default -c istio-proxy -- \
  curl -s localhost:15000/config_dump > dump.json
# 라우팅 판단 과정을 로그로 직접 관찰
istioctl proxy-config log deploy/productpage -n default --level router:debug,upstream:debug

Response flag 색인

표는 색인이며, 각 flag의 진단 방향은 아래 해설 참조.

• NR vs NC — NR은 "라우팅 테이블에 규칙 자체가 없음"(VS 계층), NC는 "규칙은 있는데 목적지 cluster가 없음"(DR 계층). 같은 503이라도 고칠 리소스가 다름.
• NC vs UH — NC는 cluster 생성 실패(DR host/subset 참조 문제), UH는 cluster는 정상이나 label 필터 결과가 빈 경우(Pod label 또는 not-ready). pc cluster → pc endpoint 순 확인으로 즉시 구분됨.
• UF — 설정 매핑이 아니라 연결 자체의 문제. STRICT mTLS 환경에서 DR에 tls.mode: DISABLE을 걸었거나, sidecar 없는 워크로드로 ISTIO_MUTUAL 트래픽을 보낸 경우가 전형적임.

증상 → 진입점 매핑

실패 시나리오 — 어떻게 관측되는가

시나리오 A — subset 참조 대상 DR 부재 503 NC

VS가 subset: v2를 참조하는데 DR이 없거나 host FQDN이 불일치하는 경우. cluster outbound|9080|v2|... 자체가 생성되지 않아 route가 존재하지 않는 cluster 이름을 가리킴. istioctl analyze의 IST0101로 사전 탐지 가능함.

시나리오 B — subset labels와 일치하는 Pod 없음 503 UH

DR은 정상 적용됐으나 version: v2 label을 가진 Pod가 0개(오타, rollout 중 label 변경, 전부 not-ready). cluster는 존재하지만 EDS 결과가 빈 목록임. 정적 검증으로는 안 잡히고 런타임에만 드러남 — pc endpoint가 유일한 확정 수단임.

시나리오 C — short name의 namespace 확장 차이 조용한 미적용

VS는 team-a, DR은 team-b에 있고 둘 다 host: reviews로 작성한 경우. 각각 reviews.team-a..., reviews.team-b...로 확장되어 KEY ①이 불일치함. 에러 없이 DR 정책만 미적용되는 형태라 발견이 늦음. subset까지 참조했다면 NC로 표면화되지만, trafficPolicy만 있는 DR이면 증상 없이 정책만 사라짐.

시나리오 D — exportTo로 가려진 리소스 호출자 위치 의존 503

DR에 exportTo: ["."]가 걸려 있으면 다른 namespace의 sidecar에는 subset cluster가 생성되지 않음. "같은 namespace에서는 되는데 다른 namespace에서 호출하면 NC"라는 위치 의존적 증상이 시그니처임. 호출자 Pod 기준으로 pc cluster를 조회해야 보이는 문제이므로, 반드시 실패하는 쪽 Pod를 기준으로 proxy-config를 확인해야 함.