FUSE で R2 バケットをマウントする

FUSE（Filesystem in Userspace）を使うと、Container 内で R2 バケットをファイルシステムとしてマウントできます。アプリケーションはオブジェクトストレージ API ではなく、標準のファイルシステム操作で R2 を扱えます。

ローカルで FUSE コンテナを動かす方法はローカル開発時の FUSE サポートを参照してください。

よくある用途は次のとおりです。

アセットでコンテナをブートストラップする - サンドボックスやエージェント環境向けに、データセット、モデル、依存関係をマウントします
ユーザー状態を永続化する - ダウンロードを管理せずに、ユーザー設定やアプリケーション状態を保存してアクセスします
大きな静的ファイル - コンテナイメージを肥大化させたり、起動時にファイルをダウンロードしたりしません
ファイルの編集 - コンテナ内でコードや設定を使えるようにし、インスタンスをまたいで編集を保存します。

バケットのマウント

R2 バケットをマウントするには、Dockerfile に FUSE アダプターをインストールし、コンテナ起動時に実行するよう設定します。

この例では tigrisfs ↗ を使います。R2 を含む S3 互換ストレージに対応しています。

Dockerfile

FROM alpine:3.20

# Install FUSE and dependencies
RUN apk add --no-cache \ 
    --repository http://dl-cdn.alpinelinux.org/alpine/v3.20/main \
    ca-certificates fuse curl bash

# Install tigrisfs
RUN ARCH=$(uname -m) && \
    if [ "$ARCH" = "x86_64" ]; then ARCH="amd64"; fi && \
    if [ "$ARCH" = "aarch64" ]; then ARCH="arm64"; fi && \
    VERSION=$(curl -s https://api.github.com/repos/tigrisdata/tigrisfs/releases/latest | grep -o '"tag_name": "[^"]*' | cut -d'"' -f4) && \
    curl -L "https://github.com/tigrisdata/tigrisfs/releases/download/${VERSION}/tigrisfs_${VERSION#v}_linux_${ARCH}.tar.gz" -o /tmp/tigrisfs.tar.gz && \
    tar -xzf /tmp/tigrisfs.tar.gz -C /usr/local/bin/ && \
    rm /tmp/tigrisfs.tar.gz && \
    chmod +x /usr/local/bin/tigrisfs

# Create startup script that mounts bucket and runs a command
RUN printf '#!/bin/sh\n\
    set -e\n\
    \n\
    mkdir -p /mnt/r2\n\
    \n\
    R2_ENDPOINT="https://${R2_ACCOUNT_ID}.r2.cloudflarestorage.com"\n\
    echo "Mounting bucket ${R2_BUCKET_NAME}..."\n\
    /usr/local/bin/tigrisfs --endpoint "${R2_ENDPOINT}" -f "${R2_BUCKET_NAME}" /mnt/r2 &\n\
    sleep 3\n\
    \n\
    echo "Contents of mounted bucket:"\n\
    ls -lah /mnt/r2\n\
    ' > /startup.sh && chmod +x /startup.sh

EXPOSE 8080
CMD ["/startup.sh"]

スタートアップスクリプトはマウントポイントを作成し、バックグラウンドで tigrisfs を起動してバケットをマウントし、マウントしたディレクトリの内容を一覧します。

コンテナへ認証情報を渡す

Container には、環境変数として R2 の認証情報と設定を渡す必要があります。認証情報は Worker secrets として保存し、envVars プロパティ経由で渡します。

src/index.jsjs

import { Container, getContainer } from "@cloudflare/containers";

export class FUSEDemo extends Container {
	defaultPort = 8080;
	sleepAfter = "10m";
	envVars = {
		AWS_ACCESS_KEY_ID: this.env.AWS_ACCESS_KEY_ID,
		AWS_SECRET_ACCESS_KEY: this.env.AWS_SECRET_ACCESS_KEY,
		R2_BUCKET_NAME: this.env.R2_BUCKET_NAME,
		R2_ACCOUNT_ID: this.env.R2_ACCOUNT_ID,
	};
}

src/index.tsts

import { Container, getContainer } from "@cloudflare/containers";

interface Env {
  FUSEDemo: DurableObjectNamespace<FUSEDemo>;
  AWS_ACCESS_KEY_ID: string;
  AWS_SECRET_ACCESS_KEY: string;
  R2_BUCKET_NAME: string;
  R2_ACCOUNT_ID: string;
}

export class FUSEDemo extends Container<Env> {
  defaultPort = 8080;
  sleepAfter = "10m";
  envVars = {
    AWS_ACCESS_KEY_ID: this.env.AWS_ACCESS_KEY_ID,
    AWS_SECRET_ACCESS_KEY: this.env.AWS_SECRET_ACCESS_KEY,
    R2_BUCKET_NAME: this.env.R2_BUCKET_NAME,
    R2_ACCOUNT_ID: this.env.R2_ACCOUNT_ID,
  };
}

AWS_ACCESS_KEY_ID と AWS_SECRET_ACCESS_KEY はシークレットとして保存します。R2_BUCKET_NAME と R2_ACCOUNT_ID は wrangler.jsonc の変数として設定できます。

{
  "vars": {
    "R2_BUCKET_NAME": "my-bucket",
    "R2_ACCOUNT_ID": "your-account-id"
  }
}

その他の S3 互換ストレージプロバイダー

AWS S3 や Google Cloud Storage を含む、ほかの S3 互換ストレージプロバイダーも、R2 と同じ方法でマウントできます。そのストレージプロバイダー用のエンドポイント URL とアクセス認証情報を指定します。

バケットのプレフィックスをマウントする

バケット内の特定のプレフィックス（サブディレクトリ）をマウントする場合、ほとんどの FUSE アダプターではバケット全体をマウントし、マウント内のプレフィックスパスへアクセスします。

tigrisfs では、バケットをマウントし、ファイルシステムパス経由でプレフィックスにアクセスします。

RUN printf '#!/bin/sh\n\
    set -e\n\
    \n\
    mkdir -p /mnt/r2\n\
    \n\
    R2_ENDPOINT="https://${R2_ACCOUNT_ID}.r2.cloudflarestorage.com"\n\
    /usr/local/bin/tigrisfs --endpoint "${R2_ENDPOINT}" -f "${R2_BUCKET_NAME}" /mnt/r2 &\n\
    sleep 3\n\
    \n\
    echo "Accessing prefix: ${BUCKET_PREFIX}"\n\
    ls -lah "/mnt/r2/${BUCKET_PREFIX}"\n\
    ' > /startup.sh && chmod +x /startup.sh

アプリケーションは /mnt/r2/${BUCKET_PREFIX} から読み取り、そのプレフィックス配下のファイルだけにアクセスできます。ほかの R2 設定とあわせて、BUCKET_PREFIX を環境変数として渡します。

バケットを読み取り専用でマウントする

アプリケーションがマウントしたバケットへ書き込めないようにするには、-o ro フラグを追加してファイルシステムを読み取り専用でマウントします。

RUN printf '#!/bin/sh\n\
    set -e\n\
    \n\
    mkdir -p /mnt/r2\n\
    \n\
    R2_ENDPOINT="https://${R2_ACCOUNT_ID}.r2.cloudflarestorage.com"\n\
    /usr/local/bin/tigrisfs --endpoint "${R2_ENDPOINT}" -o ro -f "${R2_BUCKET_NAME}" /mnt/r2 &\n\
    sleep 3\n\
    \n\
    ls -lah /mnt/r2\n\
    ' > /startup.sh && chmod +x /startup.sh

共有アセットや設定ファイルなど、アプリケーションに読み取りだけをさせたい場合に役立ちます。