패치 및 업그레이드
이제 종합적인 답변을 작성하겠습니다.
exemONE 수집서버 패치 절차 가이드
exemONE 수집서버의 패치는 Binary 모드, Docker 모드, Kubernetes 모드 3가지 설치 방식에 따라 절차가 다릅니다. 각 모드별 모듈 패치, 패키지 업그레이드, 롤백 방법을 아래와 같이 설명드립니다.
1. Binary 모드 패치
참고: https://app.clickup.com/25540965/v/dc/rbeb5-403518/rbeb5-2772638
지원 환경
- Rocky 8, Rocky 9
- CPU 8 core / Memory 16 GB (인스턴스 1대 기준)
1-1. 전체 모듈 패치 (patch_all.sh)
patch_all.sh파일을$EXEMONE_HOME에 배치patch.tar파일을$EXEMONE_HOME에patch폴더 이름으로 압축 해제$EXEMONE_HOME/.env파일에 패치할 버전으로 수정patch_all.sh실행./onectl start all로 전체 모듈 실행
1-2. 개별 모듈 패치
모듈 유형에 따라 4가지 방식으로 패치를 진행합니다.
(1) 데이터 수집 모듈 패치 (alerter, ingester, gateway, receiver, cloud-agent, db-agent)
# 1. 패치 파일 업로드 후 압축 해제
tar -xvzf exemone-alerter-v3.0.504.15.0.tar.gz
# 2. 실행 파일 복사
cp exemone-alerter-v3.0.504.15.0/exemone-alerter-v3.0.504.15.0 $EXEMONE_HOME/bins/exemone-alerter/
# 3. 실행 권한 부여
chmod +x $EXEMONE_HOME/bins/exemone-alerter/exemone-alerter-v3.0.504.15.0
# 4. .env 파일 버전 수정
vi $EXEMONE_HOME/.env
# 5. 설정파일 백업 후 수정(필요시)
cp $EXEMONE_HOME/services/exemone-alerter/configs/alert.yml $EXEMONE_HOME/services/exemone-alerter/configs/alert.yml.bak
# 6. 모듈 재시작
./onectl restart alerter
(2) exemone-api 패치 (jar 파일)
# 1. 압축 해제
tar -xvzf exemone-api-v3.0.504.15.9.tar.gz
# 2. 버전 폴더 생성 및 jar 파일 복사
mkdir $EXEMONE_HOME/bins/exemone-api/v3.0.504.15.9/
cp -r exemone-api-v3.0.504.15.9/exemone-api-v3.0.504.15.9.jar $EXEMONE_HOME/bins/exemone-api/v3.0.504.15.9/
# 3. 실행 권한 부여
chmod +x $EXEMONE_HOME/bins/exemone-api/v3.0.504.15.9/exemone-api-v3.0.504.15.9.jar
# 4. .env 파일 버전 수정 후 재시작
./onectl restart api
(3) exemone-front 패치 (dist 폴더)
# 1. 압축 해제
tar -xvzf exemone-front-v3.0.504.15.9.tar.gz
# 2. dist 폴더 복사
cp -r exemone-front/dist $EXEMONE_HOME/bins/exemone-front
# 3. version.text 파일 복사
cp exemone-front/version.text $EXEMONE_HOME/services/exemone-front
# 4. .env 파일 버전 수정 후 재시작
./onectl restart front
(4) exemone-core 패치 (db 폴더 + 실행 파일)
# 1. core 프로세스 중지
./onectl stop core
ps -ef | grep core
# 2. 압축 해제
tar -xvzf exemone-core-v3.0.504.15.9.tar.gz
# 3. db 디렉터리 백업 및 교체 (ClickHouse 테이블 마이그레이션)
cp -r $EXEMONE_HOME/services/exemone-core/db $EXEMONE_HOME/services/exemone-core/db.bak
cp -r exemone-core-v3.0.504.15.9/db $EXEMONE_HOME/services/exemone-core/
# 4. 실행 파일 복사 및 권한 부여
cp exemone-core-v3.0.504.15.9/exemone-core-v3.0.504.15.9 $EXEMONE_HOME/bins/exemone-core/
chmod +x $EXEMONE_HOME/bins/exemone-core/exemone-core-v3.0.504.15.9
# 5. .env 파일 버전 수정 후 재시작
./onectl restart core
1-3. .env 파일 버전 수정 예시
vi $EXEMONE_HOME/.env
# 패치할 모듈의 버전을 변경
EXEMONE_ALERTER=exemone-alerter-v3.0.506.15.14
EXEMONE_API=exemone-api-v3.0.506.15.3
EXEMONE_CLOUD_AGENT=exemone-cloud-agent-v3.0.506.15.3
EXEMONE_CORE=exemone-core-v3.0.506.15.20
EXEMONE_DB_AGENT=exemone-db-agent-v3.0.506.15.9
EXEMONE_GATEWAY=exemone-gateway-v3.0.506.15.4
EXEMONE_INGESTER=exemone-ingester-v3.0.506.15.14
EXEMONE_RECEIVER=exemone-receiver-v3.0.506.15.7
EXEMONE_FRONT=exemone-front-v3.0.506.15.46
1-4. 모듈별 설정 파일 경로
| 모듈명 | 설정 파일 경로 |
|---|---|
| exemone-api | $EXEMONE_HOME/services/exemone-api/configs/application.yml |
| exemone-core | $EXEMONE_HOME/services/exemone-core/configs/core.yml |
| exemone-alerter | $EXEMONE_HOME/services/exemone-alert/configs/alert.yml |
| exemone-ingester | $EXEMONE_HOME/services/exemone-ingester/configs/ingester.yml |
| exemone-gateway | $EXEMONE_HOME/services/exemone-gateway/configs/gateway.yml |
| exemone-receiver | $EXEMONE_HOME/services/exemone-receiver/configs/receiver.yml |
| exemone-cloud-agent | $EXEMONE_HOME/services/exemone-cloud-agent/configs/agent.yml |
| exemone-db-agent | $EXEMONE_HOME/services/exemone-db-agent/configs/agent.yml |
1-5. 테스트용 패치 스크립트 (patch.sh)
참고: https://app.clickup.com/25540965/v/dc/rbeb5-403518/rbeb5-2776618
patch.sh 스크립트를 사용하면 패치 파일을 nexus.exem.xyz에서 자동 다운로드하여 패치할 수 있습니다.
# 단일 모듈 패치
sh patch.sh api:3.0.506.15.30
# 여러 모듈 버전 다르게 한 번에 패치
sh patch.sh api:3.0.506.15.30 core:3.0.400.11 front:3.1.50.7.2
# 대화형 입력 (모듈별 버전을 물어봄, 엔터로 건너뛰기 가능)
sh patch.sh
지원 모듈: api, core, front, alerter, ingester, gateway, receiver, db-agent, cloud-agent
패치 적용 후 각 서비스는 자동 재시작되며, 기존
.env파일은 백업 후 자동으로 버전이 반영됩니다.
1-6. Binary 모드 롤백 방법
Binary 모드에서는 이전 버전 바이너리가 $EXEMONE_HOME/bins/ 하위에 보존되어 있으므로:
$EXEMONE_HOME/.env파일에서 해당 모듈의 버전을 이전 버전으로 되돌림- core의 경우 백업해둔 db 폴더(
db.bak)를 원복 - 설정 파일도
.bak파일에서 원복 ./onectl restart [모듈명]으로 재시작
참고: https://app.clickup.com/25540965/v/dc/rbeb5-403518/rbeb5-2773018
2. Docker 모드 패치
참고: https://app.clickup.com/25540965/v/dc/rbeb5-403518/rbeb5-2638518
2-1. 사전 설정
패치 이미지를 저장할 폴더 생성:
# 방법 1
mkdir home/exemone/exemone/image/patch
# 방법 2
mkdir home/exemone/exemone/installer/exemone/image
패치할 수집 서버 이미지를 위 폴더에 업로드합니다.
2-2. 단일 모듈 업데이트
# 1. 이미지 로드
cd {이미지 저장 폴더}
ls *.tar.gz | xargs -L 1 docker load -i
# 2. .env 파일에서 패치할 버전 변경
vi home/exemone/exemone/installer/exemone/.env
# 예: FRONT_VERSION=v3.0.504.15.16 → FRONT_VERSION=v3.0.504.15.17
# 3. 이미지 재실행
cd home/exemone/exemone/installer/exemone/scripts
./restart.sh {패치할 이미지}
# 예: ./restart.sh front
# 4. 컨테이너 정상 동작 확인
docker ps
2-3. 전체 모듈 업데이트
# 1. 전체 모듈 종료
cd home/exemone/exemone/installer/exemone/scripts
./shutdown.sh
# 2. 이미지 로드
cd {이미지 저장 폴더}
ls *.tar.gz | xargs -L 1 docker load -i
# 3. .env 파일에서 패치할 버전 변경
vi home/exemone/exemone/installer/exemone/.env
# 4. 전체 빌드 및 실행
cd home/exemone/exemone/installer/exemone
./restart.sh
# 5. 컨테이너 정상 동작 확인
docker ps
2-4. 데이터 백업 후 패키지 패치 (PostgreSQL / ClickHouse)
참고: https://app.clickup.com/25540965/v/dc/rbeb5-403518/rbeb5-3227738
패키지 업데이트의 경우 다운그레이드가 불가능하므로, 작업 전 반드시 기존 데이터 백업 후 진행합니다.
단계 1: PostgreSQL 백업
# api 중지 (마이그레이션 중복 방지)
./scripts/shutdown.sh api
# postgresql 컨테이너 접속하여 데이터 백업
docker exec -it exemone-postgresql bash
cd /var/lib/postgresql
pg_dumpall -U postgres > 250212.sql
exit
# 백업 파일 추출
docker cp exemone-postgresql:/var/lib/postgresql/250212.sql .
# postgresql 종료 및 볼륨 백업
./scripts/shutdown.sh postgresql
mv containers/exemone-postgresql/data containers/exemone-postgresql/data_bak
mkdir containers/exemone-postgresql/data
단계 2: 전체 컨테이너 종료 및 새 패키지 설치
# 전체 종료
./shutdown.sh
# 새 패키지 압축 해제
tar -xvzf exemone-pkg.gz
cd /home/exemone/exemone/installer
tar -xvf exemone.tar.gz
# ClickHouse 백업 파일 복사
cp -r {기존 EXEMONE_HOME}/containers/exemone-clickhouse/ {신규 EXEMONE_HOME}/containers/exemone-clickhouse/
# Docker 이미지 로드
ls *.tar.gz | xargs -L 1 docker load -i
# exemONE 설치
./install.sh
단계 3: PostgreSQL 데이터 복원
# api 중지 후 postgresql 실행
./scripts/shutdown.sh api
./scripts/startup.sh postgresql
# 데이터 복원
docker cp 250212.sql exemone-postgresql:/var/lib/postgresql/
docker exec -it exemone-postgresql bash
cd /var/lib/postgresql
psql -d postgres -U postgres < 250212.sql
# api 재구동
./restart.sh api
2-5. Docker 모드 롤백 방법
- 단일 모듈:
.env파일에서 해당 모듈의 버전을 이전 버전으로 되돌리고./restart.sh {모듈명}실행 (이전 Docker 이미지가 로드되어 있어야 함) - 패키지 업데이트 후: 백업해둔 기존 폴더 및 PostgreSQL dump, ClickHouse 데이터를 사용하여 이전 버전 패키지를 재설치
주의: 패키지 업데이트의 경우 다운그레이드(예: 504 → 412)가 불가능하므로, 반드시 작업 전 데이터 백업 후 진행해야 합니다.
3. Kubernetes 모드 패치
3-1. 모듈 패치 (이미지 버전 변경만 필요한 경우)
참고: https://app.clickup.com/25540965/v/dc/rbeb5-403518/rbeb5-3429398
제약 조건
- exemone-api와 exemone-receiver Pod는 동일한 Node에서 실행되어야 합니다.
# Worker Node 라벨 설정
kubectl label nodes worker-node1 workload=exemone-k8s
Deployment YAML에 nodeSelector 설정:
spec:
template:
spec:
nodeSelector:
workload: exemone-k8s
이미지 로드
모든 Node에 이미지를 로드합니다.
# docker 사용 시
docker load -i <이미지>.tar.gz
docker images | grep exemone
# containerd 사용 시
ctr -n k8s.io images import <이미지>.tar.gz
ctr -n k8s.io images ls | grep exemone
containerd에서
invalid tar header에러 발생 시:gunzip -k <이미지>.tar.gz
ctr -n k8s.io images import <이미지>.tar
패치 적용
# 1. .env 파일에서 신규 패치 버전으로 변경
vi exemone-kubernetes/installer/exemone-kubernetes/.env
# 2. apply.sh 스크립트 실행
sh exemone-kubernetes/installer/exemone-kubernetes/apply.sh
# 3. exemONE 서비스 정상 구동 확인
3-2. 패키지 패치 (template/script 파일이 변경된 경우)
참고: https://app.clickup.com/25540965/v/dc/rbeb5-403518/rbeb5-3429378
# 1. 기존 디렉토리 백업
mv exemone-kubernetes exemone-kubernetes.bak
# 2. 새 패키지 압축 해제
tar -xzvf exemone-kubernetes-pkg-v3.0.508.21.tar.gz
cd exemone-kubernetes
# 3. 모든 Node에 이미지 로드
docker load -i <이미지>.tar.gz # 또는 ctr 사용
# 4. installer 압축 해제
cd exemone-kubernetes/installer/
tar -xzvf exemone-kubernetes.tar.gz
# 5. 기존 디렉토리에서 Storage Class 확인
cd exemone-kubernetes.bak/installer/exemone-kubernetes
cat exemone/pvc.yaml | grep -m 1 storageClassName
# 6. 새 패키지 디렉토리로 이동
cd ../../../exemone-kubernetes/installer/exemone-kubernetes
# 7. 기존 YAML에서 사용자 수정사항(NodeSelector, 리소스 제한 등) 반영
# templates 폴더 내 YAML 파일 수정
# 8. generate.sh 실행 (yaml 파일 신규 생성)
./generate.sh
# 9. apply.sh 실행
./apply.sh
3-3. Kubernetes 모드 롤백 방법
- 백업해둔
exemone-kubernetes.bak디렉토리를 원복 .env파일에서 이전 버전으로 변경- 이전 버전 이미지를 모든 Node에 로드
apply.sh재실행
4. 주요 주의사항
| 항목 | 내용 |
|---|---|
| 패키지 다운그레이드 불가 | Docker 모드에서 패키지 업데이트(예: 504→412) 후 다운그레이드 불가. 반드시 사전 백업 필요 |
| PG 17 업그레이드 | 하위 버전 → 504 업데이트 시 PostgreSQL 13→17 업그레이드 선행 필요 |
| core 패치 시 | 반드시 core 프로세스 중지 후 진행, db 디렉터리 백업 필수 |
| api 중지 필수 | PostgreSQL 데이터 복원 시 api를 먼저 중지해야 마이그레이션 중복 방지 |
| 설정 파일 백업 | 패치 전 설정 파일(.yml)을 .bak으로 백업 권장 |
| restart.sh 확인 (Docker) | 2024년 5월 29일 이전 패키지의 경우 restart.sh에 build --no-cache 라인 추가 필요 |
| K8s Node 제약 | exemone-api와 exemone-receiver Pod는 반드시 동일 Node에서 실행 |
참고 문서
- Binary 모듈 패치 가이드: https://app.clickup.com/25540965/v/dc/rbeb5-403518/rbeb5-2772638
- Binary 패치 예시: https://app.clickup.com/25540965/v/dc/rbeb5-403518/rbeb5-2773018
- Binary 테스트용 패치 스크립트: https://app.clickup.com/25540965/v/dc/rbeb5-403518/rbeb5-2776618
- Docker 모듈 패치 가이드: https://app.clickup.com/25540965/v/dc/rbeb5-403518/rbeb5-2638518
- Docker 데이터 백업 후 패키지 패치: https://app.clickup.com/25540965/v/dc/rbeb5-403518/rbeb5-3227738
- Kubernetes 모듈 패치 가이드: https://app.clickup.com/25540965/v/dc/rbeb5-403518/rbeb5-3429398
- Kubernetes 패키지 패치 가이드: https://app.clickup.com/25540965/v/dc/rbeb5-403518/rbeb5-3429378