MinIO 대체 S3 저장소 고르기, Garage 로 옮기는 법

서버 한 대에 파일 저장소를 직접 올려 쓰고 있는데, 그 저장소 프로젝트가 더는 관리되지 않는다는 소식을 들으면 마음이 철렁해요. 지금 당장 잘 돌아가니까 그냥 둘까, 아니면 데이터가 쌓이기 전에 갈아탈까 고민이 시작돼요.

이 글에서 S3 는 아마존이 만든 파일 저장 서비스의 주소 규칙이에요. 많은 저장소 프로그램이 같은 규칙을 흉내 내서 "S3 호환"이라고 불러요. 은행 창구로 치면 서류 양식이 같아서, 창구를 다른 은행으로 바꿔도 같은 서류를 낼 수 있는 셈이에요.

혹시 이런 고민 있으신가요?

• 쓰던 저장소가 보관 처리됐다는데, 지금 옮겨야 하는지 나중에 해도 되는지 모르겠어요.
• 후보가 여러 개인데 무엇을 기준으로 비교해야 할지 막막해요.
• 갈아타다가 코드를 다 고쳐야 하거나 파일을 잃을까 봐 겁나요.

이 글을 읽으면

• 저장소 프로젝트의 상태를 날짜와 숫자로 확인해서 옮길지 말지 정할 수 있어요.
• 내가 쓰는 S3 기능만 추려서 후보를 같은 기준으로 비교할 수 있어요.
• 설정 이름을 공급자와 분리해 두고, 새 저장소를 띄워 올리기와 내려받기까지 확인할 수 있어요.

1단계. 보관 처리의 뜻부터 확인하기

먼저 "보관 처리"가 무슨 뜻인지 짚고 가요. 코드 저장소가 보관(archived) 상태가 되면 새 코드를 올릴 수 없고, 읽기만 돼요. 새 버전도, 보안 수정도 나오지 않는다는 뜻이에요.

지금 잘 돌아가는데 왜 서두르냐고 물을 수 있어요. 이유는 보안 권고예요. 어떤 프로그램이든 시간이 지나면 취약점이 발견돼요. 관리되는 프로젝트라면 수정판이 나오지만, 보관된 프로젝트는 고쳐 줄 곳이 없어요. 그 위에 사용자의 계약서나 서명 파일을 올려 둔다면 더 그래요.

판단은 감이 아니라 세 가지 사실로 해요.

여기에 하나를 더해요. 내가 지금 쓰는 이미지 버전이 어느 날짜인지 확인해요. 저희가 고정해 쓰던 이미지는 마지막 릴리스보다도 앞선 2025-09-07 판이었어요. 보관되기 한참 전에 이미 새 판을 못 따라가고 있었던 셈이에요.

옮기기로 정했다면 시점도 정해요. 저희는 저장소에 데이터가 아직 하나도 없을 때 결정했어요. 옮기는 비용은 데이터가 쌓일수록 커지니까, 비어 있는 지금이 가장 싼 때예요.

2단계. 내가 쓰는 S3 기능만 목록으로 만들기

후보를 고르기 전에 "내 코드가 저장소에 무엇을 시키는지"부터 적어요. S3 호환이라고 해도 모든 기능을 똑같이 지원하지는 않아요. 내가 쓰는 기능만 지원하면 충분해요.

코드에서 저장소를 부르는 곳을 훑어서 호출 이름을 모아요. 저희 목록은 일곱 개였어요.

버킷은 파일을 담는 최상위 통이에요. 폴더보다 한 단계 위의 큰 서랍이라고 생각하면 돼요.

이 목록이 비교표의 "필수" 칸이 돼요. 반대로 목록에 없는 기능, 예를 들어 버전 관리나 복제 정책은 후보를 가르는 기준으로 쓰지 않아요. 쓰지도 않는 기능 때문에 무거운 후보를 고르는 일을 막아 줘요.

3단계. 후보를 같은 기준으로 비교해 하나 고르기

목록이 생겼으니 후보를 나란히 놓아요. 서버 한 대로 운영한다는 조건이면 기준은 세 가지로 줄어요. 지금 안정판인가, 내가 쓰는 기능이 다 있는가, 운영해야 할 것이 많지 않은가.

