パスワード · API キーの変更

データレイクのサービスアカウント(PostgreSQL · Cassandra · Valkey · MinIO · Kafka/MQTT …)と API キーはすべてのインストール環境が同じデフォルト値で始まります。コミッショニング時に必ず変更し、その後はポリシーに従ってローテーションします。

変更ツールはホスト上の**bin/passwd.sh 1つ**です。

cd /opt/kopens/plantpulse-platform-docker

bin/passwd.sh --list                       # 바꿀 수 있는 키 + 계정명 + 현재값(마스킹) + 정본 위치
bin/passwd.sh PP_PG_PASSWORD               # 값을 생략하면 프롬프트 — 권장 (히스토리 · ps 에 안 남는다)
bin/passwd.sh PP_PG_PASSWORD=<새비밀번호>   # 인라인
bin/passwd.sh PP_CASSANDRA_PASSWORD PP_MINIO_PASSWORD   # 여러 개를 한 번에 — 재시작 1회
bin/passwd.sh --dry-run PP_MQ_PASSWORD     # 계획만 — 아무것도 바꾸지 않는다

ファイルを開いてパスワード行を編集しないでください

パスワードは2つの場所に別々に存在します — サーバーが受け入れる値(PostgreSQL アカウント、Cassandra ロール …)とクライアントが提示する値(設定ファイル約20個)。両者は自動的には同期されません。サイドカーだけを編集すると次の再起動時にすべてのクライアントが認証に失敗し、サーバー側だけを変更するとすぐに失敗します。

passwd.sh は ① サーバー側アカウント変更 → ② サイドカー更新 → ③ 設定再レンダリング → ④ 再起動を1つのコマンド内で順序立てて実行します。

変更可能なキー

キーは環境変数名そのものです。postgres · mq のようなエイリアスはありません — どのキーがどのコンポーネントなのかは--list が示します。

キー	コンポーネント	アカウント	値の正本はどこか
PP_PG_PASSWORD	PostgreSQL	plantpulse	コマンド — ALTER ROLE (psql)
PP_TEMPORAL_PASSWORD	Temporal のバックエンド PostgreSQL アカウント	temporal	コマンド — ALTER ROLE (psql)
PP_HIVE_PASSWORD	Hive メタストアの PostgreSQL アカウント + Kyuubi インバウンド認証	hive	コマンド — ALTER ROLE (psql) + 再レンダリング
PP_CASSANDRA_PASSWORD	Cassandra	cassandra	コマンド — ALTER ROLE (cqlsh)
PP_REDIS_PASSWORD	Valkey	—	ファイル — plantpulse-storage/cache/valkey/conf/valkey.conf
PP_MINIO_PASSWORD	MinIO	minio	起動 env — MINIO_ROOT_PASSWORD
PP_MQ_PASSWORD	Kafka + HiveMQ — 1つの値を共有	mq	ファイル — kafka/config/jaas.conf + mqtt/conf/auth.properties
PP_CEP_API_KEY	CEP API キー (X-API-Key)	—	ファイル — plantpulse-cep/config/plantpulse-cep.properties
PP_DATA_GATEWAY_API_KEY	データゲートウェイ API キー	—	ファイル — plantpulse-data-gateway/config/plantpulse-jdbc.properties
PP_DATALAKE_ADMIN_PASSWORD	管理コンソール ログイン	admin	起動 env — admin-api が自身の環境変数から読み込む
PP_DATALAKE_ADMIN_API_KEY	管理コンソール ログエンドポイント X-API-Key	—	起動 env

3つの意味:

• コマンド — サーバーアカウントが正本です。SQL/CQL で変更し、設定ファイルは接続用のコピーに過ぎません。
• ファイル — レンダリングされたそのファイルが正本です。再レンダリング + 再起動でのみ変更されます。
• 起動 env — プロセス起動時に注入されます。ランタイム変更 API がないため、再起動が唯一の反映手段です。

アカウント名(PP_*_USER)は変更しません。--list に表示されるだけです。アカウント名の変更は、サーバー側ロール作成と権限移譲が必要な別のタスクです。

--list に管理コンソールキー2つが表示されない場合

PP_DATALAKE_ADMIN_PASSWORD · PP_DATALAKE_ADMIN_API_KEY は2026-09-05 に追加されました。それ以前のインストールパッケージにはキーが9個だけです。その場合、コンソールパスワードはサーバー側アカウントがないためサイドカーを直接編集して再起動してください → ウェブ画面ログインアカウント

手順 — 初回のみ

コミッショニング時には、登録されたキーすべてをランダムな値でローテーションします。--all はpasswd.sh ではなくローテーションエンジンrotate-secret.sh のオプションです。

cd /opt/kopens/plantpulse-platform-docker

bin/rotate-secret.sh --dry-run --all --generate   # 어떤 키가 걸리는지 확인 — 아무것도 안 바꾼다
bin/rotate-secret.sh --all --generate             # 실행. 키마다 20자 무작위 값
bin/passwd.sh --list --show                       # 결과 확인 — 값이 그대로 찍히니 화면 공유 중에는 치지 마세요

• 必ずメンテナンスウィンドウで実行してください。ローテーション中に再起動が1回あり、Kafka/MQTT パスはその間切断されます。
• 作業前にバックアップを取得してください。
• 変更された値はサイドカー/etc/kopens/plantpulse-platform.env にのみあります。**引継資料には値ではなく「誰が保管するのか」**を記載してください。

手順 — 運用中に1つずつ

