From c83b40ce501f17c4971b2826c8f7429720dd2030 Mon Sep 17 00:00:00 2001
From: qorgh529 <qorgh529@gitea.com>
Date: Fri, 10 Apr 2026 21:40:33 +0900
Subject: [PATCH] =?UTF-8?q?docs:=20=EB=8F=84=EB=A9=94=EC=9D=B8=20=EC=97=B0?=
 =?UTF-8?q?=EA=B2=B0=20=EB=B0=8F=20HTTPS=20=EC=84=A4=EC=A0=95=20=EB=82=B4?=
 =?UTF-8?q?=EC=9A=A9=20=EC=B6=94=EA=B0=80?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.md | 132 ++++++++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 123 insertions(+), 9 deletions(-)

diff --git a/README.md b/README.md
index 33a5ef8..71db4de 100755
--- a/README.md
+++ b/README.md
@@ -11,17 +11,25 @@
 ## 🏗️ 전체 아키텍처
 
 ```
+사용자 (외부 인터넷)
+    ↓ https://cyanburu.com (443)
+MSI 라우터 (포트포워딩 80/443)
+    ↓
+Nginx Ingress Controller  ← TLS 종료, 라우팅
+    ↓
+cert-manager              ← Let's Encrypt 인증서 자동 발급/갱신
+    ↓
+Kubernetes - web-portal 네임스페이스
+  ├── Nginx Frontend  (ClusterIP: 80)
+  ├── FastAPI Backend (ClusterIP: 8000)
+  └── PostgreSQL DB   (ClusterIP: 5432)
+      ↑
 개발자 (git push)
     ↓
 Gitea (192.168.10.101:30000)
   └── Container Registry (이미지 저장)
     ↓
 ArgoCD 자동 감지 & 배포 (192.168.10.101:30080)
-    ↓
-Kubernetes - web-portal 네임스페이스
-  ├── Nginx Frontend  (NodePort: 30090)
-  ├── FastAPI Backend (ClusterIP: 8000)
-  └── PostgreSQL DB   (ClusterIP: 5432)
 ```
 
 ---
@@ -37,6 +45,9 @@ Kubernetes - web-portal 네임스페이스
 | Orchestration | Kubernetes (Docker Desktop 내장) |
 | GitOps | Gitea + ArgoCD |
 | Image Registry | Gitea Container Registry |
+| Ingress | Nginx Ingress Controller |
+| TLS | cert-manager + Let's Encrypt |
+| Domain | cyanburu.com (후이즈) |
 
 ---
 
@@ -63,6 +74,10 @@ nginx-portal/
 │   └── 05-frontend.yaml         # Nginx Deployment + NodePort(30090)
 ├── 06-argocd-app.yaml           # ArgoCD Application 정의 (k8s 폴더 밖에 위치)
 └── README.md
+
+k8s/ 폴더 내 추가 파일:
+├── 07-clusterissuer.yaml        # Let's Encrypt ClusterIssuer
+└── 08-ingress.yaml              # Nginx Ingress 규칙 + TLS 설정
 ```
 
 > ⚠️ `06-argocd-app.yaml` 은 반드시 `k8s/` 폴더 **밖**에 위치해야 합니다.
@@ -180,9 +195,65 @@ kubectl label secret gitea-repo-secret \
 kubectl apply -f 06-argocd-app.yaml
 ```
 
-### 6단계. 접속 확인
+### 6단계. Nginx Ingress Controller 설치 (최초 1회)
+```bash
+kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/controller-v1.10.0/deploy/static/provider/cloud/deploy.yaml
+kubectl get pods -n ingress-nginx
 ```
-http://192.168.10.101:30090
+
+### 7단계. cert-manager 설치 (최초 1회)
+```bash
+kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.14.4/cert-manager.yaml
+kubectl get pods -n cert-manager
+```
+
+### 8단계. CoreDNS 내부 도메인 등록 (헤어핀 NAT 우회)
+```bash
+kubectl patch configmap coredns -n kube-system --patch-file coredns-patch.yaml
+kubectl rollout restart deployment/coredns -n kube-system
+```
+
+> `coredns-patch.yaml` 내용:
+> ```yaml
+> data:
+>   Corefile: |
+>     cyanburu.com {
+>         hosts {
+>             192.168.10.101 cyanburu.com
+>             fallthrough
+>         }
+>         cache 30
+>     }
+>     .:53 {
+>         ... (기존 내용 유지)
+>     }
+> ```
+
+### 9단계. 라우터 포트포워딩 설정
+MSI 라우터에서 설정:
+
+| 공용 포트 | 내부 IP | 비공개 포트 |
+|-----------|---------|-------------|
+| 80 | 192.168.10.101 | 80 |
+| 443 | 192.168.10.101 | 443 |
+
+### 10단계. Ingress + ClusterIssuer 배포
+```bash
+git add k8s/07-clusterissuer.yaml k8s/08-ingress.yaml k8s/05-frontend.yaml
+git commit -m "feat: Ingress + cert-manager HTTPS 설정"
+git push origin main
+# ArgoCD가 자동 배포
+```
+
+### 11단계. 인증서 발급 확인
+```bash
+kubectl get certificate -n web-portal
+# READY: True 확인
+```
+
+### 12단계. 접속 확인
+```
+https://cyanburu.com
 ```
 
 ---
