新着: プロジェクトの最新情報についてはTwitterとMastodonでご確認ください。

cert-manager コマンドラインツール (cmctl)

cmctl は、クラスタ内の cert-manager とそのリソースを管理するのに役立つコマンドラインツールです。

📢 cert-manager CLI が新しいGitHubリポジトリに移行します

cert-manager チームは、cmctl コードを新しいGitHubリポジトリに移行することを決定しました。これにより、cmctl の新機能とバグ修正を cert-manager とは独立してリリースできるようになります。cert-manager の Go パッケージの依存関係が簡素化されるため、cert-manager のセキュリティパッチリリースが減少します。cmctl を trust-manager と approver-policy の管理機能で拡張しやすくなります。また、cert-manager のテストスイートをさらに遅くすることなく、cmctl のE2Eテストをより多く記述できるようになります。

⚠️ cert-manager 1.14 は、cert-manager-ctl コンテナイメージ、Goパッケージ、GitHubリリースバイナリが含まれる最後のリリースです。

詳細については、新しいGitHub上のcmctlリポジトリをご覧ください。

インストール

Homebrew

MacまたはLinuxでHomebrewがインストールされている場合、cmctlを以下のようにインストールできます。

brew install cmctl

これにより、シェル補完もインストールされます。

手動インストール

使用しているプラットフォームのcmctlファイルが必要です。これらは、cmctl GitHubリリースページにあります。cmctlを使用するには、バイナリがcmctlという名前で$PATHにアクセス可能である必要があります。CLIを設定するには、以下のコマンドを実行します。OSとARCHをシステムの対応するものに置き換えてください。

OS=$(go env GOOS); ARCH=$(go env GOARCH); curl -fsSL -o cmctl https://github.com/cert-manager/cmctl/releases/latest/download/cmctl_${OS}_${ARCH}
chmod +x cmctl
sudo mv cmctl /usr/local/bin

または、goを使用してcmctlをインストールできます。

go install github.com/cert-manager/cmctl/v2@latest

cmctl helpを実行して、CLIが正しく設定されていることを確認できます。

$ cmctl help


cmctl is a CLI tool manage and configure cert-manager resources for Kubernetes


Usage: cmctl [command]


Available Commands:
  approve      Approve a CertificateRequest
  check        Check cert-manager components
  completion   Generate completion scripts for the cert-manager CLI
  convert      Convert cert-manager config files between different API versions
  create       Create cert-manager resources
  deny         Deny a CertificateRequest
  experimental Interact with experimental features
  help         Help about any command
  inspect      Get details on certificate related resources
  renew        Mark a Certificate for manual renewal
  status       Get details on current status of cert-manager resources
  upgrade      Tools that assist in upgrading cert-manager
  version      Print the cert-manager CLI version and the deployed cert-manager version


Flags:
  -h, --help                           help for cmctl
      --log-flush-frequency duration   Maximum number of seconds between log flushes (default 5s)


Use "cmctl [command] --help" for more information about a command.

レガシーkubectlプラグインもありますが、スタンドアロンのcmctlバイナリの方が優れた自動補完を提供するため、推奨されなくなりました。

コマンド

CertificateRequestの承認と拒否

CertificateRequestは、それぞれのcmctlコマンドを使用して承認または拒否できます。

注記: 内部cert-manager承認者は、cert-manager-controllerのフラグ--controllers=*,-certificaterequests-approverで無効にしない限り、すべてのCertificateRequestを自動的に承認する場合があります。

$ cmctl approve -n istio-system mesh-ca --reason "pki-team" --message "this certificate is valid"
Approved CertificateRequest 'istio-system/mesh-ca'
$ cmctl deny -n my-app my-app --reason "example.com" --message "violates policy"
Denied CertificateRequest 'my-app/my-app'

変換

cmctl convertを使用して、cert-managerマニフェストファイルを異なるAPIバージョン間で変換できます。YAMLとJSONの両方の形式が受け入れられます。このコマンドは、ファイル名、ディレクトリパス、またはURLを入力として受け取ります。内容は、cert-managerが認識する最新のAPIバージョン、または--output-versionフラグで指定された形式に変換されます。

デフォルトの出力は、YAML形式でstdoutに出力されます。-oオプションを使用して、出力先を変更できます。

たとえば、これは最新のAPIバージョンでcert.yamlを出力します。

cmctl convert -f cert.yaml

作成

cmctl createを使用して、cert-managerリソースを手動で作成できます。さまざまなリソースを作成するためのサブコマンドがあります。

