가라지란 무엇인가?

가라지(Garage)는 오픈소스이며 S3 호환 분산 오브젝트 스토리지로, 자체 호스팅이 가능합니다. 소규모에서 중간 규모 및 지리적으로 분산된 배포 환경을 대상으로 하며, AGPL v3 라이선스 하에 배포됩니다.

가라지에서 HTTPS를 어떻게 제공하나요?

가가리지는 TLS 연결을 종료하지 않습니다. Nginx, Caddy 또는 Traefik과 같은 역방향 프록시를 앞에 배치하고 443번 포트에서 HTTPS를 제공하세요. 프록시는 요청을 가가리지의 API 포트로 전달합니다.

왜 차고 상태에 ‘NO ROLE ASSIGNED’가 표시되는가?

해당 노드에는 아직 레이아웃이 할당되지 않았습니다. 노드에 대해 가라지 레이아웃 할당을 실행한 후, 가라지 레이아웃 적용을 실행하여 클러스터가 새 레이아웃을 사용하도록 설정하세요.

Garage는 AWS S3와 비교해 권한을 어떻게 처리하나요?

가러지(Garage)는 AWS 스타일의 ACL(Access Control List)이나 버킷 정책을 구현하지 않습니다. 대신 가러지 CLI 또는 관리자 API를 통해 각 액세스 키별로 버킷 권한을 관리합니다.

메타데이터 디렉토리(metadata_dir)는 SSD에 위치해야 할까요, HDD에 위치해야 할까요?

가이거의 설정 참조에서는 메타데이터_dir을 빠른 SSD에 배치하여 응답 시간을 개선하는 것이 권장됩니다. data_dir은 더 큰 HDD에 배치할 수 있습니다.

가가리 - S3 호환 오브젝트 스토리지 빠른 시작

몇 분 안에 Docker에서 Garage를 실행해 보세요.

Page content

Garage은 소규모에서 중규모 배포에 적합한 오픈소스, 자체 호스팅, S3 호환 오브젝트 스토리지 시스템으로, 회복력과 지리 분산에 강점을 두고 있습니다.

이 빠른 시작 가이드는 복사/붙여넣기 기반의 단일 노드 설정에서부터 프로덕션에 적합한 패턴(클러스터 레이아웃, 복제, 역방향 프록시를 통한 TLS, 다중 디스크 스토리지 백엔드, 모니터링, 수리, 백업/복원 등)까지 안내합니다.

더 넓은 시야에서 오브젝트 스토리지, PostgreSQL, Elasticsearch, AI 네이티브 데이터 레이어에 대해 알고 싶다면 AI 시스템을 위한 데이터 인프라 문서를 참조해 주세요.

Garage Boxes

Garage란 무엇인가

Garage는 S3 호환 분산 오브젝트 스토리지이며, 자체 호스팅을 목표로 하며, 가볍고 운영이 간단한 동시에 다중 사이트/지리 분산 클러스터를 지원합니다.
AGPL v3 라이선스 하에 배포됩니다.

그것을 운영하는 데 영향을 미치는 주요 아이디어는 다음과 같습니다:

Garage는 노드 용량과 물리적 위치(“존”)를 측정하여 복제본을 배치합니다. 클러스터 토폴로지 변경(노드 추가/제거)은 버전화된 레이아웃과 리밸런싱을 통해 처리됩니다.
오브젝트는 고정 크기 블록(block_size)으로 분할되며, 이는 중복 제거 및 선택적 Zstandard 압축을 가능하게 합니다. 블록 해시는 배치 및 중복 제거에 사용됩니다.
Garage는 S3 API/web 엔드포인트에서 TLS를 종료하지 않습니다. 실제 배포에서는 역방향 프록시를 통해 HTTPS를 제공해야 합니다.

아키텍처 및 데이터 흐름

