Kubectlプラグイン ================= CloudNativePGは、Kubernetesでクラスターを管理するための\ ``kubectl`` のプラグインを提供します。 インストール ------------ さまざまな方法を使用して\ ``cnpg`` プラグインをインストールできます。 .. Note:: エアギャップシステムの場合、以前にダウンロードしたファイルを使用して、パッケージマネージャーを介したインストールが良いオプションである場合があります。 インストールスクリプトを介して ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code:: sh curl -sSfL \ https://github.com/cloudnative-pg/cloudnative-pg/raw/main/hack/install-cnpg-plugin.sh | \ sudo sh -s -- -b /usr/local/bin DebianまたはRedHatパッケージを使用する ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ `releases section of the GitHub repository `_ では、関心のあるリリースCloudNativePGオペレーターと同じまたは新しいリリースを選択してくださいに移動できます。その中には **Assets** セクションがあります。そのセクションには、さまざまなシステム用の事前ビルドパッケージが含まれています。その結果、標準の手順と手順に従って、システムにインストールできます。 Debianパッケージ ^^^^^^^^^^^^^^^^ たとえば、Intelベースの64ビットサーバーの場合、プラグインの1.22.2リリースをインストールしてみましょう。最初に、適切な\ ``.deb`` ファイルをダウンロードします。 .. code:: sh $ wget https://github.com/cloudnative-pg/cloudnative-pg/releases/download/v1.22.1/kubectl-cnpg_1.22.2_linux_x86_64.deb 次に、 ``dpkg`` を使用してローカルファイルからインストールします。 .. code:: sh $ dpkg -i kubectl-cnpg_1.22.2_linux_x86_64.deb (Reading database ... 702524 files and directories currently installed.) Preparing to unpack kubectl-cnpg_1.22.2_linux_x86_64.deb ... Unpacking cnpg (1.22.2) over (1.22.2) ... Setting up cnpg (1.22.2) .. RPMパッケージ ^^^^^^^^^^^^^ ``.deb`` パッケージの例と同様に、Intel 64ビットマシンの1.22.2リリースをインストールしましょう。ファイル名を提供する\ ``--output`` フラグに注意してください。 .. code:: sh curl -L https://github.com/cloudnative-pg/cloudnative-pg/releases/download/v1.22.2/kubectl-cnpg_1.22.2_linux_x86_64.rpm \ --output kube-plugin.rpm 次に、 ``yum`` でインストールすると、使用する準備が整います。 .. code:: sh $ yum --disablerepo=* localinstall kube-plugin.rpm yum --disablerepo=* localinstall kube-plugin.rpm Failed to set locale, defaulting to C.UTF-8 Dependencies resolved. ==================================================================================================== Package Architecture Version Repository Size ==================================================================================================== Installing: cnpg x86_64 1.22.2-1 @commandline 17 M Transaction Summary ==================================================================================================== Install 1 Package Total size: 14 M Installed size: 43 M Is this ok [y/N]: y Krewを使用する ^^^^^^^^^^^^^^ `Krew `_ を既にインストールしている場合は、単に実行できます。 .. code:: sh kubectl krew install cnpg プラグインの新しいバージョンがリリースされたら、次の方法で既存のインストールを更新できます。 .. code:: sh kubectl krew update kubectl krew upgrade cnpg Homebrewを使用する ^^^^^^^^^^^^^^^^^^ .. Note:: Homebrewコミュニティが `kubectl-cnpg plugin on Homebrew `_ の可用性を管理していることに注意してください。 `Homebrew `_ を既にインストールしている場合は、単に実行できます。 .. code:: sh brew install kubectl-cnpg プラグインの新しいバージョンがリリースされたら、次の方法で既存のインストールを更新できます。 .. code:: sh brew update brew upgrade kubectl-cnpg .. Note:: kubectlプラグインのオートコンプリートは、既にHomebrewによって管理されています。以下で説明する`kubectl_complete-cnpg` スクリプトを作成する必要はありません。 サポートされているアーキテクチャ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ CloudNativePGプラグインは、現在次のオペレーティングシステムとアーキテクチャ用にビルドされています。 - Linux *amd64* arm 5/6/7 *arm64* s390x \* ppc64le - macOS *amd64* arm64 - Windows *386* amd64 *arm 5/6/7* arm64 オートコンプリートの設定 ^^^^^^^^^^^^^^^^^^^^^^^^ プラグインのオートコンプリートを構成するには、ヘルパーシェルスクリプトを現在のPATHにインストールする必要があります。後者に\ ``/usr/local/bin`` が含まれていると仮定すると、これは次のコマンドで実行できます。 .. code:: shell cat > kubectl_complete-cnpg < .. Note:: プラグインは、標準出力チャンネルが端末に接続されているかどうかを自動的に検出します。このような場合、ANSIカラーをコマンド出力に追加する場合があります。色を無効にするには、コマンドで`--color=never` オプションを使用します。 ### インストールマニフェストの生成 ``cnpg`` プラグインを使用して、オペレーターのインストールのためのYAMLマニフェストを生成できます。このオプションは通常、レプリカの数、インストール名前空間、監視する名前空間などのデフォルト構成をオーバーライドする場合に使用されます。 詳細および使用可能なオプションについては、次を実行します。 .. code:: shell kubectl cnpg install generate --help 主なオプションは次のとおりです。 - ``-n`` オペレーターをインストールする名前空間デフォルトでは ``cnpg-system`` - ``--replicas`` 展開内のレプリカの数 - ``--version`` ``1.17`` など、インストールされるオペレーターのマイナーバージョン。マイナーバージョンが指定された場合、プラグインはそのマイナーバージョンの最新のパッチバージョンをインストールします。バージョンが指定されない場合、プラグインはオペレーターの最新の\ ``MAJOR.MINOR.PATCH`` バージョンをインストールします。 - ``--watch-namespace`` 監視する名前空間を含むコンマ区切りの文字列デフォルトではすべての名前空間 オペレーターをインストールするYAMLマニフェストを生成する\ ``generate`` コマンドの例は、次のとおりです。 .. code:: shell kubectl cnpg install generate \ -n king \ --version 1.17 \ --replicas 3 \ --watch-namespace "albert, bb, freddie" \ > operator.yaml 上記のコマンドのフラグは、次の意味を持っています。 - ``-n king`` CNPGオペレーターを\ ``king`` 名前空間にインストールします - ``--version 1.17`` マイナーバージョン1.17の最新パッチバージョンをインストールします - ``--replicas 3`` 3つのレプリカを使用してオペレーターをインストールします - ``--watch-namespace "albert, bb, freddie"`` は、オペレーターに\ ``albert`` 、\ ``bb`` 、および\ ``freddie`` 名前空間の変更のみを監視させます ステータス ^^^^^^^^^^ ``status`` コマンドは、クラスターの現在のステータスの概要を提供します。 - **一般情報** クラスターの名前、PostgreSQLのシステムID、インスタンス数、現在のタイムライン、WAL内の位置 - **backup** リカバリー可能ポイント、およびプライマリまたはレプリカクラスターの場合は指定されたプライマリから\ ``pg_stat_archiver`` ビューによって返されるWALアーカイブステータス - **ストリーミングレプリケーション** プライマリインスタンスの\ ``pg_stat_replication`` ビューから直接取得した情報 - **instances** 各Postgresインスタンスに関する情報、各インスタンスマネージャーによって直接取得されます。スタンバイの場合、\ ``Current LSN`` フィールドは、リカバリー中に再生された最新のログ先行書き込みの場所リプレイLSNに対応します。 .. Important:: 上記のステータス情報は、異なる時間に異なる場所で取得されたため、わずかに一貫性のない戻り値が発生します。たとえば、メインヘッダーの`Current Write LSN` 場所は、2つの異なる時間間隔で取得されるため、インスタンスステータスの`Current LSN` フィールドとは異なる場合があります。 .. code:: shell kubectl cnpg status sandbox .. code:: shell Cluster in healthy state Name: sandbox Namespace: default System ID: 7039966298120953877 PostgreSQL Image: ghcr.io/cloudnative-pg/postgresql:16.3 Primary instance: sandbox-2 Instances: 3 Ready instances: 3 Current Write LSN: 3AF/EAFA6168 (Timeline: 8 - WAL File: 00000008000003AF00000075) Continuous Backup status First Point of Recoverability: Not Available Working WAL archiving: OK Last Archived WAL: 00000008000003AE00000079 @ 2021-12-14T10:16:29.340047Z Last Failed WAL: - Certificates Status Certificate Name Expiration Date Days Left Until Expiration - --------------- --------------- -------------------------- cluster-example-ca 2022-05-05 15:02:42 +0000 UTC 87.23 cluster-example-replication 2022-05-05 15:02:42 +0000 UTC 87.23 cluster-example-server 2022-05-05 15:02:42 +0000 UTC 87.23 Streaming Replication status Name Sent LSN Write LSN Flush LSN Replay LSN Write Lag Flush Lag Replay Lag State Sync State Sync Priority - --- -------- --------- --------- ---------- --------- --------- ---------- ----- ---------- ------------- sandbox-1 3AF/EB0524F0 3AF/EB011760 3AF/EAFEDE50 3AF/EAFEDE50 00:00:00.004461 00:00:00.007901 00:00:00.007901 streaming quorum 1 sandbox-3 3AF/EB0524F0 3AF/EB030B00 3AF/EB030B00 3AF/EB011760 00:00:00.000977 00:00:00.004194 00:00:00.008252 streaming quorum 1 Instances status Name Database Size Current LSN Replication role Status QoS Manager Version - --- ------------- ----------- ---------------- ------ --- --------------- sandbox-1 302 GB 3AF/E9FFFFE0 Standby (sync) OK Guaranteed 1.11.0 sandbox-2 302 GB 3AF/EAFA6168 Primary OK Guaranteed 1.11.0 sandbox-3 302 GB 3AF/EBAD5D18 Standby (sync) OK Guaranteed 1.11.0 ``--verbose`` または\ ``-v`` だけを追加することにより、ステータスのより詳細なバージョンを取得することもできます。 .. code:: shell kubectl cnpg status sandbox --verbose .. code:: shell Cluster in healthy state Name: sandbox Namespace: default System ID: 7039966298120953877 PostgreSQL Image: ghcr.io/cloudnative-pg/postgresql:16.3 Primary instance: sandbox-2 Instances: 3 Ready instances: 3 Current Write LSN: 3B1/61DE3158 (Timeline: 8 - WAL File: 00000008000003B100000030) PostgreSQL Configuration archive_command = /controller/manager wal-archive --log-destination /controller/log/postgres.json %p archive_mode = on archive_timeout = 5min checkpoint_completion_target = 0.9 checkpoint_timeout = 900s cluster_name = sandbox dynamic_shared_memory_type = sysv full_page_writes = on hot_standby = true jit = on listen_addresses = * log_autovacuum_min_duration = 1s log_checkpoints = on log_destination = csvlog log_directory = /controller/log log_filename = postgres log_lock_waits = on log_min_duration_statement = 1000 log_rotation_age = 0 log_rotation_size = 0 log_statement = ddl log_temp_files = 1024 log_truncate_on_rotation = false logging_collector = on maintenance_work_mem = 2GB max_connections = 1000 max_parallel_workers = 32 max_replication_slots = 32 max_wal_size = 15GB max_worker_processes = 32 pg_stat_statements.max = 10000 pg_stat_statements.track = all port = 5432 shared_buffers = 16GB shared_memory_type = sysv shared_preload_libraries = pg_stat_statements ssl = on ssl_ca_file = /controller/certificates/client-ca.crt ssl_cert_file = /controller/certificates/server.crt ssl_key_file = /controller/certificates/server.key synchronous_standby_names = ANY 1 ("sandbox-1","sandbox-3") unix_socket_directories = /controller/run wal_keep_size = 512MB wal_level = logical wal_log_hints = on cnpg.config_sha256 = 3cfa683e23fe513afaee7c97b50ce0628e0cc634bca8b096517538a9a4428efc PostgreSQL HBA Rules # Grant local access local all all peer map=local # Require client certificate authentication for the streaming_replica user hostssl postgres streaming_replica all cert hostssl replication streaming_replica all cert hostssl all cnpg_pooler_pgbouncer all cert # Otherwise use the default authentication method host all all all scram-sha-256 Continuous Backup status First Point of Recoverability: Not Available Working WAL archiving: OK Last Archived WAL: 00000008000003B00000001D @ 2021-12-14T10:20:42.272815Z Last Failed WAL: - Streaming Replication status Name Sent LSN Write LSN Flush LSN Replay LSN Write Lag Flush Lag Replay Lag State Sync State Sync Priority - --- -------- --------- --------- ---------- --------- --------- ---------- ----- ---------- ------------- sandbox-1 3B1/61E26448 3B1/61DF82F0 3B1/61DF82F0 3B1/61DF82F0 00:00:00.000333 00:00:00.000333 00:00:00.005484 streaming quorum 1 sandbox-3 3B1/61E26448 3B1/61E26448 3B1/61DF82F0 3B1/61DF82F0 00:00:00.000756 00:00:00.000756 00:00:00.000756 streaming quorum 1 Instances status Name Database Size Current LSN Replication role Status QoS Manager Version - --- ------------- ----------- ---------------- ------ --- --------------- sandbox-1 3B1/610204B8 Standby (sync) OK Guaranteed 1.11.0 sandbox-2 3B1/61DE3158 Primary OK Guaranteed 1.11.0 sandbox-3 3B1/62618470 Standby (sync) OK Guaranteed 1.11.0 このコマンドは、 ``yaml`` および\ ``json`` 形式での出力もサポートしています。 プロモート ^^^^^^^^^^ このコマンドの意味は、クラスター内のポッドをプライマリに\ ``promote`` することにより、メンテナンス作業を開始したり、クラスターでのスイッチオーバー状況をテストしたりできます .. code:: shell kubectl cnpg promote cluster-example cluster-example-2 または、インスタンスノード番号を使用してプロモートせることができます .. code:: shell kubectl cnpg promote cluster-example 2 証明書 ^^^^^^ CloudNativePGオペレーターを使用して作成されたクラスターは、CAと連携してTLS認証証明書に署名します。 証明書を取得するには、資格情報を保存するシークレットの名前、クラスター名、およびこの証明書のユーザーを提供する必要があります .. code:: shell kubectl cnpg certificate cluster-cert --cnpg-cluster cluster-example --cnpg-user appuser シークレットが作成された後、 ``kubectl`` を使用して取得できます .. code:: shell kubectl get secret cluster-cert また、次のコマンドを使用してプレーンテキストで同じ内容を取得します。 .. code:: shell kubectl get secret cluster-cert -o json | jq -r .data | map(@base64d) | .[] 再起動 ^^^^^^ ``kubectl cnpg restart`` コマンドは、次の2つの場合に使用できます。 - 特定のクラスターのロールアウト再起動を調整するようにオペレーターに要求します。これは、カスタム監視クエリを含むConfigMapなどのクラスター依存オブジェクトに構成変更を適用する場合に役立ちます。 - 単一インスタンスの再起動を要求します。インスタンスがクラスターのプライマリの場合はインプレース、またはレプリカの場合はポッドの削除と再作成。 .. code:: shell # this command will restart a whole cluster in a rollout fashion kubectl cnpg restart [clusterName] # this command will restart a single instance, according to the policy above kubectl cnpg restart [clusterName] [pod] インプレース・リスタートが要求されたが、スイッチオーバーなしでは変更を適用できない場合、スイッチオーバーはインプレース・リスタートより優先されます。この一般的なケースは、PostgreSQLイメージのマイナーアップグレードです。 .. Note:: ConfigMapsとSecretsをインスタンスによって**自動的に**リロードしたい場合は、キー`cnpg.io/reload` を持つラベルをそれに追加できます。 リロード ^^^^^^^^ ``kubectl cnpg reload`` コマンドは、オペレーターに、特定のクラスターの調整ループをトリガーするように要求します。これは、カスタム監視クエリを含むConfigMapなどのクラスター依存オブジェクトに構成変更を適用する場合に役立ちます。 次のコマンドは、特定のクラスターのすべての構成をリロードします。 .. code:: shell kubectl cnpg reload [cluster_name] メンテナンス ^^^^^^^^^^^^ ``kubectl cnpg maintenance`` コマンドは、名前空間全体で1つ以上のクラスターを変更し、メンテナンスウィンドウ値を設定するのに役立ちます。次のフィールドを変更します。 - .spec.nodeMaintenanceWindow.inProgress - .spec.nodeMaintenanceWindow.reusePVC これを使用して\ ``set`` および\ ``unset`` を引数として受け入れ、\ ``set`` の場合は\ ``inProgress`` を\ ``true`` に設定し、\ ``unset`` の場合は\ ``false`` に設定します。 デフォルトでは、 ``--reusePVC`` フラグが渡されない限り、 ``reusePVC`` は常に\ ``false`` に設定されます。 プラグインは、変更するクラスターのリストとその新しい値の確認を求めます。これが受け入れられる場合、このアクションはリスト内のすべてのクラスターに適用されます。 Kubernetesクラスター内のすべてのPostgreSQLをメンテナンスに設定する場合は、次のコマンドを記述するだけです。 .. code:: shell kubectl cnpg maintenance set --all-namespaces 更新するすべてのクラスターのリストが得られます .. code:: shell The following are the new values for the clusters Namespace Cluster Name Maintenance reusePVC - -------- ------------ ----------- -------- default cluster-example true false default pg-backup true false test cluster-example true false Do you want to proceed? [y/n]: y レポート ^^^^^^^^ ``kubectl cnpg report`` コマンドは、さまざまな情報をZIPファイルにバンドルします。実稼働環境のクラスターの問題をデバッグするために必要なコンテキストを提供することを目的としています。 ``operator`` および\ ``cluster`` の2つのサブコマンドがあります。 レポート演算子 ^^^^^^^^^^^^^^ ``operator`` サブコマンドは、オペレーターの展開、構成、およびイベントに関する情報の提供をオペレーターに要求します。 .. Important:: SecretsとConfigMapのすべての機密情報は編集されています。データマップには**キー**が表示されますが、値は空になります。フラグ`-S` / `--stopRedaction` は、リダクションを無効にし、値を表示します。自己の責任でのみ使用します。これはプライベートデータを共有します。 .. Note:: デフォルトでは、オペレーターログは収集されませんが、 `--logs` フラグを使用してオペレーターログ収集を有効にできます - **展開情報** オペレーター展開とオペレーターポッド - **configuration** オペレーター名前空間のシークレットとConfigMap - **events** オペレーター名前空間のイベント - **webhook configuration** Webhook構成の変更および検証 - **webhook service** Webhookサービス - **logs** JSON行形式のオペレーターポッドのログオプショナル、デフォルトではオフ このコマンドは、YAML形式のさまざまなマニフェストを含むZIPファイルを生成しますデフォルトでは、 ``-o`` フラグを使用してJSONに設定可能です。 ``-f`` フラグを使用して、結果ファイルに明示的に名前を付けます。 ``-f`` フラグを使用しない場合、zipファイルにデフォルトのタイムスタンプ付きファイル名が作成されます。 .. Note:: Reportプラグインは`kubectl` 規約に従い、名前空間によって制限されたオブジェクトを検索します。 CNPGオペレーターは、通常、クラスターと同じ名前空間にインストールされません。例デフォルトのインストール名前空間はcnpg-systemです .. code:: shell kubectl cnpg report operator -n での結果 .. code:: shell Successfully written report to "report_operator_.zip" (format: "yaml") ``-f`` フラグを設定した場合 .. code:: shell kubectl cnpg report operator -n -f reportRedacted.zip ファイルを解凍すると、タイムスタンプ付きのトップレベルフォルダーが生成され、ディレクトリを整理します。 .. code:: shell unzip reportRedacted.zip 結果は次のとおりです。 .. code:: shell Archive: reportRedacted.zip creating: report_operator_/ creating: report_operator_/manifests/ inflating: report_operator_/manifests/deployment.yaml inflating: report_operator_/manifests/operator-pod.yaml inflating: report_operator_/manifests/events.yaml inflating: report_operator_/manifests/validating-webhook-configuration.yaml inflating: report_operator_/manifests/mutating-webhook-configuration.yaml inflating: report_operator_/manifests/webhook-service.yaml inflating: report_operator_/manifests/cnpg-ca-secret.yaml inflating: report_operator_/manifests/cnpg-webhook-cert.yaml ``--logs`` オプションをアクティブにすると、追加のサブディレクトリが表示されます。 .. code:: shell Archive: report_operator_.zip creating: report_operator_/operator-logs/ inflating: report_operator_/operator-logs/cnpg-controller-manager-66fb98dbc5-pxkmh-logs.jsonl .. Note:: プラグインは、 PREVIOUSオペレーターのログを取得しようとします。これは、再起動されたオペレーターを調査するときに役立ちます。すべての場合、現在のオペレーターログも取得しようとします。現在と以前のログが利用可能な場合、両方が表示されます。 .. code:: json ====== Begin of Previous Log ===== 2023-03-28T12:56:41.251711811Z {"level":"info","ts":"2023-03-28T12:56:41Z","logger":"setup","msg":"Starting CloudNativePG Operator","version":"1.19.1","build":{"Version":"1.19.0+dev107","Commit":"cc9bab17","Date":"2023-03-28"}} 2023-03-28T12:56:41.251851909Z {"level":"info","ts":"2023-03-28T12:56:41Z","logger":"setup","msg":"Starting pprof HTTP server","addr":"0.0.0.0:6060"} ====== End of Previous Log ===== 2023-03-28T12:57:09.854306024Z {"level":"info","ts":"2023-03-28T12:57:09Z","logger":"setup","msg":"Starting CloudNativePG Operator","version":"1.19.1","build":{"Version":"1.19.0+dev107","Commit":"cc9bab17","Date":"2023-03-28"}} 2023-03-28T12:57:09.854363943Z {"level":"info","ts":"2023-03-28T12:57:09Z","logger":"setup","msg":"Starting pprof HTTP server","addr":"0.0.0.0:6060"} オペレーターが再起動されていない場合、\ ``====== Begin …`` および\ ``====== End …`` ガードが表示されますが、中にコンテンツはありません。 機密情報がデフォルトで編集されていることを確認できます。 .. code:: shell cd report_operator_/manifests/ head cnpg-ca-secret.yaml .. code:: yaml data: ca.crt: "" ca.key: "" metadata: creationTimestamp: "2022-03-22T10:42:28Z" managedFields: - apiVersion: v1 fieldsType: FieldsV1 fieldsV1: ``-S`` ``--stopRedaction`` オプションを有効にすると、シークレットが表示されます。 .. code:: shell kubectl cnpg report operator -n -f reportNonRedacted.zip -S 機密情報を表示しようとしていることを示すリマインダーが届きます。 .. code:: shell WARNING: secret Redaction is OFF. Use it with caution Successfully written report to "reportNonRedacted.zip" (format: "yaml") .. code:: shell unzip reportNonRedacted.zip head cnpg-ca-secret.yaml .. code:: yaml data: ca.crt: LS0tLS1CRUdJTiBD… ca.key: LS0tLS1CRUdJTiBF… metadata: creationTimestamp: "2022-03-22T10:42:28Z" managedFields: - apiVersion: v1 fieldsType: FieldsV1 レポートクラスター ^^^^^^^^^^^^^^^^^^ ``cluster`` サブコマンドは、以下を収集します。 - **クラスターリソース** クラスター情報、\ ``kubectl get cluster -o yaml`` と同じ - **クラスターポッド** クラスター名と一致するクラスター名前空間内のポッド - **クラスタージョブ** クラスター名と一致するクラスター名前空間内のジョブがある場合 - **events** クラスター名前空間のイベント - **pod logs** JSON行形式のクラスターポッドのログオプショナル、デフォルトでオフ - **ジョブログ** ジョブによって作成されたポッドのログオプショナル、デフォルトでオフJSON行形式で ``cluster`` サブコマンドは、 ``operator`` が行うように、\ ``-f`` および\ ``-o`` フラグを受け入れます。 ``-f`` フラグを使用しない場合、デフォルトのタイムスタンプ付きレポート名が使用されます。クラスター情報には構成シークレット/構成マップが含まれていないため、 ``-S`` は無効になっていることに注意してください。 .. Note:: デフォルトでは、クラスターログは収集されませんが、 `--logs` フラグを使用してクラスターログ収集を有効にできます 使用法 .. code:: shell kubectl cnpg report cluster [flags] ``operator`` サブコマンドとは異なり、 ``cluster`` サブコマンドの場合、クラスターがデフォルトの場合を除き、クラスター名前と、多くの場合、名前空間を指定する必要があることに注意してください。 .. code:: shell kubectl cnpg report cluster example -f report.zip -n example_namespace そして .. code:: shell unzip report.zip .. code:: shell Archive: report.zip creating: report_cluster_example_/ creating: report_cluster_example_/manifests/ inflating: report_cluster_example_/manifests/cluster.yaml inflating: report_cluster_example_/manifests/cluster-pods.yaml inflating: report_cluster_example_/manifests/cluster-jobs.yaml inflating: report_cluster_example_/manifests/events.yaml ``--logs`` フラグを使用して、ポッドとジョブログをZIPに追加できることに注意してください。 .. code:: shell kubectl cnpg report cluster example -n example_namespace --logs 結果は次のとおりです。 .. code:: shell Successfully written report to "report_cluster_example_.zip" (format: "yaml") .. code:: shell unzip report_cluster_.zip .. code:: shell Archive: report_cluster_example_.zip creating: report_cluster_example_/ creating: report_cluster_example_/manifests/ inflating: report_cluster_example_/manifests/cluster.yaml inflating: report_cluster_example_/manifests/cluster-pods.yaml inflating: report_cluster_example_/manifests/cluster-jobs.yaml inflating: report_cluster_example_/manifests/events.yaml creating: report_cluster_example_/logs/ inflating: report_cluster_example_/logs/cluster-example-full-1.jsonl creating: report_cluster_example_/job-logs/ inflating: report_cluster_example_/job-logs/cluster-example-full-1-initdb-qnnvw.jsonl inflating: report_cluster_example_/job-logs/cluster-example-full-2-join-tvj8r.jsonl ログ ^^^^ ``kubectl cnpg logs`` コマンドを使用すると、CloudNativePGに関連するポッドのコレクションのログを一度にたどることができます。 現時点では、使用可能なサブコマンドが1つあります\ ``cluster`` 。 クラスターログ ^^^^^^^^^^^^^^ ``cluster`` サブコマンドは、クラスターのすべてのポッドログを単一のストリームまたはファイルに収集します。これは、単一のターミナルウィンドウで、コマンドを1回呼び出して、すべてのポッドログを取得できることを意味します。 すべてのcnpgプラグインサブコマンドと同様に、\ ``-h`` フラグの指示とヘルプを取得できます。 ``kubectl cnpg logs cluster -h`` ``logs`` コマンドは、 ``--timestamps`` フラグを使用しない限り、JSON行形式でログを表示します。その場合、人間が判読可能なタイムスタンプが各行の先頭に追加されます。この場合、行は有効なJSONでなくなり、 ``jq`` などのツールが目的のように動作しない場合があります。 ``logs cluster`` サブコマンドに\ ``-f`` フラグ別名\ ``--follow`` が指定されている場合、クラスターポッドログをたどり、コマンドが呼び出された後にクラスターで作成された新しいポッドを監視します。再起動または再作成されたポッドを含む、見つかった新しいポッドもポッドが追跡されます。ログは端末の標準出力に表示されます。このコマンドは、クラスターにポッドが残っていない場合、またはユーザーによって中断された場合にのみ終了します。 ``-f`` オプションを指定せずに\ ``logs`` が呼び出された場合、呼び出されるまですべてのクラスターポッドからログを読み取り、ターミナルの標準出力に表示してから終了します。 ``-o`` または\ ``--output`` フラグを提供して、標準出力で表示する代わりに、ログを保存するファイルの名前を指定できます。 ``--tail`` フラグを使用して、クラスター内の各ポッドから取得するログ行数を指定できます。デフォルトでは、 ``logs cluster`` サブコマンドは、クラスター内の各ポッドからのすべてのログを表示します。 「follow」フラグ\ ``-f`` と組み合わせると、\ ``--tail`` で指定された数のログが現在まで取得され、それ以降新しいログが追跡されます。 注他の\ ``cnpg`` プラグインコマンドとは異なり、 ``-f`` はファイルを指定するのではなく「フォロー」を示すために使用されます。これは、 ``kubectl logs`` の規則に従いますが、 ``-f`` は、ログに従う必要があることを意味します。 使用法 .. code:: shell kubectl cnpg logs cluster [flags] ``-f`` オプションを使用して次のことを行います。 .. code:: shell kubectl cnpg report cluster cluster-example -f ``--tail`` オプションを使用して各ポッドから3行を表示し、 ``-f`` オプションを追跡します。 .. code:: shell kubectl cnpg report cluster cluster-example -f --tail 3 .. code:: json {"level":"info","ts":"2023-06-30T13:37:33Z","logger":"postgres","msg":"2023-06-30 13:37:33.142 UTC [26] LOG: ending log output to stderr","source":"/controller/log/postgres","logging_pod":"cluster-example-3"} {"level":"info","ts":"2023-06-30T13:37:33Z","logger":"postgres","msg":"2023-06-30 13:37:33.142 UTC [26] HINT: Future log output will go to log destination \"csvlog\".","source":"/controller/log/postgres","logging_pod":"cluster-example-3"} … … ``-o`` オプションを省略し、\ ``--output`` を指定する場合 .. code:: sh kubectl cnpg logs cluster cluster-example --output my-cluster.log Successfully written logs to "my-cluster.log" デストロイ ^^^^^^^^^^ ``kubectl cnpg destroy`` コマンドは、インスタンスと、関連するすべてのPVCをKubernetesクラスターから削除するのに役立ちます。 オプションの\ ``--keep-pvc`` フラグを指定すると、PVCを保持したまま、インスタンスによって設定されたすべての\ ``metadata.ownerReferences`` を削除できます。さらに、PVCの\ ``cnpg.io/pvcStatus`` ラベルが\ ``ready`` から\ ``detached`` に変更され、使用されなくなったことを示します。 ``--keep-pvc`` フラグを指定せずにコマンドを再度実行すると、分離されたPVCが削除されます。 使用法 :: kubectl cnpg destroy [CLUSTER_NAME] [INSTANCE_ID] 次の例は、\ ``cluster-example-2`` ポッドと関連するPVCを削除します。 :: kubectl cnpg destroy cluster-example 2 クラスターハイバーネーション ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ データを保持しながらCloudNativePG ``Cluster`` の実行を一時停止し、後でアクティビティを再開することが必要になる場合があります。この機能を **クラスターハイバーネーション** と呼びます。 ハイバネーションは、 ``kubectl cnpg hibernate [on|off]`` コマンドを介してのみ使用できます。 CloudNativePGクラスターを休止するとは、 PostgreSQLプライマリインスタンスに属するPVCを除き、クラスターによって生成されたすべてのリソースを破棄することを意味します。 次の方法でクラスターを休止状態にできます。 :: kubectl cnpg hibernate on これにより、 1. すべてのPostgreSQLインスタンスをシャットダウンする 2. プライマリインスタンスのデータを含むPVCを切断し、最新のデータベースステータスと最新のクラスター構成でアノテーションを付けます。 3. 生成されたすべてのリソースを含む\ ``Cluster`` リソースを削除します-前述のPVCを除く Hybernationしている場合、CloudNativePGクラスターはPVCのグループだけで表され、\ ``PGDATA`` を含むものには、\ ``pg_controldata`` のコンテンツを含む最新の利用可能なステータスで注釈が付けられます。 .. Warning:: フェンシングもハイバーネーションプロシージャの一部であるため、フェンスされたインスタンスを持つクラスターはHybernationできません。 エラーが発生した場合、オペレーターはプロシージャーを元に戻すことはできません。次のコマンドを使用して操作を強制できます。 :: kubectl cnpg hibernate on cluster-example --force 休止状態のクラスターは、次の方法で再開できます。 :: kubectl cnpg hibernate off クラスターが休止状態になると、最後の構成と、シャットダウン後にPostgreSQLのステータスを表示できます。それは次の方法で行うことができます。 :: kubectl cnpg hibernate status pgbenchを使用したデータベースのベンチマーク ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Pgbenchは、次のコマンドを使用して、既存のPostgreSQLクラスターに対して実行できます。 :: kubectl cnpg pgbench -- --time 30 --client 1 --jobs 1 詳細については、 :ref:`Benchmarking pgbench section <ベンチマーク>` を参照してください。 fioを使用したストレージのベンチマーク ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ fioは、次のコマンドを使用して既存のストレージクラスで実行できます。 :: kubectl cnpg fio -n 詳細については、 :ref:`Benchmarking fio section <ベンチマーク>` を参照してください。 新しい物理バックアップの要求 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ``kubectl cnpg backup`` コマンドは、新しい\ ``Backup`` リソースを作成することにより、既存のPostgresクラスターの新しい物理バックアップを要求します。 次の例は、特定のクラスターのオンデマンドバックアップを要求します。 .. code:: shell kubectl cnpg backup [cluster_name] または、ボリュームスナップショットを使用する場合 .. code:: shell kubectl cnpg backup [cluster_name] -m volumeSnapshot 作成されるバックアップには、要求時間に基づいた名前が付けられます。 .. code:: shell kubectl cnpg backup cluster-example backup/cluster-example-20230121002300 created デフォルトでは、新しく作成されるバックアップは、クラスターで定義されたバックアップターゲットポリシーを使用して、実行するインスタンスを選択します。ただし、このポリシーは\ ``--backup-target`` オプションでオーバーライドできます。 ボリュームスナップショットバックアップの場合、 ``--online`` オプションを使用して、オンライン/ホットバックアップまたはオフライン/コールドバックアップを要求することもできます。さらに、 ``--immediate-checkpoint`` および\ ``--wait-for-archive`` オプションを明示的に設定することにより、オンラインバックアップを調整することもできます。 :ref:`付録A-バックアップ用の共通オブジェクトストア <付録A-バックアップ用の共通オブジェクトストア>` には、構成設定に関する詳細情報が含まれています。 psqlの起動 ^^^^^^^^^^ ``kubectl cnpg psql`` コマンドは、実際のポッドから実行しているかのように、既存のPostgresクラスターに接続された新しいPostgreSQL対話型フロントエンドプロセス psqlを起動します。これは、 ``postgres`` ユーザーを使用することを意味します。 .. Important:: `postgres` ユーザーとして接続するため、運用環境では、この方法は許可された担当者のみが細心の注意を払って使用する必要があります。 .. code:: shell kubectl cnpg psql cluster-example psql (16.3 (Debian 16.3-1.pgdg110+1)) Type "help" for help. postgres=# デフォルトでは、コマンドはプライマリインスタンスに接続します。ユーザーは\ ``--replica`` オプションを使用して、レプリカに対して作業することを選択できます。 .. code:: shell kubectl cnpg psql --replica cluster-example psql (16.3 (Debian 16.3-1.pgdg110+1)) Type "help" for help. postgres=# select pg_is_in_recovery(); pg_is_in_recovery - ------------------ t (1 row) postgres=# \q このコマンドは\ ``kubectl exec`` を起動します。正常に動作するには、\ ``PATH`` 変数で\ ``kubectl`` 実行可能ファイルに到達できる必要があります。 Postgresクラスターのスナップショット ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. Warning:: `kubectl cnpg snapshot` コマンドは削除されました。 :ref:`付録A-バックアップ用の共通オブジェクトストア <付録A-バックアップ用の共通オブジェクトストア>` を使用して、ボリュームスナップショットを使用したバックアップを要求してください。 評価/デモ目的でのみpgAdmin4を使用する ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ `pgAdmin `_ は、PostgreSQLの最も人気のある機能が豊富なオープンソースの管理および開発プラットフォームです。プロジェクトの詳細については、公式 `documentation `_ を参照してください。 pgAdmin開発チームが公式のDockerコンテナイメージを維持していることを考えると、標準のKubernetes展開として環境にpgAdminをインストールできます。 .. Important:: Kubernetes運用環境でのpgAdminの展開は、このドキュメントの範囲を超えており、より広範にはCloudNativePGプロジェクトの範囲を超えています。 ただし、 **デモと評価の目的で** 、CloudNativePGは適切なソリューションを提供します。 ``cnpg`` プラグインは\ ``pgadmin4`` コマンドを実装し、特定のデータベース\ ``Cluster`` に接続し、\ ``kind`` などのローカル環境でそのコンテンツをナビゲートする簡単な方法を提供します。 たとえば、次のとおりに\ ``cluster-example`` クラスターのpgAdmin4のデモ展開をインストールできます。 .. code:: sh kubectl cnpg pgadmin4 cluster-example このコマンドは次を生成します。 .. code:: output ConfigMap/cluster-example-pgadmin4 created Deployment/cluster-example-pgadmin4 created Service/cluster-example-pgadmin4 created Secret/cluster-example-pgadmin4 created [...] pgAdminを展開した後、 kubectlを使用してポートを転送し、画面の指示に従ってブラウザーを介して接続します。 .. figure:: /images/pgadmin4.png :width: 70% :alt: Screenshot of desktop installation of pgAdmin Screenshot of desktop installation of pgAdmin いつものように、\ ``--dry-run`` オプションを使用してYAMLファイルを生成できます。 .. code:: sh kubectl cnpg pgadmin4 --dry-run cluster-example pgAdmin4はデスクトップまたはサーバーモードでインストールできます。デフォルトはサーバーです。 ``server`` モードでは、ランダムに生成されたパスワードを使用して認証が必要で、ユーザーは接続するデータベースを手動で指定する必要があります。 一方、\ ``desktop`` モードは、認証を必要とせずにpgAdmin Webインターフェイスを開始します。 ``app`` ユーザーとして\ ``app`` データベースに自動的に接続するため、 ``kind`` を使用したローカル展開などの簡単なデモに最適です。 .. code:: sh kubectl cnpg pgadmin4 --mode desktop cluster-example デモが終了した後、次のコマンドを実行してpgAdmin展開を確実に終了します。 .. code:: sh kubectl cnpg pgadmin4 --dry-run cluster-example | kubectl delete -f - .. Warning:: プラグインを使用してpgAdminを運用環境に展開しないでください。 ロジカルレプリケーションのパブリケーション ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ``cnpg publication`` コマンドグループは、 :ref:`PostgreSQL logical replication publications <レプリケーション>` の作成と削除を合理化するように設計されています。これらのコマンドは、主に、特にリモートのPostgreSQLデータベースでの論理レプリケーションパブリケーションの作成を支援することを目的としていることに注意してください。 .. Warning:: これらのコマンドを使用する前に、PostgreSQLのネイティブ論理レプリケーションシステムの機能と制限の両方をしっかりと理解することが重要です。特に、 :ref:`logical replication restrictions <レプリケーション>` に注意してください。 新しいパブリケーションの作成 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 論理レプリケーションパブリケーションを作成するには、 ``cnpg publication create`` コマンドを使用します。このコマンドの基本的な構造は次のとおりです。 .. code:: sh kubectl cnpg publication create \ --publication \ [--external-cluster ] [options] 2つの主な使用例があります。 - ``--external-cluster`` の場合 このオプションを使用して、外部クラスターつまり ``externalClusters`` スタンザで定義された上にパブリケーションを作成します。コマンドは\ ```` から発行されますが、パブリケーションは\ ```` のデータ用です。 - ``--external-cluster`` なし このオプションを使用して、 ```` PostgreSQL ``Cluster`` デフォルトでは ``app`` データベースにパブリケーションを作成します。 .. Warning:: 外部クラスターに接続するときは、指定されたユーザーに`CREATE PUBLICATION` コマンドを実行するための十分な権限があることを確認してください。 `CREATE PUBLICATION `_ と同様の、いくつかのオプションがあります。 コマンドを使用して、レプリケートするテーブルのグループを定義します。重要なオプションには次のものが含まれます。 - ``--all-tables`` オプションを指定した場合、パブリケーション\ ``FOR ALL TABLES`` を作成します。 - または、次の複数のオカレンスを指定できます。 - ``--table`` 特定のテーブル式を追加します。 - ``--schema`` 指定されたデータベーススキーマPostgreSQL 15から利用可能にあるすべてのテーブルを含めます。 ``--dry-run`` オプションを使用すると、プラグインが実行するSQLコマンドをプレビューできます。 追加情報と詳細な手順については、次のコマンドを入力してください。 .. code:: sh kubectl cnpg publication create --help 例 '' ``source-cluster`` および\ ``destination-cluster`` を指定して、 ``source-cluster`` 上のデータのパブリケーションを作成します。 ``destination-cluster`` には、\ ``source-cluster`` を指す\ ``externalClusters`` スタンザにエントリーがあります。 次を実行できます。 .. code:: sh kubectl cnpg publication create destination-cluster \ --external-cluster=source-cluster --all-tables これは、 ``destination-cluster`` でSQLコマンドを実行し、 ``source-cluster`` のすべてのテーブルのパブリケーションを作成します。 または、その代わりに、次を実行できます。 .. code:: sh kubectl cnpg publication create source-cluster \ --publication=app --all-tables これは、 ``source-cluster`` 内のすべてのテーブルに\ ``app`` という名前のパブリケーションを作成し、ソースクラスターでSQLコマンドを実行します。 .. Note:: イラストとインスピレーションのために提供されている2つのサンプルファイル :ref:`logical-source <例>` および :ref:`logical-destination <例>` 。 パブリケーションの削除 ^^^^^^^^^^^^^^^^^^^^^^ ``cnpg publication drop`` コマンドは、パブリケーション名、クラスター名、オプションの外部クラスターを含む同様のキーオプションを提供することにより、 ``create`` コマンドをシームレスに補完します。次のコマンド構造を使用して\ ``PUBLICATION`` をドロップできます。 .. code:: sh kubectl cnpg publication drop \ --publication \ [--external-cluster ] [options] さらに詳細と正確な指示にアクセスするには、次のコマンドを使用します。 .. code:: sh kubectl cnpg publication drop --help 論理レプリケーションサブスクリプション ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ``cnpg subscription`` コマンドグループは、 :ref:`PostgreSQL logical replication subscriptions <レプリケーション>` の作成と削除を簡素化するように設計された専用のコマンドセットです。これらのコマンドは、特にリモートのPostgreSQLデータベースを扱う場合、論理レプリケーションサブスクリプションの確立を支援するように特別に作成されています。 .. Warning:: これらのコマンドを使用する前に、PostgreSQLのネイティブ論理レプリケーションシステムの機能と制限の両方を包括的に理解することが重要です。特に、 :ref:`logical replication restrictions <レプリケーション>` に注意してください。 サブスクリプション管理に加えて、ソースクラスターからすべてのシーケンスを同期するための役立つコマンドを提供します。その適用性は異なる場合がありますが、このコマンドは、メジャーアップグレードまたはリモートサーバーからのデータのインポートを含むシナリオで特に役立ちます。 新しいサブスクリプションの作成 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 論理レプリケーションサブスクリプションを作成するには、 ``cnpg subscription create`` コマンドを使用します。このコマンドの基本的な構造は次のとおりです。 .. code:: sh kubectl cnpg subscription create \ --subscription \ --publication \ --external-cluster \ [options] このコマンドは、 ```` の\ ``externalClusters`` スタンザで定義されているとおりに、指定された外部クラスター内の指定されたパブリケーションを対象としたサブスクリプションを構成します。 追加情報と詳細な手順については、次のコマンドを入力してください。 .. code:: sh kubectl cnpg subscription create --help .. _例-1: 例 '' パブリケーションに関するセクションと同様に、\ ``source-cluster`` および\ ``destination-cluster`` があり、\ ``app`` というパブリケーションを既に作成しています。 次のコマンド .. code:: sh kubectl cnpg subscription create destination-cluster \ --external-cluster=source-cluster \ --publication=app --subscription=app は、宛先クラスターに\ ``app`` のサブスクリプションを作成します。 .. Warning:: 非実稼働環境でのテストサブスクリプションを優先して、実稼働設定に実装する前にその有効性を確認し、潜在的な問題を特定します。 .. Note:: イラストとインスピレーションのために提供されている2つのサンプルファイル :ref:`logical-source <例>` および :ref:`logical-destination <例>` 。 サブスクリプションの削除 ^^^^^^^^^^^^^^^^^^^^^^^^ ``cnpg subscription drop`` コマンドは、 ``create`` コマンドをシームレスに補完します。次のコマンド構造を使用して\ ``SUBSCRIPTION`` をドロップできます。 .. code:: sh kubectl cnpg subcription drop \ --subscription \ [options] さらに詳細と正確な指示にアクセスするには、次のコマンドを使用します。 .. code:: sh kubectl cnpg subscription drop --help シーケンスの同期 ^^^^^^^^^^^^^^^^ パブリケーションとサブスクリプションを介して実装されるPostgreSQL論理レプリケーションの重要な制約の1つは、シーケンス同期の欠如です。これは、論理レプリケーションを利用する場合に特に関連します ライブデータベース移行、特にPostgreSQLの上位バージョンの場合。このプロセスの重要なステップには、アプリケーションを新しいデータベース *カットオーバー* に移行する前にシーケンスの更新が含まれます。 この制限に対処するために、 ``cnpg subscription sync-sequences`` コマンドは解決策を提供します。このコマンドは、ソースデータベースとの接続を確立し、関連するすべてのシーケンスを取得し、その後、一致するIDでローカルシーケンスを更新しますデータベーススキーマとシーケンス名に基づいて。 以下に示すようにコマンドを使用できます。 .. code:: sh kubectl cnpg subscription sync-sequences \ --subscription \ 包括的な詳細と特定の手順については、次のコマンドを使用します。 .. code:: sh kubectl cnpg subscription sync-sequences --help .. _例-2: 例 '' パブリケーションとサブスクリプションに関する以前のセクションと同様に、\ ``source-cluster`` および\ ``destination-cluster`` があります。パブリケーションとサブスクリプションは、両方とも\ ``app`` と呼ばれますが、既に存在します。 次のコマンドは、\ ``app`` サブスクリプションに関係するシーケンスをソースクラスターから宛先クラスターに同期します。 .. code:: sh kubectl cnpg subscription sync-sequences destination-cluster \ --subscription=app .. Warning:: 非実稼働環境でのテストサブスクリプションを優先して、実稼働設定に展開する前にその有効性を保証し、潜在的な問題を検出します。 K9sとの統合 ----------- ``cnpg`` プラグインは、Kubernetesクラスターと対話するための一般的なターミナルベースのUIである `K9s `_ に簡単に統合できます。 詳細は、 :ref:`k9s/plugins.yml <例>` を参照してください。