Cloudflare.CustomHostname reference

CustomHostname

Source: src/Cloudflare/CustomHostname/CustomHostname.ts

A Cloudflare for SaaS custom hostname.

Onboards a customer-owned hostname onto your zone with a managed TLS certificate. The customer points their DNS (CNAME) at your zone; Cloudflare validates ownership and issues a certificate asynchronously. The first 100 custom hostnames are free on any plan.

Traffic for custom hostnames is routed to the zone’s FallbackOrigin (or customOriginServer with the Enterprise entitlement), so a fallback origin should usually be deployed alongside.

Safety: when there is no prior state, read scans the zone for an existing hostname match. Custom hostnames carry no ownership markers, so an existing match is reported as Unowned and the engine refuses to take it over unless --adopt (or adopt(true)) is set.

CustomHostname: Creating a Custom Hostname

Basic custom hostname with TXT validation

const hostname = yield* Cloudflare.CustomHostname.CustomHostname("CustomerApp", {
  zoneId: zone.zoneId,
  hostname: "app.customer.com",
});
// Hand these to the customer so they can verify ownership:
// hostname.ownershipVerification?.name / .value

HTTP validation with a specific certificate authority

yield* Cloudflare.CustomHostname.CustomHostname("CustomerApp", {
  zoneId: zone.zoneId,
  hostname: "app.customer.com",
  ssl: {
    method: "http",
    type: "dv",
    certificateAuthority: "google",
  },
});

CustomHostname: Pairing with a Fallback Origin

const record = yield* Cloudflare.DNS.Record("Origin", {
  zoneId: zone.zoneId,
  name: "origin.my-saas.com",
  type: "A",
  content: "203.0.113.1",
  proxied: true,
});
yield* Cloudflare.CustomHostname.FallbackOrigin("Fallback", {
  zoneId: zone.zoneId,
  origin: record.name,
});
yield* Cloudflare.CustomHostname.CustomHostname("CustomerApp", {
  zoneId: zone.zoneId,
  hostname: "app.customer.com",
});

FallbackOrigin

Source: src/Cloudflare/CustomHostname/FallbackOrigin.ts

The Cloudflare for SaaS fallback origin of a zone.

A zone-level singleton: requests to any of the zone’s custom hostnames that don’t have a customOriginServer are routed to this origin. Setting a fallback origin implicitly enables Cloudflare for SaaS on the zone.

Safety: when there is no prior state, read reports an existing fallback origin as Unowned, so the engine refuses to overwrite an out-of-band configuration unless --adopt (or adopt(true)) is set.

FallbackOrigin: Setting the Fallback Origin

const record = yield* Cloudflare.DNS.Record("Origin", {
  zoneId: zone.zoneId,
  name: "origin.my-saas.com",
  type: "A",
  content: "203.0.113.1",
  proxied: true,
});
const fallback = yield* Cloudflare.CustomHostname.FallbackOrigin("Fallback", {
  zoneId: zone.zoneId,
  origin: record.name,
});