Traefik

목적

Traefik은 Lumie의 활성 ingress controller입니다. 이 페이지는 Traefik이 어디서 구성되는지, OCI에서 트래픽을 어떻게 받는지, 앱 Ingress 오브젝트가 middleware를 어떻게 연결하는지, edge 라우팅이 바뀔 때 운영자가 무엇을 확인해야 하는지 다루는 레퍼런스 문서입니다.

소스 경로

경로	역할
`lumie-infra/platform/traefik-config/argocd.yaml`	Traefik 패치를 관리하는 Argo CD 애플리케이션
`lumie-infra/platform/traefik-config/helmchartconfig.yaml`	k3s 번들 Traefik addon용 `HelmChartConfig`
`lumie-infra/provision/terraform/nlb_0214.tf`	OCI NLB에서 워커로의 TCP `443` passthrough
`lumie-infra/applications/lumie/backend/manifests/strip-prefix.yaml`	프로덕션 `/api` strip middleware
`lumie-infra/applications/lumie/develop/common-values.yaml`	dev API ingress 분리와 `/api/grading` strip middleware
`lumie-infra/applications/lumie/frontend/manifests/ingress.yaml`	메인 프런트엔드 ingress
`lumie-infra/applications/lumie/frontend/manifests/www-redirect.yaml`	`www`용 Traefik redirect middleware
`lumie-infra/applications/lumie/frontend/manifests/custom-domain.example.yaml`	도메인별 커스텀 도메인 ingress 계약

퍼블릭 표면

Traefik은 여기서 독립 차트로 배포되지 않습니다. 활성 오브젝트는 kube-system의 traefik이라는 이름을 가진 k3s addon HelmChartConfig입니다.

표면	계약
리스너 포트	번들 addon의 `web`, `websecure` 진입점
외부 경로	OCI NLB가 TCP `443`을 워커 노드로 전달
Ingress 수업	`traefik`
라우트 소스	표준 Kubernetes `Ingress` 오브젝트와 Traefik CRD `Middleware`
TLS 종료	ingress 규칙이 참조하는 cert-manager 관리 시크릿을 사용해 Traefik에서 수행

런타임 흐름

K3s 애드온 패치

저장소가 관리하는 Traefik 구성은 현재 timeout 패치입니다.

# lumie-infra/platform/traefik-config/helmchartconfig.yaml
ports:
  web:
    transport:
      respondingTimeouts:
        readTimeout: 1200s
        writeTimeout: 1200s
        idleTimeout: 600s

같은 값이 websecure에도 적용됩니다. 인라인 주석은 이유를 설명합니다. Zot로 향하는 느린 수 기가바이트 이미지 업로드가 기본 Traefik timeout 때문에 HTTP 499에 걸렸기 때문입니다.

이는 Zot에만 국한되지 않는 클러스터 전역 동작입니다.

인그레스 및 미들웨어 계약

Traefik 동작은 중앙 게이트웨이 설정이 아니라 앱 매니페스트로 결정됩니다.

프로덕션 백엔드 트래픽은 monolith의 /v1/** 라우트로 전달하기 전에 /api를 제거하는 Middleware를 사용합니다.
dev 클러스터는 dev.lumie-infra.com에서 두 개의 ingress를 사용합니다. 하나는 /api/grading을 grading-svc로, 다른 하나는 /api를 lumie-backend로 보냅니다.
프런트엔드의 www 트래픽은 Traefik redirectRegex middleware를 사용해 www.lumie-edu.com을 lumie-edu.com으로 보냅니다.
화이트라벨 커스텀 도메인은 Traefik이 올바른 TLS 시크릿을 SNI 저장소에 적재할 수 있도록 도메인마다 명시적 Ingress가 하나씩 필요합니다.

소유권 경계

관심사	소유자
노드 수준 ingress 도달성	Terraform NLB 리소스
Traefik addon 형태와 timeout	`platform/traefik-config`
호스트 및 경로 라우팅	개별 애플리케이션 ingress 매니페스트
TLS 시크릿 발급	cert-manager와 참조된 issuer
인증 및 테넌시 강제	Traefik이 아니라 애플리케이션 코드

lumie-infra/AGENTS.md는 이를 명시합니다. Traefik 앞에는 활성 API gateway가 없고, X-Tenant-Slug 같은 인증 헤더는 여전히 애플리케이션 관심사입니다.

운영 메모

2026년 6월 14일에 확인한 라이브 클러스터에는 kube-system에 실행 중인 traefik pod가 있었고, 체크인된 timeout 패치와 일치하는 HelmChartConfig가 적용되어 있었습니다.
dev ingress는 의도적으로 프런트엔드 앱을 제외하므로 https://dev.lumie-infra.com/는 404를 반환하지만 /api 라우트는 동작합니다.
메인 OCI NLB는 layer-4만 담당하므로 SNI 처리와 인증서 선택은 전적으로 Traefik 책임입니다.

장애 지점

장애 지점	동작
timeout 패치 제거	대용량 Zot push가 다시 클라이언트 연결 종료로 실패할 수 있음
middleware annotation 누락	백엔드가 `/v1/...` 대신 `/api/...`를 받아 라우트 처리가 깨짐
커스텀 도메인 ingress 누락	Traefik이 해당 호스트명에 대체 self-signed 인증서를 제공함
잘못된 ingress 수업	Git에는 규칙이 있어도 Traefik이 무시함

검증

kubectl get helmchartconfig -n kube-system traefik -o yaml
kubectl get ingress -A
kubectl get middleware -A
kubectl logs -n kube-system deploy/traefik

rg -n "traefik|strip-api-prefix|redirectRegex|ingressClassName: traefik" \
  lumie-infra/platform/traefik-config \
  lumie-infra/applications/lumie

목적​

소스 경로​

퍼블릭 표면​

런타임 흐름​

K3s 애드온 패치​

인그레스 및 미들웨어 계약​

소유권 경계​

운영 메모​

장애 지점​

검증​

목적