ガレージ - S3 互換オブジェクトストレージ クイックスタート

数分でDocker上にGarageを実行する

目次

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）経由で入り、1つ以上のGarage APIエンドポイント（通常「ゲートウェイ」ノード）に到達し、複製されたデータブロックを保持するストレージノードによって提供されます。

garage- cluster data flow

ノードには役割があります：ストレージノード（容量あり）と、データを保持せずにエンドポイントを公開するゲートウェイノード。ゲートウェイは、追加のネットワークホップを避けることによりレイテンシーを減らし、どのストレージノードをクエリするかを「知っている」ことで効率を高めます。
レプリケーションはreplication_factor（例：ゾーン間の3レプリカ）で制御され、構成リファレンスで明確に可用性/障害耐性のトレードオフが説明されています。

コピペクイックスタート

これは、ワークフローを学ぶための単一ノードの最小限の展開です：構成 → サーバー起動 → レイアウトの定義 → バケット＋キーの作成 → オブジェクトのアップロード。

事前準備

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スタイル。パススタイルは常に有効。
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リダイレクトが発生する可能性があります。

# インストール（オプションの1つ）
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のダウンロードページからバイナリをダウンロードする、ディストリビューションパッケージ（例：apk add garage on Alpine）を使用する、または必要に応じてソースからビルドする。

DockerおよびDocker Compose

Garageはコンテナイメージを提供し、クイックスタート用に最小限のdocker runメソッドをドキュメント化しています。
生産環境では通常、コンポーズ（またはオーケストレータ）を使用して永続ストレージ、リバースプロキシ、アップグレード（ローリング再起動）を管理します。Garageの「クラスタ上の展開」ガイドでは、各ノードにDockerを想定し、一般的なホストパスとメタデータ用のSSD推奨を示しています。

systemd

Garageはsystemdによる強化された展開をドキュメント化しており、systemdのDynamicUser=に関する注意点や、永続状態がディスク上にどこに保存されるかについても説明しています。
最小限のユニット例（環境に応じてパスを調整してください）：

# /etc/systemd/system/garage.service
[Unit]
Description=Garage S3-compatible object storage
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ジョブで自動化できます）。

構成、セキュリティ、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" },
]

アクセス制御モデルと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スタイルとパススタイルのバケットアドレッシング

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）経由でエクスポートできます。
ロギングについては、GarageはRUST_LOGで調整可能であり、構成リファレンスでは、stderrではなくsyslog/journaldにログを送信するための環境変数をドキュメント化しています。

耐障害性、修復、一般的なメンテナンスタスク

Garageにはバックグラウンド「スクラブ」（整合性検証）と修復ツールが含まれています。スクラブは手動で開始でき、ワーカー/タスクコマンドで監視できますが、ディスクに負荷がかかりクラスタの速度を遅くすることがあります。
トポロジ変更および容量調整はレイアウト管理を通じて処理され、操作は新しいレイアウトバージョンとして適用されます。

バックアップと復元戦略

最低限、メタデータをバックアップしてください。メタデータにはクラスタ構成、バケット/キー状態、インデックスが含まれています。Garageは定期的なメタデータスナップショット（metadata_auto_snapshot_interval）と手動スナップショット（garage meta snapshot --all）をサポートしています。
Garageの移行ガイドでは、各ノードのmetadata_dirから特定のファイル/ディレクトリをバックアップすることを明確に推奨しています（スナップショットとレイアウトファイルも含む）。

オブジェクトデータについては、Garageを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についての詳細情報：

有用なリンク