パスワード変更（クレデンシャルローテーション）

概要

PlantPulse は内部インフラコンポーネント（PostgreSQL · Aster TSDB · Valkey · RustFS · Kafka · MQTT · Hive/Kyuubi · Temporal）に接続するためのサービスアカウントを使用します。初期値はすべてのインストールで同一であるため、コミッショニング時に1回変更することを推奨します。

重要: パスワード変更は順序を守らないとプラットフォームが起動しません。 通常は、下記の自動ローテーション（bin/passwd.sh）がその順序を代行します。ツールが扱わない値やワーカーが存在する環境でのみ手動手順を使用します。必ず点検ウィンドウで実施し、作業前にバックアップを確保してください。

データレイクセクションに整理されています

どのキーをどう変更するか、失敗した場合はどうするかは、データレイク — パスワード · APIキー変更 に最新の状態で整理されています。このページは、そのツールが扱わない値の手動手順のために残されています。

自動ローテーション — passwd.sh · rotate-secret.sh

インストールパッケージの bin/passwd.sh（フロントドア）と bin/rotate-secret.sh（ローテーションエンジン）が、サーバー側アカウント変更 · 保管庫（サイドカー）更新 · 設定再レンダリング · 順次再起動を一括で実行します。手動手順の1〜3ステップをそのまま代行します。コンテナ側のローテーション機構はデータレイクイメージの pd secret rotate で、ホストスクリプトがそれを呼び出します。

オペレーターのエントリポイントはホストです。コンテナ内で開始すると、コンテナが死んだ時に進行記録も一緒に消え、再開できなくなるためです。

cd /opt/kopens/plantpulse-platform-docker

# 하나만 변경
bin/rotate-secret.sh PP_PG_PASSWORD='새비밀번호'

# 여러 개 — 재시작 1회로 묶인다
bin/rotate-secret.sh PP_PG_PASSWORD='...' PP_CASSANDRA_PASSWORD='...'

# 커미셔닝 시 전체 생성
bin/rotate-secret.sh --all --generate

# 계획만 출력 — 아무것도 바꾸지 않는다
bin/rotate-secret.sh --dry-run --all --generate

引数は必ず**변수=값**形式です。PP_PG_PASSWORD '새값' のようにスペースで区切ると 알 수 없는 인자 として拒否されます。

--all は --generate とのみ併用できます。--generate は変数ごとに20文字のランダム値を作成して使用します。まず --dry-run で対象を確認してください — どの変数が対象になるかのみ出力し、サイドカーもサーバー側も触りません。

ローテーション可能な変数

レジストリに登録された変数のみローテーションできます。登録されていない変数を指定すると、黙ってスキップせず拒否します。

環境変数	rotator	対象アカウント
PP_PG_PASSWORD	postgres	plantpulse
PP_TEMPORAL_PASSWORD	postgres	temporal
PP_HIVE_PASSWORD	postgres	hive
PP_CASSANDRA_PASSWORD	cassandra	—
PP_REDIS_PASSWORD	valkey	—
PP_S3_PASSWORD	rustfs	—
PP_MQ_PASSWORD	mq	— （Kafka · HiveMQ を同時に — 下記セクション参照）
PP_CEP_API_KEY	apikey	—
PP_DATA_GATEWAY_API_KEY	apikey	—
PP_DATALAKE_ADMIN_PASSWORD	console	admin （管理コンソールログイン、2026-09-05 追加）
PP_DATALAKE_ADMIN_API_KEY	apikey	— （管理コンソールログエンドポイント、2026-09-05 追加）

--all --generate もこのリストのみを対象にします。2026-09-05 より前のインストールパッケージには最後の2つがありません — --list が正本です。

まだ登録されていない変数 — PP_API_KEY、PP_FLOW_WEBHOOK_API_KEY（外部呼び出し元用、検証エンドポイント確定後に別件）、PP_SPARK_PASSWORD · PP_TSE_PASSWORD · PP_GRAVITINO_PASSWORD · PP_KESTRA_DB_PASSWORD · PP_KESTRA_ADMIN_PASSWORD、および TLS keystore/truststore パスワード（証明書交換と絡み別件）です。これらはスクリプトが拒否するため、手動手順で変更してください。クエリコンソールログインの2つ（PP_DATA_GATEWAY_WEB_PASSWORD · PP_CEP_WEB_PASSWORD）はローテーション対象外とする決定であり、サイドカー更新 + 再起動で変更します → Web画面ログインアカウント。

