Configure GCS

1. Create a bucket

Create a bucket in your project. (Uniform bucket-level access is recommended.)

2. Grant permissions

Grant the service account Storage Object Admin (roles/storage.objectAdmin) on the bucket. That includes the following required permissions:

Permission	Used for
storage.objects.get	reads and existence checks
storage.objects.create	writes and resumable uploads
storage.objects.delete	deletes and aborting uploads
storage.objects.list	listing a prefix

3. Generate a service-account key

LoonFS authenticates with a service-account key file:

gcloud iam service-accounts keys create ./loonfs-gcs.json \
  --iam-account {service_account_email}

4. Create the LoonFS profile

loonfs --no-input profile create gcs production \
  --bucket {bucket_name} \
  --service-account-key-path ./loonfs-gcs.json

loonfs profile use production

Optional: --key-prefix to scope LoonFS within the bucket.

GCS supports direct GET and direct PUT using CRC32C. It does not support direct multipart as of today. However, clients can still use GCS’s relatively large direct PUT ceiling for large objects.

CORS

Browser clients using direct_upload methods must configure bucket CORS for the application origin and returned signed headers.

5. Verify

loonfs maintenance store probe

GCS compare-and-swap rate limit

Google Cloud rate-limits compare-and-swap to roughly one write per second per object.

LoonFS uses native GCS generation preconditions to coordinate metadata updates. This limit can therefore impact maximum commit latency for a busy namespace, and some writes can take up to ~1s before acknowledgement.

See Tradeoffs and Write-ahead log.