Cloudflared 재기동

AI 요청 프롬프트


https://docs.axelabs.ai/ops/runbook/cloudflared 따라 axelabs-tunnel 재기동 진행해줘.

진행:
1. 현재 상태 진단 — `docker ps -a | grep axelabs-tunnel` + 외부 endpoint health (`curl -sI https://axe.axelabs.ai/frame/health`)
2. 페이지 시나리오 1 (죽음 감지) / 시나리오 2 (ingress config 변경) 중 분기 식별
3. 페이지의 각 명령 실행 + 검증, 매 step 결과 받고 다음. **절대 SIGHUP 금지** (cloudflared graceful reload 미지원) — docker restart 만 사용, 5초 다운타임 발생 사용자 사전 확인
4. 함정 — 본 runbook 은 axe-macmini 중앙 tunnel 만 다룸, customer 별 tunnel (`axelabs-{customer}`) 은 `axe onboard --apply` step 7 이 customer macmini 의 config 자동 push
5. 외부 endpoint 200 검증 + (선택) /ops/updates Ship Log

본인 AI session = Claude Code / Cursor / ChatGPT 데스크탑 / Claude.app / 기타.

페이지 본문 = 사람이 직접 read 도 가능, AI 도 참고. AI 가 본 페이지 fetch 후 위 진행 순서대로 사용자와 step-by-step interactive 풀어나감.

axelabs-tunnel (cloudflared) 가 죽거나 ingress config 변경이 필요할 때.

Tunnel layer 구분 (2026-05-23 정정): AXE 플랫폼은 2 종류 cloudflared tunnel 운용. 본 runbook 은 axe-macmini 의 중앙 tunnel (axelabs-tunnel 컨테이너 — axe.axelabs.ai / docs.axelabs.ai / admin.axelabs.ai 등 운영자 자기 서비스) 만 다룸. customer 별 tunnel (axelabs-realchoice 등 — {customer}.axelabs.ai 서빙) 은 axe onboard 가 customer macmini 의 launchd com.axelabs.{customer}.cloudflared 로 부팅하며 본 runbook 적용 안 됨. customer tunnel ingress 추가 시 axe onboard --apply 가 step 7 에서 자동 push.

절대 SIGHUP 금지


❌ docker kill -s HUP axelabs-tunnel

검증된 사실 (2026-05-15): cloudflared 는 SIGHUP graceful reload 미지원. SIGHUP 받으면 프로세스 종료.

→ docker restart 만 사용. 5초 다운타임 발생.

시나리오 1 — 죽음 감지

com.axe.health-check 또는 운영자 콘솔에서 cloudflared 죽음 감지:


# 상태 확인
docker ps -a | grep axelabs-tunnel
# Exited (1) 또는 Dead 표시
 
# 재시작
docker start axelabs-tunnel
 
# 5초 대기 후 검증
sleep 5
curl -sI https://axe.axelabs.ai/frame/health
# 200 OK

시나리오 2 — Ingress config 변경

신규 customer 추가 또는 path 추가 시:


# 1. config 편집
vim /Users/axe/.axe/tunnels/axelabs/config.yml
 
# 2. 검증
docker run --rm -v /Users/axe/.axe/tunnels/axelabs:/etc/cloudflared cloudflare/cloudflared:latest \
    tunnel --config /etc/cloudflared/config.yml ingress validate
# OK 면
 
# 3. 재시작 (다운타임 ~5s)
docker restart axelabs-tunnel
 
# 4. 새 ingress 동작 확인
sleep 5
curl -sI https://&lt;new-host&gt;/&lt;path&gt;

시나리오 3 — credentials 만료 / 회전

cloudflared 의 tunnel credentials (d8efecdd-2c3f-42de-9925-501433e21394.json) 는 일반적으로 만료 없음. 단, 의심 노출 시:


# 1. Cloudflare dashboard → Zero Trust → Networks → Tunnels → axelabs-tunnel → Configure → Rotate token
 
# 2. 새 credentials 파일 받아서 macmini 에 push
scp credentials.json axe-macmini:/Users/axe/.axe/tunnels/axelabs/
 
# 3. 재시작
docker restart axelabs-tunnel

Ingress 변경 시 함정

함정	결과	회피
docker kill -s HUP	process 종료	`docker restart`
frame upstream 을 cloudflared 에 직접 (host:port)	blue/green swap 불가	axe-frame-proxy 경유
path strip 기대	라우터에서 prefix 못 찾음	서비스에 `/frame` mount
catch-all (404) 라인 제거	unhandled 호스트 가 임의 origin 으로	마지막 `service: http_status:404` 유지

다운타임 분산 운영

cloudflared 재시작 = 5초 다운타임 (모든 customer 의 모든 서비스). 따라서:

가능한 한 새벽 시간 (03:00 KST) 에 수행
사전 알림 (customer admin 들에게 24h 전)
한 번에 여러 변경 묶어서 (재시작 1회 분량)

자동화 모니터링 (TBD)

현재는 운영자 콘솔 (https://admin.axelabs.ai, com.axe.console.refresh 매시 rebuild) 에서 health probe 결과 확인. 매분 단위 자동 알림 (com.axe.health-check launchd + axe-health-monitor script) 는 향후 작업 항목.

대안 (즉시 구현 가능):


# /Users/axe/.axe/bin/check-cloudflared.sh (TODO: 실제 launchd 등록)
if ! curl -sf https://axe.axelabs.ai/frame/health > /dev/null; then
    osascript -e 'display notification "cloudflared 또는 frame 죽음" with title "AXE Labs"'
fi

다른 cloudflared 인스턴스

축전된 다른 tunnel 들:

Tunnel	컨테이너	ingress
axelabs-tunnel	`axelabs-tunnel` (Docker)	플랫폼 (`*.axelabs.ai`)
cortex-tunnel	`com.cortex.cloudflared` (launchd)	cortex.axellc.com + mysrt.axellc.com
(기타 customer 측)	(각 customer macmini)	각 customer 의 자체

각각 독립 운영. cortex-tunnel 죽음 ≠ axelabs-tunnel 죽음.