Kubernetes環境の ACME構成

Classic/VPC環境で利用できます。

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は2種類の発行者リソースを提供します。

このガイドでは、一般的に推奨される 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