refactor: 문서 개선 중

2026-09-21 14:30:55 +09:00
parent c93cdea150
commit 805a18f486
1497 changed files with 525837 additions and 59152 deletions
@@ -23,7 +23,7 @@ source:
 - **배포 전에 사람이 돌려야 하는 것과 그 함정**
  이 사건 뒤에 목록으로 굳혔다.
 - **컨테이너는 healthy 였고 SPA 가 부팅에 필요한 파일 하나만 403 이었다**
-  같은 배포에서 드러난 다른 사건이다.
+  같은 배포에서 드러난 다른 사건이다. 여기서 SPA는 Single-Page Application을 뜻한다.

 ## 문제

@@ -15,7 +15,7 @@ source:

 # 컨테이너는 healthy 였고 SPA 가 부팅에 필요한 파일 하나만 403 이었다

-컨테이너는 healthy 로 올라왔는데 SPA 가 부팅되지 않았다. nginx 가 설정 파일 하나를 읽지 못해 그 파일만 403 을 돌려줬다. 빌드가 그 파일을 0600 으로 쓰고 있었다.
+컨테이너는 healthy 로 올라왔는데 SPA(Single-Page Application)가 부팅되지 않았다. nginx 가 설정 파일 하나를 읽지 못해 그 파일만 403 을 돌려줬다. 빌드가 그 파일을 0600 으로 쓰고 있었다.

 ## 관계

@@ -68,7 +68,7 @@ SPA 가 부팅에 필요한 설정 파일은 그 판정에 들어 있지 않다.

 빌드가 그 설정 파일을 0600 으로 쓴다. 파일을 만든 사용자만 읽을 수 있고, nginx 를 돌리는 사용자는 다른 사용자다.

-증상이 404 가 아니라 403 이라는 것이 원인을 좁혔다. 404 면 파일이 없는 것이고 403 이면 파일은 있는데 읽지 못하는 것이므로, 이미지에 파일이 들어갔는지부터 확인할 필요가 없었다.
+증상이 404 가 아니라 403 이라는 것은 이 nginx 구성에서 파일 접근 권한을 먼저 의심할 단서였다. 다만 HTTP 403 자체가 「파일은 존재하지만 읽지 못한다」를 보장하지는 않는다. nginx 의 deny 규칙이나 앞단 인증·인가에서도 403 이 날 수 있다. 이 사건은 이미지 안의 파일 mode 가 0600 인 것을 확인하면서 권한 문제로 확정했다.

 이미지가 권한을 정규화하도록 고쳤다. 빌드 단계에서 쓰는 권한을 바꾸는 대신 이미지가 마지막에 정리하게 한 것은, 빌드 도구가 그 권한을 왜 그렇게 쓰는지가 이 저장소 밖의 사정이기 때문이다.

@@ -22,7 +22,7 @@ source:
 - **배포 인자를 빠뜨려 배포본이 존재하지 않는 주소를 불렀다**
  이 경로에서 빌드 인자가 어떻게 새는지가 그 기록에 있다.
 - **컨테이너는 healthy 였고 SPA 가 부팅에 필요한 파일 하나만 403 이었다**
-  이미지 안의 권한이 배포에서 드러난 사건이다.
+  이미지 안의 권한이 배포에서 드러난 사건이다. 여기서 SPA는 Single-Page Application을 뜻한다.
 - **배포 전에 사람이 돌려야 하는 것과 그 함정**
  이 경로에서 사람이 기억해야 하는 것들이 그 기준에 있다.

@@ -32,12 +32,17 @@ source:

 ## 레지스트리를 쓰지 않는다

+이 블록은 복사해 실행하는 runbook이 아니라 배포 단계의 순서만 보여 주는 reference schematic이다.
+
 ```text
-로컬 docker build  →  docker save | gzip  →  scp dh-server:/tmp/deploy.tar.gz
-  →  kube-system 의 containerd import Job  →  kubectl set image
+로컬 이미지 빌드
+  → 이미지 tar 압축
+  → 서버로 전송
+  → 일회성 containerd import Job
+  → 배포 이미지 교체
 ```

-공개 Hub 는 소스가 들어간 이미지라 쓸 수 없다. k3s 의 containerd 소켓은 root 전용이라 사용자 셸에서 닿지 않는다. 그래서 클러스터 안에 일회성 Job 을 띄워 tar 를 import 한다 — Job 은 클러스터 권한으로 도므로 그 소켓에 닿는다.
+공개 Hub 는 소스가 들어간 이미지라 쓸 수 없다. k3s 의 containerd 소켓은 root 전용이라 사용자 셸에서 닿지 않는다. 그래서 클러스터 안의 일회성 Job 으로 tar 를 import 하는 경로를 쓴다. 다만 Job 이 `kube-system` 에 있거나 클러스터 RBAC 권한을 가진다는 이유만으로 host 소켓에 접근할 수 있는 것은 아니다. 이 경로에는 host 의 containerd 소켓을 명시적으로 mount 하고 그 소켓을 열 수 있는 권한으로 실행한다는 전제가 필요하다.

 배포 단위는 `hyeonworks.com` 하나이고 서브도메인을 쓰지 않는다. 공개는 `/`, API 는 `/api` 다.