PP_MQ_PASSWORD（Kafka · HiveMQ）はローテーション対象ですが切断が発生する唯一の項目であるため、下記のMQローテーションで個別に扱います。

オペレーター用フロントドア — passwd.sh

rotate-secret.sh を直接呼び出す代わりに使うフロントドアです。検証してローテーションエンジンを一度呼び出すだけなので動作は同じで、何を変更できるかをリストで表示する点が異なります。platform · ai · studio の3製品が同じ名前、同じ使用方法で持ちます。

cd /opt/kopens/plantpulse-platform-docker

bin/passwd.sh --list                      # 키 + 아이디 + 현재값(마스킹) + 위치
bin/passwd.sh --list --show               # 현재값 전체

bin/passwd.sh PP_MQ_PASSWORD              # 값 생략 → 프롬프트 (권장)
bin/passwd.sh PP_PG_PASSWORD=<new-password>
bin/passwd.sh PP_CASSANDRA_PASSWORD=<new-password> PP_S3_PASSWORD=<new-password>   # 묶으면 재시작 1회
bin/passwd.sh --dry-run PP_MQ_PASSWORD=<new-password>

エイリアスはありません — キーは環境変数名そのままです

mq、cassandra、postgres のようなコンポーネント名では呼び出せません。エイリアスを置くと名前と変数を結びつけるマッピング表をレジストリと別に合わせる必要があり、別名2つが同じ変数を指す場合（"kafka と hivemq は同じ値"）ごとに特別ルールが付きます。キーがそのまま変数であればその問題はありません。

どの変数がどのコンポーネントかは --list が教えてくれます — だからリストがあります。

変更できるキーと、その値の正本がどこにあるかです。

キー	コンポーネント	何で変わるか
PP_PG_PASSWORD	PostgreSQL	コマンド — ALTER ROLE （psql）
PP_TEMPORAL_PASSWORD	Temporal のバックエンド PostgreSQL アカウント	コマンド — ALTER ROLE （psql）
PP_HIVE_PASSWORD	Hive メタストアの PostgreSQL アカウント	コマンド — ALTER ROLE （psql）
PP_CASSANDRA_PASSWORD	Aster TSDB	コマンド — ALTER ROLE （cqlsh）
PP_REDIS_PASSWORD	Valkey	ファイル — plantpulse-storage/cache/valkey/conf/valkey.conf
PP_S3_PASSWORD	RustFS	起動 env — RUSTFS_SECRET_KEY
PP_MQ_PASSWORD	Kafka + HiveMQ （同じ値を共有します）	ファイル — kafka/config/jaas.conf + mqtt/conf/auth.properties
PP_CEP_API_KEY	CEP API キー	ファイル — plantpulse-cep/config/plantpulse-cep.properties
PP_DATA_GATEWAY_API_KEY	Data Gateway API キー	ファイル — plantpulse-data-gateway/config/plantpulse-jdbc.properties

3つの種類の意味は以下の通りです。

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

ID（PP_*_USER）は変更しません。 表示のみ行います — アカウント名の変更はサーバー側 role 作成と権限移譲まで必要な別の作業です。

値を省略してプロンプトで入力することが推奨経路です — パスワードが ps 出力やシェルヒストリーに残りません。

レジストリにないキーを渡すと、黙ってスキップせず拒否します。タイプミスには類似キーを提案します。

MQ（Kafka · HiveMQ）ローテーション

Kafka と HiveMQ は個別に変更できません

PP_MQ_PASSWORD 1つが2つのブローカーのサーバー側資格情報ストアであり、クライアント8つの接続パスワードです。kafka で呼ぼうと hivemq で呼ぼうと両方が一緒に変わります。

kafka と hivemq を1つのコマンドで互いに異なる値で指定すると拒否します — どちらが勝つかを黙って決めません。

