feat: 가상화 문서들 추가

2026-09-10 08:54:05 +09:00
parent e9f6a93327
commit 43e1aadef0
695 changed files with 153404 additions and 12754 deletions
@@ -136,7 +136,7 @@
      "id": "k1-rev",
      "from": "k1",
      "to": "rev",
-      "label": "반대 방향으로 재연결",
+      "label": "재연결",
      "kind": "request",
      "evidence": [
        {
@@ -32,11 +32,11 @@
  "nodes": [
    {
      "id": "attacker",
-      "label": "밖에서 보낸 위조 헤더",
+      "label": "외부 위조 헤더",
      "kind": "actor",
      "role": "source",
      "emphasis": "warning",
-      "description": "앱이 믿는 이름을 그대로 쓴다.",
+      "description": "밖에서 들어온 요청이 앱이 믿는 헤더 이름을 그대로 쓴다.",
      "details": [
        "X-Auth-Request-Roles"
      ],
@@ -126,7 +126,7 @@
      "id": "lookup-session",
      "from": "request",
      "to": "app-session",
-      "label": "세션 id 로 조회",
+      "label": "조회",
      "kind": "read",
      "evidence": [
        {
@@ -140,7 +140,7 @@
      "id": "lookup-client",
      "from": "request",
      "to": "authorized-client",
-      "label": "principal 이름으로 조회",
+      "label": "조회",
      "kind": "read",
      "evidence": [
        {
@@ -183,4 +183,4 @@
  "metadata": {
    "rationale": "이름이 비슷한 두 저장 대상을 조회 키로 갈랐다. B-1 과 B-2 의 결과가 이 분기에서 나온다."
  }
-}
+}
@@ -32,11 +32,11 @@
  "nodes": [
    {
      "id": "logout",
-      "label": "한 앱에서 로그아웃",
+      "label": "한 앱의 로그아웃",
      "kind": "actor",
      "role": "source",
      "emphasis": "primary",
-      "description": "Keycloak 세션이 끝난다.",
+      "description": "한 앱에서 로그아웃하면 Keycloak 세션이 끝난다.",
      "details": [],
      "evidence": [
        {
@@ -0,0 +1,341 @@
+{
+  "version": "1.1",
+  "id": "cpu-io-passthrough-paths",
+  "title": "게스트가 하드웨어에 닿는 갈래는 셋이고 깊이가 다르다",
+  "question": "게스트의 CPU 실행·virtio I/O·직접 할당한 장치는 각각 어디까지 내려가고 호스트 유저공간을 지나는가",
+  "type": "architecture",
+  "direction": "TB",
+  "audience": [
+    "가상화 구조를 처음 읽는 사람",
+    "이 실험대가 무엇 위에서 도는지 알아야 하는 사람"
+  ],
+  "summary": "CPU 는 QEMU 와 KVM 사이를 왕복하고, virtio 는 virtqueue 를 누가 소비하느냐에 따라 QEMU 나 커널 vhost 로 가며, 패스스루는 유저공간 드라이버가 IOMMU 보호 아래 장치에 직접 닿는다.",
+  "alt": "게스트·호스트 유저공간·호스트 커널·하드웨어 네 층을 가로지르는 세 갈래 경로도.",
+  "long_description": "위에서 아래로 읽는다. 맨 위 QEMU 에서 갈래 셋이 갈린다. 왼쪽 CPU 갈래는 KVM_RUN 으로 커널의 KVM 에 들어가고 KVM 이 VM entry 로 물리 CPU 에 올리며 게스트 코드가 VMX non-root 로 거기서 돈다. 물리 CPU 상자에 VM exit 이 함께 적혀 있고 나온 이유는 KVM 상자의 struct kvm_run 으로 유저공간에 돌아간다. 가운데 패스스루 갈래는 QEMU 가 VFIO 로 장치 fd 를 받고 vfio-pci 가 장치를 묶으며 그 장치의 DMA 가 IOMMU 를 지난다. 오른쪽 virtio 갈래는 virtqueue 가 게스트 드라이버에 닿고 같은 virtqueue 를 커널 vhost 와 나누는 길이 따로 있다. 앞의 둘은 이 실험대가 쓰고 패스스루는 쓰지 않는다.",
+  "source_context": {
+    "document": "docs/keycloak-session-store/final/document.md",
+    "document_sha256": "0ae5674723f25dc85d5069529890f07be1a11b768b56901103fa3ea6ac3dcf55",
+    "anchor": {
+      "kind": "heading",
+      "value": "이 층 아래의 구조 — 조사한 것",
+      "line": 1091
+    }
+  },
+  "composition": {
+    "profile": "component-flow",
+    "diagram_only": true,
+    "reference_ids": [
+      "payment-event-flow"
+    ],
+    "rationale": "세 갈래가 각각 방향이 있는 경로다. comparison 은 관계선을 지워도 뜻이 남는 배치라 이 그림에서는 표가 되고, 깊이가 다르다는 주장이 자리로 드러나지 않는다.",
+    "focus_node": "qemu"
+  },
+  "groups": [],
+  "nodes": [
+    {
+      "id": "qemu",
+      "label": "QEMU",
+      "kind": "service",
+      "role": "source",
+      "shape": "box",
+      "emphasis": "primary",
+      "details": [
+        "/dev/kvm",
+        "KVM_CREATE_VM · KVM_CREATE_VCPU"
+      ],
+      "description": "KVM 핸들을 열고 VM 과 vCPU 를 만드는 유저공간 프로세스. vcpu ioctl 은 그 vcpu 를 만든 스레드에서 낸다.",
+      "evidence": [
+        {
+          "start_line": 1102,
+          "end_line": 1108
+        }
+      ],
+      "assumption": false
+    },
+    {
+      "id": "vfio",
+      "label": "VFIO",
+      "kind": "service",
+      "role": "service",
+      "shape": "box",
+      "details": [
+        "vfio-pci",
+        "IOMMU 그룹",
+        "/dev/vfio/vfio"
+      ],
+      "description": "IOMMU 보호 아래 장치 접근을 유저공간에 여는 프레임워크. 소유 단위가 IOMMU 그룹이다.",
+      "evidence": [
+        {
+          "start_line": 1131,
+          "end_line": 1146
+        }
+      ],
+      "assumption": false
+    },
+    {
+      "id": "pci-device",
+      "label": "물리 PCI 장치",
+      "kind": "service",
+      "role": "service",
+      "shape": "box",
+      "details": [
+        "게스트 직접 할당"
+      ],
+      "description": "호스트 드라이버에서 떼어 vfio-pci 에 묶은 장치.",
+      "evidence": [
+        {
+          "start_line": 1131,
+          "end_line": 1133
+        },
+        {
+          "start_line": 1144,
+          "end_line": 1146
+        }
+      ],
+      "assumption": false
+    },
+    {
+      "id": "iommu",
+      "label": "IOMMU",
+      "kind": "service",
+      "role": "sink",
+      "shape": "box",
+      "details": [
+        "DMA · 인터럽트 리매핑"
+      ],
+      "description": "장치가 아무 메모리나 건드리지 못하게 막는 리매핑 장치.",
+      "evidence": [
+        {
+          "start_line": 1144,
+          "end_line": 1146
+        }
+      ],
+      "assumption": false
+    },
+    {
+      "id": "kvm",
+      "label": "KVM",
+      "kind": "service",
+      "role": "service",
+      "shape": "box",
+      "details": [
+        "struct kvm_run",
+        "KVM_GET_VCPU_MMAP_SIZE"
+      ],
+      "description": "mmap 한 공유 메모리로 나온 이유를 유저공간에 알리는 커널 쪽.",
+      "evidence": [
+        {
+          "start_line": 1105,
+          "end_line": 1108
+        }
+      ],
+      "assumption": false
+    },
+    {
+      "id": "physical-cpu",
+      "label": "물리 CPU",
+      "kind": "service",
+      "role": "service",
+      "shape": "box",
+      "details": [
+        "VMX root · VMX non-root",
+        "VM entry · VM exit",
+        "guest-state 영역"
+      ],
+      "description": "VM entry 때 guest-state 영역에서 상태를 싣고 VM exit 때 그리로 저장하는 프로세서.",
+      "evidence": [
+        {
+          "start_line": 1111,
+          "end_line": 1113
+        }
+      ],
+      "assumption": false
+    },
+    {
+      "id": "guest-code",
+      "label": "게스트 코드",
+      "kind": "service",
+      "role": "sink",
+      "shape": "box",
+      "details": [
+        "vCPU"
+      ],
+      "description": "VMX non-root 로 물리 CPU 에서 도는 게스트 명령.",
+      "evidence": [
+        {
+          "start_line": 1111,
+          "end_line": 1113
+        }
+      ],
+      "assumption": false
+    },
+    {
+      "id": "virtio-driver",
+      "label": "게스트 virtio 드라이버",
+      "kind": "service",
+      "role": "sink",
+      "shape": "box",
+      "details": [
+        "virtio-pci · virtio-mmio",
+        "virtqueue"
+      ],
+      "description": "게스트가 보는 반가상화 장치의 드라이버. 주고받는 통로가 virtqueue 다.",
+      "evidence": [
+        {
+          "start_line": 1116,
+          "end_line": 1118
+        }
+      ],
+      "assumption": false
+    },
+    {
+      "id": "vhost",
+      "label": "vhost",
+      "kind": "service",
+      "role": "sink",
+      "shape": "box",
+      "details": [
+        "리눅스 커널 구현",
+        "virtqueue 공유"
+      ],
+      "description": "virtqueue 를 QEMU 밖과 나누는 커널 구현. vhost-user 규약이 이것을 제어하는 ioctl 인터페이스를 보완한다.",
+      "evidence": [
+        {
+          "start_line": 1125,
+          "end_line": 1129
+        }
+      ],
+      "assumption": false
+    }
+  ],
+  "edges": [
+    {
+      "id": "qemu-device-fd",
+      "from": "qemu",
+      "to": "vfio",
+      "label": "장치 fd",
+      "kind": "request",
+      "style": "solid",
+      "evidence": [
+        {
+          "start_line": 1138,
+          "end_line": 1141
+        }
+      ],
+      "assumption": false
+    },
+    {
+      "id": "vfio-binds-device",
+      "from": "vfio",
+      "to": "pci-device",
+      "label": "vfio-pci 결합",
+      "kind": "control",
+      "style": "solid",
+      "evidence": [
+        {
+          "start_line": 1144,
+          "end_line": 1146
+        }
+      ],
+      "assumption": false
+    },
+    {
+      "id": "device-dma",
+      "from": "pci-device",
+      "to": "iommu",
+      "label": "DMA",
+      "kind": "data",
+      "style": "solid",
+      "evidence": [
+        {
+          "start_line": 1144,
+          "end_line": 1146
+        }
+      ],
+      "assumption": false
+    },
+    {
+      "id": "qemu-kvm-run",
+      "from": "qemu",
+      "to": "kvm",
+      "label": "KVM_RUN",
+      "kind": "request",
+      "style": "solid",
+      "evidence": [
+        {
+          "start_line": 1104,
+          "end_line": 1106
+        }
+      ],
+      "assumption": false
+    },
+    {
+      "id": "kvm-vm-entry",
+      "from": "kvm",
+      "to": "physical-cpu",
+      "label": "VM entry",
+      "kind": "request",
+      "style": "solid",
+      "evidence": [
+        {
+          "start_line": 1111,
+          "end_line": 1112
+        }
+      ],
+      "assumption": false
+    },
+    {
+      "id": "cpu-runs-guest",
+      "from": "physical-cpu",
+      "to": "guest-code",
+      "label": "VMX non-root",
+      "kind": "data",
+      "style": "solid",
+      "evidence": [
+        {
+          "start_line": 1111,
+          "end_line": 1112
+        }
+      ],
+      "assumption": false
+    },
+    {
+      "id": "qemu-virtqueue",
+      "from": "qemu",
+      "to": "virtio-driver",
+      "label": "virtqueue",
+      "kind": "data",
+      "style": "solid",
+      "evidence": [
+        {
+          "start_line": 1116,
+          "end_line": 1118
+        },
+        {
+          "start_line": 1128,
+          "end_line": 1128
+        }
+      ],
+      "assumption": false
+    },
+    {
+      "id": "qemu-vhost-ioctl",
+      "from": "qemu",
+      "to": "vhost",
+      "label": "제어 ioctl",
+      "kind": "control",
+      "style": "dashed",
+      "evidence": [
+        {
+          "start_line": 1125,
+          "end_line": 1129
+        }
+      ],
+      "assumption": false
+    }
+  ],
+  "legend": [],
+  "metadata": {
+    "rationale": "세 갈래의 깊이 차이는 어느 층까지 선이 내려가느냐로만 보이므로 배치와 관계선이 함께 있어야 한다. 셋 중 패스스루는 이 실험대가 쓰지 않으며 본문이 그 사실을 적는다."
+  }
+}
@@ -32,11 +32,11 @@
  "nodes": [
    {
      "id": "rollback",
-      "label": "옛 버전으로 되돌리기",
+      "label": "옛 버전 롤백",
      "kind": "process",
      "role": "source",
      "emphasis": "warning",
-      "description": "이미지 태그를 되돌린다.",
+      "description": "이미지 태그를 옛 버전으로 되돌린다.",
      "details": [],
      "evidence": [
        {
@@ -0,0 +1,306 @@
+{
+  "version": "1.1",
+  "id": "guest-as-host-process",
+  "title": "게스트 두 대는 호스트에서 qemu 프로세스 두 개다",
+  "question": "호스트에서 게스트는 무엇으로 존재하고, 게스트가 보는 장치는 누가 만들어 주는가",
+  "type": "deployment",
+  "direction": "TB",
+  "audience": [
+    "실험대를 운영하는 사람",
+    "호스트와 게스트의 측정값을 대조하는 사람"
+  ],
+  "summary": "libvirtd 가 게스트마다 qemu-system-x86_64 를 띄우고, 게스트가 보는 디스크와 네트워크는 그 프로세스가 virtio 로 내주며, 두 프로세스는 machine.slice 아래에서 메모리 상한을 받는다.",
+  "alt": "호스트 안에 libvirtd·machine.slice·virbr0 와 qemu 프로세스 두 개가 있고, 각 프로세스가 게스트 하나씩을 담는 배치도.",
+  "long_description": "위에서 아래로 읽는다. 호스트 test-server 경계 안에 libvirtd 가 있고 그 아래에 qemu-system-x86_64 프로세스가 게스트 수만큼 있다. 경계 밖 아래쪽에 게스트 kc-lab-1 과 kc-lab-2 가 각각 따로 있고, 게스트가 보는 디스크와 인터페이스는 자기를 담은 프로세스가 virtio 로 내준다. 프로세스에 적힌 RSS 와 게스트에 적힌 available 은 같은 메모리를 다른 껍질에서 읽은 값이다. machine.slice 와 virbr0 는 이 그림에 넣지 않았고 본문이 맡는다.",
+  "source_context": {
+    "document": "docs/keycloak-session-store/final/document.md",
+    "document_sha256": "0ae5674723f25dc85d5069529890f07be1a11b768b56901103fa3ea6ac3dcf55",
+    "anchor": {
+      "kind": "heading",
+      "value": "0층. 가상화 — 「바닥」 아래에 있는 것",
+      "line": 935
+    }
+  },
+  "composition": {
+    "profile": "component-flow",
+    "diagram_only": true,
+    "reference_ids": [
+      "payment-event-flow"
+    ],
+    "rationale": "게스트가 호스트에서 어떻게 존재하는지는 libvirtd 에서 qemu 프로세스로, 다시 게스트 커널로 내려가는 한 방향 경로다. sequence 는 이 절에 시각 순서가 없어서 맞지 않고, orchestrator-workers 는 게스트 둘을 교체 가능한 워커로 그리는데 둘은 할당량도 역할도 다르다.",
+    "focus_node": "qemu-kc-lab-1"
+  },
+  "groups": [
+    {
+      "id": "host-zone",
+      "label": "호스트 test-server",
+      "kind": "system",
+      "role": "zone",
+      "description": "libvirtd 와 게스트 프로세스가 함께 도는 호스트 경계.",
+      "evidence": [
+        {
+          "start_line": 946,
+          "end_line": 948
+        },
+        {
+          "start_line": 956,
+          "end_line": 956
+        }
+      ],
+      "assumption": false
+    },
+    {
+      "id": "guest-1-zone",
+      "label": "게스트 kc-lab-1",
+      "kind": "system",
+      "role": "zone",
+      "description": "qemu 프로세스 하나가 담는 Debian 게스트.",
+      "evidence": [
+        {
+          "start_line": 987,
+          "end_line": 990
+        },
+        {
+          "start_line": 1039,
+          "end_line": 1039
+        }
+      ],
+      "assumption": false
+    },
+    {
+      "id": "guest-2-zone",
+      "label": "게스트 kc-lab-2",
+      "kind": "system",
+      "role": "zone",
+      "description": "나머지 qemu 프로세스가 담는 Debian 게스트.",
+      "evidence": [
+        {
+          "start_line": 1033,
+          "end_line": 1033
+        },
+        {
+          "start_line": 1040,
+          "end_line": 1040
+        }
+      ],
+      "assumption": false
+    }
+  ],
+  "nodes": [
+    {
+      "id": "libvirtd",
+      "label": "libvirtd",
+      "kind": "service",
+      "role": "source",
+      "group": "host-zone",
+      "shape": "box",
+      "details": [
+        "qemu:///system"
+      ],
+      "description": "게스트마다 qemu-system-x86_64 를 하나씩 띄우는 호스트 데몬. htop 트리 뷰에서 그 아래에 게스트 프로세스가 달린다.",
+      "evidence": [
+        {
+          "start_line": 946,
+          "end_line": 948
+        },
+        {
+          "start_line": 956,
+          "end_line": 956
+        }
+      ],
+      "assumption": false
+    },
+    {
+      "id": "qemu-kc-lab-1",
+      "label": "qemu-system-x86_64",
+      "kind": "service",
+      "role": "service",
+      "group": "host-zone",
+      "shape": "box",
+      "emphasis": "primary",
+      "details": [
+        "kc-lab-1",
+        "vCPU 2",
+        "할당 3584MB",
+        "RSS 3765MB"
+      ],
+      "description": "kc-lab-1 게스트 전체가 들어 있는 호스트 프로세스. vCPU 는 이 프로세스의 스레드이고 RSS 는 게스트가 터치한 페이지만큼이다.",
+      "evidence": [
+        {
+          "start_line": 946,
+          "end_line": 948
+        },
+        {
+          "start_line": 987,
+          "end_line": 987
+        },
+        {
+          "start_line": 1032,
+          "end_line": 1032
+        }
+      ],
+      "assumption": false
+    },
+    {
+      "id": "qemu-kc-lab-2",
+      "label": "qemu-system-x86_64",
+      "kind": "service",
+      "role": "service",
+      "group": "host-zone",
+      "shape": "box",
+      "details": [
+        "kc-lab-2",
+        "할당 2560MB",
+        "RSS 2633MB"
+      ],
+      "description": "kc-lab-2 게스트 전체가 들어 있는 호스트 프로세스. A-4 의 virsh destroy 가 끊는 것이 이 프로세스다.",
+      "evidence": [
+        {
+          "start_line": 946,
+          "end_line": 948
+        },
+        {
+          "start_line": 967,
+          "end_line": 976
+        },
+        {
+          "start_line": 1033,
+          "end_line": 1033
+        }
+      ],
+      "assumption": false
+    },
+    {
+      "id": "guest-kernel-1",
+      "label": "Debian 게스트 커널",
+      "kind": "service",
+      "role": "sink",
+      "group": "guest-1-zone",
+      "shape": "box",
+      "details": [
+        "enp1s0 · 192.168.122.11",
+        "총 3423MB",
+        "available 1959MB"
+      ],
+      "description": "virtio 장치만 보는 게스트. free 가 읽는 값이 여기 있다.",
+      "evidence": [
+        {
+          "start_line": 994,
+          "end_line": 998
+        },
+        {
+          "start_line": 1039,
+          "end_line": 1039
+        }
+      ],
+      "assumption": false
+    },
+    {
+      "id": "guest-kernel-2",
+      "label": "Debian 게스트 커널",
+      "kind": "service",
+      "role": "sink",
+      "group": "guest-2-zone",
+      "shape": "box",
+      "details": [
+        "enp1s0 · 192.168.122.12",
+        "총 2480MB",
+        "available 1899MB"
+      ],
+      "description": "같은 방식으로 붙은 두 번째 게스트.",
+      "evidence": [
+        {
+          "start_line": 994,
+          "end_line": 998
+        },
+        {
+          "start_line": 1040,
+          "end_line": 1040
+        }
+      ],
+      "assumption": false
+    }
+  ],
+  "edges": [
+    {
+      "id": "libvirtd-spawns-1",
+      "from": "libvirtd",
+      "to": "qemu-kc-lab-1",
+      "label": "프로세스 생성",
+      "kind": "control",
+      "style": "solid",
+      "evidence": [
+        {
+          "start_line": 946,
+          "end_line": 948
+        },
+        {
+          "start_line": 956,
+          "end_line": 956
+        }
+      ],
+      "assumption": false
+    },
+    {
+      "id": "libvirtd-spawns-2",
+      "from": "libvirtd",
+      "to": "qemu-kc-lab-2",
+      "label": "프로세스 생성",
+      "kind": "control",
+      "style": "solid",
+      "evidence": [
+        {
+          "start_line": 946,
+          "end_line": 948
+        },
+        {
+          "start_line": 956,
+          "end_line": 956
+        }
+      ],
+      "assumption": false
+    },
+    {
+      "id": "qemu1-virtio",
+      "from": "qemu-kc-lab-1",
+      "to": "guest-kernel-1",
+      "label": "virtio 디스크 · virtio-net",
+      "kind": "data",
+      "style": "solid",
+      "evidence": [
+        {
+          "start_line": 987,
+          "end_line": 990
+        },
+        {
+          "start_line": 994,
+          "end_line": 998
+        }
+      ],
+      "assumption": false
+    },
+    {
+      "id": "qemu2-virtio",
+      "from": "qemu-kc-lab-2",
+      "to": "guest-kernel-2",
+      "label": "virtio 디스크 · virtio-net",
+      "kind": "data",
+      "style": "solid",
+      "evidence": [
+        {
+          "start_line": 987,
+          "end_line": 990
+        },
+        {
+          "start_line": 994,
+          "end_line": 998
+        }
+      ],
+      "assumption": false
+    }
+  ],
+  "legend": [],
+  "metadata": {
+    "rationale": "배치도로 고른 이유는 이 절이 주장하는 것이 순서가 아니라 담김이기 때문이다 — 게스트 하나가 호스트 프로세스 하나 안에 있고, 게스트가 보는 장치는 그 프로세스가 내준다. 메모리를 읽는 곳 셋과 machine.slice·virbr0 는 본문 표와 문단이 맡는다."
+  }
+}
@@ -90,9 +90,9 @@
      "kind": "process",
      "role": "target",
      "emphasis": "warning",
-      "description": "클레임 변경이 반영되지 않는 이유.",
+      "description": "IdP 에서 클레임을 바꿔도 재인증까지 옛 값이 간다.",
      "details": [
-        "재인증까지 옛 값"
+        "옛 클레임 값"
      ],
      "evidence": [
        {
@@ -56,7 +56,9 @@
      "emphasis": "primary",
      "description": "OFFLINE_USER_SESSION 에 세션 행을 보관한다. 두 노드가 같은 행을 본다.",
      "details": [
-        "offline_flag='0'"
+        "OFFLINE_USER_SESSION",
+        "offline_flag='0'",
+        "두 노드 공용"
      ],
      "evidence": [
        {
@@ -98,7 +100,10 @@
        }
      ],
      "assumption": false,
-      "details": []
+      "details": [
+        "노드 둘 등록",
+        "세션 복제 아님"
+      ]
    }
  ],
  "edges": [
@@ -163,4 +168,4 @@
  "metadata": {
    "rationale": "클러스터 형성과 세션 복제를 한 그림에서 분리했다. 발견(JGROUPS_PING)과 공유(OFFLINE_USER_SESSION)가 같은 데이터베이스 안의 다른 테이블이라는 점이 이 절의 오해가 생기는 자리다."
  }
-}
+}