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

概要

PlantPulse は内部インフラ コンポーネント(PostgreSQL · Cassandra · Valkey · MinIO · 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_MINIO_PASSWORD	minio	—
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 キーストア/トラストストア パスワード(証明書交換と関連し別扱い)です。 これらはスクリプトが拒否するため、手動手順で変更してください。 クエリ コンソール ログイン 2つ(PP_DATA_GATEWAY_WEB_PASSWORD · PP_CEP_WEB_PASSWORD)はローテーション対象ではないという決定です。サイドカー更新 + 再起動で変更します → ウェブ画面ログイン アカウント。

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_MINIO_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	Cassandra	コマンド — ALTER ROLE (cqlsh)
PP_REDIS_PASSWORD	Valkey	ファイル — plantpulse-storage/cache/valkey/conf/valkey.conf
PP_MINIO_PASSWORD	MinIO	起動 env — MINIO_ROOT_PASSWORD
PP_MQ_PASSWORD	Kafka + HiveMQ (1つの値を共有します)	ファイル — 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)は変更しません。 表示するだけです — アカウント名の変更はサーバー側のロール作成と権限引き継ぎを必要とする別の作業です。

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

レジストリにないキーを指定すると、無視せず拒否します。 タイプミスは類似したキーを提案します。

MQ(Kafka · HiveMQ)ローテーション (設計段階)

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

PP_MQ_PASSWORD が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 が設定されていると、スクリプトが拒否して中止します。 ワーカー ノードごとに独自の /etc/kopens/plantpulse-platform.env があり、マスターのみを変更するとワーカーが古いパスワードのまま残り、クラスターが半分になります。 部分的な成功が最悪の失敗なため、無言でマスターのみを処理しません。

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

順序が重要な理由

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

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

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

変更可能なアカウント

자동 회전 列が「対象」であるものは passwd.sh で変更します。 手動手順は、その他の値とワーカーがある環境のためのものです。

環境変数	対象	サーバー側変更が必要	自動ローテーション(予定)
PP_PG_PASSWORD	PostgreSQL アカウント plantpulse	必要	対象
PP_TEMPORAL_PASSWORD	PostgreSQL アカウント temporal (Temporal バックエンド)	必要	対象
PP_HIVE_PASSWORD	PostgreSQL アカウント hive (Hive メタストア) + Hive/Kyuubi 接続認証	必要	対象
PP_CASSANDRA_PASSWORD	Cassandra ロール	必要	対象
PP_REDIS_PASSWORD	Valkey requirepass	不要 (設定ファイル)	対象
PP_MINIO_PASSWORD	MinIO ルート クレデンシャル	不要 (起動時注入)	対象
PP_MQ_PASSWORD	Kafka SASL · MQTT ブローカー	不要 (設定ファイル)	対象 (MQ ローテーション)

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

PP_HIVE_PASSWORD は1つの値が双方向で使用されます。 Hive メタストアが PostgreSQL に接続するときに提示する値であり、同時にクライアントが HiveServer2/Kyuubi に接続してくるときに検証する値です。 したがってPostgreSQL アカウント変更と設定再生成の両方を実行する必要があります。 一方だけ実行するとメタストアまたは HiveServer2 のどちらかが停止します。

手動手順

次の場合にこの手順を使用します — 自動ローテーションが対応していない変数(TLS キーストア/トラストストア、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 '새비밀번호';"

Cassandra:

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

Cassandra は変更直後、約2秒間、新旧どちらのパスワードでも接続できません。 cassandra.yaml の credentials_validity(デフォルト 2000ms) クレデンシャル キャッシュのためです。 変更直後の接続失敗を見ても、失敗と判定せず、3~5秒後に再度確認してください。

Valkey · MinIO · 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つです

プラットフォームのシークレットはリポジトリ ツリーの外である /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 も上書きします
Cassandra のみ接続失敗	クレデンシャル キャッシュ(2秒)	3~5秒後に再度確認
Hive/Kyuubi は動作するがメタストア エラー	PostgreSQL hive アカウント未変更	ステップ1の ALTER USER hive 実行
ALTER ROLE は成功しているが接続失敗	引用符ミスで意図と異なる値が保管された	ステップ1の検証手順参照 — 成功返却は値の正確性を保証しない
特定のパスのみ失敗	一部設定ファイル未更新	データレイク コンテナー内で ./configure.sh 再実行後、下記のコマンドで残存確認

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

# 데이터레이크 컨테이너 안에서
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をホストに公開していません。 systemctl restart ppctl もコンテナー内で実行されるスタックには該当しません。

以下の内容は、コントロール センターを別途運用する環境向けのものです。 コンテナー環境でプラットフォームを起動・停止・制御する方法は システムの起動と停止の共通動詞(up.sh · down.sh · restart.sh · status.sh)をご覧ください。

前の手順とまったく別のパスワードがもう1つあります。 コントロール センター(ppctl)はポート9700で実行される別のウェブ画面で、独自のログイン アカウントを使用します。 このアカウントは、プラットフォーム ウェブ コンソール アカウントでもなく、上記のインフラ サービス アカウントでもありません。

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

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

変更方法

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

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

1. コントロール センターを起動する環境(plantpulse-startup の環境ファイルまたは systemd ユニット ppctl.service の Environment=)上記の2つの値を設定します。

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

   systemctl restart ppctl

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

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

PP_CONTROL_NOAUTH は本番環境で有効にしないでください

PP_CONTROL_NOAUTH=1(または JVM オプション -Dppctl.noauth=1) を指定すると、コントロール センターのログインが完全に無効化されます。 信頼できるネットワーク デモ用スイッチであり、デフォルトは無効です。

ポート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が発生するため、両方を同時に変更する必要があります。 2つのキーとも自動ローテーションの対象です。
• 自動ローテーションが残す /etc/kopens/rotation.journal には、新旧値がエンコードされて記録されます。 サイドカーと同じ機密度であるため、権限 0600 を保つしてください。

関連ドキュメント

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