新着: プロジェクトの最新情報についてはTwitterとMastodonでご確認ください。

HTTP検証

HTTP検証を使用したACME証明書の発行

cert-managerは、ACMEプロトコルを使用して、CAから証明書を取得するために使用できます。ACMEプロトコルは、ドメインの所有権を証明するために使用される様々なチャレンジメカニズムをサポートしており、それによってそのドメインに対して有効な証明書を発行できます。

そのようなチャレンジメカニズムの1つに、HTTP01チャレンジがあります。HTTP01チャレンジでは、特定のファイルがドメインに存在することを確認することで、ドメインの所有権を証明します。指定されたパスに指定されたファイルを公開できる場合、そのドメインを制御しているとみなされます。

以下の発行者 (Issuer) は、HTTP検証を有効にするために必要な情報を定義しています。発行者 (Issuer) リソースの詳細については、発行者 (Issuer) ドキュメントを参照してください。

apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
  name: letsencrypt-staging
  namespace: default
spec:
  acme:
    # The ACME server URL
    server: https://acme-staging-v02.api.letsencrypt.org/directory
    # Email address used for ACME registration
    email: user@example.com
    # Name of a secret used to store the ACME account private key
    privateKeySecretRef:
      name: letsencrypt-staging
    # Enable the HTTP-01 challenge provider
    solvers:
    # An empty 'selector' means that this solver matches all domains
    - selector: {}
      http01:
        ingress:
          ingressClassName: nginx

Let's Encryptのステージング環境のACMEサーバーURLを指定しました。ステージング環境は信頼できる証明書を発行しませんが、本番環境に移行する前に検証プロセスが正常に機能していることを確認するために使用されます。Let's Encryptの本番環境ははるかに厳しいレート制限を課しているため、これらの制限に達する可能性を減らすために、ステージング環境から始めることを強くお勧めします。本番環境に移行するには、URLをhttps://acme-v02.api.letsencrypt.org/directoryに設定した新しい発行者 (Issuer) を作成するだけです。

ACMEプロトコルの最初の段階は、クライアントがACMEサーバーに登録することです。この段階には、非対称キーペアの生成が含まれ、次に発行者 (Issuer) で指定されたメールアドレスに関連付けられます。このメールアドレスを所有する有効なアドレスに変更してください。これは一般的に、証明書の更新時期が近づいたときに期限切れの通知を送信するために使用されます。生成された秘密鍵は、letsencrypt-stagingという名前のシークレットに保存されます。

ACMEチャレンジを処理するためのソルバーを1つ以上提供する必要があります。この場合、HTTP検証を使用したいので、http01ソルバーを指定します。オプションで、異なるドメインに異なるソルバー構成をマップすることもできます。

上記の発行者 (Issuer) を作成したら、それを利用して証明書を取得できます。

apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: example-com
  namespace: default
spec:
  secretName: example-com-tls
  issuerRef:
    name: letsencrypt-staging
  commonName: example.com
  dnsNames:
  - www.example.com

証明書リソースは、目的の証明書と、それを取得するために使用できる可能性のある方法を記述しています。ドキュメントで証明書リソースの詳細を確認できます。証明書が正常に取得された場合、結果のキーペアは、証明書と同じ名前空間にあるexample-com-tlsという名前のシークレットに保存されます。

証明書は、example.comという共通名を持ち、サブジェクト代替名 (SAN)はexample.comとwww.example.comになります。TLSクライアントによってこれらのSANのみが尊重されることに注意してください。

証明書では、上記のletsencrypt-staging発行者を参照しています。発行者は、証明書と同じ名前空間にある必要があります。クラスタスコープバージョンの発行者であるClusterIssuerを参照する場合は、issuerRefスタンザにkind: ClusterIssuerを追加する必要があります。

ClusterIssuerの詳細については、ClusterIssuerドキュメントを参照してください。

acmeスタンザは、ACMEチャレンジの構成を定義します。ここでは、ドメインの所有権を検証するために使用されるHTTP01チャレンジの構成を定義しました。http01スタンザに記載されている各ドメインの所有権を検証するために、cert-managerは、HTTP01チャレンジを満たすHTTPエンドポイントを公開するPod、サービス、およびIngressを作成します。

http01スタンザのingressClassName、class、およびnameフィールドを使用して、cert-managerがIngressリソースとどのように対話するかを制御できます。

  • ingressClassNameフィールドが指定されている場合、チャレンジを解決するために、ランダムに生成された名前を持つ新しいIngressリソースが作成されます。この新しいリソースには、ingressClassNameフィールドの値を持つingressClassNameフィールドが含まれます。これは、どのIngressコントローラーを使用するかを構成する推奨方法です。これは、NGINX Ingressコントローラーなどにも有効です。

  • classフィールドが指定されている場合、チャレンジを解決するために、ランダムに生成された名前を持つ新しいIngressリソースが作成されます。この新しいリソースには、キーkubernetes.io/ingress.classと、classフィールドの値に設定された値を持つアノテーションが含まれます。このフィールドは、ingressClassNameフィールドをサポートしていないingress-gceでのみ推奨されます。

  • nameフィールドが指定されている場合、証明書と同じ名前空間にある同じ名前のIngressリソースが既に存在する必要があり、チャレンジを解決するために適切なルールを追加するためだけに変更されます。このフィールドは、各Ingressリソースに1つのパブリックIPアドレスを割り当てるGoogle Cloud Load Balancer Ingressコントローラーや、その他多数のコントローラーに役立ちます。手動で介入しないと、新しいIngressリソースを作成すると、すべてのチャレンジが失敗します。

  • どちらも指定されていない場合、ランダムに生成された名前を持つ新しいIngressリソースが作成されますが、Ingressクラスのアノテーションは設定されません。

  • 両方が指定されている場合、ingressフィールドが優先されます。

ドメインの所有権が検証されると、cert-managerの影響を受けるすべてのリソースはクリーンアップまたは削除されます。

注：各ドメイン名をIngressコントローラーの正しいIPアドレスにポイントすることは、あなたの責任です。

上記の証明書を作成した後、kubectl describeを使用して、証明書が正常に取得されたかどうかを確認できます。

$ kubectl describe certificate example-com
Events:
  Type    Reason          Age      From          Message
  ----    ------          ----     ----          -------
  Normal  CreateOrder     57m      cert-manager  Created new ACME order, attempting validation...
  Normal  DomainVerified  55m      cert-manager  Domain "example.com" verified with "http-01" validation
  Normal  DomainVerified  55m      cert-manager  Domain "www.example.com" verified with "http-01" validation
  Normal  IssueCert       55m      cert-manager  Issuing certificate...
  Normal  CertObtained    55m      cert-manager  Obtained certificate from ACME server
  Normal  CertIssued      55m      cert-manager  Certificate issued successfully

kubectl get secret example-com-tls -o yamlを使用して、発行が成功したかどうかを確認することもできます。base64でエンコードされた署名付きTLSキーペアが表示されます。

証明書を取得すると、cert-managerは定期的にその有効性をチェックし、期限切れが近づくと更新を試みます。cert-managerは、証明書の「Not After」フィールドが現在時刻プラス30日より小さい場合、証明書が期限切れに近づいていると見なします。