kubectl apply

kubectlと静的マニフェストを使用してcert-managerをインストールする方法を学習します。

前提条件

kubectl バージョン >= v1.19.0 をインストールしてください。 (そうでない場合、CRDの更新に問題が発生します - v0.16 アップグレードノートを参照してください)
サポートされているバージョンのKubernetesまたはOpenShiftをインストールします。サポートされているKubernetes/OpenShiftのバージョン
クラウドプラットフォームでKubernetesを使用している場合は、Kubernetesプラットフォームプロバイダーとの互換性をお読みください。

手順

1. cert-managerリリースマニフェストからのインストール

すべてのリソース（CustomResourceDefinitionsとcert-manager、cainjector、webhookコンポーネント）は、単一のYAMLマニフェストファイルに含まれています。

すべてのcert-managerコンポーネントをインストールします。

kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.16.1/cert-manager.yaml

デフォルトでは、cert-managerはcert-manager名前空間にインストールされます。異なる名前空間でcert-managerを実行することもできますが、デプロイマニフェストを変更する必要があります。

cert-managerをインストールしたら、cert-manager名前空間で実行中のポッドを確認して、正しくデプロイされていることを確認できます。

$ kubectl get pods --namespace cert-manager

NAME                                       READY   STATUS    RESTARTS   AGE
cert-manager-5c6866597-zw7kh               1/1     Running   0          2m
cert-manager-cainjector-577f6d9fd7-tr77l   1/1     Running   0          2m
cert-manager-webhook-787858fcdb-nlzsq      1/1     Running   0          2m

cert-manager、cert-manager-cainjector、およびcert-manager-webhookポッドが実行中状態になっているはずです。webhookは、他のコンポーネントよりもプロビジョニングに少し時間がかかる場合があります。

問題が発生した場合は、まずFAQを確認してください。

2. (オプション) cert-manager webhookの準備完了を待つ

webhookコンポーネントの起動には時間がかかる場合があり、Kubernetes APIサーバーがwebhookの証明書を信頼するようになります。

まず、cmctlがインストールされていることを確認してください。

cmctlは、Kubernetesクラスタに対してドライランの証明書作成チェックを実行します。成功すると、The cert-manager API is readyというメッセージが表示されます。

$ cmctl check api
The cert-manager API is ready

このコマンドを使用して、チェックが成功するまで待機することもできます。cert-managerのインストールと同時にコマンドを実行した際の出力例を次に示します。

$ cmctl check api --wait=2m
Not ready: the cert-manager CRDs are not yet installed on the Kubernetes API server
Not ready: the cert-manager CRDs are not yet installed on the Kubernetes API server
Not ready: the cert-manager webhook deployment is not ready yet
Not ready: the cert-manager webhook deployment is not ready yet
Not ready: the cert-manager webhook deployment is not ready yet
Not ready: the cert-manager webhook deployment is not ready yet
The cert-manager API is ready

2. (オプション) インストールのエンドツーエンド検証

インストールを完全に検証する最良の方法は、テスト証明書を発行することです。そのため、テスト名前空間に自己署名発行者と証明書リソースを作成します。

cat <<EOF > test-resources.yaml
apiVersion: v1
kind: Namespace
metadata:
  name: cert-manager-test
---
apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
  name: test-selfsigned
  namespace: cert-manager-test
spec:
  selfSigned: {}
---
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: selfsigned-cert
  namespace: cert-manager-test
spec:
  dnsNames:
    - example.com
  secretName: selfsigned-cert-tls
  issuerRef:
    name: test-selfsigned
EOF

テストリソースを作成します。

kubectl apply -f test-resources.yaml

新しく作成された証明書のステータスを確認します。cert-managerが証明書要求を処理するまで、数秒待つ必要がある場合があります。

$ kubectl describe certificate -n cert-manager-test

...
Spec:
  Common Name:  example.com
  Issuer Ref:
    Name:       test-selfsigned
  Secret Name:  selfsigned-cert-tls
Status:
  Conditions:
    Last Transition Time:  2019-01-29T17:34:30Z
    Message:               Certificate is up to date and has not expired
    Reason:                Ready
    Status:                True
    Type:                  Ready
  Not After:               2019-04-29T17:34:29Z