cd /opt/kopens/plantpulse-platform-docker
bin/passwd.sh --dry-run PP_PG_PASSWORD    # 계획 확인
bin/passwd.sh PP_PG_PASSWORD              # 프롬프트에 새 값 입력

完了したら確認します。

bin/status.sh                                                           # 0 = 정상
docker exec plantpulse-datalake pd node psql -c "SELECT 1;"             # 새 비밀번호로 실제 접속되나
docker exec plantpulse-datalake pd node cql -e "SELECT now() FROM system.local;"
curl -kfsS https://<server-ip>:4950/api/health | jq .status               # OK 또는 WARN

失敗時 — 同じコマンドを再実行

ローテーションはロールバックしません。 失敗時点ではどの値が有効かが不確実なため、戻すことでステータスをさらに悪化させる可能性があります。代わりに前方復旧します。

ホストの/etc/kopens/rotation.journal(0600)に新 · 旧の値が事前に記録されています。同じコマンドをそのまま再実行すると、各コンポーネントが現在どの値を受け入れているかをプローブして続行します。すでに変更されたものはスキップされます。

メッセージ	意味	対応
probe=NEITHER	新 · 旧どの値でも接続不可	自動化が判断する根拠がありません。その コンポーネントに直接接続して状態を確認してください
apply 失敗	サーバー側変更失敗、即座に中止	原因を修正して同じコマンドを再実行
verify 失敗	サーバーは変更されたが新値で接続不可	最も危険です。ジャーナルがAPPLIED に残ります — 人間が確認する必要があります
configure 失敗	再起動なしで中止	意図した動作です(旧設定で起動すると全認証失敗)。原因を修正して再実行
variable not in the registry	登録されていないキー	以下のローテーション非対象値を参照

ワーカーノードがある場合は拒否されます

クラスタワーカーが設定されている場合、ローテーションツールは拒否して中止します。ワーカーごとに別のサイドカーがあるため、マスターだけをローテーションするとワーカーが旧値のままでクラスタが半分になってしまうからです。ワーカーがある環境は手動手順に従い、ワーカーごとにサイドカー更新と再起動を繰り返してください。

PP_MQ_PASSWORD — Kafka と HiveMQ は一緒に変更されます

1つの値が2つのブローカーのサーバー側認証情報ストレージであり、すべてのクライアントの接続パスワードです。別々に変更することはできず、ローテーションツールの検証は両方が新値に接続できる場合のみ成功と判定します。

静的 JAAS は新 · 旧の値を同時に受け入れることができないため、ブローカーとコンシューマーが順序立てて再起動されている間MQ パスが切断されます。 ノンストップローテーションはサポート範囲外です。

PP_HIVE_PASSWORD — 1つの値が双方向で使われます

Hive メタストアが PostgreSQL に接続する際に提示する値である一方、クライアントが Kyuubi に接続する際に検証される値でもあります。そのため、ローテーションツールはPostgreSQL アカウント変更と設定再レンダリングの両方を実行します。手動で行う場合、1つだけ行うとメタストアまたは Kyuubi の一方が停止します。

ローテーション非対象値 — 手動で変更

レジストリにないキーが指定された場合、静かにスキップされるのではなく拒否されます。以下はまだ登録されていないもので、手動手順で変更します。

変数	何か	手動変更のポイント
PP_SPARK_PASSWORD	Spark/Kyuubi クライアントアカウント	サーバーアカウントが存在しません。hive-auth.properties がこの値でアカウントを作成します — サイドカー更新 + 再起動
PP_TSE_PASSWORD	時系列エンジンアカウント	サイドカー更新 + 再起動
PP_GRAVITINO_PASSWORD · PP_KESTRA_DB_PASSWORD	各々のバックエンド PostgreSQL アカウント	データレイクは起動のたびに PostgreSQL ロールパスワードをサイドカー値に同期します — サイドカー更新 + 再起動
PP_KESTRA_ADMIN_PASSWORD	Kestra 管理者	ウェブ画面ログインアカウント
PP_TLS_KEYSTORE_PASSWORD (+ truststore 派生セット)	証明書全体	証明書再発行と関連しています → セキュリティ設定
PP_OPCUA_PASSWORD	OPC-UA サーバー(アプリコンテナ)	データレイク外
PP_API_KEY · PP_FLOW_WEBHOOK_API_KEY	外部呼び出し者用(アプリコンテナ)	データレイク外
PP_DATA_GATEWAY_WEB_PASSWORD · PP_CEP_WEB_PASSWORD	クエリコンソール ブラウザログイン	ローテーション対象ではないという決定です(2026-09-07)。サイドカー更新 + 再起動 → ウェブ画面ログインアカウント

しないでください

• コンテナ内でpd secret rotate を直接編集しないでください。 ローテーションジャーナルとサイドカーはコンテナ再生成で生き残るようにホストに置かれます。ホストのpasswd.sh がそれを呼び出します。
• bin/env.sh のパスワードデフォルト値を編集して反映されることを期待しないでください。 サイドカーが優先されます。
• --list --show 出力をチケット · チャットに貼り付けないでください。
• ローテーション中にCtrl+C で中止して別の値で再開しないでください。 ジャーナルが最初の値を記憶しています。同じ値で再実行して完了させた後、再び変更してください。

関連文書

• ウェブ画面ログインアカウント
• パスワード変更(クレデンシャルローテーション) — 手動手順 — ツールが対象としない値
• 初期パスワード変更 — コミッショニングチェックリスト全体