고수준으로 보면 Garage는 S3 호환 클라이언트를 통해 상호작용하며, 트래픽은 일반적으로 역방향 프록시(TLS)를 통해 들어오고, 하나 이상의 Garage API 엔드포인트(종종 “게이트웨이” 노드)에 도달한 후, 복제된 데이터 블록을 저장하는 스토리지 노드에 의해 제공됩니다.

garage- 클러스터 데이터 흐름

노드에는 역할이 있습니다: 저장 용량이 있는 저장 노드와 데이터를 저장하지 않고 엔드포인트를 노출하는 게이트웨이 노드. 게이트웨이는 추가 네트워크 헷지와 “어떤 저장 노드를 쿼리해야 하는지” 아는 것으로 인해 지연 시간을 줄입니다.
복제는 replication_factor를 통해 제어되며(예: 존 간 3-way 복제), 구성 참조에서 설명된 가용성/장애 허용 거래-offs가 명확합니다.

복사/붙여넣기 빠른 시작

이것은 학습을 위한 의도적으로 최소한의 단일 노드 배포입니다: 구성 → 서버 시작 → 레이아웃 정의 → 버킷 + 키 생성 → 오브젝트 업로드.

사전 요구사항

docker, openssl, 그리고 (선택 사항으로) awscli와 같은 S3 클라이언트가 필요합니다. Garage CLI는 클러스터를 관리하는 데 사용되는 동일한 이진 파일입니다.

단계별 가이드

# 0) 작업 공간 생성
mkdir -p ~/garage-quickstart/{config,meta,data}
cd ~/garage-quickstart

# 1) 기본 구성 파일 생성 (컨테이너 내부의 지속 가능한 경로)
cat > ./config/garage.toml <<EOF
metadata_dir = "/var/lib/garage/meta"
data_dir     = "/var/lib/garage/data"
db_engine = "sqlite"

# 학습용 단일 노드 배포 (복구성 없음). 프로덕션 배포는 나중에 참조.
replication_factor = 1

rpc_bind_addr   = "[::]:3901"
rpc_public_addr = "127.0.0.1:3901"
rpc_secret      = "$(openssl rand -hex 32)"

[s3_api]
s3_region = "garage"
api_bind_addr = "[::]:3900"
# 선택적 vhost 스타일. Path 스타일은 항상 활성화됨.
root_domain = ".s3.garage.localhost"

[s3_web]
bind_addr = "[::]:3902"
root_domain = ".web.garage.localhost"
index = "index.html"

[admin]
api_bind_addr = "[::]:3903"
admin_token   = "$(openssl rand -base64 32)"
metrics_token = "$(openssl rand -base64 32)"
EOF

# 2) 이미지 태그 선택 (예시). Garage 문서에서 예시 태그가 제공됨.
GARAGE_IMAGE="dxflrs/garage:TAG_PLACEHOLDER"

# 3) Garage 실행 (Docker)
docker run -d --name garaged \
  -p 3900:3900 -p 3901:3901 -p 3902:3902 -p 3903:3903 \
  -v "$PWD/config/garage.toml:/etc/garage.toml:ro" \
  -v "$PWD/meta:/var/lib/garage/meta" \
  -v "$PWD/data:/var/lib/garage/data" \
  "$GARAGE_IMAGE"

# 4) 컨테이너 내부에서 garage CLI 사용
alias garage='docker exec -ti garaged /garage'

# 5) 노드 상태 확인 (아마도 "NO ROLE ASSIGNED"를 볼 수 있음)
garage status

# 6) 레이아웃 할당(단일 노드) 및 적용
NODE_ID="$(garage status | awk '/NO ROLE ASSIGNED/{print $1; exit}')"
garage layout assign -z dc1 -c 1G "$NODE_ID"
garage layout apply --version 1

# 7) 버킷 + 키 생성 및 최소 권한 부여
garage bucket create example-bucket
garage key create example-app-key
garage bucket allow --read --write --owner example-bucket --key example-app-key

