Skip to main content

Cloudflare R2 as your own storage

Bring-Your-Own-Storage (BYOS) lets a project keep its bytes in a bucket you own. R2 is an available BYOS provider, and BYOS is the way R2 becomes your project's storage. The storage location you create here is the single source of truth for where those bytes live.

This guide covers R2 specifically. The model is shared across providers, so what you learn here carries over.

1. What BYOS controls, and what it doesn't​

BYOS decides where bytes are stored: your R2 bucket, in your Cloudflare account. It does not decide who holds the key that protects them. That is the project's custody mode, and the two compose independently. A project can use BYOS with platform-managed keys, or BYOS with keys you hold (BYOK or HYOK).

2. What you need from Cloudflare​

  • A bucket. Create it in your Cloudflare account. Bucket creation, lifecycle rules, and custom-domain setup are done in Cloudflare's dashboard, not through Kilimanjaro.
  • An R2 API token the platform can use to mint short-lived credentials against your bucket. Scope it to R2 temporary-credential creation on that one bucket and nothing more.
  • Your Cloudflare account ID (accountId).
  • The Access Key ID of that API token (parentAccessKeyId). The platform uses it as the parent when it mints each short-lived credential.

accountId and parentAccessKeyId are both required for R2. They are not secrets. Creating a location without them is refused before anything is stored.

3. Store your token and get a credential reference​

A storage location never holds your token. It holds a credential reference, a kibo://byos-creds/<secId> pointer to a secret in your project's vault. You create the secret first:

k9o byos-cred create byos/r2-prod --provider r2 --region <your project region> --api-token <token>

This seals the token as a private vault secret under the reserved byos-creds/ namespace and prints the kibo://byos-creds/<secId> reference. For R2 the secret holds only the API token. accountId and parentAccessKeyId are not secret, and go on the storage location itself (§4).

Prefer the K9O_BYOS_API_TOKEN environment variable or the interactive prompt to the --api-token flag, so the token isn't left in your shell history.

Your token is sent over TLS through the platform API to the vault, where it's encrypted under your project's key. The platform never stores it anywhere else and never shows it back to you; only the storage service uses it, to mint short-lived credentials scoped to your bucket.

The storage-location route in §4 takes only the reference. They never accept a raw credential. When the platform writes to your bucket, a short-lived credential scoped to that bucket is minted inside the confined execution core from your token, and your long-lived key is revealed only to that core.

R2 API tokencreated inyour Cloudflare accountVault secretsealed in your vaultbyos-creds/ namespaceStorage locationholds the kibo://reference, not the tokenExecution coremints short-livedscoped credentialon each writeYour R2 bucketin your Cloudflare account
The storage location never holds the token; only the execution core uses it, to mint a short-lived credential for your bucket.

4. Create a storage location​

A BYOS storage location is per project. Creating one requires the project admin role; project viewers have read-only access.

POST <orgSlug>.api.k9o.io/@<projectSlug>/storage/locations
{
"provider": "r2",
"bucketName": "my-bucket",
"region": "<your project region>",
"providerRegion": "auto",
"credentialRef": "kibo://byos-creds/<secId>",
"providerParams": {
"accountId": "<your Cloudflare account ID>",
"parentAccessKeyId": "<Access Key ID of your R2 API token>"
}
}

region is the platform region of the project, and providerRegion is the provider's own region; for R2 it is always auto. Both are required. endpointOverride is optional, for the case where you need a non-default endpoint. credentialRef is validated before the location is created.

To re-point a location at a different credential, for example when you rotate your token, PATCH the location with a new credentialRef. Create the new secret first (§3), then re-point. The location validates the new reference and switches to it.

5. Test it​

POST <orgSlug>.api.k9o.io/@<projectSlug>/storage/locations/<location-id>/test

Run a test against a location after you create or re-point it. The test is a dry run: it does not make a live connection to your bucket.

6. Where an R2 location is used​

  • Audit-anchor capture. Anchored audit archives can be written to your bucket.
  • Documents and files. Project file storage can live in your bucket: uploads (including multipart), signed-URL reads, and deletes all resolve to your R2 bucket instead of a platform-managed one.
  • Extension static assets. Static bundles that an extension publishes, such as Console iframe assets, are served from your bucket.
  • Lakehouse datasets. A Lakehouse dataset can live in your bucket, chosen per dataset when you create it. A dataset references its storage location explicitly: set storageTarget to { "kind": "byos", "bindingId": "<location-id>" } when you create the dataset.

7. Retiring a storage location​

Retiring is a soft retire: the location's history is kept for audit, and nothing is hard-deleted. What happens next differs by use, and it matters.

Retire locationsoft retire, history keptFiles, audit anchors, extension assetsnext write falls back to platform-managed storageno error, no blockLakehouse datasetsthe dataset names its location by explicit ID, so no fallbackfails closed: K9O_DATASET_STORAGE_TARGET_INVALID
Retiring silently moves new file writes to platform-managed storage, while a dataset fails closed.
  • Files, audit anchors and extension assets. After you retire the active location, the next write falls back to platform-managed storage. There is no error and no block. This is a change in where your data physically lands, and it produces no visible failure, so check that you want it before you retire.
  • Lakehouse datasets. A dataset references its location by explicit ID, so there is nothing to fall back to. Any later operation against the retired location fails closed with K9O_DATASET_STORAGE_TARGET_INVALID.

If you are moving to a new bucket, create and test the new location first, then retire the old one.

8. See also​