新機能：プロジェクトの最新情報はこちらで入手できますTwitterとMastodon

アノテーション付きIngressリソース

apiVersion: networking.k8s.io/v1
kind: Ingress

cert-managerの一般的なユースケースは、Ingressリソースを保護するためにTLS署名付き証明書を要求することです。これは、Ingressリソースにアノテーションを追加するだけで実行でき、cert-managerはCertificateリソースの作成を容易にします。cert-managerの小さなサブコンポーネントであるingress-shimがこの処理を担当します。

動作方法

サブコンポーネントingress-shimは、クラスタ全体のIngressリソースを監視します。サポートされているアノテーションセクションで説明されているアノテーションが付いたIngressを検出すると、tls.secretNameフィールドに指定された名前のCertificateリソースが、Ingressで説明されているように構成され、Ingressのネームスペースに存在することを保証します。例：

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    # add an annotation indicating the issuer to use.
    cert-manager.io/cluster-issuer: nameOfClusterIssuer
  name: myIngress
  namespace: myIngress
spec:
  rules:
  - host: example.com
    http:
      paths:
      - pathType: Prefix
        path: /
        backend:
          service:
            name: myservice
            port:
              number: 80
  tls: # < placing a host in the TLS config will determine what ends up in the cert's subjectAltNames
  - hosts:
    - example.com
    secretName: myingress-cert # < cert-manager will store the created certificate in this secret.

サポートされているアノテーション

Certificateリソースが自動的に作成されるようにするには、Ingressリソースに次のアノテーションを指定できます。

  • cert-manager.io/issuer: このIngressに必要な証明書を発行する発行者の名前。

    ⚠️ このアノテーションは、ネームスペーススコープの発行者を想定していません。cert-manager.io Issuerをデフォルトで使用しますが、外部発行者タイプの場合は、ネームスペーススコープとクラスタスコープの両方の発行者タイプで使用してください。

    ⚠️ ネームスペーススコープの発行者を使用する場合は、発行者はIngressリソースと同じネームスペースに存在する必要があります。

  • cert-manager.io/cluster-issuer: このIngressに必要な証明書を取得するcert-manager.io ClusterIssuerの名前。ClusterIssuerはネームスペースを持たないリソースであるため、Ingressがどのネームスペースに存在するかは関係ありません。

    ⚠️ このアノテーションは、グループと種類を指定せずにcert-manager.io ClusterIssuerを参照するためのショートカットです。外部クラスタスコープの発行者を指定するために使用することを意図したものではありません。それらにはcert-manager.io/issuerアノテーションを使用してください。

  • cert-manager.io/issuer-kind: 外部発行者リソースの種類（例：AWSPCAIssuer）。これはツリー外の発行者に対してのみ必要です。

  • cert-manager.io/issuer-group: 外部発行者コントローラのAPIグループ（例：awspca.cert-manager.io）。これはツリー外の発行者に対してのみ必要です。

  • kubernetes.io/tls-acme: "true": このアノテーションには、ingress-shimの追加設定が必要です。下記参照。つまり、デフォルトの発行者をingress-shimコンテナの引数として指定する必要があります。

  • acme.cert-manager.io/http01-ingress-class: このアノテーションにより、このIngressのチャレンジを解決するために使用されるIngressクラスを設定できます。内部サービスを保護し、Ingressとは異なるIngressクラスを使用してチャレンジを解決する必要がある場合に、これをカスタマイズすると便利です。指定されていない場合、かつacme-http01-edit-in-placeアノテーションが設定されていない場合、これはIssuerリソースに定義されているIngressクラスをデフォルトで使用します。

  • acme.cert-manager.io/http01-edit-in-place: "true": これは、Ingressが「その場で」変更されるか、HTTP01チャレンジ用に新しいIngressが作成されるかを制御します。「true」に設定されている場合、既存のIngressが変更されます。それ以外の値、またはアノテーションがない場合は「false」と見なされます。このアノテーションは、作成された証明書に"cert-manager.io/issue-temporary-certificate": "true"アノテーションを追加し、最終的な署名済み証明書が返されるまで、結果のSecretに一時的な証明書が設定されます。これはingress-gceコンポーネントとの互換性を維持するために役立ちます。

  • cert-manager.io/common-name: （オプション）このアノテーションにより、生成されるCertificateのspec.commonNameを設定できます。

  • cert-manager.io/email-sans: （オプション）このアノテーションにより、生成されるCertificateのspec.emailAddressesフィールドを設定できます。コンマ区切りの値をサポートします（例：「me@example.com,you@example.com」）。

  • cert-manager.io/subject-organizations: （オプション）このアノテーションにより、生成されるCertificateのspec.subject.organizationsフィールドを設定できます。コンマ区切りの値をサポートします（例：「Company 1,Company 2」）。

  • cert-manager.io/subject-organizationalunits: （オプション）このアノテーションにより、生成されるCertificateのspec.subject.organizationalUnitsフィールドを設定できます。コンマ区切りの値をサポートします（例：「IT Services,Cloud Services」）。

  • cert-manager.io/subject-countries: （オプション）このアノテーションにより、生成されるCertificateのspec.subject.countriesフィールドを設定できます。コンマ区切りの値をサポートします（例：「Country 1,Country 2」）。

  • cert-manager.io/subject-provinces: （オプション）このアノテーションにより、生成されるCertificateのspec.subject.provincesフィールドを設定できます。コンマ区切りの値をサポートします（例：「Province 1,Province 2」）。

  • cert-manager.io/subject-localities: （オプション）このアノテーションにより、生成されるCertificateのspec.subject.localitiesフィールドを設定できます。コンマ区切りの値をサポートします（例：「City 1,City 2」）。

  • cert-manager.io/subject-postalcodes: （オプション）このアノテーションにより、生成されるCertificateのspec.subject.postalCodesフィールドを設定できます。コンマ区切りの値をサポートします（例：「123ABC,456DEF」）。

  • cert-manager.io/subject-streetaddresses: （オプション）このアノテーションにより、生成されるCertificateのspec.subject.streetAddressesフィールドを設定できます。コンマ区切りの値をサポートします（例：「123 Example St,456 Other Blvd」）。

  • cert-manager.io/subject-serialnumber: （オプション）このアノテーションにより、生成されるCertificateのspec.subject.serialNumberフィールドを設定できます。コンマ区切りの値をサポートします（例：「10978342379280287615,1111144445555522228888」）。

  • cert-manager.io/duration: （オプション）このアノテーションにより、生成されるCertificateのspec.durationフィールドを設定できます。

  • cert-manager.io/renew-before：（オプション）このアノテーションを使用すると、生成される証明書のspec.renewBeforeフィールドを設定できます。

  • cert-manager.io/usages：（オプション）このアノテーションを使用すると、生成される証明書のspec.usagesフィールドを設定できます。「key agreement,digital signature, server auth」のように、コンマ区切りの文字列で値を渡します。

  • cert-manager.io/revision-history-limit：（オプション）このアノテーションを使用すると、spec.revisionHistoryLimitフィールドを設定し、証明書のために保持するCertificateRequestの数を制限できます。最小値は1です。設定しない場合、すべてのCertificateRequestが保持されます。

  • cert-manager.io/private-key-algorithm：（オプション）このアノテーションを使用すると、spec.privateKey.algorithmフィールドを設定し、証明書の秘密鍵生成のアルゴリズムを設定できます。有効な値はRSA、ECDSA、Ed25519です。設定しない場合、アルゴリズムRSAが使用されます。

  • cert-manager.io/private-key-encoding：（オプション）このアノテーションを使用すると、spec.privateKey.encodingフィールドを設定し、証明書の秘密鍵生成のエンコーディングを設定できます。有効な値はPKCS1とPKCS8です。設定しない場合、アルゴリズムPKCS1が使用されます。

  • cert-manager.io/private-key-size：（オプション）このアノテーションを使用すると、spec.privateKey.sizeフィールドを設定し、証明書の秘密鍵のサイズを設定できます。アルゴリズムがRSAに設定されている場合、有効な値は2048、4096、8192であり、指定しない場合は2048がデフォルトになります。アルゴリズムがECDSAに設定されている場合、有効な値は256、384、521であり、指定しない場合は256がデフォルトになります。アルゴリズムがEd25519に設定されている場合、サイズは無視されます。

  • cert-manager.io/private-key-rotation-policy：（オプション）このアノテーションを使用すると、spec.privateKey.rotationPolicyフィールドを設定し、証明書の秘密鍵のローテーションポリシーを設定できます。有効な値はNeverとAlwaysです。設定しない場合、ローテーションポリシーNeverが使用されます。