Events:
  Type    Reason      Age   From          Message
  ----    ------      ----  ----          -------
  Normal  CertIssued  4s    cert-manager  Certificate issued successfully

テストリソースをクリーンアップします。

kubectl delete -f test-resources.yaml

上記のすべてのステップがエラーなく完了した場合、準備完了です！

アンインストール

警告: cert-managerをアンインストールするには、常にインストールと同じプロセスを逆順で使用してください。cert-managerが静的マニフェストまたはHelmからインストールされているかにかかわらず、次のプロセスから逸脱すると、問題が発生し、状態が壊れる可能性があります。これを防ぐために、アンインストールする際には以下の手順に従ってください。

続行する前に、ユーザーによって作成された不要なcert-managerリソースが削除されていることを確認してください。次のコマンドを使用して、既存のリソースを確認できます。

kubectl get Issuers,ClusterIssuers,Certificates,CertificateRequests,Orders,Challenges --all-namespaces

cert-managerをアンインストールする前に、これらのすべてのリソースを削除することをお勧めします。後で再インストールする予定で、カスタムリソースを失いたくない場合は、それらを保持できます。ただし、これにより、ファイナライザーに問題が発生する可能性があります。Challengesなどのリソースは、保留状態になるのを防ぐために削除する必要があります。

不要なリソースが削除されたら、インストール方法によって決まる手順を使用してcert-managerをアンインストールできます。

警告: cert-managerをアンインストールしたり、Certificateリソースを単純に削除すると、metadata.ownerReferencesがcert-managerによって設定されている場合、TLS Secretが削除される可能性があります。Secretにオーナー参照を追加するかどうかは、--enable-certificate-owner-refコントローラーフラグを使用して制御できます。デフォルトでは、このフラグはfalseに設定されているため、オーナー参照は追加されません。ただし、cert-manager v1.8以前では、フラグの値をtrueからfalseに変更しても、既存のオーナー参照は削除されませんでした。この動作はcert-manager v1.8で修正されました。オーナー参照を確認して、実際に削除されていることを確認してください。

通常のマニフェストを使用したアンインストール

通常のマニフェストによるインストールからのアンインストールは、kubectlの削除コマンドを使用して、インストールプロセスを逆順に実行することです。

現在実行中のバージョンvX.Y.Zへのリンクを使用して、インストールマニフェストを削除します。

警告: このコマンドは、インストール済みのcert-manager CRDも削除します。すべてのcert-managerリソース（例：certificates.cert-manager.ioリソース）は、Kubernetesのガベージコレクタによって削除されます。CustomResourceDefinitionを削除すると、カスタムリソースを保持することはできません。リソースを保持する場合は、CustomResourceDefinitionを個別に管理する必要があります。

kubectl delete -f https://github.com/cert-manager/cert-manager/releases/download/vX.Y.Z/cert-manager.yaml

名前空間が終了状態のままになる

cert-managerのインストールを最初に削除せずに名前空間が削除用にマークされている場合、名前空間は終了状態のままになる可能性があります。これは通常、APIServiceリソースはまだ存在するが、webhookは実行されていないため、到達不能になっているという事実が原因です。これを解決するには、上記のコマンドを正しく実行していることを確認し、それでも問題が発生する場合は、次のコマンドを実行します。

kubectl delete apiservice v1beta1.webhook.cert-manager.io

保留中のチャレンジの削除

Challengeは、ファイナライザーが完了できず、Kubernetesがcert-managerコントローラーの終了を待機している場合、保留状態のままになる可能性があります。これは、コントローラーがフラグを削除するために実行されなくなり、リソースが待機する必要があると定義されている場合に発生します。コントローラーが実行する操作を手動で実行することで、この問題を解決できます。

最初に、既存のcert-manager webhook構成（存在する場合）を削除します。

kubectl delete mutatingwebhookconfigurations cert-manager-webhook
kubectl delete validatingwebhookconfigurations cert-manager-webhook

次に、チャレンジリソースを編集して、.metadata.finalizersフィールドを空のリストに変更します。

kubectl edit challenge <the-challenge>