Istio 문서 모음 — README

홈랩 Istio ingress/egress gateway 도입 검증 프로젝트의 학습·참조·실습 문서. 모든 파일은 flat 구조 + 파일명 prefix로 주제를 구분한다. (Caddy file-server 서빙, cloudflared 외부 노출)

들어가는 문 · 확장 방법

• 📚 카탈로그 index.html — 세 가지 뷰를 토글로 제공:
• 🧭 이해의 흐름(기본): flow.json에 정의한 큐레이션 독서 경로. 0설치→1Envoy/xDS 원리→2트래픽 in/out→3보안→4무중단 종료→5대규모 운영. 단계마다 "왜 이 순서" + 순서대로 링크된 문서 + 📎 실제 yaml·script(attachment)·외부 공식문서 링크.
• 📚 토픽 목록: arch/gt/gw/sec/xds prefix별 목록 + 🔎 검색 + 타입/◆viz/deprecated 칩.
• 🕸 관계도: 문서 간 링크를 force 그래프로(색=토픽, 크기=피참조 수, hover=이웃 강조, 클릭=열기, 드래그=이동). 하단 🔎 링크 점검(고아·깨진 링크). 딥링크 index.html#graph. 그래프 관계 데이터는 markdown/*.md 링크를 reindex 때 다시 읽는 파생값(정본은 md).
• 📁 폴더 구조 files.html — 모든 파일 트리. 하위 폴더 raw listing(/markdown/, /attachment/ 등)은 Caddy --browse 동작.
• 📎 첨부 attachment/ — 문서가 근거로 삼은 실제 repo IaC(yaml·shell·README·runbook) 스냅샷. 각 문서/흐름 단계의 📎 링크로 직접 열람. repo(~/labs/istio) 변경 시 재복사 필요(스냅샷). 서빙은 Caddyfile이 .sh·.yaml·.md 등 소스/설정 파일을 text/plain으로 강제 → 브라우저가 다운로드하지 않고 인라인 표시(html·css·json·svg는 그대로).
• 🏠 복귀 링크 — 모든 문서 페이지 헤더에 🏠 목록(→index.html). 템플릿(md2viz.py)에 박혀 신규 문서도 자동 포함.

새 문서 추가(= 아카이브 확장)는 publish.sh로 한 번에:

./publish.sh add  ~/path/새문서.md  gw__guide-egress-canary   # ingest + 렌더 + 인덱스
./publish.sh render <basename>      # 수정 후 재렌더 (손수 SVG 강화본은 자동 보존)
./publish.sh rebuild                # 게시 문서 전체 갱신 (SVG·미게시 자동 skip)
./publish.sh reindex                # index.html + files.html 만 재생성

• 다이어그램이 있으면 렌더 후 html에 placeholder가 남는다 → Claude Code에서 md-viz skill의 SVG 강화 워크플로 호출(svg-enhance-workflow.js, args=basename 배열).
• 게시/제외/보존: html이 있으면 게시, 없으면 제외, 손수 SVG가 박힌 html은 base 재렌더가 덮어쓰지 않음.
• 스타일 변경은 assets/viz.css 한 곳 → 전체 반영(재렌더 불필요). 컨벤션 정본: ~/.claude/skills/md-viz/SKILL.md.

이 아카이브는 독립 Istio 문서 사이트다. 교차참조는 [라벨](basename.html) 실제 링크를 쓴다(Obsidian <span class="wikilink" title="wikilink">🔗 wikilink</span> 미사용 — md2viz가 비클릭 표식으로만 렌더하기 때문). 현재 51편 전부 게시(개념 note-·런북 runbook- 포함, 스텁 없음). 독서 경로는 flow.json에서 편집한다.

파일명 규칙

{주제}__{타입}-{이름}.md
   │       │
   │       └─ 문서 타입 (note/src/guide/report/MOC)
   └────────── 주제 대분류 (gw/gt/xds/sec/arch)

1) 주제 prefix — __ 앞 (대분류)

2) 타입 표시 — __ 뒤 (문서 성격)

타입 prefix는 카탈로그 그룹화·필터용 표식일 뿐, 모든 문서는 완성형이다. istio- 공통어와 긴 graceful-termination-은 prefix가 대체하므로 파일명에서 생략했다.

파일 구성

gw__ — Gateway / 트래픽 in·out

• report-2026-06-07_ingress-egress — Ingress/Egress Gateway 동작 검증 리포트(외부→gateway 200, TLS termination, egress 경유 강제 실측)
• report-2026-06-07_dns-resolution — ServiceEntry resolution: DNS 동작·진단 런북(STRICT/LOGICAL_DNS, outlier detection, ambient DNS 질의 경로)
• guide-egress-gateway-https — Istio 1.30 Egress Gateway 외부 HTTPS 통신 설치·구성·테스트 가이드
• note-eastwest-gateway-sni — east-west gateway가 클러스터 정보를 SNI에 인코딩해 복호화 없이 트래픽을 프록시하는 원리
• note-circuit-breaking-mechanisms — connection pool 제어 + outlier detection으로 연쇄 장애를 끊는 회로 차단
• note-sidecar-scope — Sidecar 리소스로 푸시 설정 범위를 좁혀 성능과 egress 거버넌스를 얻는 계층 규칙
• src-egress-gateway — Egress Gateway 필드 매뉴얼(HTTPS passthrough 중심)
• src-egress-http-vs-https — Egress 외부 endpoint 프로토콜별(HTTP vs HTTPS) Istio 설정
• src-egress-operations — Egress Gateway 운영 가이드(passthrough + ISTIO_MUTUAL)
• src-sidecar-scope — Sidecar CRD 적용 범위(scope) 설정 방법
• guide-egress-dual-gateway — 이중 egress gateway(passthrough + mTLS)를 별도 ns·별도 pod로 나란히 배치한 검증 랩
• src-egress-https-over-mtls — Egress HTTPS over mTLS 구조 해부(outer 메시 mTLS + inner 앱 TLS, 15443/tcp route)
• report-2026-06-08_egress-mtls — Egress ISTIO_MUTUAL 실측 리포트(requireClientCertificate, SPIFFE 검증)
• note-egress-identity-without-mtls — egress 신원을 이중 TLS 없이(passthrough + Calico NetworkPolicy) 확보하는 근거(반론)
• note-egress-vs-scoping — egress route 스코핑(exportTo / sidecar import)과 멀티-gateway의 전제

