# 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`로 한 번에:

```bash
./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 `[[wikilink]]` 미사용 — md2viz가 비클릭 표식으로만 렌더하기 때문). 현재 **51편 전부 게시**(개념 `note-`·런북 `runbook-` 포함, 스텁 없음). 독서 경로는 `flow.json`에서 편집한다.

---

## 파일명 규칙

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

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

| prefix | 주제 | 포함 내용 |
|---|---|---|
| `gw__`   | **Gateway / 트래픽 in·out** | ingress·egress gateway, TLS termination/passthrough, sidecar scope, circuit breaking, DNS resolution |
| `gt__`   | **Graceful Termination** | 무중단 종료 실험 시리즈 — 연결 드레이닝, IGW 커스텀 배포, HAProxy/Envoy 비교 |
| `xds__`  | **Envoy / xDS internals** | Envoy 설정 모델, xDS 계층(LDS/RDS/CDS/EDS/SDS), 데이터플레인 진단 |
| `sec__`  | **Security** | mTLS/SPIFFE 신원, 인증·인가 리소스 |
| `arch__` | **Architecture / Ops** | 설치 구조, 컨트롤플레인 성능, phantom workload |

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

| 표시 | 의미 |
|---|---|
| `note-`   | 개념 문서 (단일 개념을 메커니즘 수준으로 정리) |
| `src-`    | 참조 자료 (긴 정리·실습기록) |
| `guide-`  | 실전 설치·구성 가이드 |
| `report-` | 홈랩 실습 검증 리포트 (이 클러스터에서 실측) |
| `MOC-`    | Map of Content (주제 목차/인덱스) |
| `runbook-`| 장애 대응·재설치 런북 (절차서) |

> 타입 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)