# 8) 키 정보 확인 (보안적으로 저장)
garage key info example-app-key

구성 패턴(S3 API는 3900, RPC는 3901, 웹 엔드포인트는 3902, 관리 API는 3903)과 “레이아웃이 필요함” 워크플로는 원본 빠른 시작에서 그대로 가져왔습니다.

AWS CLI로 검증

Garage는 클라이언트가 구성된 s3_region(종종 “garage”)을 사용하도록 요구합니다. 클라이언트가 us-east-1을 사용하는 경우 AuthorizationHeaderMalformed 리디렉션을 받을 수 있습니다.

# 설치 (선택 사항)
python -m pip install --user awscli

# 환경 설정 (예시)
export AWS_ACCESS_KEY_ID="YOUR_GARAGE_KEY_ID"
export AWS_SECRET_ACCESS_KEY="YOUR_GARAGE_SECRET_KEY"
export AWS_DEFAULT_REGION="garage"
export AWS_ENDPOINT_URL="http://localhost:3900"

aws s3 ls
aws s3 cp /etc/hosts s3://example-bucket/hosts.txt
aws s3 ls s3://example-bucket/
aws s3 cp s3://example-bucket/hosts.txt /tmp/hosts.txt

원본 빠른 시작은 ~/.awsrc 파일을 사용하여 엔드포인트/키 간 전환을 제안하며, 편리한 엔드포인트 처리를 위해 최소 AWS CLI 버전을 언급합니다.

설치 및 배포 옵션

이진 파일 설치 및 패키지

Garage 문서는 명시적으로 지원합니다: Garage 다운로드 페이지에서 이진 파일 다운로드, 디스트로 패키지 사용(예: Alpine에서 apk add garage), 필요 시 소스에서 빌드.

Docker 및 Docker Compose

Garage는 컨테이너 이미지와 빠른 시작용 최소 docker run 방법을 문서화합니다.
프로덕션에서는 일반적으로 compose(또는 오케스트레이터)를 사용하여 지속 가능한 저장소, 역방향 프록시, 업그레이드(롤링 재시작)를 관리합니다. Garage “클러스터 배포” 가이드는 각 노드에 Docker를 사용하며, 일반적인 호스트 경로와 메타데이터에 SSD를 권장합니다.

systemd

Garage는 systemd를 통한 강화된 배포를 문서화하고, systemd의 DynamicUser= 주의사항과 지속 상태가 디스크에 저장되는 위치를 설명합니다.
최소한의 유닛 예시(환경에 맞게 경로를 조정):

# /etc/systemd/system/garage.service
[Unit]
Description=Garage S3 호환 오브젝트 스토리지
After=network.target

[Service]
ExecStart=/usr/local/bin/garage -c /etc/garage.toml server
Restart=on-failure
Environment=RUST_LOG=garage=info

[Install]
WantedBy=multi-user.target

Kubernetes 및 Helm

Garage는 Helm 차트를 레포지토리에 포함하고, Kubernetes 배포에 대한 공식 문서 페이지를 제공합니다.
일반적인 주의사항은 설치 후 클러스터 레이아웃을 부트스트랩/적용해야 한다는 것입니다. 이 작업을 자동화하려면 Kubernetes Job을 사용할 수 있습니다.

구성, 보안 및 TLS

저장 백엔드 및 디스크 레이아웃

Garage는 저장을 metadata_dir과 data_dir로 분리합니다. 구성 참조에서는 metadata_dir을 빠른 SSD에 배치하여 응답 시간을 향상시키고, data_dir은 더 큰 HDD에 배치할 것을 권장합니다.
다중 데이터 드라이브가 있는 노드의 경우, Garage는 data_dir에 대해 여러 디스크를 지원하며, 경로별 용량과 자동 균형을 제공합니다.