CertificateRequest

cert-manager CertificateRequestを作成するには、cmctl create certificaterequestを使用します。このコマンドは、作成するCertificateRequestの名前を入力として受け取り、--from-certificate-fileフラグで指定されたCertificateリソースのYAMLマニフェストに基づいて新しいCertificateRequestリソースを作成します。ローカルに秘密鍵を生成し、「証明書署名要求」を作成してcert-manager発行者 (Issuer) に送信します。秘密鍵はローカルファイルに書き込まれ、デフォルトは<name_of_cr>.keyですが、--output-key-fileフラグを使用して指定できます。

CertificateRequestが署名されるのを待って、X.509証明書をファイルに保存する場合は、--fetch-certificateフラグを設定できます。証明書の発行を待機する際のデフォルトのタイムアウトは5分ですが、--timeoutフラグで指定できます。X.509証明書を保存するファイルのデフォルトの名前は<name_of_cr>.crtですが、--output-certificate-fileフラグを使用して変更できます。

秘密鍵とX.509証明書の両方がファイルに書き込まれ、Kubernetes内には保存されませんことに注意してください。

例えば、これは`my-certificate.yaml`で記述されているcert-manager証明書に基づいて、「my-cr」という名前のCertificateRequestリソースを作成し、秘密鍵とX.509証明書をそれぞれ`my-cr.key`と`my-cr.crt`に保存します。

cmctl create certificaterequest my-cr --from-certificate-file my-certificate.yaml --fetch-certificate --timeout 20m

更新

`cmctl`を使用すると、特定の証明書の更新を手動でトリガーできます。これは、ラベルセレクタ(`-l app=example`)を使用して一度に1つの証明書ずつ、または`--all`フラグを使用して行うことができます。

例えば、`example-com-tls`証明書を更新できます。

$ kubectl get certificate
NAME                       READY   SECRET               AGE
example-com-tls            True    example-com-tls      1d


$ cmctl renew example-com-tls
Manually triggered issuance of Certificate default/example-com-tls


$ kubectl get certificaterequest
NAME                              READY   AGE
example-com-tls-tls-8rbv2         False    10s

指定された名前空間内のすべての証明書を更新することもできます。

$ cmctl renew --namespace=app --all

更新コマンドでは、いくつかのオプションを指定できます。

  • `--all` は、指定された名前空間内のすべての証明書、または`--all-namespaces`と組み合わせるとすべての名前空間内のすべての証明書を更新します。
  • `-A`または`--all-namespaces`は、名前空間全体で証明書の更新をマークします。
  • `-l` `--selector` は、ラベルクエリを設定してフィルタリングするためのオプションです。また、`--context`や`--namespace`などの`kubectl`のようなグローバルフラグも使用できます。

証明書のステータス

`cmctl status certificate`は、CertificateリソースとCertificateRequest、Secret、Issuerなどの関連リソースの現在のステータスの詳細を出力します。ACME証明書の場合は、OrderとChallengesも出力されます。このコマンドは、リソースに関する情報（Conditions、Eventsなど）、およびSecretのKey UsagesやExtended Key Usages、OrderのAuthorizationsなどのリソース固有のフィールドを出力します。これは、証明書のトラブルシューティングに役立ちます。

このコマンドは、Certificateリソースの名前を指定する1つの引数を取ります。名前空間は、通常どおり`-n`または`--namespace`フラグで指定できます。

この例では、`my-namespace`名前空間内の`my-certificate`という名前のCertificateのステータスを照会します。

cmctl status certificate my-certificate -n my-namespace

補完

`cmctl`は、サブコマンドと実行時オブジェクトの両方について自動補完をサポートしています。

$ cmctl approve -n <TAB> <TAB>
default             kube-node-lease     kube-public         kube-system         local-path-storage

使用しているシェルについての手順に従って、環境に補完をインストールできます。現在、bash、fish、zsh、powershellをサポートしています。

$ cmctl completion help

実験的

`cmctl x`には、現在cert-manager本体への組み込みを検討中の操作に関する実験的なサブコマンドがあります。これらのコマンドの動作とインターフェースは、将来のリリースで変更または削除される可能性があります。

作成

`cmctl x create`は、cert-managerリソースを手動で作成するために使用できます。さまざまなリソースを作成するためのサブコマンドが用意されています。

CertificateSigningRequest

CertificateSigningRequestを作成するには、以下を使用します。

cmctl x create csr