gt__ — Graceful Termination

• MOC-graceful-termination — graceful termination 시리즈 전체 목차(진입점)
• src-w1-big-picture — W1. 트래픽 경로 + 6 events + 4 시나리오 큰 그림
• src-w2-hc-fsm — W2. backend + hc + drain.sh Go 코드 메커니즘(FSM)
• src-w3-igw-deployment — W3. IngressGateway 커스텀 Deployment 설계(K8s 매니페스트)
• src-w5-test-scenarios — W5. 테스트 시나리오 4종 설계 의도 + artifacts 해석
• src-w6-production-apply — W6. 프로덕션 적용 가이드(실험 결론 → 온프렘 매핑)
• src-quickstart — LEARN-01. 5분 안에 실험 다시 돌리기
• src-apps-walkthrough — LEARN-02. backend + hc + graceful-drain.sh 워크스루
• src-manifests-walkthrough — LEARN-03. IGW 커스텀 Deployment/Service/Gateway/VS
• src-haproxy-walkthrough — LEARN-04. HAProxy L7 offload + on-marked-down
• src-runbook — 사내 도입 런북(실험 → 적용 가이드)
• src-tests-walkthrough — 테스트 하니스 코드 워크스루
• src-envoy-drain-listeners — Envoy graceful drain(listener 드레이닝) 실험 정리

xds__ — Envoy / xDS internals

• note-xds-api-layers — xDS의 LDS/RDS/CDS/EDS/SDS 계층과 ADS 단일 스트림 순서 보장
• note-envoy-static-vs-dynamic-config — 정적(부트스트랩) vs 동적(컨트롤플레인 푸시) 설정 차이
• note-envoy-routing-chain-debugging — listener→route→cluster→endpoint 체인을 proxy-config로 디버깅
• note-envoy-admin-api-diagnosis — config_dump/clusters/stats로 데이터플레인 실제 설정 진단
• note-envoy-filter-chain-extension — network/HTTP filter chain과 Lua·Wasm·ext-proc 확장
• note-data-plane-sync-state — proxy-status의 SYNCED/STALE로 보는 최종 일관성 동기화
• note-file-based-xds-constraints — 파일 기반 xDS의 포맷·move 교체·EDS 클러스터당 1리소스 제약
• src-cr-xds-model — Istio CR 멘탈모델(CR은 입력, Envoy config가 진실)
• src-envoy-static-dynamic-xds-lab — Envoy 정적/동적 xDS 실습(Istio in Action Ch.3.2)
• src-sidecar-traffic-capture — Sidecar가 pod 트래픽을 가로채는 법: iptables/nftables REDIRECT와 15001·15006, packet flow
• src-cluster-anatomy — Envoy cluster 해부: listener/cluster/endpoint 포트 3종, subset, DestinationRule→cluster 필드 매핑
• src-xds-layers-and-diagnosis — xDS 5계층(LDS/RDS/CDS/EDS/SDS)과 istioctl proxy-config/proxy-status/x describe 진단
• src-envoy-response-flags — Envoy 응답 플래그 운영 레퍼런스(전체 표 + 503 분류 + RESPONSE_FLAGS_LONG 켜기)

sec__ — Security

• note-mtls-spiffe-identity — SPIFFE 표준으로 워크로드 신원을 X.509 SVID SAN에 박는 mTLS 기반
• note-security-resource-trio — PeerAuthentication·RequestAuthentication·AuthorizationPolicy 역할 분담
• src-authorizationpolicy-mental-model — AuthorizationPolicy 멘탈모델: inbound 보호·mTLS identity·HTTP vs TCP DENY 함정·egress

arch__ — Architecture / Ops

• note-install-cp-dp-decoupling — 컨트롤/데이터 플레인 설치 분리로 업그레이드를 데이터플레인에 투명하게
• note-control-plane-performance-factors — istiod 성능 4요인(변경률·리소스·워크로드 수·설정 크기)과 Sidecar 레버
• note-phantom-workloads — 엔드포인트 전파 지연으로 사라진 워크로드에 트래픽을 보내는 현상
• src-phantom-workloads — Phantom workload 처리 방법(실무 정리)
• src-operations-playbook — 대규모 운영 플레이북: Envoy 컴파일러 모델·multi-cluster topology·config scope·revision upgrade·LLMOps
• runbook-controlplane-outage — istiod 0/1 컨트롤플레인 장애 추적 런북(/etc/hosts 이름해석 실패 → 단일 실패점)
• runbook-helm-reinstall — Istio Helm 스택 재설치 런북(base→istiod→gateway 의존 순서, CRD keep-policy)