新着：プロジェクトの最新情報はTwitterとMastodonで入手してください

リソースのバックアップとリストア

cert-manager をアンインストールする必要がある場合、またはインストールを新しいクラスターに転送する場合は、後で再インストールするために cert-manager のすべての構成をバックアップできます。

cert-manager リソース構成のバックアップ

以下のコマンドは、cert-managerリソースの設定をバックアップします。これは、cert-managerをアップグレードする前に役立つ場合があります。このバックアップには、X.509証明書を含むSecretsは含まれていないため、これらのSecretオブジェクトがまだないクラスターに復元すると、証明書が再発行されることになります。

バックアップ

cert-managerの設定リソースをすべてバックアップするには、以下を実行します。

kubectl get --all-namespaces -oyaml issuer,clusterissuer,cert > backup.yaml

新しいクラスターにデータを転送する場合、設定されたIssuerによって参照される追加のSecretリソース（例：）もコピーする必要がある場合があります。

CA Issuer

  • issuer.spec.ca.secretNameによって参照されるルートCAのSecret

Vault Issuer

  • issuer.spec.vault.auth.tokenSecretRefによって参照されるトークン認証Secret
  • issuer.spec.vault.auth.appRole.secretRefによって参照されるAppRole構成Secret

ACME Issuer

  • issuer.acme.privateKeySecretRefによって参照されるACMEアカウントの秘密鍵Secret
  • issuer.acme.dns01.providersおよびissuer.acme.solvers.dns01フィールドで構成されたDNSプロバイダーによって参照される任意のSecret

復元

設定を復元するには、cert-managerのインストール後、上記で作成したファイルに対してkubectl applyを実行できます。uidフィールドとresourceVersionフィールドは復元する必要はありません。

kubectl apply -f <(awk '!/^ *(resourceVersion|uid): [^ ]+$/' backup.yaml)

クラスター全体のバックアップと復元

このセクションでは、障害復旧、クラスター移行などのシナリオのために、クラスター内の「すべて」の Kubernetes リソース（一部のcert-managerリソースを含む）のバックアップと復元について説明します。

注：このプロセスは、限られた Kubernetes リリースのシンプルな Kubernetes テストクラスターでテストされています。データ損失を避けるため、本番環境で使用する前に、ご自身のクラスターでバックアップと復元の両方の戦略をテストしてください。エラーが発生した場合は、GitHub issue または PR を開いて、さまざまな Kubernetes 環境でのこのプロセスのバリエーションを文書化してください。

不要な証明書の再発行を避ける

復元の順序

cert-managerがCertificateのX.509証明書を含むKubernetes Secretを見つけられない場合、再発行がトリガーされます。復元後の不要な再発行を避けるために、SecretがCertificateの前に復元されていることを確認してください。同様に、ingress-shimを使用している場合は、SecretをIngressの前に復元する必要があります。

バックアップから一部のcert-managerリソースを除外する

cert-managerには、特定の時点での操作を表すように設計された多くのカスタムリソースがあります。例としては、X.509証明書に対する1回限りのリクエストを表すCertificateRequestがあります。これらのリソースのステータスは、一時的な秘密鍵を保持するSecretなど、他の一時的なリソースに依存する可能性があるため、cert-managerは後でこれらのリソースの状態を正しく再作成できない場合があります。

ほとんどの場合、バックアップおよび復元ツールはカスタムリソースのステータスを復元しないため、このような1回限りのリソースをバックアップに含めると、復元後に不要な再発行が発生する可能性があります。ステータスフィールドがないと、cert-managerは、たとえば、Orderがすでに完了していることを判別できないためです。不要な再発行を避けるために、OrderとChallengeをバックアップから除外することをお勧めします。また、CertificateRequestのバックアップも推奨しません。「CertificateRequestsのバックアップ」を参照してください。

Ingress証明書の復元

ingress-shim経由でIngress用に作成されたCertificateには、オーナー参照がIngressリソースを指しています。cert-managerはオーナー参照を使用して、CertificateがそのIngressに「属して」いることを確認し、既存のCertificateに対して作成/修正を試行しません。クラスター全体の再作成後、復元されたオーナー参照は（IngressのUUIDが変更されているため）おそらく正しくありません。正しくないオーナー参照は、Ingress（つまり新しいDNS名）に対する更新がCertificateに適用されない状況につながる可能性があります。