Kafka は静的 JAAS（kafka-jaas.conf）、HiveMQ はセキュリティエクステンション（plantpulse-mq-auth.properties）から値を読み取ります。クライアント8つ（plantpulse-mq · plantpulse-mqtt · plantpulse-batch · プラグイン2種 + cluster/ 変種）も同じローテーションで一緒に新しい値を受け取るため、クライアントだけ古いパスワードのまま残る穴はありません。

ローテーション中に MQ 経路が切断されます

静的 JAAS は新・旧パスワードを同時に受け入れられません。ブローカーとコンシューマーを順次再起動する間にMQ経路に切断が発生します。 無停止ローテーションはサポート範囲外です — 必ず点検ウィンドウで実施してください。

BifroMQ は対象ではありません。 実際の MQTT ブローカーは HiveMQ です。

失敗したとき — 同じコマンドを再実行

ロールバックはしません。 元に戻すには再度接続する必要がありますが、失敗時点ではどの資格情報が有効か不確実で、戻す試みが状態をさらに壊します。前進復旧のみサポートします。

失敗したら同じコマンドをそのまま再実行してください。ホストの /etc/kopens/rotation.journal（0600）に新・旧の値が先行記録されており、再実行すると各コンポーネントの現在状態を判定して継続します。すでに新しい資格情報に変わったコンポーネントはスキップされます。

メッセージ	意味	対処
probe=NEITHER	新旧どちらでも接続不可	自動化が判断する根拠がありません。人が状態を確認する必要があります
apply 실패	サーバー側変更失敗、即時停止	原因を修正し、同じコマンドを再実行
verify 실패	サーバー側は変わったが新値で接続不可	最も危険です。journal が APPLIED として残ります — 人が確認する必要があります
configure 실패	再起動せずに停止	旧設定で起動すると全て認証失敗するため、意図された動作です

ワーカーノードがあると使用できません

PP_WORKER_NODES が設定されていると、スクリプトが拒否して停止します。ワーカーノードごとにサイドカーが別にあるため、マスターだけローテーションするとワーカーが古いパスワードのまま残り、クラスターが半分になります。部分成功が最悪の失敗なので、黙ってマスターだけ処理しません。

マルチノードはまだサポートしていません。クラスター（マルチノード）環境の手動手順に従ってください。

なぜ順序が重要なのか

パスワードは2箇所に別々に存在します。両者は自動的に同期されません。

• ①だけ変更すると すべてのクライアントが認証に失敗します。
• ②だけ変更すると サーバーが依然として古いパスワードを要求するため認証に失敗します。
• ③を忘れると 今は動作しますが、次のコンテナ再作成時に古いパスワードが再注入され起動に失敗します。最も見落としやすいステップです。

したがって順序は常に① サーバー → ③ 保管庫 → ② 設定再生成 → 再起動です。

変更可能なアカウント

자동 회전 列が «対象» であるものは passwd.sh で変更します。手動手順はそれ以外の値とワーカーが存在する環境のためのものです。

以下はインフラアカウント7つです。APIキー4つ（PP_CEP_API_KEY · PP_DATA_GATEWAY_API_KEY · PP_DATALAKE_ADMIN_PASSWORD · PP_DATALAKE_ADMIN_API_KEY）も同じツールの対象であり、 合計11個すべては上記のローテーション可能な変数にあります。

環境変数	対象	サーバー側変更必要	自動ローテーション
PP_PG_PASSWORD	PostgreSQL アカウント plantpulse	必要	対象
PP_TEMPORAL_PASSWORD	PostgreSQL アカウント temporal （Temporal バックエンド）	必要	対象
PP_HIVE_PASSWORD	PostgreSQL アカウント hive （Hive metastore） + Hive/Kyuubi 接続認証	必要	対象
PP_CASSANDRA_PASSWORD	Aster TSDB role	必要	対象
PP_REDIS_PASSWORD	Valkey requirepass	不要 （設定ファイル）	対象
PP_S3_PASSWORD	RustFS ルートクレデンシャル	不要 （起動時に注入）	対象
PP_MQ_PASSWORD	Kafka SASL · MQTT ブローカー	不要 （設定ファイル）	対象 （MQローテーション）

