HTTP01

cert-managerは、HTTP01チャレンジを解決するために、既存のIngressまたはGateway構成を使用します。

HTTP01 Ingressソルバーの構成

このページでは、IssuerリソースのHTTP01チャレンジソルバー構成で利用可能なさまざまなオプションについて詳しく説明します。ACME IssuerとそのAPI形式の構成の詳細については、「ACME Issuer」のドキュメントを参照してください。

HTTP01チャレンジタイプがどのように機能するかについては、Let's Encryptチャレンジタイプのページを参照してください。

以下に、より多くの構成オプションを備えた単純なHTTP01 ACME Issuerの例を示します。

apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
  name: example-issuer
spec:
  acme:
    server: https://acme-staging-v02.api.letsencrypt.org/directory
    privateKeySecretRef:
      name: example-issuer-account-key
    solvers:
    - http01:
        ingress:
          ingressClassName: nginx

オプション

HTTP01 Issuerは、いくつかの追加オプションをサポートしています。利用可能なオプションの範囲の詳細については、リファレンスドキュメントを参照してください。

ingressClassName

ingressClassNameフィールドが指定されている場合、cert-managerは、ACMEチャレンジ検証リクエストに応答するacmesolverポッドにトラフィックをルーティングするために、新しいIngressリソースを作成します。

これは、Ingressコントローラーを構成する推奨される方法です。ほとんどのIngressコントローラーは、ingressClassNameをサポートしており、ingress-gceは例外です（外部負荷分散のためのIngressの構成のページを参照）。

class

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

このフィールドは、ingress-gceでのみ推奨されます。ingress-gceは、ingressClassNameフィールドをサポートしていません。

name

nameフィールドが指定されている場合、cert-managerは、HTTP01チャレンジを解決するために、指定されたIngressリソースを編集します。

これは、作成されたIngressリソースごとに一意のIPアドレスを利用するingress-gceなどのIngressコントローラーとの互換性を保つために役立ちます。

このモードは、すべてのIngressリソースに対して単一のIPを公開するIngressコントローラーを使用する場合は避ける必要があります。これにより、特定のIngressコントローラー固有のアノテーションとの互換性の問題が発生する可能性があります。

serviceType

まれに、Kubernetesの制限により、HTTP01チャレンジ応答サービスにNodePortをタイプとして使用することが不可能/望ましくない場合があります。チャレンジ応答中に使用するKubernetesサービスタイプを定義するには、次のHTTP01構成を指定します。

http01:
      ingress:
        # Valid values are ClusterIP and NodePort
        serviceType: ClusterIP

デフォルトでは、HTTP01を設定しない場合、またはserviceTypeを空の文字列に設定した場合、タイプNodePortが使用されます。通常、これを変更する必要はありません。

podTemplate

ソルバーポッドのラベルとアノテーションを変更または追加したい場合があります。これらは、podTemplateのmetadataフィールドで構成できます。

同様に、podTemplateのspecフィールドで構成することにより、ソルバーポッドのnodeSelector、tolerations、affinityを設定できます。他のspecフィールドは編集できません。

テンプレートを構成する方法の例を次に示します。

apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
  name: ...
spec:
  acme:
    server: ...
    privateKeySecretRef:
      name: ...
    solvers:
    - http01:
        ingress:
          podTemplate:
            metadata:
              labels:
                foo: "bar"
                env: "prod"
            spec:
              nodeSelector:
                bar: baz

追加されたラベルとアノテーションは、cert-managerのデフォルトの上にマージされ、同じキーのエントリを上書きします。

podTemplateには他のフィールドは存在しません。

ingressTemplate

ソルバーIngressリソースにラベルとアノテーションを追加できます。クラスター全体で複数のIngressコントローラーを管理していて、適切なコントローラーがソルバーをピックアップして（解決すべき今後のチャレンジのために）公開することを保証したい場合に非常に役立ちます。これらは、ingressTemplateのmetadataフィールドで構成できます。

apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
  name: ...
spec:
  acme:
    server: ...
    privateKeySecretRef:
      name: ...
    solvers:
    - http01:
        ingress:
          ingressTemplate:
            metadata:
              labels:
                foo: "bar"
              annotations:
                "nginx.ingress.kubernetes.io/whitelist-source-range": "0.0.0.0/0,::/0"
                "nginx.org/mergeable-ingress-type": "minion"
                "traefik.ingress.kubernetes.io/frontend-entry-points": "http"

追加されたラベルとアノテーションは、cert-managerのデフォルトの上にマージされ、同じキーのエントリを上書きします。

Ingressの他のフィールドは編集できません。

HTTP-01 Gateway API ソルバーの設定

機能の状態: cert-manager 1.15 [beta]

Gateway および HTTPRoute リソースは、Gateway API の一部であり、Kubernetes クラスタにインストールする一連の CRD で、Ingress API に比べてさまざまな改善を提供します。

kubectl apply -f "https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.0.0/standard-install.yaml"

kubectl rollout restart deployment cert-manager -n cert-manager

Gateway API HTTPRoute HTTP-01 ソルバーは、指定されたラベルを使用して一時的な HTTPRoute を作成します。これらのラベルは、80 ポートでリスナーを持つ Gateway に一致する必要があります。

次に、Gateway API を使用した HTTP-01 ACME Issuer の例を示します。

apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
  name: letsencrypt
  namespace: default
spec:
  acme:
    solvers:
      - http01:
          gatewayHTTPRoute:
            parentRefs:
              - name: traefik
                namespace: traefik
                kind: Gateway

Issuer は、クラスタに存在する既存の Gateway に依存します。cert-manager は Gateway リソースを編集しません。

たとえば、次の Gateway では、Issuer がチャレンジを解決できます。

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: traefik
  namespace: traefik
spec:
  gatewayClassName: traefik
  listeners:
  - name: http
    protocol: HTTP
    port: 80
    allowedRoutes:
        namespaces:
          from: All

上記の例では、Gateway は HTTP-01 チャレンジを解決する目的で特別に作成されていますが、ポート 80 にリスナーがある限り、既存の Gateway を再利用することもできます。

Issuer の labels は、Gateway のポート 80 リスナーが from: All で構成されている限り、別の名前空間にある Gateway を参照できます。証明書は Issuer と同じ名前空間に作成されるため、上記の Gateway でこの Secret を参照することはできないことに注意してください。

上記の Issuer に証明書が提示されると、cert-manager は一時的な HTTPRoute を作成します。たとえば、次の証明書の場合

apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: example-tls
  namespace: default
spec:
  issuerRef:
    name: letsencrypt
  dnsNames:
  - example.net

HTTPRoute が表示されます

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: cm-acme-http-solver-gdhvg
  namespace: default
spec:
  parentRefs:
    - name: traefik
      namespace: traefik
      kind: Gateway
  hostnames:
  - example.net
  rules:
  - backendRefs:
    - port: 8089
      name: cm-acme-http-solver-gdhvg
      weight: 1
    matches:
    - path:
        type: Exact
        value: /.well-known/acme-challenge/YadC4gaAzqEPU1Yea0D2MrzvNRWiBCtUizCtpiRQZqI

証明書が発行されると、HTTPRoute は削除されます。

labels

これらのラベルは、HTTP-01 チャレンジを解決するために cert-manager によって作成された一時的な HTTPRoute にコピーされます。これらのラベルは、クラスタ上のいずれかの Gateway リソースと一致する必要があります。一致した Gateway には、ポート 80 にリスナーがあります。

ラベルがクラスタ上のいずれの Gateway にも一致しない場合、cert-manager は一時的な HTTPRoute チャレンジを作成しますが、何も起こらないことに注意してください。

serviceType

このフィールドは、http01.ingress.serviceType と同じ意味を持ちます。

HTTP-01 ソルバーの伝播チェック用ネームサーバーの設定

cert-manager は、HTT01 チャレンジを試行する前に到達可能性テストを実行します。デフォルトでは、cert-manager は /etc/resolv.conf から取得した再帰ネームサーバーを使用してチャレンジ URL をクエリします。

これが望ましくない場合 (たとえば、スプリットホライズン DNS の場合)、cert-manager コントローラーは、この動作を変更できるフラグを公開します

--acme-http01-solver-nameservers cert-manager がクエリする必要がある再帰ネームサーバーのホストとポートをコンマで区切った文字列。

使用例

--acme-http01-solver-nameservers="8.8.8.8:53,1.1.1.1:53"

cert-manager helm チャートを使用している場合は、.Values.extraArgs を使用するか、helm install/upgrade 時に --set を使用して再帰ネームサーバーを設定できます。

--set 'extraArgs={--acme-http01-solver-nameservers=8.8.8.8:53\,1.1.1.1:53}'