저희가 2026-09-21 에 살펴본 후보와 판단은 이래요.

출처는 각 프로젝트의 공개 코드 저장소와 릴리스 목록, README 이고 조회일은 2026-09-21 이에요. Garage 가 일곱 개 호출을 지원하는지는 해당 버전의 소스와 S3 호환 문서로 확인했어요. 후보의 상태는 금방 바뀌니 여러분은 날짜를 새로 확인하세요.

보관 처리 확인, 필수 기능 대조, 운영 규모 순으로 후보가 줄어드는 모습

고를 때 지킨 원칙이 하나 있어요. 새 저장소를 고르는 일이 목표가 아니라, 내 기능 목록을 만족하는 가장 가벼운 후보를 고르는 일이에요. "가장 인기 있다"나 "기능이 제일 많다"는 이유가 되지 않아요.

그리고 라이선스도 꼭 읽어요. AGPL-3.0 은 프로그램을 수정해서 네트워크로 서비스할 때 소스 공개 의무가 생기는 라이선스예요. 저장소를 수정 없이 그대로 쓰기만 하면 부담이 크지 않지만, 고쳐서 쓸 계획이라면 먼저 따져 봐야 해요. 이전에 쓰던 프로그램도 같은 조건이었어서 저희에게는 달라지는 점이 없었어요.

4단계. 설정 이름에서 공급자 빼고 새 저장소 띄우기

고른 뒤에 가장 먼저 할 일은 설정 이름 바꾸기예요. 저장소 접속 정보를 담는 환경 변수 이름에 이전 프로그램 이름이 박혀 있다면, 갈아탈 때마다 코드와 배포 설정과 테스트를 전부 고쳐야 해요. 이름에서 공급자를 빼 두면 다음에는 값만 바꾸면 돼요.

바꿀 때는 코드, 예시 설정 파일, 테스트, 로컬 실행 설정, 자동 검사 설정을 한 번에 맞춰요. 그다음 이전 이름이 남았는지 코드 전체를 검색해서 확인해요. 의도한 곳, 예를 들어 옛 기록 문서만 남아야 해요.

S3 호환 SDK 를 쓰고 있다면 저장소를 부르는 코드는 한 줄도 바뀌지 않아요. 저희도 바뀐 것은 환경 변수 이름과 컨테이너뿐이었어요.

이제 새 저장소를 띄워요. Garage 는 갓 뜬 인스턴스에 접근 키와 버킷이 없어요. 이전 프로그램의 관리자 계정 같은 것이 없어서, 키와 버킷을 따로 만들어야 해요. 예전에는 초기화용 컨테이너를 하나 더 두는 방식이었지만, 2.3.0 판부터는 서버가 시작할 때 스스로 만들어 줘요.

garage server --single-node --default-bucket

• --single-node: 서버 한 대짜리 구성을 자동으로 잡아요.
• --default-bucket: 환경 변수로 준 키와 버킷을 만들고, 그 키에 버킷 소유 권한을 줘요.

필요한 환경 변수는 세 개예요. 값은 여러분이 정하는 난수로 채워요.

GARAGE_DEFAULT_ACCESS_KEY=<접근 키 아이디>GARAGE_DEFAULT_SECRET_KEY=<접근 키 비밀값>GARAGE_DEFAULT_BUCKET=<버킷 이름>

이 명령은 이미 있으면 건너뛰기 때문에 두 번째 기동에도 같은 명령을 써도 돼요. 단, 이미 있는 키에 다른 비밀값을 주면 기동이 실패해요. 처음 값을 잃어버리지 않게 보관하세요.

설정 파일에서 하나만 꼭 맞춰야 해요. 지역 이름이에요.

[s3_api]s3_region = "us-east-1"api_bind_addr = "[::]:3900"

S3 요청에는 서명이 붙는데, 그 서명 안에 지역 이름이 들어가요. Garage 는 이 이름을 설정의 s3_region 과 대조해요. 코드의 SDK 에 적은 지역과 한 글자라도 다르면 요청이 거절돼요. 저희는 SDK 쪽을 건드리지 않으려고 기존 값 us-east-1 을 설정 쪽에 그대로 적었어요.

