Skip to content

Runbook: Onboard a New GCS Bucket to Cloudflare R2 Sync

This document outlines the repeatable, step-by-step process for onboarding a new GCS bucket to the existing Cloudflare R2 synchronization pipeline and CDN distribution network.

Note: If you are setting up this infrastructure from scratch for the very first time, please refer to the GCP to Cloudflare R2 Synchronization & CDN Distribution before proceeding.

The Runbook (Repeatable Process)

Follow these steps every time a new resource type or service requires a dedicated GCS-to-R2 sync and CDN endpoint.

Step 1: Create the Cloudflare R2 Bucket & Credentials

Create the destination bucket in Cloudflare and generate access keys.

  1. In the Cloudflare Dashboard, navigate to R2 and click Create bucket.
  2. Name the bucket following our convention (e.g., <resource-type>-<env>).
  3. Go to Manage R2 API Tokens and click Create Account API token.
  4. Set permissions to Object Read & Write and explicitly restrict access to the bucket you just created.
  5. Securely save the Access Key ID, Secret Access Key, and Endpoint URL.

Step 2: Configure Cloud Run & Eventarc Triggers

Connect the new GCS bucket to our synchronization service.

Assuming the base ac-r2-sync-service container is already deployed. If you deploy a new Cloud Run instance per bucket, create a new service using the existing container image and inject the R2 credentials from Step 1.

  1. In the GCP Console, go to your Cloud Run sync service.
  2. If using a dedicated instance per bucket, update the Variables & Secrets with the new R2_BUCKET_NAME, R2_ACCESS_KEY, and R2_SECRET_KEY.
  3. Go to the Triggers tab and click Add Eventarc Trigger.
  4. Add Upload Trigger:
    • Event provider: Cloud Storage
    • Event type: google.cloud.storage.object.v1.finalized
    • Bucket: Select the new source GCS bucket.
    • Service Account: r2-sync-service-account
  5. Add Deletion Trigger:
    • Repeat the process above, but select the google.cloud.storage.object.v1.deleted event type.

Step 3: Migrate Existing Legacy Data

Eventarc only syncs new files. Move any existing data from the GCS bucket to R2.

  1. In the Cloudflare Dashboard, go to R2 > Data Migration.
  2. Click Migrate data from Google Cloud Storage.
  3. Enter your GCS bucket details and upload the GCP Service Account JSON key (requires Storage Object Admin).
  4. Enter your new R2 bucket credentials (from Step 1) and start the migration.

Step 4: Create Cloudflare CDN Worker & Bind R2

Deploy a new Worker to act as the secure CDN layer for this specific bucket.

  1. Clone the repository: https://github.com/appcircleio/ac-cloudflare-cdn-worker
  2. In the Cloudflare Dashboard, go to Workers & Pages > Overview.
  3. Click Create application > Create Worker. Name it (e.g., <resource-type>-cdn-<env>) and click Deploy.
  4. Go to the Worker's Settings > Bindings tab.
  5. Under R2 Bucket Bindings, click Add binding. Bind the variable BUCKET to the R2 bucket you created in Step 1.
  6. Go to the Settings > Variables tab. Add the following as an encrypted environment variable:
    • ASPNETCORE_CLOUDFLARE_URL_SIGN_SECRET (Use your secure random secret string).
  7. Click Edit Code at the top of the page, paste the source code from the repository, and click Save and Deploy. (Note: Automation via Jenkins is planned for this step).

Step 5: Map the CDN in the Resource Service

Route backend traffic for this specific resource through the Cloudflare Worker CDN.

  1. Update the .NET Resource Server environment variables (or config map).
  2. Append the new resource to the CDN mapping: 
    # Add your new resource to the existing mapping
ASPNETCORE_S3_CDN_MAPPING="...,NewResource=https://<new-worker-domain>.workers.dev"
  3. If this resource requires URL signing, ensure it is routed to the Cloudflare module: 
    ASPNETCORE_CDN_MODULE_PROVIDERS="...,NewResource=CLOUDFLARE"
  4. Deploy/Restart the Resource Service to apply changes.

Validation Checklist

Whenever you onboard a new bucket, verify the following:

  • Cloudflare R2 bucket created and scoped API tokens generated.
  • Eventarc finalized and deleted triggers attached to the correct GCS bucket.
  • Historical data successfully migrated via R2 Data Migration.
  • ASPNETCORE_S3_CDN_MAPPING updated with the new CDN endpoint.
  • Upload a test file to the GCS bucket and verify it appears in the R2 bucket within seconds.
  • Fetch the file via the CDN URL and verify the signature/response.