CloudNativePGプラグイン¶
CloudNativePGは、Kubernetesでクラスターを管理するためのkubectl
用プラグインを提供します。
インストールする¶
次の方法でシステムにプラグインをインストールできます。
curl -sSfL \
https://github.com/cloudnative-pg/cloudnative-pg/raw/main/hack/install-cnpg-plugin.sh | \
sudo sh -s -- -b /usr/local/bin
サポートされているアーキテクチャ¶
CloudNativePG プラグインは現在、次のオペレーティングシステムとアーキテクチャ向けにビルドされています。
Linux * amd64 * arm 5/6/7 * arm64 * s390x * ppc64le
macOS * amd64 * arm64
Windows * 386 * amd64 * arm 5/6/7 * arm64
使用する¶
プラグインをインストールして展開したら、次のように使用を開始できます。
kubectl cnpg <command> <args...>
ステータス¶
status コマンドは、クラスターの現在のステータスの概要を提供します。
一般情報 ：クラスターの名前、PostgreSQLのシステムID、インスタンス数、WALでの現在のタイムラインと位置
backup ：回復可能性ポイント、およびプライマリから
pg_stat_archiverビューによって返されるWALアーカイブステータス-またはレプリカクラスターの場合は指定されたプライマリストリーミングレプリケーション ：プライマリインスタンスの
pg_stat_replicationビューから直接取得した情報インスタンス ：各インスタンスマネージャーが直接取得する各Postgresインスタンスに関する情報。スタンバイの場合、
Current LSNフィールドは、リカバリ中にリプレイされた最新のログ先行書き込みの場所（リプレイLSN）に対応します。
重要
上記のステータス情報はさまざまな時間にさまざまな場所で取得され、結果としてわずかに一貫性のない値が返されます。たとえば、メインヘッダーの`Current Write LSN` の場所は、2つの異なる時間間隔で取得されるため、インスタンスステータスの`Current LSN` フィールドとは異なる場合があります。
kubectl cnpg status sandbox
Cluster in healthy state
Name: sandbox
Namespace: default
System ID: 7039966298120953877
PostgreSQL Image: ghcr.io/cloudnative-pg/postgresql:14.4
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
を追加して、ステータスのより詳細なバージョンを取得することもできます
kubectl cnpg status sandbox --verbose
Cluster in healthy state
Name: sandbox
Namespace: default
System ID: 7039966298120953877
PostgreSQL Image: ghcr.io/cloudnative-pg/postgresql:14.4
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
できるため、クラスターでメンテナンス作業を開始したり、スイッチオーバー状況をテストしたりできます
kubectl cnpg promote cluster-example cluster-example-2
または、インスタンスノード番号を使用して昇格できます
kubectl cnpg promote cluster-example 2
証明書¶
CloudNativePG オペレーターを使用して作成されたクラスターは、CA と連携して TLS 認証証明書に署名します。
証明書を取得するには、資格情報を保存するシークレットの名前、クラスター名、およびユーザーを指定する必要があります
kubectl cnpg certificate cluster-cert --cnpg-cluster cluster-example --cnpg-user appuser
シークレットが作成されたら、 kubectl を使用して取得できます
kubectl get secret cluster-cert
そして、次のコマンドを使用して、プレーンテキストで同じ内容を表示します。
kubectl get secret cluster-cert -o json | jq -r .data | map(@base64d) | .[]
再起動¶
kubectl cnpg restart コマンドは、次の2つの場合に使用できます。
オペレーターに、特定のクラスターのロールアウトの再起動を調整するように要求します。これは、カスタムモニタリングクエリを含む ConfigMap などのクラスター依存オブジェクトに構成の変更を適用する場合に役立ちます。
単一のインスタンスの再起動を要求します。インスタンスがクラスターのプライマリの場合はその場で、ポッドがレプリカの場合はポッドを削除して再作成します。
# 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イメージのマイナーアップグレードです。
注釈
ConfigMapとシークレットをインスタンスによって**自動的に**リロードしたい場合、キー cnpg.io/reload でラベルを追加できます。
リロード¶
kubectl cnpg reload
コマンドは、特定のクラスターの調整ループをトリガーするようにオペレーターに要求します。これは、カスタムモニタリングクエリを含む
ConfigMap
などのクラスター依存オブジェクトに構成の変更を適用する場合に役立ちます。
次のコマンドは、特定のクラスターのすべての構成をリロードします。
kubectl cnpg reload [cluster_name]
メンテナンス¶
kubectl cnpg maintenance
コマンドは、名前空間全体で1つ以上のクラスターを変更し、メンテナンスウィンドウの値を設定するのに役立ちます。次のフィールドを変更します。
.spec.nodeMaintenanceWindow.inProgress
.spec.nodeMaintenanceWindow.reusePVC
これを使用してset およびunset
を引数として受け入れ、set の場合はtrue に、unset
の場合はfalse に設定します。
デフォルトでは、 --reusePVC フラグが渡されない限り、 reusePVC
は常にfalse に設定されます。
プラグインは変更するクラスターとその新しい値のリストを使用して確認を求めます。これが受け入れられると、このアクションがリスト内のすべてのクラスターに適用されます。
Kubernetesクラスター内のすべてのPostgreSQLをメンテナンスに設定する場合は、次のコマンドを記述するだけです。
kubectl cnpg maintenance set --all-namespaces
そして、更新するすべてのクラスターのリストがあります
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
サブコマンドは、オペレーターの展開、構成、およびイベントに関する情報を提供するようにオペレーターに要求します。
重要
SecretsとConfigMapsのすべての機密情報はREDACTEDです。データマップには**キー**が表示されますが、値は空になります。フラグ -S / --stopRedaction は、リダクションを無効にして値を表示します。ご自身の責任でのみ使用してください。これは個人データを共有します。
注釈
デフォルトでは、オペレーターログは収集されませんが、 --logs フラグでオペレーターログの収集を有効にできます
デプロイメント情報 : オペレーターデプロイメントとオペレーターポッド
構成 ：オペレーター名前空間のSecretsとConfigMaps
events : オペレーター名前空間のイベント
Webhook構成 ：Webhook構成の変更と検証
ウェブフックサービス ：ウェブフックサービス
logs ：JSON行形式のオペレーターPod（オプション、デフォルトでオフ）のログ
このコマンドは、さまざまなマニフェストをYAML形式で含むZIPファイルを生成します（デフォルトでは、
-o フラグでJSONに設定できます）。 -f
フラグを使用して、結果ファイルに明示的に名前を付けます。 -f
フラグを使用しない場合、デフォルトのタイムスタンプ付きのファイル名がzipファイルに作成されます。
注釈
レポートプラグインは`kubectl` 規則に従い、名前空間によって制約されるオブジェクトを探します。 CNPG Operatorは通常、クラスターと同じ名前空間にはインストールされません。例デフォルトのインストール名前空間は cnpg-system
kubectl cnpg report operator -n <namespace>
の結果
Successfully written report to "report_operator_<TIMESTAMP>.zip" (format: "yaml")
-f フラグを設定します。
kubectl cnpg report operator -n <namespace> -f reportRedacted.zip
ファイルを解凍すると、ディレクトリを整理するためのタイムスタンプ付きの最上位フォルダーが生成されます。
unzip reportRedacted.zip
結果：
Archive: reportRedacted.zip
creating: report_operator_<TIMESTAMP>/
creating: report_operator_<TIMESTAMP>/manifests/
inflating: report_operator_<TIMESTAMP>/manifests/deployment.yaml
inflating: report_operator_<TIMESTAMP>/manifests/operator-pod.yaml
inflating: report_operator_<TIMESTAMP>/manifests/events.yaml
inflating: report_operator_<TIMESTAMP>/manifests/validating-webhook-configuration.yaml
inflating: report_operator_<TIMESTAMP>/manifests/mutating-webhook-configuration.yaml
inflating: report_operator_<TIMESTAMP>/manifests/webhook-service.yaml
inflating: report_operator_<TIMESTAMP>/manifests/cnpg-ca-secret.yaml
inflating: report_operator_<TIMESTAMP>/manifests/cnpg-webhook-cert.yaml
機密情報が REDACTED であることを確認できます。
cd report_operator_<TIMESTAMP>/manifests/
head cnpg-ca-secret.yaml
data:
ca.crt: ""
ca.key: ""
metadata:
creationTimestamp: "2022-03-22T10:42:28Z"
managedFields:
- apiVersion: v1
fieldsType: FieldsV1
fieldsV1:
-S （--stopRedaction
）オプションを有効にすると、シークレットが表示されます。
kubectl cnpg report operator -n <namespace> -f reportNonRedacted.zip -S
機密情報を表示しようとしているというリマインダーが表示されます。
WARNING: secret Redaction is OFF. Use it with caution
Successfully written report to "reportNonRedacted.zip" (format: "yaml")
unzip reportNonRedacted.zip
head cnpg-ca-secret.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 : クラスター名前空間のイベント
podlogs : JSON行形式のクラスターポッド（オプション、デフォルトでオフ）のログ
ジョブログ ：ジョブによって作成されたPodのログ（オプション、デフォルトでオフ）
cluster サブコマンドは、 operator と同様に、 -f
および-o フラグを受け入れます。 -f
フラグを使用しない場合、デフォルトのタイムスタンプ付きのレポート名が使用されます。クラスター情報には構成Secrets
/ ConfigMapsが含まれていないため、 -S は無効になっています。
注釈
デフォルトでは、クラスターログは収集されませんが、 --logs フラグでクラスターログ収集を有効にできます
使用法:
kubectl cnpg report cluster <clusterName> [flags]
operator サブコマンドとは異なり、 cluster
サブコマンドでは、クラスターがデフォルトにない限り、クラスター名、およびほとんどの場合名前空間を指定する必要があることに注意してください。
kubectl cnpg report cluster example -f report.zip -n example_namespace
そして：
unzip report.zip
Archive: report.zip
creating: report_cluster_example_<TIMESTAMP>/
creating: report_cluster_example_<TIMESTAMP>/manifests/
inflating: report_cluster_example_<TIMESTAMP>/manifests/cluster.yaml
inflating: report_cluster_example_<TIMESTAMP>/manifests/cluster-pods.yaml
inflating: report_cluster_example_<TIMESTAMP>/manifests/cluster-jobs.yaml
inflating: report_cluster_example_<TIMESTAMP>/manifests/events.yaml
--logs
フラグを使用して、ポッドとジョブのログをZIPに追加できることに注意してください。
kubectl cnpg report cluster example -n example_namespace --logs
結果：
Successfully written report to "report_cluster_example_<TIMESTAMP>.zip" (format: "yaml")
unzip report_cluster_<TIMESTAMP>.zip
Archive: report_cluster_example_<TIMESTAMP>.zip
creating: report_cluster_example_<TIMESTAMP>/
creating: report_cluster_example_<TIMESTAMP>/manifests/
inflating: report_cluster_example_<TIMESTAMP>/manifests/cluster.yaml
inflating: report_cluster_example_<TIMESTAMP>/manifests/cluster-pods.yaml
inflating: report_cluster_example_<TIMESTAMP>/manifests/cluster-jobs.yaml
inflating: report_cluster_example_<TIMESTAMP>/manifests/events.yaml
creating: report_cluster_example_<TIMESTAMP>/logs/
inflating: report_cluster_example_<TIMESTAMP>/logs/cluster-example-full-1.jsonl
creating: report_cluster_example_<TIMESTAMP>/job-logs/
inflating: report_cluster_example_<TIMESTAMP>/job-logs/cluster-example-full-1-initdb-qnnvw.jsonl
inflating: report_cluster_example_<TIMESTAMP>/job-logs/cluster-example-full-2-join-tvj8r.jsonl
