donghyeon.kang/document-haness
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

docs(keycloak-session-store): remake all 28 diagrams through the techviz pipeline

Browse Source 
The originating repository's SVGs were drawn by hand and every one of them
put a title, a subtitle and an explanation band inside the canvas. This
repository forbids both, so they could not be carried over — the whole set
was rebuilt through the skill's pipeline instead.

Each diagram went through prepare, references, prompt, a VizSpec 1.1 citing
document line ranges, lint, and render. All 28 pass lint and produce the
same eight formats the existing keycloak project has. Sentences moved out of
the canvas into <desc> and the paragraph beside each figure; the drawings
carry names only.

Two lint rules did real work rather than formatting work:

  edge-through-node                  caught arrows crossing an unrelated
                                     node and implying an adjacency that
                                     does not exist — four diagrams had to
                                     be restructured, not just relaid out
  evidence-outside-prepared-context  caught a diagram citing another
                                     section; its anchor moved from B-0 to
                                     B-1 so all three sections it draws on
                                     are inside the prepared context

lab-topology also had to change profile: its context offers a different
candidate set, and query-fanout with shard roles is what the section
actually shows — one entry point spreading to two Keycloak nodes.

The document now carries all 28 inline, one per claim that needed one, and
the section recording what was still missing is updated: the diagram gap is
closed, Studio records remain.

