업그레이드·마이그레이션 | MLOps Central Platform 매뉴얼

업그레이드는 새 소스로 이미지를 다시 빌드해 실행하는 것이 전부. DB 마이그레이션은 앱 시작 시 자동 수행. 다만 학습·빌드 이미지는 클러스터 내부에서 따로 빌드. 그 코드나 빌드 설정이 변경되면 해당 이미지를 다시 게시해야 반영.

1. 업그레이드 전에

백업 생성. 마이그레이션은 되돌리기(다운그레이드)보다 백업 복구가 안전.

sudo systemctl start geo-mlops-backup.service
journalctl -u geo-mlops-backup.service -n 5    # "backup finished" 확인

실행 중인 학습이 있는지 확인. 앱이 재시작되면 실행 중인 학습에 종료 신호를 보내 체크포인트를 저장할 시간(기본 60초, GEO_MLOPS_TRAINING_GRACE_PERIOD)을 준 뒤 중지하고 INTERRUPTED 로 정리. 대기(QUEUED) 중이던 학습도 다음 기동 때 INTERRUPTED 가 되며, 자동으로 다시 제출되지 않음. 가능하면 학습이 없을 때 업그레이드.

2. 새 버전 실행

소스를 새 버전으로 교체한 뒤(예: /opt/geo-mlops 에 새 버전 내려받기) 아래 명령 실행.

D=/opt/geo-mlops
export GIT_COMMIT=$(git -C $D rev-parse HEAD)          # 선택: 시스템 진단에 커밋 표시
export BUILT_AT=$(date -u +%Y-%m-%dT%H:%M:%SZ)

# 1) 전체 스택을 파일에 정의된 상태로 맞춘다 (서비스 이름을 주지 않는다)
docker compose -f $D/docker-compose.yml up -d --build --remove-orphans

# 2) 모니터링 설정 파일 변경을 확실히 반영한다
docker compose -f $D/docker-compose.yml up -d --force-recreate --no-deps prometheus alertmanager

# 3) 오래된 앱 이미지 정리
docker image prune -f

서비스 이름(app) 지정 금지. up -d app 은 앱과 그 의존 서비스만 갱신하므로, Prometheus·Alertmanager 설정이 변경되어도 반영되지 않음.
Prometheus·Alertmanager 설정은 파일 마운트이므로, 컨테이너를 다시 생성해야 새 파일을 읽음. 데이터(TSDB, 알림 상태)는 볼륨에 있어 유지.
빌드마다 이전 앱 이미지가 이름 없이 남으므로 주기적으로 docker image prune -f 로 삭제.
앱 메모리 상한을 변경해 사용 중이면 1) 의 명령에도 같은 GEO_APP_MEM_LIMIT 지정. 생략하면 16 GB 로 되돌아감(Docker Compose 로 설치).

3. 확인

docker inspect --format='{{.State.Health.Status}}' geo-mlops-app     # healthy
curl -s http://localhost:10000/api/v1/readyz

이어서 시스템 진단의 "배포 정보" 에서 백엔드 커밋이 방금 배포한 커밋인지, "의존 컴포넌트" 의 PostgreSQL 카드에서 마이그레이션 번호가 변경되었는지 확인. 프론트엔드 커밋이 이전 커밋이면 브라우저가 이전 번들을 캐시하고 있는 상태(새로 고침).

DB 마이그레이션

자동 (기본)

앱 컨테이너의 시작 스크립트(start-uvicorn.sh)는 서버 기동 전에 alembic upgrade head 실행. 마이그레이션이 실패하면 서버는 기동되지 않고 컨테이너가 재시작을 반복하므로, 로그에서 원인 확인.

docker logs --tail=100 geo-mlops-app

수동

평소에는 불필요. 상태 확인이나 별도 적용 시 앱 컨테이너 내부에서 실행(컨테이너의 GEO_MLOPS_* 설정을 그대로 사용).

docker exec geo-mlops-app ./run alembic current      # 지금 적용된 리비전
docker exec geo-mlops-app ./run alembic heads        # 코드의 최신 리비전
docker exec geo-mlops-app ./run alembic upgrade head # 최신으로

빌드 설정 변경 후 이미지 재게시

학습 런타임·데이터셋 스테이저·서빙 빌더 이미지는 k3s 에서 한 번 빌드해 레지스트리에 저장한 것. 앱을 업그레이드해도 이미 빌드한 이미지는 변경되지 않음. 다음 경우에는 해당 이미지를 다시 게시.

변경 사항	다시 게시할 이미지
패키지 프록시 설정(`GEO_MLOPS_BUILD_PACKAGE_PROXY_ENABLED`, `…_BUILD_PIP_INDEX_URL`, `…_BUILD_APT_PROXY`)을 처음 변경	서빙 빌더: 모델 서빙 이미지를 빌드하는 스크립트가 빌더 이미지에 포함되어 있어서, 재게시 전까지는 새 설정을 무시하고 예전처럼 빌드
새 버전에서 학습 런타임(트레이너) 코드가 변경됨	학습 런타임: 학습 Job 은 이미지 내부의 트레이너를 실행
새 버전에서 스테이저 코드가 변경됨(새 파일 종류 등)	데이터셋 스테이저

시스템 콘솔 공유 이미지에서 해당 탭(학습 런타임 / 데이터셋 스테이저 / 서빙 빌더) 선택. 테넌트가 자체 이미지를 따로 사용하면 그 테넌트 관리자 콘솔의 같은 이름 화면에서 진행.
이미지 줄의 다시 게시를 누르고, 빌드가 끝날 때까지 대기. 레이어 캐시 덕분에 두 번째부터는 빠름.
게시가 끝난 뒤 제출한 학습·빌드부터 새 이미지 사용. 진행 중인 작업은 이전 이미지로 완료.

다음: 백업·복구

1. 업그레이드 전에#

2. 새 버전 실행#

3. 확인#

DB 마이그레이션#

자동 (기본)#

수동#

빌드 설정 변경 후 이미지 재게시#