2노드 분리 설치 (데이터레이크 / 애플리케이션)

개요

PlantPulse 플랫폼을 데이터레이크 노드와 애플리케이션 노드 두 대의 서버에 나눠 설치하는 방법입니다. 단일 박스(FULL) 설치와 달리 저장소·메시징·분석 계층과 콘솔·배치 계층이 서로 다른 박스에서 동작하므로, 대용량 배치 작업(아카이브 등)이 콘솔 응답성에 영향을 주지 않고 노드별 메모리 요구량도 낮아집니다.

언제 사용하나요? 단일 서버 메모리가 128GB 이하이거나, 데이터 처리 부하와 콘솔 서비스를 분리해 안정성을 높이고 싶을 때 적합합니다. 한 대로 충분한 환경(권장 256GB)이라면 원라인 설치의 기본(FULL) 설치를 사용하세요.

티어(PP_TIER) 개념

설치 시 PP_TIER 환경 변수로 노드의 역할을 지정합니다.

PP_TIER	역할	기동 서비스
FULL (기본값)	단일 박스 올인원	전체 (미지정 시 기존 설치와 완전 동일)
DATALAKE	데이터레이크 노드	Cassandra · PostgreSQL · Kafka · MQTT · Redis · MinIO · Spark · Hive · TSE · CEP · Data Gateway · Temporal · Kestra · Monitor 등 인프라 계층
APP	애플리케이션 노드	Server(콘솔 80/443) · Batch · Warehouse · OPC-UA · AASX · HA 등 애플리케이션 계층

• PP_TIER는 클러스터링 변수 PP_MODE(MASTER/WORKER)와 독립입니다.
• APP 노드의 모든 데이터레이크 접속(호스트 변수)은 PP_MASTER_IP(데이터레이크 노드 IP)로 자동 연결됩니다.

노드별 설정 파일 (복사 대상 vs 노드별)

2노드 설치에서 /etc/kopens/의 파일은 역할이 서로 다릅니다. 무엇을 복사하고 무엇을 복사하면 안 되는지가 가장 중요합니다.

파일/디렉터리	내용	성격	노드 간 복사
/etc/kopens/plantpulse-platform.env	서비스 시크릿 사이드카 (DB/메시징 비밀번호 등)	클러스터 공유	✅ 복사 대상
/etc/kopens/ca/	공유 클러스터 CA (CA.crt/CA.key) — 노드 간 TLS 신뢰	클러스터 공유	✅ 복사 대상
/etc/kopens/platform.node.env	노드 토폴로지 (PP_TIER, PP_MASTER_IP) — 설치 시 자동 기록	노드별 정체성	❌ 복사 금지

경로 확인 — 시크릿 사이드카의 정본은 /etc/kopens/plantpulse-platform.env 하나입니다(권한 0600). 옛 설치에서 /opt/kopens/ 밑에 같은 이름이 남아 있을 수 있지만 읽지 않으며, 설치 스크립트가 정본으로 되돌립니다 → 환경 변수 레퍼런스

• platform.node.env는 설치 시 stack-run.sh가 자동 생성·기록하며, 이 파일 덕분에 재시작·업그레이드 후에도 노드가 자기 티어를 기억합니다.
• 토폴로지(PP_TIER)를 시크릿 사이드카가 아닌 별도 파일에 두는 이유: 사이드카는 앱 노드로 그대로 복사되는 파일이라, 여기에 티어가 들어 있으면 데이터레이크 노드의 티어가 앱 노드로 새어 들어가 앱 노드가 DATALAKE로 잘못 설치됩니다.

노드별 요구 사양

노드	최소 사양	비고
데이터레이크	16 vCPU / 64GB RAM / 500GB+ 디스크	데이터 저장량에 따라 디스크 증설
애플리케이션	8 vCPU / 48GB RAM / 100GB 디스크	실측 상주 약 35GB

두 노드는 같은 네트워크에서 서로 도달 가능해야 합니다(포트 목록은 아래 방화벽 절 참고).

설치 절차

1단계 — 데이터레이크 노드 설치

데이터레이크로 사용할 서버에서 실행합니다.

sudo -i
export PP_TIER=DATALAKE
curl -fsSL https://product.kopens.io/plantpulse-platform/install.sh | bash

