Skip to content
SHC Docs

Cloudflare

Cloudflare is not a compute substrate; it is the connection most estates already have for DNS. Since SHC-849 the same cloudflare connection also offers the s3 capability, and unlike the s3 connection type (which holds a key pair you pasted) this one provisions: the daemon creates the R2 bucket, mints an account API token scoped to that bucket alone, derives the S3 key pair from it, and attaches a public hostname under a zone the connection holds. A deployment bound to it never sees a pasted credential.

ConcernCloudflare answer
Connection typecloudflare. token is the one required credential; account_id is an optional ride-along that pins the account (recommended).
DNSThe cloudflare DNS provider, the same as before. zones are confirmed at connect.
Object storageThe s3 capability, impl cloudflare-r2. Endpoint <account>.r2.cloudflarestorage.com, region auto, port 443.
What a bind mintsOne R2 bucket (or the set the scope names), one account-owned API token scoped to exactly those buckets, accessKey = the token id, secretKey = sha256 of the token value.
Custom domainAttached when the scope names one for the bucket, and only under a zone the connection confirmed.
What destroy removesThe token it minted, the domain it attached, and a bucket it created if it is still empty. It never lists or deletes objects; a bucket holding data is retained and named in a warning.

Mint one account API token in the Cloudflare dashboard (My Profile → API Tokens → Create Token → Custom). Give it:

ScopePermissionWhy
Zone → DNSEditthe DNS provider, and the record the R2 custom domain rides on
Zone → ZoneReadGET /zones?name=: the zone confirmation at connect and the zone id for the custom domain
Account → Workers R2 StorageEditcreate the bucket, attach the custom domain
Account → Account API TokensEditmint the per-bucket token, and read the permission-group ids it needs

Restrict the zone resources to the zone(s) you will declare, and the account resources to the one account. If the custom-domain attach ever answers 403, add Zone → SSL and Certificates → Edit; Cloudflare provisions the edge certificate on attach.

Then put the token where secrets live: ~/.drover/tokens/cloudflare.token, mode 600. The connection reads it from terraform or the CLI; the daemon escrows it to the vault and never returns it.

The account id is on the dashboard’s overview page for any zone. Passing it as account_id saves a GET /accounts at every mint and is required when the token can see more than one account.

Every step below is a terraform resource too; the CLI form is shown because it is what you type on the estate. Substitute basedlinux.com, corp and the account id.

  1. Add the connection (DNS + R2 from one token):

    Terminal window
    shc connection connect cloudflare --type cloudflare --scope system \
    --cred account_id=<account-id> \
    --cred token=- --value-file "$HOME/.drover/tokens/cloudflare.token" \
    --zone basedlinux.com --purpose public
    resource "shc_connection" "cloudflare" {
    name = "cloudflare"
    type = "cloudflare"
    credentials = { token = var.cloudflare_token, account_id = var.cloudflare_account }
    zones = ["basedlinux.com"]
    }
  2. Grant s3 to the tenant, naming the buckets it may mint and the public hostnames they may carry. The bucket names are the mirror target names (see step 4); a bucket with no domains entry gets no hostname.

    Terminal window
    shc connection grant cloudflare --tenant master --capability s3 --grantee corp \
    --boundary '{"buckets":["apt-basedlinux"],"domains":{"apt-basedlinux":"apt.basedlinux.com"}}'
    resource "shc_connection_grant" "cloudflare_s3_corp" {
    connection_name = shc_connection.cloudflare.name
    capability = "s3"
    grantee = "corp"
    boundary_policy = jsonencode({
    buckets = ["apt-basedlinux"]
    domains = { "apt-basedlinux" = "apt.basedlinux.com" }
    })
    }

    No {"unscoped":true} acknowledgement is needed: this capability is a scoped mint, never a hold. Leave --boundary off entirely and a plain binding mints a bucket named shc-<tenant>-<stack>.

  3. Deploy a generic R2 provider: external-s3 as cloudflare-r2, so any app can -i s3=cloudflare-r2:

    Terminal window
    shc install external-s3 -t <tenant> --stack cloudflare-r2 -C s3=cloudflare

    The socket serves the minted endpoint, region, bucket and key pair, and external-s3’s own discovery probe verifies the bucket before the first consumer attaches. A boundary naming several buckets creates and scopes every one; bucket on the socket is the first sorted.

  4. Bind it to pulp as a mirror target. The target name is the bucket name:

    Terminal window
    shc update pulp -C mirror.apt-basedlinux=cloudflare

    See pulp mirror targets for what that renders and how the probe gates the converge.

The s3 scope vocabulary is shared with the held s3 type and stays tiny:

{"buckets": ["apt-basedlinux", "bin-basedlinux"],
"domains": {"apt-basedlinux": "apt.basedlinux.com"}}
  • buckets: the set a mint may create and scope to. The app’s policy: and the grant’s --boundary intersect; a many-bound target must be in the set when the set is non-empty.
  • domains: bucket → public hostname, or a list of them. The app’s policy and the boundary may each name some; if both do, the app’s must be among the boundary’s, and each hostname must fall under a zone the connection confirmed at connect (X400483CFRZON otherwise).

Refusals happen before the first write: a domain outside the zones, a target outside the scope, a malformed document, or a token that resolves more than one account with no account_id (X400481CFRACC).

One boundary per tenant, and what a plain binding does with it

Section titled “One boundary per tenant, and what a plain binding does with it”

A grant is keyed on (connection, capability, grantee), so there is exactly one boundary for cloudflare + s3 + corp. Everything that tenant mints against that connection is capped by it, and the two binding shapes read it differently:

  • a many binding (-C mirror.apt-basedlinux=cloudflare) picks its own name and checks it against the set. It mints apt-basedlinux and nothing else, whatever else the boundary lists.
  • a plain binding (-C s3=cloudflare) has no name of its own, so it takes the whole effective set: it creates every bucket the boundary lists and scopes its token to all of them, with the socket’s bucket being the first sorted.

So with the step-2 boundary above, the cloudflare-r2 stack in step 3 serves apt-basedlinux, the same bucket the mirror target uses. That is usually what you want for a provider stack that exists to front the estate’s R2, and it is why the two steps share one boundary.

If you want the generic stack on a bucket of its own, name it in the same boundary and address it per consumer, or leave the bucket list off the boundary entirely (--boundary '{"domains":{…}}', or no --boundary at all) and every plain binding derives shc-<tenant>-<stack> instead. What you cannot do is give one tenant two different bucket sets for the same connection: that is one grant, by construction.

  • It never stores the account token anywhere but the vault, and never puts it in a render context; only the minted, bucket-scoped key pair reaches a deployment.
  • It never deletes objects. shc uninstall of a bound stack revokes the token, detaches the domain it attached, and deletes the bucket only when the mint created it and R2 reports it empty (X200485CFRKEP names what was kept).
  • shc connection rm cloudflare refuses while any deployment still holds a minted key (X409903CONUSE); uninstall or rebind first.