verify-pipeline.py passes. audit-records.py reports no issues.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
DongHyeonka
2026-09-05 11:03:10 +09:00
co-authored by Claude Opus 5
parent b2963105a8
commit 75bed382c8
286 changed files with 65385 additions and 710 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/keycloak-session-store/final/assets/d2-upgrade-direction/d2-upgrade-direction.alt.md
+24
View File
@@ -0,0 +1,24 @@
# 방향에 따라 갈리는 업그레이드
## Alternative text
앞으로 가는 경로는 무중단이고 뒤로 가는 경로는 Liquibase 검증에서 막히는 구성. 롤링 업데이트가 그 사고를 절반에서 멈춘다.
## Long description
26.7.0 에서 26.7.3 으로 올리는 것은 무중단이었고 87회 요청이 전부 200 이었다. 되돌리기는 Liquibase 가 체크섬 검증에서 막았다. 새 버전이 남긴 체크섬을 옛 버전이 거부하기 때문이다. 그런데 서비스는 살아 있었다. StatefulSet 롤링 업데이트가 첫 파드에서 멈추고 나머지를 건드리지 않았기 때문이다. 롤백 불가는 조건부이며 판단 기준은 databasechangelog 의 행 수가 업그레이드 전후로 같은가이다.
## Elements and evidence
- **옛 버전으로 되돌리기** (process): 이미지 태그를 되돌린다. Evidence: L483–L490.
- **Liquibase 검증** (process): 새 버전이 남긴 체크섬을 거부한다. Evidence: L483–L491.
- **StatefulSet 롤링 업데이트** (process): 첫 파드가 실패하면 거기서 멈춘다. Evidence: L492–L497.
- **외부 서비스** (service): 남은 파드가 계속 200 을 낸다. Evidence: L492–L498.
- **databasechangelog 행 수** (datastore): 전후로 같으면 롤백된다. Evidence: L499–L505.
## Relationships
- **Liquibase 검증 → databasechangelog 행 수:** 무엇을 보고 판단하나. Evidence: L499–L505.
- **Liquibase 검증 → StatefulSet 롤링 업데이트:** 실패가 여기서 멈춘다. Evidence: L492–L497.
- **옛 버전으로 되돌리기 → Liquibase 검증:** 기동 시 검증. Evidence: L483–L491.
- **StatefulSet 롤링 업데이트 → 외부 서비스:** 남은 파드가 응답한다. Evidence: L492–L498.
docs/keycloak-session-store/final/assets/d2-upgrade-direction/d2-upgrade-direction.d2
+22
View File
@@ -0,0 +1,22 @@
# 방향에 따라 갈리는 업그레이드
# Question: 되돌릴 수 있는지는 무엇이 결정하는가
direction: down
n0: "옛 버전으로 되돌리기" {
shape: rectangle
}
n1: "Liquibase 검증" {
shape: rectangle
}
n2: "StatefulSet 롤링 업데이트" {
shape: rectangle
}
n3: "외부 서비스" {
shape: rectangle
}
n4: "databasechangelog 행 수" {
shape: cylinder
}
n0 -> n1: "기동 시 검증"
n1 -> n2: "실패가 여기서 멈춘다"
n2 -> n3: "남은 파드가 응답한다"
n1 -> n4: "무엇을 보고 판단하나"
docs/keycloak-session-store/final/assets/d2-upgrade-direction/d2-upgrade-direction.dot
+14
View File
@@ -0,0 +1,14 @@
digraph techviz {
graph [rankdir=TB, splines=ortho, nodesep=0.55, ranksep=0.85];
node [fontname=Helvetica, fontsize=11, margin="0.18,0.12", style="rounded,filled", fillcolor=white, color="#2d4357", penwidth=1.5];
edge [fontname=Helvetica, fontsize=10, color="#364b5f", penwidth=1.4, arrowsize=0.75];
n0 [label="옛 버전으로 되돌리기", shape=box, style="rounded,filled"];
n1 [label="Liquibase 검증", shape=box, style="rounded,filled"];
n2 [label="StatefulSet 롤링 업데이트", shape=box, style="rounded,filled"];
n3 [label="외부 서비스", shape=box, style="rounded,filled"];
n4 [label="databasechangelog 행 수", shape=cylinder, style="rounded,filled"];
n0 -> n1 [label="기동 시 검증", style=solid];
n1 -> n2 [label="실패가 여기서 멈춘다", style=solid];
n2 -> n3 [label="남은 파드가 응답한다", style=solid];
n1 -> n4 [label="무엇을 보고 판단하나", style=solid];
}
docs/keycloak-session-store/final/assets/d2-upgrade-direction/d2-upgrade-direction.drawio
+46
View File
@@ -0,0 +1,46 @@
<?xml version="1.0" encoding="UTF-8"?>
<mxfile host="app.diagrams.net" modified="2026-07-23T00:00:00.000Z" agent="techviz-harness" version="24.7.17" type="device">
<diagram id="d2-upgrade-direction" name="방향에 따라 갈리는 업그레이드">
<mxGraphModel dx="680" dy="689" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="827" pageHeight="1169" math="0" shadow="0">
<root>
<mxCell id="0"/>
<mxCell id="1" parent="0"/>
<mxCell id="n_rollback" value="옛 버전으로 되돌리기" tooltip="이미지 태그를 되돌린다. | Evidence: L483-L490" style="whiteSpace=wrap;html=1;rounded=1;strokeWidth=2;fontSize=14;fontStyle=1;fillColor=#ffffff;strokeColor=#2d4357;verticalAlign=middle;strokeColor=#d97706;fillColor=#fffdf5;" vertex="1" parent="1">
<mxGeometry x="199.0" y="60.0" width="150.0" height="64.0" as="geometry"/>
</mxCell>
<mxCell id="n_liquibase" value="Liquibase 검증&lt;br/&gt;ValidationFailedException: 1 changesets check sum" tooltip="새 버전이 남긴 체크섬을 거부한다. | Evidence: L483-L491" style="whiteSpace=wrap;html=1;rounded=1;strokeWidth=2;fontSize=14;fontStyle=1;fillColor=#ffffff;strokeColor=#2d4357;verticalAlign=middle;strokeColor=#d97706;fillColor=#fffdf5;" vertex="1" parent="1">
<mxGeometry x="124.0" y="220.0" width="300.0" height="71.0" as="geometry"/>
</mxCell>
<mxCell id="n_changelog" value="databasechangelog 행 수&lt;br/&gt;늘었으면 스키마가 움직였다" tooltip="전후로 같으면 롤백된다. | Evidence: L499-L505" style="whiteSpace=wrap;html=1;rounded=1;strokeWidth=2;fontSize=14;fontStyle=1;fillColor=#ffffff;strokeColor=#2d4357;verticalAlign=middle;shape=cylinder3;boundedLbl=1;backgroundOutline=1;fillColor=#eef6fb;strokeColor=#2563eb;strokeWidth=2;" vertex="1" parent="1">
<mxGeometry x="70.0" y="387.0" width="181.0" height="97.0" as="geometry"/>
</mxCell>
<mxCell id="n_rolling" value="StatefulSet 롤링 업데이트&lt;br/&gt;나머지 파드는 건드리지 않는다" tooltip="첫 파드가 실패하면 거기서 멈춘다. | Evidence: L492-L497" style="whiteSpace=wrap;html=1;rounded=1;strokeWidth=2;fontSize=14;fontStyle=1;fillColor=#ffffff;strokeColor=#2d4357;verticalAlign=middle;strokeColor=#2563eb;strokeWidth=2;" vertex="1" parent="1">
<mxGeometry x="311.0" y="400.0" width="167.0" height="71.0" as="geometry"/>
</mxCell>
<mxCell id="n_service" value="외부 서비스" tooltip="남은 파드가 계속 200 을 낸다. | Evidence: L492-L498" style="whiteSpace=wrap;html=1;rounded=1;strokeWidth=2;fontSize=14;fontStyle=1;fillColor=#ffffff;strokeColor=#2d4357;verticalAlign=middle;strokeColor=#2563eb;strokeWidth=2;" vertex="1" parent="1">
<mxGeometry x="199.0" y="580.0" width="150.0" height="64.0" as="geometry"/>
</mxCell>
<mxCell id="e_l-cl" value="무엇을 보고 판단하나" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;strokeWidth=2;endArrow=block;endFill=1;" edge="1" parent="1" source="n_liquibase" target="n_changelog">
<mxGeometry relative="1" as="geometry">
<mxPoint x="212.8" y="311.0" as="offset"/>
</mxGeometry>
</mxCell>
<mxCell id="e_l-ro" value="실패가 여기서 멈춘다" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;strokeWidth=2;endArrow=block;endFill=1;" edge="1" parent="1" source="n_liquibase" target="n_rolling">
<mxGeometry relative="1" as="geometry">
<mxPoint x="338.8" y="317.5" as="offset"/>
</mxGeometry>
</mxCell>
<mxCell id="e_r-l" value="기동 시 검증" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;strokeWidth=2;endArrow=block;endFill=1;" edge="1" parent="1" source="n_rollback" target="n_liquibase">
<mxGeometry relative="1" as="geometry">
<mxPoint x="298.0" y="172.0" as="offset"/>
</mxGeometry>
</mxCell>
<mxCell id="e_ro-s" value="남은 파드가 응답한다" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;strokeWidth=2;endArrow=block;endFill=1;" edge="1" parent="1" source="n_rolling" target="n_service">
<mxGeometry relative="1" as="geometry">
<mxPoint x="334.2" y="497.5" as="offset"/>
</mxGeometry>
</mxCell>
</root>
</mxGraphModel>
</diagram>
</mxfile>
docs/keycloak-session-store/final/assets/d2-upgrade-direction/d2-upgrade-direction.excalidraw
+754
View File
@@ -0,0 +1,754 @@
{
"type": "excalidraw",
"version": 2,
"source": "techviz-harness",
"elements": [
{
"id": "edge-l-cl",
"type": "arrow",
"x": 160.5,
"y": 291.0,
"width": 104.5,
"height": 96.0,
"angle": 0,
"strokeColor": "#1e1e1e",
"backgroundColor": "transparent",
"fillStyle": "solid",
"strokeWidth": 2,
"strokeStyle": "solid",
"roughness": 1,
"opacity": 100,
"groupIds": [],
"frameId": null,
"index": null,
"roundness": null,
"seed": 417114022,
"version": 1,
"versionNonce": 417951526,
"isDeleted": false,
"boundElements": [],
"updated": 0,
"link": null,
"locked": false,
"points": [
[
104.5,
0.0
],
[
104.5,
48.0
],
[
0.0,
48.0
],
[
0.0,
96.0
]
],
"lastCommittedPoint": null,
"startBinding": {
"elementId": "node-liquibase",
"focus": 0,
"gap": 4
},
"endBinding": {
"elementId": "node-changelog",
"focus": 0,
"gap": 4
},
"startArrowhead": null,
"endArrowhead": "arrow",
"elbowed": true
},
{
"id": "edge-label-l-cl",
"type": "text",
"x": 167.75,
"y": 299.0,
"width": 90,
"height": 24,
"angle": 0,
"strokeColor": "#1e1e1e",
"backgroundColor": "transparent",
"fillStyle": "solid",
"strokeWidth": 1,
"strokeStyle": "solid",
"roughness": 0,
"opacity": 100,
"groupIds": [],
"frameId": null,
"index": null,
"roundness": {
"type": 3
},
"seed": 927744910,
"version": 1,
"versionNonce": 1746507351,
"isDeleted": false,
"boundElements": [],
"updated": 0,
"link": null,
"locked": false,
"fontSize": 13,
"fontFamily": 5,
"text": "무엇을 보고 판단하나",
"textAlign": "center",
"verticalAlign": "middle",
"containerId": null,
"originalText": "무엇을 보고 판단하나",
"autoResize": true,
"lineHeight": 1.25
},
{
"id": "edge-l-ro",
"type": "arrow",
"x": 283.0,
"y": 291.0,
"width": 111.5,
"height": 109.0,
"angle": 0,
"strokeColor": "#1e1e1e",
"backgroundColor": "transparent",
"fillStyle": "solid",
"strokeWidth": 2,
"strokeStyle": "solid",
"roughness": 1,
"opacity": 100,
"groupIds": [],
"frameId": null,
"index": null,
"roundness": null,
"seed": 383387180,
"version": 1,
"versionNonce": 79738608,
"isDeleted": false,
"boundElements": [],
"updated": 0,
"link": null,
"locked": false,
"points": [
[
0.0,
0.0
],
[
0.0,
54.5
],
[
111.5,
54.5
],
[
111.5,
109.0
]
],
"lastCommittedPoint": null,
"startBinding": {
"elementId": "node-liquibase",
"focus": 0,
"gap": 4
},
"endBinding": {
"elementId": "node-rolling",
"focus": 0,
"gap": 4
},
"startArrowhead": null,
"endArrowhead": "arrow",
"elbowed": true
},
{
"id": "edge-label-l-ro",
"type": "text",
"x": 293.75,
"y": 305.5,
"width": 90,
"height": 24,
"angle": 0,
"strokeColor": "#1e1e1e",
"backgroundColor": "transparent",
"fillStyle": "solid",
"strokeWidth": 1,
"strokeStyle": "solid",
"roughness": 0,
"opacity": 100,
"groupIds": [],
"frameId": null,
"index": null,
"roundness": {
"type": 3
},
"seed": 203307058,
"version": 1,
"versionNonce": 518380451,
"isDeleted": false,
"boundElements": [],
"updated": 0,
"link": null,
"locked": false,
"fontSize": 13,
"fontFamily": 5,
"text": "실패가 여기서 멈춘다",
"textAlign": "center",
"verticalAlign": "middle",
"containerId": null,
"originalText": "실패가 여기서 멈춘다",
"autoResize": true,
"lineHeight": 1.25
},
{
"id": "edge-r-l",
"type": "arrow",
"x": 274.0,
"y": 124.0,
"width": 0.0,
"height": 96.0,
"angle": 0,
"strokeColor": "#1e1e1e",
"backgroundColor": "transparent",
"fillStyle": "solid",
"strokeWidth": 2,
"strokeStyle": "solid",
"roughness": 1,
"opacity": 100,
"groupIds": [],
"frameId": null,
"index": null,
"roundness": null,
"seed": 365871980,
"version": 1,
"versionNonce": 1230363411,
"isDeleted": false,
"boundElements": [],
"updated": 0,
"link": null,
"locked": false,
"points": [
[
0.0,
0.0
],
[
0.0,
48.0
],
[
0.0,
48.0
],
[
0.0,
96.0
]
],
"lastCommittedPoint": null,
"startBinding": {
"elementId": "node-rollback",
"focus": 0,
"gap": 4
},
"endBinding": {
"elementId": "node-liquibase",
"focus": 0,
"gap": 4
},
"startArrowhead": null,
"endArrowhead": "arrow",
"elbowed": true
},
{
"id": "edge-label-r-l",
"type": "text",
"x": 253.0,
"y": 160.0,
"width": 90,
"height": 24,
"angle": 0,
"strokeColor": "#1e1e1e",
"backgroundColor": "transparent",
"fillStyle": "solid",
"strokeWidth": 1,
"strokeStyle": "solid",
"roughness": 0,
"opacity": 100,
"groupIds": [],
"frameId": null,
"index": null,
"roundness": {
"type": 3
},
"seed": 403610727,
"version": 1,
"versionNonce": 1279300050,
"isDeleted": false,
"boundElements": [],
"updated": 0,
"link": null,
"locked": false,
"fontSize": 13,
"fontFamily": 5,
"text": "기동 시 검증",
"textAlign": "center",
"verticalAlign": "middle",
"containerId": null,
"originalText": "기동 시 검증",
"autoResize": true,
"lineHeight": 1.25
},
{
"id": "edge-ro-s",
"type": "arrow",
"x": 274.0,
"y": 471.0,
"width": 120.5,
"height": 109.0,
"angle": 0,
"strokeColor": "#1e1e1e",
"backgroundColor": "transparent",
"fillStyle": "solid",
"strokeWidth": 2,
"strokeStyle": "solid",
"roughness": 1,
"opacity": 100,
"groupIds": [],
"frameId": null,
"index": null,
"roundness": null,
"seed": 1207881606,
"version": 1,
"versionNonce": 455117194,
"isDeleted": false,
"boundElements": [],
"updated": 0,
"link": null,
"locked": false,
"points": [
[
120.5,
0.0
],
[
120.5,
54.5
],
[
0.0,
54.5
],
[
0.0,
109.0
]
],
"lastCommittedPoint": null,
"startBinding": {
"elementId": "node-rolling",
"focus": 0,
"gap": 4
},
"endBinding": {
"elementId": "node-service",
"focus": 0,
"gap": 4
},
"startArrowhead": null,
"endArrowhead": "arrow",
"elbowed": true
},
{
"id": "edge-label-ro-s",
"type": "text",
"x": 289.25,
"y": 485.5,
"width": 90,
"height": 24,
"angle": 0,
"strokeColor": "#1e1e1e",
"backgroundColor": "transparent",
"fillStyle": "solid",
"strokeWidth": 1,
"strokeStyle": "solid",
"roughness": 0,
"opacity": 100,
"groupIds": [],
"frameId": null,
"index": null,
"roundness": {
"type": 3
},
"seed": 900557432,
"version": 1,
"versionNonce": 552667501,
"isDeleted": false,
"boundElements": [],
"updated": 0,
"link": null,
"locked": false,
"fontSize": 13,
"fontFamily": 5,
"text": "남은 파드가 응답한다",
"textAlign": "center",
"verticalAlign": "middle",
"containerId": null,
"originalText": "남은 파드가 응답한다",
"autoResize": true,
"lineHeight": 1.25
},
{
"id": "node-rollback",
"type": "rectangle",
"x": 199.0,
"y": 60.0,
"width": 150.0,
"height": 64.0,
"angle": 0,
"strokeColor": "#1e1e1e",
"backgroundColor": "#ffffff",
"fillStyle": "solid",
"strokeWidth": 2,
"strokeStyle": "solid",
"roughness": 1,
"opacity": 100,
"groupIds": [],
"frameId": null,
"index": null,
"roundness": {
"type": 3
},
"seed": 860780826,
"version": 1,
"versionNonce": 1667969784,
"isDeleted": false,
"boundElements": [],
"updated": 0,
"link": null,
"locked": false
},
{
"id": "node-label-rollback",
"type": "text",
"x": 209.0,
"y": 70.0,
"width": 130.0,
"height": 44.0,
"angle": 0,
"strokeColor": "#1e1e1e",
"backgroundColor": "transparent",
"fillStyle": "solid",
"strokeWidth": 1,
"strokeStyle": "solid",
"roughness": 0,
"opacity": 100,
"groupIds": [],
"frameId": null,
"index": null,
"roundness": {
"type": 3
},
"seed": 1555979348,
"version": 1,
"versionNonce": 640255252,
"isDeleted": false,
"boundElements": [],
"updated": 0,
"link": null,
"locked": false,
"fontSize": 15,
"fontFamily": 5,
"text": "옛 버전으로 되돌리기",
"textAlign": "center",
"verticalAlign": "middle",
"containerId": null,
"originalText": "옛 버전으로 되돌리기",
"autoResize": true,
"lineHeight": 1.25
},
{
"id": "node-liquibase",
"type": "rectangle",
"x": 124.0,
"y": 220.0,
"width": 300.0,
"height": 71.0,
"angle": 0,
"strokeColor": "#1e1e1e",
"backgroundColor": "#ffffff",
"fillStyle": "solid",
"strokeWidth": 2,
"strokeStyle": "solid",
"roughness": 1,
"opacity": 100,
"groupIds": [],
"frameId": null,
"index": null,
"roundness": {
"type": 3
},
"seed": 1141244519,
"version": 1,
"versionNonce": 1693830728,
"isDeleted": false,
"boundElements": [],
"updated": 0,
"link": null,
"locked": false
},
{
"id": "node-label-liquibase",
"type": "text",
"x": 134.0,
"y": 230.0,
"width": 280.0,
"height": 51.0,
"angle": 0,
"strokeColor": "#1e1e1e",
"backgroundColor": "transparent",
"fillStyle": "solid",
"strokeWidth": 1,
"strokeStyle": "solid",
"roughness": 0,
"opacity": 100,
"groupIds": [],
"frameId": null,
"index": null,
"roundness": {
"type": 3
},
"seed": 860083864,
"version": 1,
"versionNonce": 527868087,
"isDeleted": false,
"boundElements": [],
"updated": 0,
"link": null,
"locked": false,
"fontSize": 15,
"fontFamily": 5,
"text": "Liquibase 검증\nValidationFailedException: 1 changesets check sum",
"textAlign": "center",
"verticalAlign": "middle",
"containerId": null,
"originalText": "Liquibase 검증\nValidationFailedException: 1 changesets check sum",
"autoResize": true,
"lineHeight": 1.25
},
{
"id": "node-changelog",
"type": "rectangle",
"x": 70.0,
"y": 387.0,
"width": 181.0,
"height": 97.0,
"angle": 0,
"strokeColor": "#1e1e1e",
"backgroundColor": "#e7f5ff",
"fillStyle": "solid",
"strokeWidth": 2,
"strokeStyle": "solid",
"roughness": 1,
"opacity": 100,
"groupIds": [],
"frameId": null,
"index": null,
"roundness": {
"type": 3
},
"seed": 118557854,
"version": 1,
"versionNonce": 419589167,
"isDeleted": false,
"boundElements": [],
"updated": 0,
"link": null,
"locked": false
},
{
"id": "node-label-changelog",
"type": "text",
"x": 80.0,
"y": 397.0,
"width": 161.0,
"height": 77.0,
"angle": 0,
"strokeColor": "#1e1e1e",
"backgroundColor": "transparent",
"fillStyle": "solid",
"strokeWidth": 1,
"strokeStyle": "solid",
"roughness": 0,
"opacity": 100,
"groupIds": [],
"frameId": null,
"index": null,
"roundness": {
"type": 3
},
"seed": 656588475,
"version": 1,
"versionNonce": 1944113786,
"isDeleted": false,
"boundElements": [],
"updated": 0,
"link": null,
"locked": false,
"fontSize": 15,
"fontFamily": 5,
"text": "databasechangelog 행 수\n늘었으면 스키마가 움직였다",
"textAlign": "center",
"verticalAlign": "middle",
"containerId": null,
"originalText": "databasechangelog 행 수\n늘었으면 스키마가 움직였다",
"autoResize": true,
"lineHeight": 1.25
},
{
"id": "node-rolling",
"type": "rectangle",
"x": 311.0,
"y": 400.0,
"width": 167.0,
"height": 71.0,
"angle": 0,
"strokeColor": "#1e1e1e",
"backgroundColor": "#ffffff",
"fillStyle": "solid",
"strokeWidth": 2,
"strokeStyle": "solid",
"roughness": 1,
"opacity": 100,
"groupIds": [],
"frameId": null,
"index": null,
"roundness": {
"type": 3
},
"seed": 564674954,
"version": 1,
"versionNonce": 565935337,
"isDeleted": false,
"boundElements": [],
"updated": 0,
"link": null,
"locked": false
},
{
"id": "node-label-rolling",
"type": "text",
"x": 321.0,
"y": 410.0,
"width": 147.0,
"height": 51.0,
"angle": 0,
"strokeColor": "#1e1e1e",
"backgroundColor": "transparent",
"fillStyle": "solid",
"strokeWidth": 1,
"strokeStyle": "solid",
"roughness": 0,
"opacity": 100,
"groupIds": [],
"frameId": null,
"index": null,
"roundness": {
"type": 3
},
"seed": 749722027,
"version": 1,
"versionNonce": 1585714182,
"isDeleted": false,
"boundElements": [],
"updated": 0,
"link": null,
"locked": false,
"fontSize": 15,
"fontFamily": 5,
"text": "StatefulSet 롤링 업데이트\n나머지 파드는 건드리지 않는다",
"textAlign": "center",
"verticalAlign": "middle",
"containerId": null,
"originalText": "StatefulSet 롤링 업데이트\n나머지 파드는 건드리지 않는다",
"autoResize": true,
"lineHeight": 1.25
},
{
"id": "node-service",
"type": "rectangle",
"x": 199.0,
"y": 580.0,
"width": 150.0,
"height": 64.0,
"angle": 0,
"strokeColor": "#1e1e1e",
"backgroundColor": "#ffffff",
"fillStyle": "solid",
"strokeWidth": 2,
"strokeStyle": "solid",
"roughness": 1,
"opacity": 100,
"groupIds": [],
"frameId": null,
"index": null,
"roundness": {
"type": 3
},
"seed": 730729362,
"version": 1,
"versionNonce": 1977234944,
"isDeleted": false,
"boundElements": [],
"updated": 0,
"link": null,
"locked": false
},
{
"id": "node-label-service",
"type": "text",
"x": 209.0,
"y": 590.0,
"width": 130.0,
"height": 44.0,
"angle": 0,
"strokeColor": "#1e1e1e",
"backgroundColor": "transparent",
"fillStyle": "solid",
"strokeWidth": 1,
"strokeStyle": "solid",
"roughness": 0,
"opacity": 100,
"groupIds": [],
"frameId": null,
"index": null,
"roundness": {
"type": 3
},
"seed": 247193971,
"version": 1,
"versionNonce": 1117674851,
"isDeleted": false,
"boundElements": [],
"updated": 0,
"link": null,
"locked": false,
"fontSize": 15,
"fontFamily": 5,
"text": "외부 서비스",
"textAlign": "center",
"verticalAlign": "middle",
"containerId": null,
"originalText": "외부 서비스",
"autoResize": true,
"lineHeight": 1.25
}
],
"appState": {
"gridSize": 10,
"viewBackgroundColor": "#ffffff",
"currentItemFontFamily": 5
},
"files": {}
}
docs/keycloak-session-store/final/assets/d2-upgrade-direction/d2-upgrade-direction.manifest.json
+32
View File
@@ -0,0 +1,32 @@
{
"harness_version": "0.2.0",
"spec_id": "d2-upgrade-direction",
"spec_version": "1.1",
"spec_sha256": "30ae7b783f6b33d4364a113637e61b09cbf87be39bac08a41b49f134f2a845be",
"source_context": {
"document": "docs/keycloak-session-store/final/document.md",
"document_sha256": "1d44cba1905544d92f1d26ae36a8deb64a3db3914d6b488fd30d6ae7f8cfbabe",
"anchor": {
"kind": "heading",
"value": "D-1 · D-2 — 백업과 업그레이드",
"line": 481
}
},
"outputs": [
"d2-upgrade-direction.svg",
"d2-upgrade-direction.mmd",
"d2-upgrade-direction.d2",
"d2-upgrade-direction.dot",
"d2-upgrade-direction.drawio",
"d2-upgrade-direction.excalidraw",
"d2-upgrade-direction.alt.md"
],
"lint_issue_count": 0,
"assumption_count": 0,
"assumptions_allowed": false,
"composition_profile": "component-flow",
"reference_ids": [
"payment-event-flow"
],
"diagram_only": true
}
docs/keycloak-session-store/final/assets/d2-upgrade-direction/d2-upgrade-direction.mmd
+12
View File
@@ -0,0 +1,12 @@
%% 방향에 따라 갈리는 업그레이드
%% question: 되돌릴 수 있는지는 무엇이 결정하는가
flowchart TB
n0["옛 버전으로 되돌리기"]
n1["Liquibase 검증"]
n2["StatefulSet 롤링 업데이트"]
n3["외부 서비스"]
n4[("databasechangelog 행 수")]
n0 -->|"기동 시 검증"| n1
n1 -->|"실패가 여기서 멈춘다"| n2
n2 -->|"남은 파드가 응답한다"| n3
n1 -->|"무엇을 보고 판단하나"| n4
docs/keycloak-session-store/final/assets/d2-upgrade-direction/d2-upgrade-direction.svg
+91
View File
@@ -0,0 +1,91 @@
<?xml version="1.0" encoding="UTF-8"?>
<svg xmlns="http://www.w3.org/2000/svg" width="680" height="689" viewBox="0 0 680 689" role="img" aria-labelledby="diagram-title diagram-description">
<title id="diagram-title">방향에 따라 갈리는 업그레이드</title>
<desc id="diagram-description">26.7.0 에서 26.7.3 으로 올리는 것은 무중단이었고 87회 요청이 전부 200 이었다. 되돌리기는 Liquibase 가 체크섬 검증에서 막았다. 새 버전이 남긴 체크섬을 옛 버전이 거부하기 때문이다. 그런데 서비스는 살아 있었다. StatefulSet 롤링 업데이트가 첫 파드에서 멈추고 나머지를 건드리지 않았기 때문이다. 롤백 불가는 조건부이며 판단 기준은 databasechangelog 의 행 수가 업그레이드 전후로 같은가이다.</desc>
<metadata>{&quot;techviz&quot;:{&quot;spec_version&quot;:&quot;1.1&quot;,&quot;id&quot;:&quot;d2-upgrade-direction&quot;,&quot;profile&quot;:&quot;component-flow&quot;},&quot;source_context&quot;:{&quot;document&quot;:&quot;docs/keycloak-session-store/final/document.md&quot;,&quot;document_sha256&quot;:&quot;1d44cba1905544d92f1d26ae36a8deb64a3db3914d6b488fd30d6ae7f8cfbabe&quot;,&quot;anchor&quot;:{&quot;kind&quot;:&quot;heading&quot;,&quot;value&quot;:&quot;D-1 · D-2 — 백업과 업그레이드&quot;,&quot;line&quot;:481}},&quot;evidence_policy&quot;:&quot;Each factual element cites source lines or is marked assumption.&quot;,&quot;diagram_only&quot;:true}</metadata>
<defs>
<marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
<path d="M 0 0 L 10 5 L 0 10 z" />
</marker>
<style>
:root { color-scheme: light; }
text { font-family: Inter, Pretendard, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #111827; }
.canvas { fill: #ffffff; }
.group-box { fill: #ffffff; stroke: #9ca3af; stroke-width: 1.4; stroke-dasharray: 7 5; }
.group-label-bg { fill: #ffffff; }
.group-label { font-size: 13px; font-weight: 650; fill: #374151; }
.edge { fill: none; stroke: #374151; stroke-width: 1.8; stroke-linejoin: round; stroke-linecap: round; marker-end: url(#arrow); }
.edge.style-dashed, .edge.semantic-dashed, .edge.assumption { stroke-dasharray: 7 5; }
.edge.style-dotted { stroke-dasharray: 2 5; }
.edge.emphasis-primary { stroke: #2563eb; stroke-width: 2.2; }
.edge.emphasis-muted { stroke: #9ca3af; }
.edge.emphasis-warning, .edge.kind-failure, .edge.kind-error { stroke: #dc2626; stroke-width: 2.2; }
.edge-label-bg { fill: #ffffff; }
.edge-label { font-size: 12px; font-weight: 560; text-anchor: middle; }
.node-shape { fill: #ffffff; stroke: #4b5563; stroke-width: 1.7; }
.node-shape.emphasis-primary { stroke: #2563eb; stroke-width: 2.2; }
.node-shape.emphasis-muted { stroke: #9ca3af; fill: #f9fafb; }
.node-shape.emphasis-warning { stroke: #d97706; stroke-width: 2; fill: #fffdf5; }
.node-shape.kind-database, .node-shape.kind-datastore, .node-shape.kind-storage { fill: #f8fafc; }
.node-shape.kind-queue, .node-shape.kind-event, .node-shape.kind-topic { fill: #fafafa; }
.node-shape.assumption { stroke-dasharray: 4 4; }
.storage-bottom, .controller-divider { fill: none; stroke: #4b5563; stroke-width: 1.4; }
.controller-led { fill: #4b5563; }
.actor-symbol { fill: none; stroke: #4b5563; stroke-width: 1.8; stroke-linecap: round; }
.actor-symbol.emphasis-primary { stroke: #2563eb; stroke-width: 2.2; }
.node-label { font-size: 14px; font-weight: 650; text-anchor: middle; }
.node-role { font-size: 10px; letter-spacing: 0.04em; text-anchor: middle; fill: #6b7280; }
.node-detail-divider { stroke: #d1d5db; stroke-width: 1; }
.node-detail { font-size: 11px; fill: #374151; }
.assumption-badge { font-size: 9px; font-weight: 700; fill: #92400e; }
.failure-mark { stroke: #dc2626; stroke-width: 4; stroke-linecap: round; }
.lifeline { stroke: #9ca3af; stroke-width: 1.2; stroke-dasharray: 5 5; }
.timeline-axis { stroke: #374151; stroke-width: 1.8; marker-end: url(#arrow); }
.timeline-stem { stroke: #6b7280; stroke-width: 1.3; }
.timeline-marker { fill: #ffffff; stroke: #374151; stroke-width: 1.7; }
.timeline-marker.primary { fill: #2563eb; stroke: #2563eb; }
.timeline-marker.warning { fill: #dc2626; stroke: #dc2626; }
.timeline-label { font-size: 13px; font-weight: 650; text-anchor: middle; }
.timeline-detail { font-size: 11px; fill: #4b5563; text-anchor: middle; }
</style>
</defs>
<rect class="canvas" width="680" height="689" />
<polyline class="edge kind-read style-solid emphasis-normal" points="265.0,291.0 265.0,339.0 160.5,339.0 160.5,387.0" data-evidence="499-505" />
<rect class="edge-label-bg" x="166.9" y="297.0" width="91.7" height="22" rx="3" />
<text class="edge-label" x="212.8" y="312.0">무엇을 보고 판단하나</text>
<polyline class="edge kind-blocked style-solid emphasis-normal" points="283.0,291.0 283.0,345.5 394.5,345.5 394.5,400.0" data-evidence="492-497" />
<rect class="edge-label-bg" x="292.9" y="303.5" width="91.7" height="22" rx="3" />
<text class="edge-label" x="338.8" y="318.5">실패가 여기서 멈춘다</text>
<polyline class="edge kind-request style-solid emphasis-normal" points="274.0,124.0 274.0,172.0 274.0,172.0 274.0,220.0" data-evidence="483-491" />
<rect class="edge-label-bg" x="265.6" y="158.0" width="64.9" height="22" rx="3" />
<text class="edge-label" x="298.0" y="173.0">기동 시 검증</text>
<polyline class="edge kind-request style-solid emphasis-normal" points="394.5,471.0 394.5,525.5 274.0,525.5 274.0,580.0" data-evidence="492-498" />
<rect class="edge-label-bg" x="288.4" y="483.5" width="91.7" height="22" rx="3" />
<text class="edge-label" x="334.2" y="498.5">남은 파드가 응답한다</text>
<g id="node-rollback">
<rect class="node-shape kind-process emphasis-warning role-source" data-evidence="483-490" x="199.0" y="60.0" width="150.0" height="64.0" rx="7" />
<text class="node-label" x="274.0" y="90.0">옛 버전으로 되돌리기</text>
</g>
<g id="node-liquibase">
<rect class="node-shape kind-process emphasis-warning role-control" data-evidence="483-491" x="124.0" y="220.0" width="300.0" height="71.0" rx="7" />
<text class="node-label" x="274.0" y="247.0">Liquibase 검증</text>
<line class="node-detail-divider" x1="138.0" y1="268.0" x2="410.0" y2="268.0" />
<text class="node-detail" x="140.0" y="285.0">ValidationFailedException: 1 changesets check sum</text>
</g>
<g id="node-changelog">
<rect class="node-shape kind-datastore emphasis-primary role-support" data-evidence="499-505" x="70.0" y="400.0" width="181.0" height="71.0" /><ellipse class="node-shape kind-datastore emphasis-primary role-support" cx="160.5" cy="400.0" rx="90.5" ry="13.0" /><path class="storage-bottom" d="M 70.0 471.0 A 90.5 13.0 0 0 0 251.0 471.0" />
<text class="node-label" x="160.5" y="427.0">databasechangelog 행 수</text>
<line class="node-detail-divider" x1="84.0" y1="448.0" x2="237.0" y2="448.0" />
<text class="node-detail" x="86.0" y="465.0">늘었으면 스키마가 움직였다</text>
</g>
<g id="node-rolling">
<rect class="node-shape kind-process emphasis-primary role-control" data-evidence="492-497" x="311.0" y="400.0" width="167.0" height="71.0" rx="7" />
<text class="node-label" x="394.5" y="427.0">StatefulSet 롤링 업데이트</text>
<line class="node-detail-divider" x1="325.0" y1="448.0" x2="464.0" y2="448.0" />
<text class="node-detail" x="327.0" y="465.0">나머지 파드는 건드리지 않는다</text>
</g>
<g id="node-service">
<rect class="node-shape kind-service emphasis-primary role-target" data-evidence="492-498" x="199.0" y="580.0" width="150.0" height="64.0" rx="7" />
<text class="node-label" x="274.0" y="610.0">외부 서비스</text>
</g>
</svg>
Side by Side

After

Width:  |  Height:  |  Size: 7.7 KiB