# 예: 데이터 블록을 위한 여러 HDD
metadata_dir = "/mnt/ssd/garage-meta"
data_dir = [
  { path = "/mnt/hdd1/garage-data", capacity = "8T" },
  { path = "/mnt/hdd2/garage-data", capacity = "8T" },
]

접근 제어 모델 vs S3 버킷 정책

Garage는 AWS 스타일의 ACL 또는 버킷 정책을 구현하지 않으며, 자체 “버킷당 접근 키” 권한 시스템을 사용합니다. 이는 Garage CLI / 관리 API를 통해 관리됩니다.
이로 인해 일반적으로 Garage에 대응하는 “정책"은: 어떤 접근 키가 어떤 버킷(들)에 대해 읽기/쓰기/소유권을 가지는지입니다.

# 버킷에 대한 읽기 전용 키 생성:
garage key create ro-key
garage bucket allow --read example-bucket --key ro-key

# 접근 제거:
garage bucket deny example-bucket --key ro-key

DNS 스타일 vs 경로 스타일 버킷 주소 지정

Garage는 [s3_api].root_domain을 구성하면 가상 호스트 (DNS) 스타일 버킷 접근을 지원할 수 있습니다. 경로 스타일은 항상 활성화됩니다.
vhost 스타일(와일드카드 DNS + 와일드카드 TLS)을 설정하지 않으면, 많은 클라이언트는 경로 스타일을 강제로 사용하여 작동할 수 있으며, Garage 문서는 force_path_style = true를 사용하는 클라이언트 예시를 제공합니다.

TLS

Garage의 S3 API 및 웹 엔드포인트는 TLS를 직접 지원하지 않습니다. 공식 지침은 일반적으로 Nginx와 같은 역방향 프록시를 앞에 배치하여 HTTPS를 제공하고, 포트 443에서 서비스를 복용하는 것입니다.

최소한의 Nginx 구성(공식 역방향 프록시 요리책을 참조하십시오):

# /etc/nginx/sites-available/garage.conf (요약)
upstream garage_s3 { server 127.0.0.1:3900; }

server {
  listen 443 ssl;
  server_name garage.example.com;

  ssl_certificate     /etc/letsencrypt/live/garage.example.com/fullchain.pem;
  ssl_certificate_key /etc/letsencrypt/live/garage.example.com/privkey.pem;

  location / {
    proxy_pass http://garage_s3;
    proxy_set_header Host $host;
  }
}

서버 측 암호화

Garage는 S3 SSE-C(“고객 제공 키를 사용한 서버 측 암호화”)를 지원합니다: 클라이언트는 요청별로 암호화 키를 헤더에 보내고, Garage는 암호화된 상태로 저장한 후 요청이 끝나면 키를 삭제합니다.
Garage의 S3 호환성 표에서는 버킷 수준 암호화 구성 엔드포인트가 구현되지 않았음을 명시하고 있으므로, SSE-C는 오브젝트/요청 기반 행동으로 간주해야 하며 버킷 기본값이 아닙니다.

프로덕션 환경에서 Garage 운영

모니터링 및 로깅

Garage는 Prometheus 형식의 메트릭을 노출하고, OpenTelemetry 형식의 추적을 내보내는 것을 지원합니다.
관리 및 메트릭 엔드포인트는 토큰(admin_token, metrics_token, metrics_require_token)으로 보호될 수 있으며, 추적은 trace_sink(OTLP)를 통해 내보내질 수 있습니다.
로깅은 RUST_LOG로 조정할 수 있으며, 구성 참조는 syslog/journald로 로그를 전송하기 위해 환경 변수를 설명합니다.

내구성, 수리 및 일반 유지보수 작업

Garage는 백그라운드 “스크럽”(정확성 검증) 및 수리 도구를 포함하고 있습니다. 스크럽은 수동으로 시작되고, 워커/태스크 명령을 통해 모니터링할 수 있지만, 디스크 집약적일 수 있고 클러스터 속도를 느리게 할 수 있습니다.
토폴로지 변경 및 용량 조정은 레이아웃 관리를 통해 처리되며, 작업은 새로운 레이아웃 버전으로 적용됩니다.

