Skip to main content

Changing Passwords · API Keys

The data lake's service accounts (PostgreSQL · Aster TSDB · Valkey · RustFS · Kafka/MQTT …) and API keys all start with the same default values across every installation. You must change them during commissioning, and then rotate them according to policy thereafter.

The tool for changing them is one on the host: bin/passwd.sh.

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_S3_PASSWORD   # 여러 개를 한 번에 — 재시작 1회
bin/passwd.sh --dry-run PP_MQ_PASSWORD     # 계획만 — 아무것도 바꾸지 않는다
Do not edit the password lines in a file directly

Passwords exist in two separate places — the values the servers accept (PostgreSQL accounts, Aster TSDB roles …) and the values the clients present (in about 20 configuration files). These two are not automatically synchronized. If you change only the sidecar, all clients will fail authentication on the next restart; if you change only the servers, they will fail immediately.

passwd.sh performs ① changing the server-side account → ② updating the sidecar → ③ re-rendering the configuration → ④ restarting, all in a single command, in order.

Keys You Can Change​

Keys are exactly the environment variable names. There are no aliases like postgres · mq — --list tells you which key corresponds to which component.

KeyComponentAccountWhere the canonical value lives
PP_PG_PASSWORDPostgreSQLplantpulseCommand — ALTER ROLE (psql)
PP_TEMPORAL_PASSWORDTemporal's backend PostgreSQL accounttemporalCommand — ALTER ROLE (psql)
PP_HIVE_PASSWORDHive metastore's PostgreSQL account + Kyuubi inbound authenticationhiveCommand — ALTER ROLE (psql) + re-render
PP_CASSANDRA_PASSWORDAster TSDBcassandraCommand — ALTER ROLE (cqlsh)
PP_REDIS_PASSWORDValkey—File — plantpulse-storage/cache/valkey/conf/valkey.conf
PP_S3_PASSWORDRustFSrustfsStartup env — RUSTFS_SECRET_KEY
PP_MQ_PASSWORDKafka + HiveMQ — shares a single valuemqFile — kafka/config/jaas.conf + mqtt/conf/auth.properties
PP_CEP_API_KEYCEP API key (X-API-Key)—File — plantpulse-cep/config/plantpulse-cep.properties
PP_DATA_GATEWAY_API_KEYData gateway API key—File — plantpulse-data-gateway/config/plantpulse-jdbc.properties
PP_DATALAKE_ADMIN_PASSWORDManagement console loginadminStartup env — admin-api reads it from its own environment variables
PP_DATALAKE_ADMIN_API_KEYManagement console log endpoint X-API-Key—Startup env

What the three categories mean:

  • Command — The server account is the canonical value. Change it via SQL/CQL; the configuration file is merely a copy used for connection.
  • File — The rendered file itself is the canonical value. It only changes through re-render + restart.
  • Startup env — Injected when the process starts. There's no runtime change API, so a restart is the only way to apply it.

Do not change the account names (PP_*_USER). They are only displayed in --list. Changing account names is a different task that requires server-side role creation and permission migration to follow.

If you don't see the two management console keys in --list

PP_DATALAKE_ADMIN_PASSWORD · PP_DATALAKE_ADMIN_API_KEY were added on 2026-09-05. Installation packages from before that date contain only 9 keys. In that case, the console password has no server-side account, so you edit the sidecar directly and restart → Web Console Login Accounts

Procedure — First Time Only​

During commissioning, rotate all registered keys to random values. --all is an option of the rotation engine rotate-secret.sh, not passwd.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                       # 결과 확인 — 값이 그대로 찍히니 화면 공유 중에는 치지 마세요
  • Do this during a maintenance window, without exception. There is one restart during the rotation, and the Kafka/MQTT paths are interrupted during that time.
  • Secure a backup before starting.
  • The changed values reside only in the sidecar /etc/kopens/plantpulse-platform.env. In the handover documentation, record who holds the values, not the values themselves.

Procedure — One at a Time During Operation​

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

When finished, verify.

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

On Failure — Run the Same Command Again​

Rotation is not rolled back. At the point of failure, it is unclear which value is valid, so attempting to revert can further corrupt the state. Instead, you recover forward.

The host's /etc/kopens/rotation.journal(0600) has the new and old values pre-appended. Running the same command again lets the tool probe which value each component currently accepts and continue from there. Already-changed components are skipped.

MessageMeaningAction
probe=NEITHERNot connectable with either the new or old valueThe automation has no basis to decide. A person must connect directly to that component and check its status
apply failedServer-side change failed, immediately haltedFix the cause and re-run the same command
verify failedServer was changed, but connecting with the new value failsMost dangerous. The journal remains as APPLIED — a person must check it
configure failedHalted without restartingThis is intentional behavior (if it started with the old config, everything would fail authentication). Fix the cause and re-run
variable not in the registryUnregistered keySee Values Not Rotated — Manually below
Rejected if worker nodes exist

If cluster workers are configured, the rotation tool refuses and halts. Each worker has its own sidecar, so rotating only the master would leave workers with the old value, halving the cluster. In environments with workers, follow the manual procedure and repeat the sidecar update and restart for each worker.

PP_MQ_PASSWORD — Kafka and HiveMQ Change Together​

One value serves as both the server-side credential store for the two brokers and the connection password for all clients. You cannot change them separately, and the rotation tool's validation only succeeds if both brokers connect with the new value.

Static JAAS cannot accept both the new and old values simultaneously, so the MQ path gets interrupted while the broker and consumers are restarted sequentially. Zero-downtime rotation is not supported.

PP_HIVE_PASSWORD — One Value Is Used in Both Directions​

It is the value that the Hive metastore presents when connecting to PostgreSQL, and simultaneously the value that the server validates when a client connects to Kyuubi. Therefore, the rotation tool performs both the PostgreSQL account change and the configuration re-render. If you do only one of these manually, either the metastore or Kyuubi will die.

Values Not Rotated — Manually​

If you provide a key that's not in the registry, the tool rejects it rather than silently skipping it. The following are not yet registered, and you change them via the manual procedure.

VariableWhatKey point of manual change
PP_SPARK_PASSWORDSpark/Kyuubi client accountNo server account exists. hive-auth.properties creates the account with this value — sidecar update + restart
PP_TSE_PASSWORDTime series engine accountSidecar update + restart
PP_GRAVITINO_PASSWORD · PP_KESTRA_DB_PASSWORDRespective backend PostgreSQL accountsThe data lake sets the PostgreSQL role password to the sidecar value at every boot — sidecar update + restart
PP_KESTRA_ADMIN_PASSWORDKestra adminWeb Console Login Accounts
PP_TLS_KEYSTORE_PASSWORD (+ derived truststore set)Certificates as a wholeTied to certificate re-issuance → Security Settings
PP_OPCUA_PASSWORDOPC-UA server (app container)Outside the data lake
PP_API_KEY · PP_FLOW_WEBHOOK_API_KEYFor external callers (app container)Outside the data lake
PP_DATA_GATEWAY_WEB_PASSWORD · PP_CEP_WEB_PASSWORDQuery console browser loginDecision made on 2026-09-07 that this is not a rotation target. Sidecar update + restart → Web Console Login Accounts

What Not to Do​

  • Do not run pd secret rotate directly inside a container. The rotation journal and sidecar must reside on the host to survive container recreation. The host's passwd.sh invokes it.
  • Do not expect to modify the default password values in bin/env.sh to take effect. The sidecar wins.
  • Do not paste --list --show output into tickets or chat.
  • Do not interrupt the rotation with Ctrl+C and then start again with a different value. The journal remembers the first value. Re-run with the same value to finish, then change it again.