본문으로 건너뛰기

cert-manager 값 소스 안정화

이 페이지는 2026년 6월 20일 안정화 변경 이후 인증서 관리자 소스 레이아웃 혼란에 대한 troubleshooting 문서입니다. 더 광범위한 배포 계약은 인프라 네트워킹 인증서 관리자 참조 페이지에 있습니다.

증상​

cert-manager 변경 사항은 cloudflare-api-token-vss를 생성하기 위해 애플리케이션에 차트 값과 별도의 매니페스트 전용 Git 소스가 모두 필요한 것처럼 보이기 때문에 추론하기 어렵습니다.

접두사 레이아웃에서 platform/cert-manager/argocd.yaml는 다음을 수행했습니다.

  • Jetstack 차트 소스
  • charts/common 및 $values/platform/cert-manager/common-values.yaml에 대한 저장소 소스
  • platform/cert-manager/manifests에 대한 또 다른 저장소 소스

추가 매니페스트 소스는 불안정한 부분이었습니다.

가능한 원인​

  • Cloudflare 토큰 VaultStaticSecret는 charts/common에 이미 vault-static-secrets.yaml 렌더러가 있었음에도 불구하고 platform/cert-manager/manifests/vault-static-secret.yaml에 있었습니다.
  • platform/cert-manager/common-values.yaml에는 여전히 신뢰할 수 있는 것처럼 보이는 clusterIssuers 블록이 포함되어 있지만 charts/common/templates/는 ClusterIssuer 리소스를 전혀 렌더링하지 않습니다.

수정​

f9280254는 Cloudflare 토큰 비밀을 common.vaultStaticSecrets 아래의 platform/cert-manager/common-values.yaml로 이동하고 platform/cert-manager/argocd.yaml에서 path: platform/cert-manager/manifests 소스를 제거했습니다.

나머지 레이아웃은 의도적인 것입니다.

  • Jetstack 차트 소스는 cert-manager 자체를 설치합니다.
  • repo 지원 values 소스는 여전히 charts/common 및 $values/platform/cert-manager/common-values.yaml를 제공합니다.
  • charts/common/templates/vault-static-secrets.yaml는 common.vaultStaticSecrets를 렌더링합니다.

수정 사항은 repo 지원 값 소스가 아닌 추가 매니페스트 소스를 제거했습니다.

진단 경로​

  1. platform/cert-manager/argocd.yaml를 검사하고 path: platform/cert-manager/manifests로 소스가 없는지 확인합니다.
  2. platform/cert-manager/common-values.yaml를 검사하고 common.vaultStaticSecrets가 cloudflare-api-token-vss를 정의하는지 확인합니다.
  3. charts/common/templates/vault-static-secrets.yaml를 검사하고 .Values.common.vaultStaticSecrets를 렌더링하는지 확인합니다.
  4. 발급자 동작의 경우 platform/cert-manager/common-values.yaml의 오래된 clusterIssuers 블록이 아닌 applications/cluster-bootstrap/manifests/cluster-issuer.yaml를 검사합니다.

예방​

  • 플랫폼 앱이 이미 charts/common를 사용하는 경우 공통 차트가 실제로 리소스를 렌더링할 수 없는 한 해당 값 파일에 네임스페이스화된 VaultStaticSecret 리소스를 유지하세요.
  • common-values.yaml.clusterIssuers를 발행자 기준으로 취급하지 마십시오. 활성 ClusterIssuer 개체는 applications/cluster-bootstrap/manifests/cluster-issuer.yaml에서 나옵니다.

확인​

cd lumie-infra
rg -n "platform/cert-manager/manifests|path: charts/common|ref: values" \
  platform/cert-manager/argocd.yaml
rg -n "cloudflare-api-token-vss|vaultStaticSecrets|clusterIssuers" \
  platform/cert-manager/common-values.yaml \
  charts/common/templates/vault-static-secrets.yaml \
  applications/cluster-bootstrap/manifests/cluster-issuer.yaml

성공은 argocd.yaml에 platform/cert-manager/manifests 소스가 없고, common-values.yaml가 Cloudflare 토큰 VaultStaticSecret를 정의하며, 발급자 소유권이 여전히 클러스터 부트스트랩 매니페스트에만 표시된다는 의미입니다.

운영 세부사항​

이 문제는 cert-manager controller 실패가 아니라 GitOps ownership 문제였습니다. 여러 파일이 certificate 관련 resource를 선언할 수 있을 것처럼 보였지만, 실제로 render되는 것은 일부뿐이라는 점이 혼란의 핵심이었습니다.

resource type안정화 후 active owner비고
cert-manager chartplatform/cert-manager/argocd.yaml의 Jetstack chart source.controller component를 설치합니다.
Cloudflare token secret synccharts/common이 render하는 common.vaultStaticSecrets.추가 manifest source를 대체합니다.
ClusterIssuerapplications/cluster-bootstrap/manifests/cluster-issuer.yaml.common-values.yaml.clusterIssuers에서 render되지 않습니다.

진단 중에는 먼저 어떤 renderer가 object를 소유하는지 확인합니다. values block이 존재한다는 이유만으로 active하다고 가정하지 않습니다.

복구 절차​

  1. Argo CD가 cert-manager에 대해 예상 밖의 extra source를 적용하는지 확인합니다.
  2. VaultStaticSecret가 없다면 새 manifest directory를 추가하기 전에 common chart values를 확인합니다.
  3. ClusterIssuer가 없거나 오래됐다면 cert-manager values가 아니라 cluster-bootstrap manifest를 봅니다.
  4. 죽은 값이나 오해를 부르는 값은 template에서 소비되지 않는다는 점을 확인한 뒤 제거합니다.
  5. controller 설치 실패와 issuer 선언 실패가 섞이지 않도록 cert-manager와 cluster-bootstrap을 별도로 sync합니다.

검증 증거​

다음을 기록합니다.

  • cert-manager의 Argo CD source list에 platform/cert-manager/manifests path가 없습니다.
  • rendered manifest에 common chart에서 온 cloudflare-api-token-vss가 포함됩니다.
  • live VaultStaticSecret가 cert-manager가 기대하는 namespace에 존재합니다.
  • live ClusterIssuer object가 cluster-bootstrap과 일치합니다.
  • operator runbook이 오래된 clusterIssuers block을 편집하라고 안내하지 않습니다.

피해야 할 패턴​

  • charts/common이 이미 resource type을 render하는데 또 다른 manifest source를 추가하는 것.
  • renderer를 추가하지 않은 채 issuer ownership을 cert-manager values로 옮기는 것.
  • 두 source가 같은 object를 소유하는 것처럼 보이는데 Argo CD multi-source layout을 무해하다고 보는 것.
  • Cloudflare token secret이 render되고 sync되는지 확인하기 전에 DNS-01 실패부터 디버깅하는 것.