114 lines
6.2 KiB
Markdown
114 lines
6.2 KiB
Markdown
---
|
|
date: 2026-04-29
|
|
topic: Outline 0.82.0 → 1.7.0 메이저 업그레이드 (OIDC SameSite 쿠키 수정)
|
|
areas: [infra/platform/outline.md, infra/data/postgresql-ha.md]
|
|
tags: [outline, k3s, upgrade, oidc, postgresql, pgpool, helm-charts, argocd]
|
|
---
|
|
|
|
## 배경
|
|
|
|
Outline 0.82.0 의 OIDC 로그인이 외부에서 `State not return in OAuth flow` 에러로 실패. 진단 결과(2026-04-29 오전):
|
|
- 환경변수 / Gitea OAuth 앱 / Redis / 시계 모두 정상
|
|
- 외부 응답에 Set-Cookie 헤더 부재 — 브라우저의 bounce-tracking protection이 SameSite 미지정 쿠키를 strip
|
|
- 같은 결함이 GitHub Issue [outline/outline#11933](https://github.com/outline/outline/issues/11933) 에 보고. 1.7.0에서 csrfToken 쿠키에 `samesite=lax` 명시 추가하여 수정
|
|
|
|
## 결정
|
|
|
|
helm chart `gitea.inouter.com/kaffa/helm-charts` 의 `charts/outline/values.yaml` 에 image tag `0.82.0 → 1.7.0` 변경 후 ArgoCD 자동 sync.
|
|
|
|
## 사전 백업
|
|
|
|
| 백업 항목 | 위치 |
|
|
|---|---|
|
|
| Longhorn PVC snapshot | `pre-upgrade-outline-1-7-0` (volume `pvc-c4bb2746-79f4-41ea-85fc-765cfc473b15`, ready=true) |
|
|
| K8s deploy/secret/PVC | `~/outline-upgrade-backup/{deploy,outline-secrets,pvc,argocd-app}.yaml` |
|
|
| Outline DB pg_dump | `~/outline-upgrade-backup/outline-pre-1.7.0.dump` (2.1MB, custom format, Patroni leader postgres-2 = kr1 10.100.3.185) |
|
|
|
|
## 실행
|
|
|
|
1. helm-charts 레포 clone (Gitea PAT) → `charts/outline/values.yaml` 의 image tag 0.82.0 → 1.7.0 변경 → commit `outline: 0.82.0 -> 1.7.0 (OIDC SameSite fix)` push
|
|
2. ArgoCD App `outline` sync 트리거 → Deployment image 갱신
|
|
|
|
## 부수 이슈 — pgpool DDL/DML 라우팅
|
|
|
|
### 1차: 마이그레이션 ALTER TABLE 실패
|
|
|
|
신규 1.7.0 pod 기동 시 마이그레이션 `20250207120103-add-collectionId-to-subscriptions.js` 가 `cannot execute ALTER TABLE in a read-only transaction` 으로 실패. 누적 5회 CrashLoopBackOff.
|
|
|
|
### 2차: 운영 후 apiKeys UPDATE 실패
|
|
|
|
마이그레이션 완료 후 deploy env override 제거 + 운영 DATABASE_URL = `pgpool:9999` 로 복귀했는데, API 요청마다 발생하는 `UPDATE "apiKeys" SET "lastActiveAt"=$1 WHERE "id" = $2` 가 동일 사유로 실패 (PG error 25006). pgpool 이 DDL뿐 아니라 DML UPDATE 도 replica 로 라우팅.
|
|
|
|
### 원인
|
|
|
|
- DATABASE_URL 이 `pgpool.db.svc.cluster.local:9999` 사용 → pgpool이 ALTER TABLE 및 UPDATE 를 stream replication 모드에서 replica로 라우팅
|
|
- Patroni 자체는 healthy (Leader postgres-2 running, replicas streaming, lag=0)
|
|
- pgpool config 에서 write를 primary로 강제 라우팅하는 설정이 미적용으로 보임
|
|
|
|
### 해결 (영구 override)
|
|
|
|
ArgoCD selfHeal=false 유지 + deployment env 에 직접 DATABASE_URL override 적용 (`haproxy-pg.db.svc.cluster.local:5432` — Patroni leader 전용 라우팅, K3s db ns LoadBalancer):
|
|
|
|
```yaml
|
|
env:
|
|
- name: DATABASE_URL
|
|
value: postgresql://outline:outline@haproxy-pg.db.svc.cluster.local:5432/outline
|
|
- (기존 env: DEFAULT_LANGUAGE/ENABLE_UPDATES/FILE_STORAGE/.../URL ...)
|
|
```
|
|
|
|
마이그레이션 정상 적용:
|
|
- `20250207120103-add-collectionId-to-subscriptions.js` (up) 완료
|
|
- 누적된 0.82.0 → 1.7.0 마이그레이션 모두 적용
|
|
- "Listening on http://localhost:3000 / https://outline.inouter.com" 출력
|
|
|
|
운영 후 apiKeys UPDATE 에러도 해소됨.
|
|
|
|
> 외부 secret(`outline-secrets`)은 ESO가 1h 주기로 Vault `secret/apps/outline` 동기화. ESO 사이클이 patch를 1h 안에 revert하므로 secret 직접 수정은 무의미 — deploy env override 가 정답.
|
|
|
|
> ArgoCD selfHeal 은 영구 false 유지 — 활성화하면 chart values 의 DATABASE_URL 이 patch 를 덮어 다시 깨짐. 후속으로 chart values 자체에 haproxy-pg 명시 또는 pgpool config 수정 필요.
|
|
|
|
### pgpool DDL 라우팅 후속 과제
|
|
|
|
- pgpool config `disable_load_balance_on_write: 'transaction'` 또는 `dml_adaptive_object_relationship_list` 검토
|
|
- 또는 Outline 같은 schema 변경 잦은 앱은 처음부터 haproxy-pg 라우팅 사용 (chart values 에 DATABASE_URL 명시 검토)
|
|
|
|
## 검증
|
|
|
|
| 항목 | 결과 |
|
|
|---|---|
|
|
| Pod 상태 | 1/1 Running, restarts=1 (초기 liveness probe 한 번 실패 후 안정화) |
|
|
| Container image | `outlinewiki/outline:1.7.0` |
|
|
| 외부 https://outline.inouter.com/healthz | HTTP 200 |
|
|
| /api/auth.config (POST) | `{"data":{"name":"Outline","providers":[{"id":"oidc","name":"Gitea","authUrl":"/auth/oidc"}]}}` ✓ Gitea OIDC provider 등장 |
|
|
| Pod-internal /auth/oidc Set-Cookie | **2개 쿠키, csrfToken 에 `samesite=lax` 명시** + state 쿠키. 0.82.0 대비 csrfToken 쿠키 신규 추가됨 (issue #11933 fix) |
|
|
|
|
샘플 (pod-internal):
|
|
```
|
|
set-cookie: csrfToken=…; path=/; domain=localhost; samesite=lax
|
|
set-cookie: state=localhost|…|web||; path=/; expires=…; domain=localhost; httponly
|
|
```
|
|
|
|
브라우저는 cross-site OAuth redirect 후 csrfToken 쿠키를 동봉 → state mismatch 해소.
|
|
|
|
> 외부 (BunnyCDN/APISIX 경유) 응답에는 여전히 Set-Cookie 가 보이지 않음. 별개 이슈 (CDN 또는 APISIX route 가 Set-Cookie 를 strip 하는 가능성). 추후 디버깅 — 본 업그레이드 범위 외.
|
|
|
|
## 운영 메모
|
|
|
|
- Outline 1.7.0 의 `/api/auth.config` 는 **POST** 만 받음 (0.82.0 GET → 1.7.0 POST). 외부 모니터링 스크립트가 GET 사용 중이면 404 받게 됨 — 갱신 필요
|
|
- 1.7.0 부터 `Restricting process count to 1 due to use of collaborative service without REDIS_COLLABORATION_URL` 로그 — collaboration service가 단일 process로 동작. multi-replica 확장 시 `REDIS_COLLABORATION_URL` env 필요
|
|
- helm chart 자체는 thin wrapper (deployment + ingressroute + service) — Outline secrets/config 대부분 outside chart (ESO + Vault + APISIX route)
|
|
|
|
## 롤백 절차
|
|
|
|
```bash
|
|
# helm-charts 레포에서 tag 되돌리기
|
|
sed -i 's|tag: "1.7.0"|tag: "0.82.0"|' charts/outline/values.yaml
|
|
git commit -am "outline: rollback 1.7.0 -> 0.82.0"
|
|
git push
|
|
|
|
# ArgoCD 자동 sync 후 pod 재기동. PVC 데이터는 그대로 유지됨
|
|
# DB schema 변경은 forward-only — 0.82.0 으로 내릴 시 신규 컬럼/테이블이 무시됨 (오류 없음)
|
|
```
|
|
|
|
PVC snapshot `pre-upgrade-outline-1-7-0` 으로 데이터 복원 가능 (1.7.0 schema 적용 전 상태). 단 schema 다운그레이드는 위험 — 가능하면 forward-only.
|