5단계. 비운 상태에서 왕복 확인하고 백업 대상 바꾸기

띄웠다고 끝이 아니에요. 두 가지를 확인해요. 빈 상태에서 혼자 일어서는지, 내 호출 일곱 개가 모두 통하는지예요.

첫째는 빈 볼륨 기동이에요. 저장 공간을 지우고 다시 띄웠을 때 키와 버킷이 저절로 생기는지 봐요. 저희는 자동 검사 환경에서 같은 실행 설정으로 확인했는데, 새 저장 공간에서 몇 초 안에 건강한 상태가 됐어요. 자동 검사 환경은 항상 빈 상태로 시작하니, 지운 직후와 같은 조건이에요.

둘째는 왕복 테스트예요. 2단계의 목록을 그대로 시험으로 옮겨요.

1. 버킷 확인과 생성 (HeadBucket, CreateBucket)2. 64KiB 파일 올리기 (PutObject)3. 목록에서 그 파일 찾기 (ListObjectsV2)4. 내려받아 올린 바이트와 같은지 비교 (GetObject)5. 지우고 다시 찾으면 없는지 확인 (DeleteObject)6. 여러 개를 올린 뒤 한 번에 비우기 (DeleteObjects)

핵심은 4번이에요. 파일이 "내려받아진다"가 아니라 "올린 것과 한 바이트도 다르지 않다"까지 비교해야 해요.

코드와 S3 규칙은 그대로 두고 저장소 컨테이너와 설정 이름만 바뀌는 모습

마지막은 백업이에요. 저장소를 바꾸면 백업 대상도 바뀌어요. 이전 프로그램은 데이터 볼륨 하나를 백업하면 됐지만, Garage 는 메타데이터와 데이터 두 디렉터리가 따로 있어요. 메타데이터는 "어떤 파일이 어디 있는지" 적은 색인이에요. 파일이 멀쩡해도 색인을 잃으면 객체를 찾을 수 없으니, 둘 다 백업해야 해요.

자주 묻는 질문

Q1. 데이터가 이미 많이 쌓였다면 어떻게 옮기나요?

두 저장소가 모두 S3 호환이면 복사 도구로 버킷 통째로 옮길 수 있어요. 순서는 새 저장소를 먼저 띄우고, 복사한 뒤, 파일 수와 크기를 비교하고, 마지막에 접속 정보를 바꾸는 거예요. 저희는 데이터가 없는 시점에 옮겨서 이 과정을 겪지 않았어요. 그래서 이 부분은 직접 해 본 결과가 아니라 일반적인 절차예요.

Q2. 지금 잘 돌아가는데 꼭 바꿔야 하나요?

급한 보안 문제가 없다면 당장은 안전할 수 있어요. 다만 새 권고가 나와도 고쳐 줄 곳이 없다는 점이 위험이에요. 데이터가 적고 쓰는 호출이 적을수록 옮기는 값이 싸니, 미루면 미룰수록 비싸진다는 점만 기억하세요.

Q3. 후보를 고르는 데 시간이 너무 오래 걸려요. 줄일 방법이 있나요?

2단계의 호출 목록이 가장 큰 지름길이에요. 목록이 있으면 후보의 호환 문서에서 그 호출만 찾으면 돼서, 후보마다 읽을 양이 크게 줄어요.

정리

• 보관 표시, 마지막 푸시, 마지막 릴리스 세 가지 날짜로 옮길지 정해요.
• 내 코드가 쓰는 S3 호출만 목록으로 만들어 후보를 같은 기준으로 비교해요.
• 서버 한 대라면 필수 기능이 있는 가장 가벼운 후보를 고르고, 미리보기 판은 피해요.
• 설정 이름에서 공급자 이름을 빼서 다음 이사 비용을 줄여요.
• 빈 상태 기동, 한 바이트까지 비교하는 왕복 테스트, 백업 대상 변경까지 확인해야 이사가 끝나요.

저장소는 눈에 잘 띄지 않지만 모든 파일이 지나가는 길목이라서, 바꿀 때를 직접 정해 두면 마음이 훨씬 편해요.