document-haness/docs/keycloak-session-store/final/.techviz/d2-upgrade-direction/spec.json

{
  "version": "1.1",
  "id": "d2-upgrade-direction",
  "title": "방향에 따라 갈리는 업그레이드",
  "question": "되돌릴 수 있는지는 무엇이 결정하는가",
  "type": "architecture",
  "direction": "TB",
  "audience": [
    "버전 업그레이드를 계획하는 운영 엔지니어"
  ],
  "summary": "스키마가 움직였는지가 결정한다. databasechangelog 의 행 수를 전후로 비교하면 알 수 있다.",
  "alt": "앞으로 가는 경로는 무중단이고 뒤로 가는 경로는 Liquibase 검증에서 막히는 구성. 롤링 업데이트가 그 사고를 절반에서 멈춘다.",
  "long_description": "26.7.0 에서 26.7.3 으로 올리는 것은 무중단이었고 87회 요청이 전부 200 이었다. 되돌리기는 Liquibase 가 체크섬 검증에서 막았다. 새 버전이 남긴 체크섬을 옛 버전이 거부하기 때문이다. 그런데 서비스는 살아 있었다. StatefulSet 롤링 업데이트가 첫 파드에서 멈추고 나머지를 건드리지 않았기 때문이다. 롤백 불가는 조건부이며 판단 기준은 databasechangelog 의 행 수가 업그레이드 전후로 같은가이다.",
  "source_context": {
    "document": "docs/keycloak-session-store/final/document.md",
    "document_sha256": "1d44cba1905544d92f1d26ae36a8deb64a3db3914d6b488fd30d6ae7f8cfbabe",
    "anchor": {
      "kind": "heading",
      "value": "D-1 · D-2 — 백업과 업그레이드",
      "line": 481
    }
  },
  "composition": {
    "profile": "component-flow",
    "diagram_only": true,
    "reference_ids": [
      "payment-event-flow"
    ],
    "rationale": "같은 작업이 방향에 따라 다른 결과를 내는 것이 지배적 질문이다. 경로의 차단 지점이므로 component-flow 를 골랐다."
  },
  "groups": [],
  "nodes": [
    {
      "id": "rollback",
      "label": "옛 버전으로 되돌리기",
      "kind": "process",
      "role": "source",
      "emphasis": "warning",
      "description": "이미지 태그를 되돌린다.",
      "details": [],
      "evidence": [
        {
          "start_line": 483,
          "end_line": 490
        }
      ],
      "assumption": false
    },
    {
      "id": "liquibase",
      "label": "Liquibase 검증",
      "kind": "process",
      "role": "control",
      "emphasis": "warning",
      "description": "새 버전이 남긴 체크섬을 거부한다.",
      "details": [
        "ValidationFailedException: 1 changesets check sum"
      ],
      "evidence": [
        {
          "start_line": 483,
          "end_line": 491
        }
      ],
      "assumption": false
    },
    {
      "id": "rolling",
      "label": "StatefulSet 롤링 업데이트",
      "kind": "process",
      "role": "control",
      "emphasis": "primary",
      "description": "첫 파드가 실패하면 거기서 멈춘다.",
      "details": [
        "나머지 파드는 건드리지 않는다"
      ],
      "evidence": [
        {
          "start_line": 492,
          "end_line": 497
        }
      ],
      "assumption": false
    },
    {
      "id": "service",
      "label": "외부 서비스",
      "kind": "service",
      "role": "target",
      "emphasis": "primary",
      "description": "남은 파드가 계속 200 을 낸다.",
      "details": [],
      "evidence": [
        {
          "start_line": 492,
          "end_line": 498
        }
      ],
      "assumption": false
    },
    {
      "id": "changelog",
      "label": "databasechangelog 행 수",
      "kind": "datastore",
      "role": "support",
      "emphasis": "primary",
      "description": "전후로 같으면 롤백된다.",
      "details": [
        "늘었으면 스키마가 움직였다"
      ],
      "evidence": [
        {
          "start_line": 499,
          "end_line": 505
        }
      ],
      "assumption": false
    }
  ],
  "edges": [
    {
      "id": "r-l",
      "from": "rollback",
      "to": "liquibase",
      "label": "기동 시 검증",
      "kind": "request",
      "evidence": [
        {
          "start_line": 483,
          "end_line": 491
        }
      ],
      "assumption": false
    },
    {
      "id": "l-ro",
      "from": "liquibase",
      "to": "rolling",
      "label": "실패가 여기서 멈춘다",
      "kind": "blocked",
      "evidence": [
        {
          "start_line": 492,
          "end_line": 497
        }
      ],
      "assumption": false
    },
    {
      "id": "ro-s",
      "from": "rolling",
      "to": "service",
      "label": "남은 파드가 응답한다",
      "kind": "request",
      "evidence": [
        {
          "start_line": 492,
          "end_line": 498
        }
      ],
      "assumption": false
    },
    {
      "id": "l-cl",
      "from": "liquibase",
      "to": "changelog",
      "label": "무엇을 보고 판단하나",
      "kind": "read",
      "evidence": [
        {
          "start_line": 499,
          "end_line": 505
        }
      ],
      "assumption": false
    }
  ],
  "legend": [],
  "metadata": {
    "rationale": "체크섬 검증과 롤링 업데이트를 함께 그렸다. 하나는 막고 하나는 피해를 줄인다."
  }
}