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

Garage は、小規模から中規模の展開に最適化された、オープンソースでセルフホスト可能な S3 互換のオブジェクトストレージシステムです。これは、高耐性と地理的分散性を強調しています。

このクイックスタートでは、コピー＆ペーストで単一ノードのセットアップから、本番環境向けのパターン（クラスタレイアウト、レプリケーション、リバースプロキシ経由の TLS、マルチディスクストレージバックエンド、モニタリング、修復、バックアップ/復元）までを紹介します。

より広い観点—オブジェクトストレージ、PostgreSQL、Elasticsearch、および AI にネイティブなデータレイヤーについて—は、AIシステム向けデータインフラ 記事でご確認ください。

Garage とは

Garage は S3 互換の分散型オブジェクトストレージ で、セルフホストを目的としており、軽量で運用が簡単であることを目指しています。これは、マルチサイト/地理的に分散されたクラスタをサポートしています。
AGPL v3 ライセンスの下でリリースされています。

あなたがどう運用するかを形作る主な考え方：

Garage はノードの容量と物理的な場所（「ゾーン」）を測定し、レプリカを配置します。クラスタのトポロジー変更（ノードの追加/削除）は、バージョン付きレイアウトと再バランス処理によって処理されます。
オブジェクトは固定サイズのブロック（block_size）に分割され、これは重複除去とオプションの Zstandard 圧縮を可能にします。ブロックハッシュは配置および重複除去に使用されます。
Garage は S3 API/webエンドポイントで TLS を終了しません。実際の展開では、リバースプロキシで HTTPS を配置することが期待されています。

アーキテクチャとデータフロー

高レベルでは、Garage は S3 互換のクライアントを通じて操作します。トラフィックは通常、リバースプロキシ（TLS）を経由し、1つ以上の Garage API エンドポイント（通常は「ゲートウェイ」ノード）に到達し、その後、レプリケートされたデータブロックを保持するストレージノードによって提供されます。

ノードには役割があります：ストレージノード（容量）とゲートウェイノード（データを保持せずにエンドポイントを公開）。ゲートウェイは、追加のネットワークホップを避けることにより、レイテンシを低減し、どのストレージノードをクエリするかを「知っている」ためです。
レプリケーションは 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 のダウンロードページからバイナリをダウンロードする、または distro パッケージ（例：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 互換オブジェクトストレージ
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）経由でエクスポートできます。
ログについては、Garage は RUST_LOG で調整でき、構成リファレンスでは、標準エラー出力ではなく 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）を持つマネージドリファレンス実装です。

詳細については、Garage vs MinIO vs AWS S3 比較 をご覧ください。

MinIO についての詳細情報：

• MinIO は AWS S3 の代替。MinIO の概要とインストール
• MinIO コマンドラインパラメータチートシート

有用なリンク

• Garage HQ ドキュメント（メイン）
• Garage クイックスタート
• Garage 構成ファイル形式
• Garage リバースプロキシ / TLS
• Garage マルチHDDサポート
• Garage レイアウト管理
• Garage 耐久性 & 修復
• Garage バックアップ統合
• Garage GitHub ミラー