백업 및 복구 전략

최소한으로 메타데이터를 백업해야 합니다. 메타데이터에는 클러스터 구성, 버킷/키 상태 및 인덱스가 포함되어 있습니다. Garage는 주기적인 메타데이터 스냅샷(metadata_auto_snapshot_interval) 및 수동 스냅샷(garage meta snapshot --all)을 지원합니다.
Garage 이전 가이드에서는 각 노드의 metadata_dir에서 특정 파일/디렉토리를 백업하는 것을 명시적으로 권장합니다(스냅샷 및 레이아웃 파일 포함).

오브젝트 데이터는 S3 엔드포인트와 동일하게 처리하십시오: S3 호환 백업 도구(예: restic, duplicity)를 사용하여 Garage 버킷을 대상으로 하되, Garage의 “백업” 통합 페이지에서 문서화된 대로 합니다.

일반적인 오류 해결

garage status에서 NO ROLE ASSIGNED는 일반적으로 레이아웃을 생성하고 적용하지 않았다는 의미입니다. 해결 방법: garage layout assign …을 실행한 후 garage layout apply를 실행하십시오.
AuthorizationHeaderMalformed는 일반적으로 클라이언트가 잘못된 지역을 사용하고 있음을 나타냅니다. AWS_DEFAULT_REGION(또는 동등한 값)을 [s3_api].s3_region과 일치시켜 주세요.
서명/요청 실패는 경로 스타일과 vhost 스타일의 불일치로 인해 발생할 수 있습니다. vhost 스타일을 위해 [s3_api].root_domain을 구성하거나, 클라이언트에서 경로 스타일을 강제로 사용하십시오(예: rclone의 force_path_style=true).
권한 오류는 일반적으로 “키가 버킷에 허용되지 않음"일 수 있습니다. garage bucket info <bucket>으로 확인하고, garage bucket allow가 올바른 플래그를 사용하는지 확인하십시오.

성능 조정에 주의해야 할 사항

가능한 한 metadata_dir을 SSD에 배치하십시오. Garage 문서에서는 응답 시간 향상과 “드라마틱하게 줄어든” 지연 시간 잠재력을 언급합니다.
block_size와 압축을 신중하게 조정하십시오: Garage의 기본값은 일반적으로 합리적이지만, 구성 참조에서는 트레이드오프를 설명하고, 변경 사항이 새롭게 업로드된 데이터에만 적용됨을 명시합니다.
NVMe가 있다면, 블록 쓰기 동시성을 증가시켜 처리량을 향상시킬 수 있지만, 메모리 사용량이 증가할 수 있습니다. Garage는 block_max_concurrent_writes_per_request에 대한 지침을 제공합니다.
Garage 자체 벤치마크는 지리 분산 설정에서 클러스터 내부 지연 시간의 비용을 강조하고, 지리 지연 시간 영향을 줄이는 설계 선택(예: 합의 리더를 피함)을 강조합니다.

MinIO 및 AWS S3와의 짧은 비교

Garage는 자체 호스팅, 지리 분산 클러스터 및 운영 간소화에 최적화되어 있으며, 일부 S3 기능의 간격이 존재합니다(예: S3 버킷 정책/ACL 없음, 제한된 버전 관리 지원).
MinIO는 S3 API 범위와 고성능 기업 배포에 집중합니다(예: MinIO 자체 자료에서 오브젝트 잠금, 복제, 이벤트 알림과 같은 기능을 설명).
AWS S3는 강력한 일관성, 11 nines 내구성, 99.99% 가용성 목표, 광범위한 기능 생태계(저장 클래스, 생명주기, 이벤트, IAM)를 가진 관리형 참조 구현입니다.

MinIO에 대한 더 많은 정보: