cert-manager Webhook について

cert-manager は、カスタムリソース定義を使用して Kubernetes API を拡張します。これは、主に3つの機能を持つ Webhook をインストールします。

検証: cert-manager リソースが作成または更新される際に、API のルールに準拠していることを保証します。この検証は、例えばリソースが OpenAPI スキーマに準拠していることを確認するよりも詳細で、例えば Issuer リソースごとに複数の Issuer タイプを指定できないようにするなどのロジックが含まれています。検証アドミッションは常に呼び出され、成功または失敗の応答を返します。
変更/デフォルト設定: リソースの作成および更新操作中に、例えばデフォルト値を設定するためにリソースの内容を変更します。
変換: Webhook は、cert-manager CustomResources (cert-manager.io) におけるバージョン間の変換を実装する責任も担います。これは、複数の API バージョンが同時にサポートできることを意味します。v1alpha2 から v1 までです。これにより、特定バージョンの構成スキーマに依存することが可能になります。

ℹ️ これは動的アドミッションコントロールとして知られています。Kubernetes ドキュメントの動的アドミッションコントロールについて詳しくはこちらをご覧ください。

概要

Webhook コンポーネントは、メインの cert-manager コントローラーおよび CA インジェクターコンポーネントと並行して実行される別の Pod としてデプロイされます。

API サーバーが Webhook コンポーネントと通信するためには、Webhook には、API サーバーが信頼するように構成された TLS 証明書が必要です。

Webhook は、Webhook がデプロイされた名前空間に secret/cert-manager-webhook-ca を作成します。このシークレットには、この要件を満たすために、Webhook Pod の証明書に署名するために使用される自己署名ルート CA 証明書が含まれています。

その後、Webhook は次のいずれかで構成できます。

Webhook CA によって署名された TLS 証明書とキーへのパス、または
Webhook の起動時に証明書とキーを動的に生成するための CA シークレットへの参照

既知の問題と解決策

GKE プライベートクラスターでの Webhook 接続の問題

Webhook 周りでエラーが発生しているが、Webhook が実行されている場合は、API サーバーから Webhook に到達できない可能性が最も高いです。この場合、GKE プライベートクラスターの説明に従って、API サーバーが Webhook と通信できることを確認してください。

AWS EKS での Webhook 接続の問題

EKS でカスタム CNI (Weave や Calico など) を使用している場合、Webhook は cert-manager から到達できません。これは、コントロールプレーンが EKS のカスタム CNI で実行するように構成できないため、コントロールプレーンとワーカーノード間で CNI が異なるために発生します。解決策は、cert-manager から到達できるようにホストネットワークで Webhook を実行することです。

cert-manager インストール直後の Webhook 接続の問題

cert-manager を最初にインストールすると、cert-manager API が使用可能になるまでに数秒かかります。これは、cert-manager API が cert-manager Webhook サーバーを必要とするためであり、起動に時間がかかるためです。理由は次のとおりです。

Webhook サーバーは、起動時にリーダー選出を実行します。これには数秒かかる場合があります。
Webhook サーバーは、起動して自己署名 CA およびサービス証明書を生成し、それらをシークレットに公開するまでに数秒かかる場合があります。
cainjector は、起動時にリーダー選出を実行します。これには数秒かかる場合があります。
cainjector は、起動後、すべての Webhook 構成の caBundle を更新するまでに数秒かかります。

これらの理由から、cert-manager のインストール後、インストール後の cert-manager API 操作を実行する際には、一時的な API 構成エラーを確認し、再試行する必要があります。

kubectl --dry-run 操作を cert-manager API で実行するインストール後のチェックを追加することもできます。または、インストール検証手順が成功するまで自動的に再試行するインストール後のチェックを追加することもできます。

その他の Webhook の問題

Webhook に関するその他の問題が発生した場合は、webhook トラブルシューティングガイドを参照してください。