PP_TEMPORAL_PASSWORD は Temporal 自体のアカウントではありません。 Temporal がバックエンド PostgreSQL に接続する際に使うDBアカウントです。

PP_HIVE_PASSWORD は値1つが双方向で使われます。 Hive metastore が PostgreSQL に接続する際に提示する値であり、同時にクライアントが HiveServer2/Kyuubi に接続してくる際に検証する値です。そのためPostgreSQL アカウント変更と設定再生成の両方を行う必要があります。片方だけでは metastore または HiveServer2 のどちらかが死にます。

手動手順

次の場合にこの手順を使用します — 自動ローテーションが扱わない変数（TLS keystore/truststore、Spark · TSE · Gravitino · Kestra アカウントなど）、およびワーカーノードがありスクリプトが拒否する環境です。それ以外では bin/passwd.sh がこの手順を代行します。

1ステップ — サーバー側アカウント変更

古いパスワードで接続して変更します。このステップをスキップすると残りがすべて無意味になります。

PostgreSQL （アカウント3つ — 変更するもののみ）:

psql -U plantpulse -c "ALTER USER plantpulse PASSWORD '새비밀번호';"
psql -U temporal   -d temporal -c "ALTER USER temporal PASSWORD '새비밀번호';"
psql -U hive       -d hive     -c "ALTER USER hive     PASSWORD '새비밀번호';"

Aster TSDB:

cqlsh -u cassandra -p 구비밀번호 \
  -e "ALTER ROLE cassandra WITH PASSWORD = '새비밀번호';"

Aster TSDB は変更直後 約2秒間、新旧どちらでも接続できません。 cassandra.yaml の credentials_validity（デフォルト 2000ms）資格情報キャッシュのためです。変更直後の接続失敗を見ても失敗と判断せず、3〜5秒後に再確認してください。

Valkey · RustFS · Kafka · MQTT はサーバー側に保存されたアカウントがありません — 設定ファイルと起動環境変数が正本であるため、このステップは不要です。

⚠ 変更直後に必ず新しいパスワードで接続してみてください

ALTER USER は誤った値を入れても成功（ALTER ROLE）を返します。 成功メッセージは「コマンドが実行された」という意味だけで、「意図した値が入った」という保証ではありません。

最も一般的な事故はクォート処理の失敗です。シェル変数をシングルクォート内に入れると展開されず、文字通り保存されます。

# ✗ 위험 — 변수가 확장되지 않아 '$NEW_PW' 라는 문자열이 비밀번호가 된다.
#          그런데도 ALTER ROLE 은 성공을 반환한다.
psql -U hive -c 'ALTER USER hive PASSWORD "$NEW_PW";'

# ✓ 안전 — 값을 직접 적거나, 확장되는 문맥인지 확인한다
psql -U hive -c "ALTER USER hive PASSWORD '실제새비밀번호';"

そのため各アカウントを変更した直後にその場で接続を確認してください。次のステップに進んでから発見すると原因を特定しにくくなります。

PGPASSWORD='새비밀번호' psql -U hive -h 127.0.0.1 -d postgres -w -tAc "SELECT 1"
# 1 이 나오면 정상. 인증 실패면 값이 의도와 다르게 들어간 것이다.

接続できない場合は古いパスワードがまだ有効かをまず確認してください。有効であれば変更が反映されていないことで、新旧両方ダメなら意図しない値が入ったことなので、その値を見つけて再接続し修正する必要があります。

パスワードにシングルクォート（'）が含まれる場合、SQL/CQL 文内では2つにエスケープする必要があります（a'b → 'a''b'）。

2ステップ — 保管庫（サイドカー）更新

このステップを忘れると次の再起動で古いパスワードが再注入されます。

設定正本は /etc/kopens/plantpulse-platform.env の1つです

プラットフォームの秘密は repo ツリー外の /etc/kopens/ に 0600 としてあります。正本は1ファイルのみです。

ls -l /etc/kopens/