@@ -267,6 +338,11 @@ location /api/auth/login {
 - **CAPTCHA**: 로그인 3회 실패 시 Google reCAPTCHA 표시 (추가 개발 필요)
 - **JWT 만료 시간 단축**: `main.py` 에서 `timedelta(hours=8)` → `timedelta(hours=2)` 변경 가능
 
+### HTTPS / TLS
+- cert-manager가 Let's Encrypt 인증서를 **자동으로 갱신** (만료 30일 전)
+- HTTP 접속 시 자동으로 HTTPS로 리다이렉트 (`ssl-redirect: "true"`)
+- 인증서 상태 확인: `kubectl get certificate -n web-portal`
+
 ---
 
 ## ❗ 트러블슈팅
@@ -481,7 +557,35 @@ git push origin main
 
 ---
 
-### 11. git commit 시 Author identity unknown
+### 11. cert-manager HTTP01 Challenge pending (헤어핀 NAT)
+**증상**
+```
+propagation check failed: failed to perform self check GET request
+context deadline exceeded (Client.Timeout exceeded while awaiting headers)
+```
+**원인** cert-manager가 K8s 내부에서 외부 도메인(`cyanburu.com`)으로 self-check 요청을 보낼 때,
+공인 IP → 라우터 → 내부 PC로 돌아오는 헤어핀 NAT이 지원되지 않아 타임아웃 발생.
+
+**해결**
+CoreDNS에 내부 도메인을 직접 등록해서 K8s 내부에서 도메인을 내부 IP로 해석하게 설정:
+```bash
+kubectl patch configmap coredns -n kube-system --patch-file coredns-patch.yaml
+kubectl rollout restart deployment/coredns -n kube-system
+```
+
+---
+
+### 12. Ingress Controller EXTERNAL-IP가 localhost로 표시
+**증상** `kubectl get svc -n ingress-nginx` 에서 EXTERNAL-IP가 `localhost` 로 표시됨.
+
+**원인** Docker Desktop 환경의 정상적인 동작. `localhost` = 실제 PC를 의미.
+
+**해결** 포트포워딩을 NodePort(30118, 30963)가 아닌 **80, 443 → PC내부IP:80, 443** 으로 설정.
+Docker Desktop이 80/443을 받아서 Ingress Controller로 자동 전달.
+
+---
+
+### 13. git commit 시 Author identity unknown
 **증상**
 ```
 Author identity unknown
@@ -505,7 +609,8 @@ git config --global user.name "계정명"
 - Gitea + ArgoCD GitOps 파이프라인 구성
 - Gitea Container Registry 연동
 
-### 2026-04-10 (기능 추가)
+### 2026-04-10 (기능 추가 + 도메인 연결)
+#### 기능 추가
 - **MY Page**: 탭명/목록 제목 영문 변경, URL 미표기, Favicon 자동 표시
 - **비밀번호 보안 강화**
   - 로그인 비밀번호 표시/숨김 토글 버튼
@@ -516,3 +621,12 @@ git config --global user.name "계정명"
 - **공지사항 탭**: 관리자 작성 전용, 모든 사용자 댓글 가능
 - **관리자 요청 탭**: 게시판 형태, 모든 사용자 작성/답글 가능
 - **Nginx Rate Limiting**: 로그인 API 분당 5회 제한 (Brute Force 방어)
+
+#### 도메인 연결 (HTTPS)
+- **Nginx Ingress Controller** 설치 및 구성
+- **cert-manager** 설치 + Let's Encrypt 인증서 자동 발급
+- **cyanburu.com** 도메인 연결 (후이즈)
+- **MSI 라우터** 포트포워딩 설정 (80/443)
+- **CoreDNS** 내부 도메인 등록 (헤어핀 NAT 우회)
+- **HTTPS 자동 리다이렉트** 적용
+- 최종 접속 URL: `https://cyanburu.com`