업그레이드·마이그레이션

업그레이드는 새 소스로 이미지를 다시 빌드해 띄우는 것이 전부입니다. DB 마이그레이션은 앱이 시작할 때 스스로 합니다. 다만 학습·빌드에 쓰는 이미지는 클러스터 안에서 따로 구워진 것이라, 그쪽 코드나 빌드 설정이 바뀌었다면 해당 이미지를 다시 게시해야 반영됩니다.

1. 올리기 전에

백업을 한 번 받아 둡니다. 마이그레이션은 되돌리기(다운그레이드)보다 백업에서 복구하는 편이 안전합니다.
```
sudo systemctl start geo-mlops-backup.service
journalctl -u geo-mlops-backup.service -n 5    # "backup finished" 확인
```
실행 중인 학습이 있는지 봅니다. 앱이 재시작하면 실행 중인 학습에 종료 신호를 보내 체크포인트를 남길 시간(기본 60초)을 준 뒤 멈추고, 다음 기동 때 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 로 지웁니다.

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 마이그레이션#

자동 (기본)#

수동#

빌드 설정을 바꿨다면: 이미지 재게시#