このコマンドは、作成するCertificateSigningRequestの名前と、Certificateマニフェストを含むファイル(`-f, --from-certificate-file`)を取ります。このコマンドは、Certificateのオプションに基づいて秘密鍵を生成し、ローカルファイル`.key`、または`-k, --output-key-file`で指定されたファイルに書き込みます。

$ cmctl x create csr -f my-cert.yaml my-req

cert-managerは、CertificateSigningRequestを自動的に承認しません。クラスタでカスタム承認者を実行していない場合は、CertificateSigningRequestを手動で承認する必要がある可能性があります。

$ kubectl certificate approve <name>

このコマンドは、`-w, --fetch-certificate`フラグを使用して、CertificateSigningRequestが署名されるのを待つこともできます。署名されると、結果として得られた署名付き証明書がローカルファイル`.crt`、または`-c, --output-certificate-file`で指定されたファイルに書き込まれます。

$ cmctl x create csr -f my-cert.yaml my-req -w

インストール

cmctl x install

このコマンドは、必要な`CustomResourceDefinitions`がcert-manager、cainjector、webhookコンポーネントと共にインストールされていることを確認します。内部的には、Helmインストール手順と同様の手順が使用されます。

`cmctl x install`を使用して、cert-managerのインストールをカスタマイズすることもできます。

以下の例は、デフォルトのHelm値をオーバーライドしてcert-managerのインストールを調整する方法を示しています。

cmctl x install \
    --set prometheus.enabled=false \  # Example: disabling prometheus using a Helm parameter
    --set webhook.timeoutSeconds=4s   # Example: changing the wehbook timeout using a Helm parameter

cert-managerのArtifactHubページでインストールパラメータの完全なリストを確認できます。これらは、Helmチャートを使用する場合に使用できるパラメータと同じです。cert-managerをデプロイしたら、インストールを確認できます。

CLIを使用すると、マニフェストをクラスタにインストールする代わりに、テンプレート化されたマニフェストを`stdout`に出力することもできます。

cmctl x install --dry-run > cert-manager.custom.yaml

アンインストール

cmctl x uninstall

このコマンドは、Helmで管理されているcert-managerのリリースをアンインストールします。

cmctl `v2.0.0`以降、アンインストールコマンドは安全であり、デフォルトではCRDを削除しません。これは、v1.15.0より前のcert-manager Helmチャート（`--set installCRDs=true`オプションを使用）でインストールされた場合でも同様です。cert-manager v1.15.0以降、Helmチャートをアンインストールする際に、デフォルトではCRDは削除されません。

🕐 `v2.0.0`より前では、cmctlは、Helmチャートでインストールされた場合、CRDを削除していました（Helmの動作と同様）。

`helm uninstall`でサポートされている機能のほとんどはこのコマンドでもサポートされています。

使用例

cmctl x uninstall


cmctl x uninstall --namespace my-cert-manager


cmctl x uninstall --dry-run

アップグレード

cert-managerのアップグレードを支援するツール

$ cmctl upgrade --help
APIバージョンの移行

このコマンドは、cert-manager `v1`より前に作成されたcert-managerインストールを、cert-managerバージョン`v1.6`以降にアップグレードするための準備に使用できます。これにより、非推奨のAPIバージョンでetcdに保存されているcert-managerカスタムリソースが`v1`に移行されます。非推奨APIリソースの移行の詳細を参照してください。

$ cmctl upgrade migrate-api-version --qps 5 --burst 10

kubectlプラグイン

kubectl 1.26以降、kubectlプラグインは自動補完をサポートしています。つまり、スタンドアロンのcmctlバイナリとkubectlプラグインで同じ操作性が得られます。

プラグインをインストールするには、使用しているプラットフォーム用のkubectl_cert-managerファイルが必要です。これらのファイルは、当社のcmctl GitHubリリースページで見つけることができます。kubectlプラグインを使用するには、そのバイナリがkubectl-cert_managerという名前で$PATHにアクセス可能である必要があります。

kubectl cert-manager helpを実行して、プラグインが正しく設定されていることを確認できます。

kubectlプラグインでの自動補完

kubectl 1.26以降、プラグインの自動補完を有効にすることができます。kubectl_cert-managerを/usr/local/binにインストールした場合、次のコマンドを実行して自動補完を設定できます。

cat >kubectl_complete-cert_manager <<'EOF'
#!/usr/bin/env sh
kubectl cert-manager __complete "$@"
EOF
sudo install kubectl_complete-cert_manager /usr/local/bin