• 부팅 게이트는 티어를 자동 인식합니다. 데이터레이크 노드는 모니터 헬스(:4950/api/health)가 OK/WARN이 될 때까지 대기한 뒤 스택 전체 준비 판정(bin/stack-verify-boot.sh)을 통과해야 설치 성공으로 봅니다.
• 설치가 완료되면 조인 번들이 자동으로 생성됩니다:
  • /etc/kopens/plantpulse-platform.env — 서비스 시크릿 (클러스터 공유)
  • /etc/kopens/ca/ — 공유 클러스터 CA (노드 간 TLS 신뢰)

데이터레이크 노드가 클러스터의 CA 발급 권위입니다. 애플리케이션 노드는 이 CA를 받아 재사용하므로 노드 간 TLS(CEP 이벤트 채널)가 자동으로 신뢰됩니다.

2단계 — 조인 번들 복사

데이터레이크 노드에서 애플리케이션 노드로 두 항목을 복사합니다.

# 데이터레이크 노드에서 실행 (<app-ip> = 애플리케이션 노드 IP)
scp /etc/kopens/plantpulse-platform.env root@<app-ip>:/etc/kopens/
scp -r /etc/kopens/ca root@<app-ip>:/etc/kopens/

주의: /etc/kopens/platform.node.env 파일은 복사하면 안 됩니다. 이 파일은 노드의 티어 정체성(자기 역할)을 담는 노드별 파일입니다. 복사 대상은 위 두 항목뿐입니다(노드별 설정 파일 참고).

구버전으로 설치했던 서버라면 platform.env.generated 안에 export PP_TIER=... 줄이 남아 있을 수 있습니다. 최신 설치 스크립트가 자동으로 제거(마이그레이션)하지만, 복사 전에 해당 줄을 지우는 것이 안전합니다.

3단계 — 애플리케이션 노드 설치

애플리케이션 노드에서 실행합니다. PP_MASTER_IP에 데이터레이크 노드 IP를 지정합니다.

sudo -i
export PP_TIER=APP
export PP_MASTER_IP=<데이터레이크 노드 IP>
curl -fsSL https://product.kopens.io/plantpulse-platform/install.sh | bash

• stack-run.sh가 조인 번들의 공유 CA(/etc/kopens/ca/)를 첫 기동 전에 pp-security 볼륨에 자동 적용(seed)합니다. 이후 인증서 준비 단계가 공유 CA로 이 노드의 인증서를 서명하고 truststore를 구성하므로, 데이터레이크 노드의 TLS 서비스(CEP 이벤트 채널 등)가 자동으로 신뢰됩니다.
• 모든 데이터레이크 백엔드(Cassandra/PostgreSQL/Kafka/Redis/MinIO/TSE/CEP 등) 접속이 PP_MASTER_IP로 자동 설정됩니다.
• 앱 노드에는 모니터(:4950)가 없으므로 부팅 게이트는 콘솔(:80/status) 200 응답 기준으로 수행됩니다.

방화벽 (데이터레이크 노드)

데이터레이크 노드에서 애플리케이션 노드의 접근을 허용해야 합니다. 가장 간단한 방법은 firewalld trusted zone에 애플리케이션 노드 IP를 추가하는 것입니다.

# 데이터레이크 노드에서 실행
firewall-cmd --permanent --zone=trusted --add-source=<app-ip>
firewall-cmd --reload

주요 크로스노드 포트: 9042(Cassandra) · 5432(PostgreSQL) · 9092/9093/9094(Kafka) · 1883/1884(MQTT) · 6379(Redis) · 9000(MinIO) · 7077(Spark) · 9083(Hive) · 10000(Kyuubi) · 19001(Gravitino) · 7800/7801(TSE) · 7400(CEP) · 5500(Data Gateway) · 7233(Temporal) · 4950(Monitor)

설치 확인

# 데이터레이크 노드 — 인프라 헬스 (OK 또는 WARN 이면 정상)
curl -kfsS https://127.0.0.1:4950/api/health | jq .status

# 애플리케이션 노드 — 콘솔 상태
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:80/status   # 200 이면 정상

웹 콘솔 접속: https://<애플리케이션 노드 IP> — 로그인까지 성공해야 최종 확인입니다 (초기 계정은 로그인 참고).

크로스노드 TLS (공유 CA) 확인

