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.
At a glance
Section titled “At a glance”| Concern | Cloudflare answer |
|---|---|
| Connection type | cloudflare. token is the one required credential; account_id is an optional ride-along that pins the account (recommended). |
| DNS | The cloudflare DNS provider, the same as before. zones are confirmed at connect. |
| Object storage | The s3 capability, impl cloudflare-r2. Endpoint <account>.r2.cloudflarestorage.com, region auto, port 443. |
| What a bind mints | One 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 domain | Attached when the scope names one for the bucket, and only under a zone the connection confirmed. |
| What destroy removes | The 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. |
The token you mint
Section titled “The token you mint”Mint one account API token in the Cloudflare dashboard (My Profile → API Tokens → Create Token → Custom). Give it:
| Scope | Permission | Why |
|---|---|---|
| Zone → DNS | Edit | the DNS provider, and the record the R2 custom domain rides on |
| Zone → Zone | Read | GET /zones?name=: the zone confirmation at connect and the zone id for the custom domain |
| Account → Workers R2 Storage | Edit | create the bucket, attach the custom domain |
| Account → Account API Tokens | Edit | mint 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.
The four commands
Section titled “The four commands”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.
-
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 publicresource "shc_connection" "cloudflare" {name = "cloudflare"type = "cloudflare"credentials = { token = var.cloudflare_token, account_id = var.cloudflare_account }zones = ["basedlinux.com"]} -
Grant
s3to 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 nodomainsentry 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.namecapability = "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--boundaryoff entirely and a plain binding mints a bucket namedshc-<tenant>-<stack>. -
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=cloudflareThe 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;
bucketon the socket is the first sorted. -
Bind it to pulp as a mirror target. The target name is the bucket name:
Terminal window shc update pulp -C mirror.apt-basedlinux=cloudflareSee pulp mirror targets for what that renders and how the probe gates the converge.
The scope document
Section titled “The scope document”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’spolicy:and the grant’s--boundaryintersect; 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 (X400483CFRZONotherwise).
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 mintsapt-basedlinuxand 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’sbucketbeing 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.
What the daemon does not do
Section titled “What the daemon does not do”- 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 uninstallof 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 (X200485CFRKEPnames what was kept). shc connection rm cloudflarerefuses while any deployment still holds a minted key (X409903CONUSE); uninstall or rebind first.