ファイル	状態
/etc/kopens/plantpulse-platform.env	正本 — platform · ai · studio の3製品共通規約（plantpulse-<product>.env）
/opt/kopens/plantpulse-platform.env	2026-08-25 〜 08-29 にのみ使われたパス。読みも書きもしません — 残っていればインストールスクリプトが正本に戻します

platform.env.generated はもう存在しません（2026-08-22 削除）。同じ理由で platform-credentials.txt も廃止されました（2026-08-16） — 同じ秘密を2つ持っていたのにローテーションエンジンがそのファイルを更新せず、パスワード変更後も古い値を案内していました。値を参照するときもサイドカー1つだけを見ます。

sudo vi /etc/kopens/plantpulse-platform.env

該当する export PP_..._PASSWORD=... 行を新しい値に修正します。ファイル権限は 0600 を維持してください。

sudo chmod 600 /etc/kopens/plantpulse-platform.env

3ステップ — 再起動

ホストでスタックを再起動します。設定再生成は起動プロセスに含まれています。

cd /opt/kopens/plantpulse-platform-docker/bin
./restart.sh       # graceful drain → 재기동 → 준비될 때까지 대기 (0 = 쓸 수 있다)

データレイクコンテナは起動時にテンプレートを再レンダリングします。したがってコンポーネント設定ファイルを直接修正すると、再起動時にテンプレート値に戻ります。 設定はホストの /etc/kopens/conf （コンテナの plantpulse-datalake-cli/config/templates にバインドマウント）で変更してください。

アプリ6つはテンプレートをレンダリングしません — compose が渡した環境変数のみで値を受け取ります。

4ステップ — 検証

# 플랫폼 전체 상태 (호스트에서) — 0 = 정상 / 2 = 비정상
cd /opt/kopens/plantpulse-platform-docker/bin
./status.sh
./ops-check.sh

# 각 컴포넌트가 새 비밀번호로 실제 접속되는지 (데이터레이크 컨테이너 안에서)
./shell.sh
/opt/kopens/plantpulse-platform/plantpulse-datalake-cli/bin/pd node psql -c "SELECT 1;"
/opt/kopens/plantpulse-platform/plantpulse-datalake-cli/bin/pd node cql -e "SELECT now() FROM system.local;"
exit

ヘルス API が OK または WARN を返せば正常です。

curl -kfsS https://<server-ip>:4950/api/health | jq .status

クラスター（マルチノード）環境

ワーカーノードがある環境ではマスターだけ変更してはいけません。

ワーカーノードも自前の /etc/kopens/plantpulse-platform.env を持ちコンテナに注入します。マスターだけで変更するとワーカーが古いパスワードのまま残り、クラスターが半分しか動作しません。

すべてのワーカーノードで**2ステップ（サイドカー更新）と3ステップ（再起動）**を同様に実施してください。1ステップ（サーバー側変更）は共有リソースなので1回だけ行えば十分です。

失敗したとき

症状	原因	対処
変更直後にすべてのコンポーネントで認証失敗	1ステップのみ実施し3ステップ未実施	ホストで bin/restart.sh
再起動後に古いパスワードに戻る	2ステップ（サイドカー）漏れ	/etc/kopens/plantpulse-platform.env 修正後再起動。サイドカーが bin/env.sh もシェル export も勝ちます
Aster TSDB のみ接続失敗	資格情報キャッシュ（2秒）	3〜5秒後に再確認
Hive/Kyuubi は動くが metastore エラー	PostgreSQL hive アカウント未変更	1ステップの ALTER USER hive を実施
ALTER ROLE は成功したが接続失敗	クォートミスで意図と異なる値が保存された	1ステップの検証手順参照 — 成功返却は値の正確性を保証しない
特定経路のみ失敗	一部設定ファイル未更新	データレイクコンテナ内で pd config render 再実行後、下記コマンドで残存確認

デプロイされた設定に置換されていないプレースホルダーが残っていないか確認:

# 데이터레이크 컨테이너 안에서
grep -rn '\${PP_' /opt/kopens/plantpulse-platform/ \
  --include='*.conf' --include='*.properties' --include='*.xml' --include='*.yaml' \
  | grep -v '/plantpulse-datalake-cli/config/templates/'