양 노드에서 CA 지문을 출력해 동일한지 확인합니다. 지문이 다르면 노드 간 TLS 신뢰가 깨져 있는 것입니다.

CA 자재는 pp-security 볼륨에 있고, 그 볼륨을 마운트한 컨테이너 안에서 읽습니다. 노드마다 물어볼 컨테이너가 다릅니다 — 데이터레이크 노드에는 plantpulse-datalake 가 있고, 앱 노드에는 없습니다.

# 데이터레이크 노드에서
docker exec plantpulse-datalake \
  openssl x509 -in /var/security/plantpulse/CA.crt -noout -fingerprint -sha256

# 애플리케이션 노드에서 (앱 컨테이너면 무엇이든 같은 볼륨을 읽습니다)
docker exec plantpulse-server-web \
  openssl x509 -in /var/security/plantpulse/CA.crt -noout -fingerprint -sha256

애플리케이션 노드 로그에 TLS 신뢰 오류(PKIX)가 0건인지 확인합니다.

# 애플리케이션 노드에서 — 아무 것도 출력되지 않아야 정상
grep -Rl "PKIX" /opt/kopens/plantpulse-platform-docker/logs 2>/dev/null

데이터레이크 연결 확인

애플리케이션 노드에서 데이터레이크 연결을 확인하려면:

앱 컨테이너는 데이터레이크의 설정 렌더러를 갖고 있지 않고 그쪽 env.sh 를 읽지도 않습니다. 앱이 보는 값의 정의처는 compose 하나뿐이므로, 컨테이너에 실제로 주입된 환경변수를 그대로 확인합니다.

# 애플리케이션 노드에서 — 백엔드 호스트가 데이터레이크 IP 로 잡혀 있는지
docker exec plantpulse-server-web env | grep -E '_HOST=|MASTER_IP='

값이 127.0.0.1 이면 PP_MASTER_IP 없이 설치된 것입니다.

재시작·업그레이드 시 동작

• 티어 정체성은 각 노드의 /etc/kopens/platform.node.env에 저장되어 재시작·업그레이드 후에도 유지됩니다. 재설치가 아닌 한 PP_TIER를 다시 지정할 필요가 없습니다.
• 컨테이너 이미지 업그레이드는 노드별로 기존 절차(update.sh)와 동일합니다.

티어 전환·재설치 시 주의

• 단일 박스(FULL)로 재설치할 때는 /etc/kopens/platform.node.env를 먼저 삭제해야 합니다. 이 파일이 남아 있으면 환경 설정이 파일을 자동으로 읽어 들여 이전 티어(DATALAKE/APP)로 부팅됩니다. PP_TIER 미지정(FULL) 설치는 이 파일을 덮어쓰지 않기 때문입니다.

  rm -f /etc/kopens/platform.node.env

• APP 노드를 FULL(단일 박스)로 전환하려면 클린 재설치해야 합니다. APP 노드에는 로컬 인프라(데이터베이스 스키마 등)가 초기화된 적이 없으므로, 컨테이너·볼륨·설정을 모두 제거한 뒤 처음부터 FULL로 설치하세요 (제거 절차는 Docker 설치의 완전 제거 절 참고).

문제 해결

증상	원인/조치
APP 노드 서비스가 127.0.0.1 로 접속 시도	PP_MASTER_IP 미지정 설치 — node.env 확인 후 재설치
재설치했는데 이전 티어로 부팅	/etc/kopens/platform.node.env 잔존 — 삭제 후 재설치 (티어 전환·재설치 시 주의)
앱 노드가 DATALAKE 로 설치됨	구버전 사이드카에 PP_TIER 줄 잔존 상태로 복사 — 사이드카에서 해당 줄 제거 후 재설치
CEP 이벤트 TLS 오류 (PKIX)	조인 번들의 ca/ 복사 누락(CA 지문 불일치) — 2단계 재수행 후 APP 노드 재설치
APP 노드에서 Kafka 발행 실패 (Expiring records)	데이터레이크 방화벽에서 APP 노드 미허용, 또는 구버전 설치 스크립트 — 방화벽 확인 후 최신 스크립트로 재설치
로그인 화면에서 오류	APP 노드 부팅 초기 데이터레이크 연결 지연 — 콘솔 컨테이너 재시작(docker compose -f compose/docker-compose.yml restart plantpulse-server-web)