본문으로 건너뛰기

cert-manager

목적​

cert-manager는 Lumie ingress 호스트와 명시적 인증서 리소스의 TLS 발급을 담당합니다. 이 페이지는 cert-manager 배포, ACME issuer 위치, Cloudflare 토큰 동기화, 네임스페이스 차트 구성과 클러스터 범위 issuer 매니페스트 사이의 경계를 다루는 레퍼런스 문서입니다.

소스 경로​

경로역할
lumie-infra/platform/cert-manager/argocd.yamlcert-manager용 Argo CD 애플리케이션
lumie-infra/platform/cert-manager/helm-values.yaml컨트롤러, webhook, cainjector용 Jetstack 차트 값
lumie-infra/platform/cert-manager/common-values.yaml공유 차트 값과 오래된 clusterIssuers 블록
lumie-infra/platform/cert-manager/manifests/vault-static-secret.yamlCloudflare API 토큰을 동기화하는 VaultStaticSecret
lumie-infra/applications/cluster-bootstrap/manifests/cluster-issuer.yaml활성 ClusterIssuer 정의
lumie-infra/applications/lumie/frontend/manifests/custom-domain.example.yaml화이트라벨 커스텀 도메인 ingress 계약
lumie-infra/security/teleport/manifests/certificate.yaml명시적 Certificate 소비자 예시

퍼블릭 표면​

표면목적
cert-manager 컨트롤러Certificate와 issuer 리소스를 위한 메인 reconciliation 루프
cert-manager-webhookcert-manager CRD용 admission 및 validation
cert-manager-cainjectorwebhook 기반 리소스용 CA 번들 주입
VaultStaticSecret cloudflare-api-token-vssCloudflare API 토큰을 cert-manager 네임스페이스로 sync
ClusterIssuer letsencrypt-prod표준 Lumie 도메인을 위한 프로덕션 ACME issuer
ClusterIssuer letsencrypt-staging안전한 테스트용 스테이징 ACME issuer
ClusterIssuer letsencrypt-customdomain운영자가 온보딩한 화이트라벨 도메인을 위한 DNS-01 전용 issuer

런타임 흐름​

활성 Issuer​

권위 있는 issuer 정의는 cert-manager 차트 값이 아니라 applications/cluster-bootstrap/manifests/cluster-issuer.yaml에 있습니다.

이 파일은 다음을 정의합니다.

  • letsencrypt-prod: ingress 수업 traefik을 통한 HTTP-01과 lumie-infra.com용 Cloudflare DNS-01을 모두 사용
  • letsencrypt-staging: traefik을 통한 HTTP-01 사용
  • letsencrypt-customdomain: 운영자가 온보딩한 테넌트 도메인을 위한 DNS-01 전용 사용

커스텀 도메인 issuer는 Certificate 또는 Ingress마다 의도적으로 opt-in 방식이며, 운영자가 lumie-infra.com 바깥 도메인도 온보딩할 수 있으므로 dnsZones를 제한하지 않습니다.

Cloudflare 시크릿 동기화​

Cloudflare 자격 증명은 Git에 두지 않습니다. Vault에서 동기화됩니다.

apiVersion: secrets.hashicorp.com/v1beta1
kind: VaultStaticSecret
metadata:
  name: cloudflare-api-token-vss
spec:
  path: tokens
  destination:
    name: cloudflare-api-token

2026년 6월 14일에 확인한 라이브 클러스터에는 cert-manager 네임스페이스에 cloudflare-api-token-vss가 존재했고, 세 ClusterIssuer 리소스 모두 READY=True를 보고했습니다.

소비자​

저장소에서 흔한 패턴은 다음과 같습니다.

  • 표준 Lumie 호스트를 위한 cert-manager.io/cluster-issuer: letsencrypt-prod 같은 Ingress annotation
  • 화이트라벨 호스트를 위한 letsencrypt-customdomain 기반 도메인별 프런트엔드 ingress
  • security/teleport/manifests/certificate.yaml의 Teleport 와일드카드 인증서 같은 명시적 Certificate 오브젝트

OCI는 TCP passthrough만 수행하므로, 발급된 시크릿은 결국 워커에서 TLS 종료를 수행하는 Traefik이 소비합니다.

계약 드리프트​

저장소 내부에 중요한 불일치가 하나 있습니다.

  • platform/cert-manager/common-values.yaml에는 아직 clusterIssuers 블록이 남아 있지만, charts/common/templates/에는 ClusterIssuer 렌더러가 없습니다. 활성 issuer 리소스는 공유 차트 값이 아니라 applications/cluster-bootstrap/manifests/cluster-issuer.yaml에서 옵니다.

issuer 동작을 바꿀 때는 먼저 cluster-부트스트랩 매니페스트를 수정하고, clusterIssuers values 블록은 제거되거나 렌더러에 연결되기 전까지 오래된 값으로 취급하세요.

장애 지점​

장애 지점영향
Cloudflare 토큰 누락 또는 오래됨lumie-infra.com 또는 커스텀 도메인의 DNS-01 발급 실패
잘못된 issuer annotationingress가 기대한 TLS 시크릿을 받지 못함
커스텀 도메인 ingress에 명시적 host 항목 누락Traefik이 인증서를 SNI 저장소에 적재하지 못함
운영자가 오래된 clusterIssuers values 블록만 수정함라이브 issuer 변경이 전혀 일어나지 않음

검증​

kubectl get pods -n cert-manager
kubectl get vaultstaticsecret -n cert-manager
kubectl get clusterissuers
rg -n "ClusterIssuer|cert-manager.io/cluster-issuer|cloudflare-api-token-vss" \
  lumie-infra/platform/cert-manager \
  lumie-infra/applications/cluster-bootstrap \
  lumie-infra/applications/lumie \
  lumie-infra/security/teleport