Kubernetes 환경 ACME 구성

cert-manager를 사용하여 Kubernetes 클러스터에서 Ncloud ACME 서버로 인증서를 발급받는 방법을 안내합니다.

시작하기 전에

ACME 사용 준비의 모든 단계를 완료한 뒤, 다음 항목이 준비되어야 합니다.

• 발급된 EAB Key ID 및 EAB HMAC Key
• kubectl 사용 권한 및 클러스터 관리자(cluster-admin) 권한
• cert-manager가 지원하는 DNS 제공자 계정 및 API 권한 (지원 목록 확인)
• OV 인증서 사용 시, Certificate Manager > Organization에서 조직 검증 완료

동작 구조

cert-manager를 통한 인증서 자동화 흐름은 다음과 같습니다.

  사용자 브라우저
       │ HTTPS
       ▼
  Ingress
       │ tls.secretName 참조
       ▼
  K8s Secret (인증서 저장)
       ▲ 자동 발급 / 갱신
       │
  cert-manager
       │ ACME DNS-01 챌린지
       ▼
  Ncloud ACME 서버  ←→  DNS 제공자 (TXT 레코드 자동 처리)

cert-manager는 인증서 lifetime의 2/3 시점에 자동 갱신을 시도합니다. 갱신 시점을 명시적으로 지정하려면 Certificate.spec.renewBefore 필드를 사용해 주십시오.

1단계: cert-manager 설치

다음 명령어를 실행하여 cert-manager를 클러스터에 설치해 주십시오.

kubectl apply -f \
  https://github.com/cert-manager/cert-manager/releases/latest/download/cert-manager.yaml

설치 후 모든 Pod가 Running 상태가 될 때까지 대기해 주십시오.

kubectl get pods -n cert-manager

출력 예시:

NAME                                       READY   STATUS    RESTARTS
cert-manager-xxxx                          1/1     Running   0
cert-manager-cainjector-xxxx               1/1     Running   0
cert-manager-webhook-xxxx                  1/1     Running   0

2단계: EAB Secret 생성

ACME 계정 등록에 사용할 EAB HMAC Key를 Kubernetes Secret으로 저장합니다. [EAB_HMAC_KEY]를 발급받은 실제 값으로 교체하여 실행해 주십시오.

kubectl create secret generic ncp-acme-eab \
  --from-literal secret="[EAB_HMAC_KEY]" \
  -n cert-manager

3단계: ClusterIssuer 생성

cert-manager는 두 가지 발급자 리소스를 제공합니다.

본 가이드는 일반적으로 권장되는 ClusterIssuer를 사용합니다. 다음 내용으로 clusterissuer.yaml 파일을 작성해 주십시오. [EAB_KEY_ID], admin@example.com, solvers 섹션을 사용 환경에 맞게 교체해 주십시오.

apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: ncp-acme
spec:
  acme:
    server: https://acme.navercloudtrust.com/acme/directory
    email: admin@example.com
    privateKeySecretRef:
      name: ncp-acme-account-key
    externalAccountBinding:
      keyID: "[EAB_KEY_ID]"
      keySecretRef:
        name: ncp-acme-eab
        key: secret
    solvers:
    - dns01:
        # 사용 중인 DNS 제공자에 따라 설정
        # 상세 설정은 cert-manager 공식 문서 참조
        # https://cert-manager.io/docs/configuration/acme/dns01/

파일 작성 후 다음 명령어를 실행하여 ClusterIssuer를 생성해 주십시오.

kubectl apply -f clusterissuer.yaml

생성 후 등록 상태를 확인해 주십시오. Ready 상태가 True이면 정상입니다.

kubectl get clusterissuer ncp-acme
kubectl describe clusterissuer ncp-acme

4단계: 인증서 요청

Certificate 리소스를 생성하여 인증서를 요청합니다. 다음 내용으로 certificate.yaml 파일을 작성해 주십시오.

apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: company-tls
  namespace: default
spec:
  secretName: company-tls-secret
  issuerRef:
    name: ncp-acme
    kind: ClusterIssuer
  dnsNames:
  - www.example.com
  - api.example.com

kubectl apply -f certificate.yaml

발급 상태를 확인하려면 다음 명령어를 실행해 주십시오. Ready 상태가 True가 될 때까지 대기합니다. DNS-01 챌린지 완료까지 수분이 소요될 수 있습니다.

# 인증서 발급 상태 확인
kubectl get certificate company-tls -n default

# 상세 이벤트 확인 (오류 발생 시 원인 파악)
kubectl describe certificate company-tls -n default
kubectl describe certificaterequest -n default

# 발급 완료 후 Secret 확인
kubectl get secret company-tls-secret -n default

인증서를 재발급하려면 Certificate 리소스를 삭제 후 재생성해 주십시오.

kubectl delete -f certificate.yaml
kubectl apply -f certificate.yaml

5단계: Ingress 적용

발급된 인증서를 Ingress에 적용합니다. 다음 내용으로 ingress.yaml 파일을 작성해 주십시오.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: company-ingress
  annotations:
    cert-manager.io/cluster-issuer: "ncp-acme"
spec:
  tls:
  - hosts:
    - www.example.com
    secretName: company-tls-secret
  rules:
  - host: www.example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: company-service
            port:
              number: 80

kubectl apply -f ingress.yaml

문제 해결

보안 권고

• EAB HMAC Key가 저장된 ncp-acme-eab Secret 및 ACME 계정 키 ncp-acme-account-key Secret은 cert-manager 네임스페이스에서만 접근 가능하도록 RBAC를 설정해 주십시오.
• DNS 제공자 API 키가 저장된 Secret의 접근 권한을 최소화해 주십시오.
• DNS 제공자 API 키에는 해당 DNS 서비스에 필요한 최소 권한만 부여하는 것을 권장합니다.
• Secret 리소스를 Git 저장소에 직접 커밋하지 마십시오. Sealed Secrets 또는 외부 Secret 관리 도구 사용을 권장합니다.

참고 문서

• cert-manager 공식 문서
• cert-manager ACME DNS-01 설정
• cert-manager External Account Binding