複数のIngressで複数の証明書を生成する

複数のIngressから証明書を生成する必要がある場合、Issuerアノテーションが設定されていることを確認してください。アノテーションに加えて、各Ingressに一意のtls.secretNameが必要です。

オプションの設定

ingress-shimサブコンポーネントは、インストールの一部として自動的にデプロイされます。

古いkube-legoのkubernetes.io/tls-acme: "true"アノテーションを完全に自動化されたTLSに使用したい場合は、cert-managerのデプロイ時にデフォルトのIssuerを設定する必要があります。これは、Helmを使用してデプロイする際に以下の--setを追加することで実行できます。

--set ingressShim.defaultIssuerName=letsencrypt-prod \
   --set ingressShim.defaultIssuerKind=ClusterIssuer \
   --set ingressShim.defaultIssuerGroup=cert-manager.io

または、cert-managerデプロイメントのpodTemplateコンテナ引数に以下の引数を追加します。

- --default-issuer-name=letsencrypt-prod
  - --default-issuer-kind=ClusterIssuer
  - --default-issuer-group=cert-manager.io

上記の例では、cert-managerはkubernetes.io/tls-acme: "true"アノテーションを持つすべてのIngressに対して、ClusterIssuer letsencrypt-prodを参照するCertificateリソースを作成します。

アノテーションを介して設定されたIssuerは、デフォルトのIssuerよりも優先されます。CLIフラグでデフォルトのIssuerが設定されていて、cert-manager.io/cluster-issuerまたはcert-manager.io/issuerアノテーションもIngressに追加されている場合、作成されたCertificateはアノテーションを介して設定されたIssuerを参照します。

cert-managerのデプロイの詳細については、インストールガイドを参照してください。

トラブルシューティング

ingress-shimアノテーションを適用した後、Certificateリソースが作成されない場合は、少なくともcert-manager.io/issuerまたはcert-manager.io/cluster-issuerが設定されていることを確認してください。kubernetes.io/tls-acme: "true"を使用する場合は、上記すべてのステップを確認し、解決しない場合はcert-manager podのログでエラーを探してください。

開発者向けの内部動作図

[1] https://cert-manager.dokyumento.jp/docs/usage/certificate