この問題を回避するために、ほとんどの場合、ingress-shim経由で作成されたCertificateをバックアップから除外する必要があります。復元が正しい順序で行われる場合（X.509証明書を含むSecretがIngressの前に復元される）、cert-managerはIngress用の新しいCertificateを作成し、既存のSecretがそのCertificate用のものであると判断できます。

Velero

velero v1.12.2およびcert-managerバージョンv1.13.2でバックアップと復元をテストしました。

いくつかの潜在的なエッジケース

  • バックアップに cert-manager CRDが含まれていることを確認してください。例えば、--exclude-namespaces フラグが velero backup create に渡された場合、バックアップに含める実際のリソースがない CRD は、--include-cluster-resources=true フラグもバックアップコマンドに渡されない限り、バックアップに含まれない可能性があります。

  • Veleroはカスタムリソースのステータスを復元しないため、バックアップから Order、Challenge、および CertificateRequest を除外する必要があります。「バックアップから特定のcert-managerリソースを除外する」を参照してください。

  • Veleroのデフォルトの復元順序（Secrets を Ingress の前に、カスタムリソースを最後に復元）により、復元操作の順序による不要な証明書の再発行がないようにする必要があります。「復元順序」を参照してください。

  • cert-manager 自体のデプロイメントを復元する場合、残りのデプロイメントの前に cert-manager のRBACリソースを復元する必要がある場合があります。これは、cert-manager のコントローラーが、Webhookが準備完了になる前に、cert-manager のWebhook用の Certificate を作成できる必要があるためです。これを行うには、コントローラーに適切な権限が必要です。VeleroはデフォルトでRBACリソースの前にPodを復元するため、復元がWebhook Podが準備完了になるのを待って停止する可能性があります。

  • Veleroは所有者参照を復元しないため、Ingress 用に作成された Certificate を、Ingress 自体を再作成しない場合でも、バックアップから除外する必要がある場合があります。「Ingress証明書の復元」を参照してください。

Veleroを使用したバックアップと復元の例

次のコマンドは、Order、Challenge、および CertificateRequest (上記参照) を除外して、デフォルトおよびcert-manager名前空間内のすべてのKubernetesリソースのバックアップを作成します。

velero backup create \
  full-backup \
  --include-namespaces cert-manager,default \
  --include-cluster-resources=true \
  --exclude-resources challenges.acme.cert-manager.io,orders.acme.cert-manager.io,certificaterequests.cert-manager.io

Veleroが所有者参照を復元しないことを回避するために、バックアップを2つのステップで復元できます。最初に、Secret と Ingress、および cert-manager デプロイメントを復元し、次に Certificate リソースを復元します。これにより、cert-manager のコントローラーがIngress用のCertificate を作成し、所有者参照を設定できます。次に、2回目の復元で、手動で作成されたCertificate を復元し、Ingress 用に生成されたCertificate が既に存在することを検出し、再作成を試みません。

  1. Certificate リソースを除くすべてを復元します
velero restore create \
  --from-backup full-backup \
  --exclude-resources certificates.cert-manager.io
  1. cert-managerがIngress用のCertificateを作成するのを待ちます（cert-managerにRBAC/Webhookの問題がある場合は、デプロイメントを手動で再起動する必要がある場合があります）。自動生成されたCertificateが作成されたら、手動で作成されたCertificateを復元します
velero restore create \
  --from-backup full-backup

CertificateRequestのバックアップ

ほとんどのシナリオでは、バックアップに CertificateRequest リソースを含めることは推奨されなくなりました。CertificateRequest は、X.509証明書の1回限りの要求を表すように設計されています。リクエストが完了すると、CertificateRequest は通常、安全に削除できます1。ほとんどの場合（Certificate 用にCertificateRequestが作成されている場合など）、必要なときに（つまり、Certificateの更新時）、新しいCertificateRequestが作成されます。v1.3.0では、ポリシーの実装に向けた取り組みの一環として、CertificateRequest リソースのIDフィールドを導入しました。作成時に、cert-mananager のWebhookは、CertificateRequest のspecを、CertificateRequest の作成者のIDを表すイミュータブルなIDフィールドで更新します。これにより、復元者のIDが元の作成者のIDと異なる可能性があるため、CertificateRequest をバックアップおよび復元する際にいくつかの複雑さが加わり、ほとんどの場合、復元されたCertificateRequestは不適切な状態になる可能性が高くなります。

脚注

  1. Certificate specに対する特定の変更が、そのCertificateのCertificateRequestがない場合、再発行をトリガーしないというエッジケースがあります。「証明書が再発行されるタイミングに関するドキュメント」を参照してください。↩