# 아무것도 나오지 않아야 정상입니다

途中で失敗し片方だけ変わった状態なら、どのパスワードが有効かから確認してください。

PGPASSWORD='구비밀번호' psql -U plantpulse -h 127.0.0.1 -c "SELECT 1;"   # 구 값으로 접속되는가
PGPASSWORD='새비밀번호' psql -U plantpulse -h 127.0.0.1 -c "SELECT 1;"   # 신 값으로 접속되는가

• 古い値で接続できる → 1ステップが適用されていません。1ステップから再実施してください。
• 新しい値で接続できる → 1ステップは完了しています。2・3ステップのみ実施すれば十分です。

コントロールセンター（ppctl）オペレーターアカウント

現行コンテナ出荷版ではこの画面にアクセスできません

compose スタックのどのコンテナも9700ポートをホストに publish しません。 systemctl restart ppctl もコンテナ内で動くスタックには該当しません。

以下の内容はコントロールセンターを別途運用する環境のために残されたものです。コンテナ環境でプラットフォームを起動・停止・制御する方法はシステム起動および停止の共通動詞（up.sh · down.sh · restart.sh · status.sh）です。

前述の手順と完全に別個のパスワードがもう1つあります。コントロールセンター（ppctl）は ポート 9700 で動く別のWeb画面で、独自のログインアカウントを使用します。このアカウントは プラットフォームWebコンソールアカウントでも、上記のインフラサービスアカウントでもありません。

デフォルト値のままにしないでください

コントロールセンターはプラットフォーム全体を root 権限で起動・停止・制御する画面です。 環境変数を設定しないとすべてのインストールで同一の開発用デフォルトアカウント（ユーザー名 admin）で ログインされます。コミッショニング時に必ず変更してください。

変更方法

環境変数2つで決定します。値を指定するとデフォルト値の代わりにその値が使用されます。

環境変数	用途
PP_CONTROL_USER	コントロールセンターログインユーザー名
PP_CONTROL_PASSWORD	コントロールセンターログインパスワード

1. コントロールセンターを起動する環境（サイドカー /etc/kopens/plantpulse-platform.env または systemd ユニット ppctl.service の Environment=）に上記2つの値を設定します。

2. コントロールセンターを再起動します。

   systemctl restart ppctl

3. https://[HOST]:9700 に新しい値でログインできるか確認します。

このアカウントは画面上で変更する機能がありません。環境変数を修正して再起動することが 唯一の変更方法です。

PP_CONTROL_NOAUTH は運用で有効にしないでください

PP_CONTROL_NOAUTH=1（または JVM オプション -Dppctl.noauth=1）を指定すると、コントロールセンターの ログインが丸ごと無効化されます。信頼ネットワークデモ用スイッチで、デフォルト値は OFF です。

ポート9700 に到達できる誰もが認証なしでプラットフォーム全体を制御できるようになるため、 運用環境では有効にせず、ファイアウォールで9700へのアクセスもオペレーター帯域に制限してください。

注意事項

• パスワードにシングルクォート（'）を使用する場合、SQL/CQL 文内では2つにエスケープする必要があります（a'b → 'a''b'）。
• 変更履歴と新しいパスワードは安全な場所に保管してください。/etc/kopens/platform-credentials.txt に現在値が記録されますが、このファイルは平文であるため、権限（0600）を必ず維持する必要があります。
• CEP · Data Gateway の API キー（PP_CEP_API_KEY · PP_DATA_GATEWAY_API_KEY）はサーバーとコンシューマーが同じ値をそれぞれ読み取って比較する方式です。片方だけ変更すると即座に401が発生するため、両方を同時に変更する必要があります。両キーとも自動ローテーションの対象です。
• 自動ローテーションが残す /etc/kopens/rotation.journal には新・旧の値がエンコードされて記録されます。サイドカーと同じ機密性なので、権限 0600 を維持してください。

関連ドキュメント

• セキュリティ設定
• ユーザー管理 — Webコンソールログインアカウント（このドキュメントとは別です）
• 環境変数リファレンス
• トラブルシューティング