비밀번호 · API 키 바꾸기

데이터레이크의 서비스 계정(PostgreSQL · Cassandra · Valkey · MinIO · Kafka/MQTT …)과 API 키는 모든 설치본이 같은 기본값으로 시작합니다. 커미셔닝 때 반드시 바꾸고, 그 뒤로는 정책에 따라 회전합니다.

바꾸는 도구는 호스트의 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_MINIO_PASSWORD   # 여러 개를 한 번에 — 재시작 1회
bin/passwd.sh --dry-run PP_MQ_PASSWORD     # 계획만 — 아무것도 바꾸지 않는다

파일을 열어 비밀번호 줄을 고치지 마세요

비밀번호는 두 곳에 따로 있습니다 — 서버가 받아들이는 값(PostgreSQL 계정, Cassandra role …)과 클라이언트가 제시하는 값(설정 파일 20여 개). 둘은 자동으로 맞춰지지 않습니다. 사이드카만 고치면 다음 재시작에서 모든 클라이언트가 인증에 실패하고, 서버만 바꾸면 지금 당장 실패합니다.

passwd.sh 는 ① 서버 쪽 계정 변경 → ② 사이드카 갱신 → ③ 설정 재렌더 → ④ 재시작을 한 명령 안에서 순서대로 합니다.

바꿀 수 있는 키

키는 환경 변수 이름 그대로입니다. 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 — 한 값을 공유	`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

세 갈래의 뜻:

명령 — 서버 계정이 정본입니다. SQL/CQL 로 바꾸고, 설정 파일은 접속용 사본일 뿐입니다.
파일 — 렌더된 그 파일이 곧 정본입니다. 재렌더 + 재시작으로만 바뀝니다.
기동 env — 프로세스 기동 때 주입됩니다. 런타임 변경 API 가 없어 재시작이 유일한 반영 수단입니다.

계정 이름(PP_*_USER)은 바꾸지 않습니다. --list 에 표시만 됩니다. 계정명 변경은 서버 쪽 role 생성과 권한 이관이 따라와야 하는 다른 작업입니다.

--list 에 관리 콘솔 키 둘이 안 보인다면

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                       # 결과 확인 — 값이 그대로 찍히니 화면 공유 중에는 치지 마세요

반드시 점검 창에서 하세요. 회전 중 재시작이 한 번 있고, Kafka/MQTT 경로는 그동안 끊깁니다.
작업 전 백업을 확보하세요.
바꾼 값은 사이드카 /etc/kopens/plantpulse-platform.env 에만 있습니다. 인계 문서에는 값이 아니라 «누가 보관하는지» 를 적으세요.

절차 — 운영 중 하나씩

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://<서버IP>:4950/api/health | jq .status               # OK 또는 WARN

실패했을 때 — 같은 명령을 다시

회전은 롤백하지 않습니다. 실패 시점에는 어느 값이 유효한지 불확실해서 되돌리는 시도가 상태를 더 망가뜨립니다. 대신 전진 복구합니다.

호스트의 /etc/kopens/rotation.journal(0600)에 신 · 구 값이 선행 기록돼 있습니다. 같은 명령을 그대로 다시 실행하면 각 컴포넌트가 지금 어느 값을 받아들이는지 판정(probe)해서 이어서 합니다. 이미 바뀐 것은 건너뜁니다.

메시지	뜻	조치
`probe=NEITHER`	신 · 구 어느 값으로도 접속되지 않음	자동화가 판단할 근거가 없습니다. 사람이 그 컴포넌트에 직접 접속해 상태를 확인하세요
`apply` 실패	서버 쪽 변경 실패, 즉시 중단	원인을 고치고 같은 명령 재실행
`verify` 실패	서버는 바뀌었는데 신 값으로 접속 불가	가장 위험합니다. 저널이 `APPLIED` 로 남습니다 — 사람이 확인해야 합니다
`configure` 실패	재시작하지 않고 중단	의도된 동작입니다(구 설정으로 뜨면 전부 인증 실패). 원인을 고치고 재실행
`variable not in the registry`	등록되지 않은 키	아래 회전되지 않는 값

워커 노드가 있으면 거부합니다

클러스터 워커가 설정돼 있으면 회전 도구는 거부하고 중단합니다. 워커마다 사이드카가 따로 있어 마스터만 회전하면 워커가 옛 값으로 남아 클러스터가 반쪽이 되기 때문입니다. 워커가 있는 환경은 수동 절차를 따르고, 워커마다 사이드카 갱신과 재시작을 반복하세요.

`PP_MQ_PASSWORD` — Kafka 와 HiveMQ 는 함께 바뀝니다

한 값이 두 브로커의 서버 쪽 자격 저장소이자 클라이언트 전부의 접속 비밀번호입니다. 따로 바꿀 수 없고, 회전 도구의 검증은 둘 다 새 값으로 붙어야 성공으로 칩니다.

정적 JAAS 는 신 · 구 값을 동시에 받아들이지 못하므로, 브로커와 소비자가 순차 재시작되는 동안 MQ 경로가 끊깁니다. 무중단 회전은 지원 범위가 아닙니다.

`PP_HIVE_PASSWORD` — 값 하나가 양방향으로 쓰입니다

Hive 메타스토어가 PostgreSQL 에 접속할 때 제시하는 값이면서, 동시에 클라이언트가 Kyuubi 에 접속해 올 때 검증하는 값입니다. 그래서 회전 도구가 PostgreSQL 계정 변경과 설정 재렌더를 둘 다 합니다. 수동으로 할 때 하나만 하면 메타스토어나 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 로 끊고 다른 값으로 다시 시작하지 마세요. 저널이 첫 값을 기억합니다. 같은 값으로 재실행해 끝낸 뒤 다시 바꾸세요.

바꿀 수 있는 키​

절차 — 처음 한 번​

절차 — 운영 중 하나씩​

실패했을 때 — 같은 명령을 다시​

PP_MQ_PASSWORD — Kafka 와 HiveMQ 는 함께 바뀝니다​

PP_HIVE_PASSWORD — 값 하나가 양방향으로 쓰입니다​

회전되지 않는 값 — 수동으로​

하지 마세요​

관련 문서​