dockerinstaller케이스별_시나리오
0. 공통 확인 항목 (모든 케이스 공통)
| 확인 항목 | 예상 동작 | 확인 필요 |
|---|---|---|
| Docker 미설치 시 실행 | xmError(501) 출력 후 종료 | ✅ |
| Docker 데몬 미기동 시 실행 | xmError(502) 출력 후 종료 | ✅ |
| ./start.sh 실행 | exemone-kafka-agent 컨테이너 기동됨 | ✅ |
| ./stop.sh 실행 | exemone-kafka-agent 컨테이너 종료됨 | ✅ |
| cfg/ 디렉토리 owner | 1200:1200 (컨테이너 사용자) | ✅ |
| log/ 디렉토리 권한 | 777 (컨테이너 쓰기 가능) | ✅ |
정보
⚠️ v3.0.23.3-2 대비 변경
- 컨테이너명 변경:
exem-kafka-agent→exemone-kafka-agent - 이미지명 변경:
maxgauge/exem-kafka-agent→maxgauge/exemone-kafka-agent - RECEIVER_IP에 hostname/FQDN 허용 (이전엔 IP만 허용)
- Legacy 환경 지원 - Legacy 환경 감지/거절 분기 추가
- cfg/.env:
KAFKA_GROUP_ID제거,KAFKA_AGENT_INSTALL_USER추가
1. Unpack (2번 선택)
- 사전 조건: exem/ 디렉토리 없는 상태
- 실행: .bin 실행 → 2번(unpack) 선택
- 기대 로그:
Unpack completed
UNPACK_DIR={실행경로}/exem/kafka
xmSuccess(0): unpack completed
| 확인 항목 | 예상 동작 | 확인 필요 |
|---|---|---|
| exem/kafka/ 생성 | 생성됨 | ✅ |
| start.sh, stop.sh | 존재 | ✅ |
| lib/exemone-kafka-agent-v*.tar.gz | 존재 (Docker 이미지 파일) | ✅ |
| Docker 이미지 로드 여부 | 로드 안 됨 (unpack만 수행) | ✅ |
정보
⚠️ v3.0.23.3-2 대비 변경
- 추출 경로 변경:
{실행경로}/exemone-kafka-agent→{실행경로}/exem/kafka
2. 신규 설치 — Interactive (1번 선택)
- 사전 조건: exem/ 디렉토리 없는 상태,
$EXEMONE_HOME미설정 - 실행: .bin 실행 → 1번 → EXEM_HOME Enter(기본값) → RECEIVER_IP 입력 → 나머지 Enter
- 기대 로그:
Installation completed
AGENT_VERSION=...
PKG_VERSION=...
INSTALL_DIR={실행경로}/exem/kafka
RECEIVER_ADDR=...
IMAGE=maxgauge/exemone-kafka-agent:v...
To start: {실행경로}/exem/kafka/start.sh
xmSuccess(0): installation completed
| 확인 항목 | 예상 동작 | 확인 필요 |
|---|---|---|
| Docker 이미지 로드됨 | docker images로 확인 가능 | ✅ |
| 설치 위치 | {실행경로}/exem/kafka | ✅ |
| start.sh, stop.sh | 존재 | ✅ |
| cfg/.env | 생성됨 (RECEIVER_ADDR, VERSION 등 포함) | ✅ |
| exem-docker-installer-tmp/ | 남아있지 않음 | ✅ |
| RECEIVER_IP에 hostname 입력 (예: receiver) | 정상 처리됨 | ✅ |
변형: 설치 중 exemone-kafka-agent 컨테이너가 이미 실행 중인 경우
| 확인 항목 | 예상 동작 | 확인 필요 |
|---|---|---|
| 컨테이너 자동 종료 여부 | 종료하지 않음 | ✅ |
| 완료 메시지 | "Container is currently running" 안내 + To apply 출력 | ✅ |
정보
⚠️ v3.0.23.3-2 대비 변경
- 기존 컨테이너 자동 stop/rm 제거 - 이전엔 자동 제거 시도했으나 컨테이너명이 달라 정상 동작 하지 않았음
3. 신규 설치 — Config mode
- 실행:
./docker-installer.bin config.env - config.env 예시:
INSTALL_DIR=/opt/exem
RECEIVER_IP=10.20.30.40
RECEIVER_PORT=9009
| 확인 항목 | 예상 동작 | 확인 필요 |
|---|---|---|
| 대화형 입력 없이 설치 완료 | 확인 | ✅ |
| INSTALL_DIR 키 | 설치 경로로 인식됨 | ✅ |
| RECEIVER_PORT 미지정 시 | 기본값 9009 적용 | ✅ |
| EXEM_AGENT_NAME 미지정 시 | 기본값 kafka-agent 적용 | ✅ |
| RECEIVER_IP 미지정 시 | xmError(505) 출력 후 종료 | ✅ |
| RECEIVER_IP에 hostname 지정 (예: receiver) | 정상 처리됨 | ✅ |
정보
⚠️ v3.0.23.3-2 대비 변경
- Config key 변경:
INSTALL_PATH→INSTALL_DIR
4. Standalone 패치 — Interactive (1번 선택, 기존 설치 있음)
- 사전 조건: exem/kafka/ 에 기존 설치 있음,
$EXEMONE_HOME미설정 - 실행: 같은 경로에서 .bin 실행 → 1번 → EXEM_HOME Enter → Patch it? Enter → 기존값 유지 Enter
- 기대 로그:
Existing installation found. Running patch...
Existing version:
agent : x.x.x
package : x.x.x
New version:
agent : x.x.x
package : x.x.x
...
Patch completed (agent not started)
xmSuccess(0): patch completed
| 확인 항목 | 예상 동작 | 확인 필요 |
|---|---|---|
| 교체되는 항목 | ||
| Docker 이미지 | 새 버전으로 교체됨 | ✅ |
| 기존 이미지 | 삭제됨 (이미지 ID가 다른 경우) | ✅ |
| start.sh, stop.sh | 새 버전으로 교체됨 | ✅ |
| cfg/kafka.conf | 새 버전으로 교체됨 | ✅ |
| cfg/cfg.reload | 새 버전으로 교체됨 | ✅ |
| cfg/.env | RECEIVER_ADDR, VERSION 등 갱신됨 | ✅ |
| lib/ | 새 버전으로 교체됨 | ✅ |
| 유지되는 항목 | ||
| log/ | 기존 유지 | ✅ |
| 컨테이너 자동 종료 여부 | 종료하지 않음 | ✅ |
| 정리 | ||
| exem-docker-installer-tmp/ | 남아있지 않음 | ✅ |
변형: 컨테이너 실행 중인 경우
| 확인 항목 | 예상 동작 | 확인 필요 |
|---|---|---|
| 컨테이너 자동 종료 여부 | 종료하지 않음 | ✅ |
| 완료 메시지 | "Container is currently running with the old version" 안내 + To apply 출력 | ✅ |
정보
⚠️ v3.0.23.3-2 대비 변경
- 버전 출력 상세화:
Existing version: x.x.x→ agent/package 분리 출력 - 완료 메시지:
OLD_VERSION/NEW_VERSION→OLD_AGENT_VERSION/OLD_PKG_VERSION/NEW_AGENT_VERSION/NEW_PKG_VERSION
5. Standalone 패치 — Config mode
- 실행:
./docker-installer.bin config.env - config.env 예시:
INSTALL_DIR=/opt/exem
RECEIVER_IP=10.20.30.40
| 확인 항목 | 예상 동작 | 확인 필요 |
|---|---|---|
| 대화형 입력 없이 패치 완료 | 확인 | ✅ |
| RECEIVER_IP 미지정 시 | 기존 cfg/.env 값 그대로 유지 | ✅ |
| RECEIVER_IP 지정 시 | cfg/.env에 새 값 반영됨 | ✅ |
| 나머지 동작 | 4번(Standalone 패치)과 동일 | ✅ |
정보
⚠️ v3.0.23.3-2 대비 변경
- 4번(Standalone 패치 Interactive)과 동일
6. Legacy 환경 패치 — Interactive
- 사전 조건:
$EXEMONE_HOME=/opt/exemone,$EXEMONE_HOME/containers/exemone-kafka-agent디렉토리 존재 - 실행: .bin 실행 → 1번 → Y 선택 → Patch it? Enter → 기존값 유지 Enter
- 기대 로그:
exemone-package environment detected. (EXEMONE_HOME: /opt/exemone)
Install to exemone-package environment? [Y/n]: Y
KAFKA_HOME: /opt/exemone/containers/exemone-kafka-agent
Existing installation found. Running patch...
...
Image tagged for legacy environment: maxgauge/exemone-kafka-agent:{VERSION}
...
Patch completed (agent not started)
To apply: cd $EXEMONE_HOME && ./scripts/restart.sh kafka-agent
xmSuccess(0): patch completed
| 확인 항목 | 예상 동작 | 확인 필요 |
|---|---|---|
| KAFKA_HOME | $EXEMONE_HOME/containers/exemone-kafka-agent 고정 | ✅ |
| 기존 설정 읽기 | kafka.conf의 RECEIVER_ADDR에서 읽음 | ✅ |
| 이미지 태그 | v prefix 없는 태그로 re-tagging됨 | ✅ |
| $EXEMONE_HOME/.env 갱신 | KAFKA_AGENT_VERSION, KAFKA_AGENT_IMAGE 업데이트됨 | ✅ |
| kafka.conf | 덮어쓰지 않음 (기존 설정 보존) | ✅ |
| cfg.reload | 새 버전으로 교체됨 | ✅ |
| cfg/log 소유권 | $EXEMONE_HOME/.env의 UID/GID 기준 chown (없으면 1200:1200) | ✅ |
| 재기동 안내 | ./scripts/restart.sh kafka-agent 안내 출력 | ✅ |
7. Legacy 환경 패치 — Config mode
- 사전 조건:
$EXEMONE_HOME설정됨,containers/exemone-kafka-agent존재 - 실행:
./docker-installer.bin config.env(config.env에 값 없거나 일부만 지정)
| 확인 항목 | 예상 동작 | 확인 필요 |
|---|---|---|
| 대화형 입력 없이 패치 완료 | 확인 | ✅ |
| RECEIVER_IP 미지정 시 | kafka.conf 기존 값 유지 | ✅ |
| RECEIVER_IP 지정 시 | cfg/.env에 새 값 반영됨 | ✅ |
| 나머지 동작 | 6번(Legacy 패치)과 동일 | ✅ |
8. Legacy 환경 감지 → 거절(n 선택) → 신규 설치
- 사전 조건:
$EXEMONE_HOME설정됨, 신규 설치 대상 경로 없음 - 실행: .bin 실행 → 1번 → n 선택 → EXEM_HOME 입력 → 신규 설치 진행
- 기대 로그:
exemone-package environment detected. (EXEMONE_HOME: /opt/exemone)
Install to exemone-package environment? [Y/n]: n
Enter EXEM_HOME [/home/admin/exem]: ...
| 확인 항목 | 예상 동작 | 확인 필요 |
|---|---|---|
| Legacy 환경 무시하고 standalone 신규 설치 진행 | 확인 | ✅ |
| 나머지 동작 | 2번(신규 설치)과 동일 | ✅ |
9. Legacy 환경 감지 → 거절(n 선택) → Standalone 패치
- 사전 조건:
$EXEMONE_HOME설정됨, 별도 standalone 설치도 존재 - 실행: .bin 실행 → 1번 → n 선택 → EXEM_HOME에 기존 standalone 경로 입력
- 기대 로그:
exemone-package environment detected. (EXEMONE_HOME: /opt/exemone)
Install to exemone-package environment? [Y/n]: n
Enter EXEM_HOME [/home/admin/exem]: /data/exem
Existing installation found at /data/exem/kafka. Patch it? [Y]: ...
| 확인 항목 | 예상 동작 | 확인 필요 |
|---|---|---|
| Legacy 환경 무시하고 standalone 패치 진행 | 확인 | ✅ |
| 나머지 동작 | 4번(Standalone 패치)과 동일 | ✅ |
10. 에러 케이스
| 상황 | 기대 출력 | 확인 필요 |
|---|---|---|
| Docker 미설치 | xmError(501): Docker is not installed. Please install Docker first. | ✅ |
| Docker 데몬 미기동 | xmError(502): Docker daemon is not running. Please start Docker first. | ✅ |
| 패키지 손상 (버전 정보 없음) | xmError(503): version information not found in package | ✅ |
| 이미지 파일 없음 | xmError(504): Docker image file not found: ... | ✅ |
| 이미지 로드 실패 | xmError(504): Docker image load failed | ✅ |
| Config mode — RECEIVER_IP 미지정 | xmError(505): RECEIVER_IP is required in config file | ✅ |
| Config mode — RECEIVER_IP 형식 오류 | xmError(505): Invalid RECEIVER_IP format (e.g., 127.0.0.1 or receiver) | ✅ |
| Config mode — RECEIVER_PORT 범위 오류 | xmError(505): Invalid RECEIVER_PORT (must be 1-65535) | ✅ |
| 설치 디렉토리 생성 실패 | xmError(505): failed to create install directory ... | ✅ |
| 파일 복사 실패 | xmError(505): failed to copy files to ... | ✅ |
| 패키지 추출 실패 (tar 손상) | xmError(506): unpack failed | ✅ |
| 메뉴 잘못된 입력 | xmError(500): invalid option selected | ✅ |
| 3번(exit) 선택 | xmError(509): exit requested by user | ✅ |
| 컨테이너 제거 실패 (start.sh) | xmError(103) | ✅ |
| 컨테이너 생성 실패 (start.sh) | xmError(106) | ✅ |
| 컨테이너 중지 실패 (stop.sh) | xmError(200) | ✅ |
정보
⚠️ v3.0.23.3-2 대비 변경
- xmError(502) 신규: Docker 데몬 미기동 에러 (이전엔 이 체크 없었음)
- xmError(506) 신규: unpack 실패 에러코드 변경 (이전엔 xmError(502)였음)
- xmError(505) RECEIVER_IP 형식 오류 메시지 변경: hostname도 허용하도록 안내 문구 수정