Cloudflare.LoadBalancer reference

LoadBalancer

Source: packages/cloudflare/src/LoadBalancer/LoadBalancer.ts

A Cloudflare Load Balancer — a zone-level DNS hostname that distributes traffic across Pools with health-based failover, geo/latency steering, and session affinity.

Requires the Load Balancing subscription to be enabled for the zone; without it, creation fails with the typed LoadBalancingNotEnabledForZone error.

LoadBalancer: Creating a Load Balancer

DNS-only (unproxied) load balancer

const lb = yield* Cloudflare.LoadBalancer.LoadBalancer("ApiLb", {
  zoneId: zone.zoneId,
  name: "api.example.com",
  defaultPools: [pool.poolId],
  fallbackPool: pool.poolId,
  proxied: false,
  ttl: 30,
});

Proxied load balancer with steering and affinity

const lb = yield* Cloudflare.LoadBalancer.LoadBalancer("AppLb", {
  zoneId: zone.zoneId,
  name: "app.example.com",
  defaultPools: [primary.poolId, secondary.poolId],
  fallbackPool: secondary.poolId,
  proxied: true,
  steeringPolicy: "random",
  sessionAffinity: "cookie",
});

LoadBalancer: Geo steering

yield* Cloudflare.LoadBalancer.LoadBalancer("GeoLb", {
  zoneId: zone.zoneId,
  name: "geo.example.com",
  defaultPools: [us.poolId],
  fallbackPool: us.poolId,
  steeringPolicy: "geo",
  regionPools: {
    WEU: [eu.poolId],
    ENAM: [us.poolId],
  },
});

Monitor

Source: packages/cloudflare/src/LoadBalancer/Monitor.ts

A Cloudflare Load Balancing monitor — an active health check (HTTP, HTTPS, TCP, ICMP, or SMTP probe) that Load Balancing pools reference to decide which origins are healthy.

Monitors are account-scoped and have no name field; the description carries the physical name so lost state can be recovered. All properties are mutable in place.

Requires the Load Balancing subscription on the account. The allowed interval range is plan-dependent.

Monitor: Creating a Monitor

HTTPS health check

const monitor = yield* Cloudflare.LoadBalancer.Monitor("ApiMonitor", {
  type: "https",
  path: "/health",
  expectedCodes: "2xx",
});

TCP port check

const tcp = yield* Cloudflare.LoadBalancer.Monitor("DbMonitor", {
  type: "tcp",
  port: 5432,
});

Monitor: Using with a Pool

const pool = yield* Cloudflare.LoadBalancer.Pool("ApiPool", {
  origins: [{ name: "origin-1", address: "203.0.113.10" }],
  monitor: monitor.monitorId,
});

Monitor: Looking up an existing Monitor

Monitor.lookup reads a monitor Alchemy doesn’t manage (created in the dashboard or by another stack), found by monitorId or description, so pools can use it. It is read during plan/deploy and never created, updated or deleted.

const monitor = Cloudflare.LoadBalancer.Monitor.lookup({
  description: "shared-http-health",
});
const pool = yield* Cloudflare.LoadBalancer.Pool("ApiPool", {
  origins: [{ name: "origin-1", address: "203.0.113.10" }],
  monitor: monitor.monitorId,
});

MonitorGroup

Source: packages/cloudflare/src/LoadBalancer/MonitorGroup.ts

A Cloudflare Load Balancing monitor group — aggregates several Monitors into one health signal that a Pool can reference via monitorGroup (mutually exclusive with monitor).

Monitor groups are an Enterprise-only feature; on non-entitled accounts creation fails with the typed MonitorGroupsNotEnabled error.

MonitorGroup: Creating a Monitor Group

const group = yield* Cloudflare.LoadBalancer.MonitorGroup("ApiChecks", {
  members: [
    { monitorId: httpsMonitor.monitorId },
    { monitorId: tcpMonitor.monitorId, mustBeHealthy: false },
  ],
});

MonitorGroup: Using with a Pool

yield* Cloudflare.LoadBalancer.Pool("ApiPool", {
  origins: [{ name: "origin-1", address: "203.0.113.10" }],
  monitorGroup: group.monitorGroupId,
});

MonitorGroup: Looking up an existing monitor group

MonitorGroup.lookup references a group Alchemy doesn’t manage (created in the dashboard or by another stack), found by monitorGroupId or description. It is read during plan/deploy and never created, updated or deleted.

const group = Cloudflare.LoadBalancer.MonitorGroup.lookup({ description: "api-health" });
yield* Cloudflare.LoadBalancer.Pool("ApiPool", {
  origins: [{ name: "origin-1", address: "203.0.113.10" }],
  monitorGroup: group.monitorGroupId,
});

Pool

Source: packages/cloudflare/src/LoadBalancer/Pool.ts

A Cloudflare Load Balancing pool — an account-scoped group of origin servers that Load Balancers route traffic to. Pools optionally reference a Monitor for active health checking.

Requires the Load Balancing subscription on the account; without it, pool creation fails with the typed PoolAccessFailed error.

Pool: Creating a Pool

Pool with one origin

const pool = yield* Cloudflare.LoadBalancer.Pool("ApiPool", {
  origins: [{ name: "origin-1", address: "203.0.113.10" }],
});

Health-checked pool

const monitor = yield* Cloudflare.LoadBalancer.Monitor("ApiMonitor", {
  type: "https",
  path: "/health",
  expectedCodes: "2xx",
});

const pool = yield* Cloudflare.LoadBalancer.Pool("ApiPool", {
  origins: [
    { name: "origin-1", address: "203.0.113.10", weight: 0.7 },
    { name: "origin-2", address: "203.0.113.11", weight: 0.3 },
  ],
  monitor: monitor.monitorId,
  minimumOrigins: 1,
});

Pool: Using with a Load Balancer

yield* Cloudflare.LoadBalancer.LoadBalancer("ApiLb", {
  zoneId: zone.zoneId,
  name: "api.example.com",
  defaultPools: [pool.poolId],
  fallbackPool: pool.poolId,
});

Pool: Looking up an existing Pool

Pool.lookup reads a pool Alchemy doesn’t manage (created in the dashboard or by another stack), found by poolId or name, so a load balancer can route to it. It is read during plan/deploy and never created, updated or deleted.

const pool = Cloudflare.LoadBalancer.Pool.lookup({ name: "api-origins" });
yield* Cloudflare.LoadBalancer.LoadBalancer("ApiLb", {
  zoneId: zone.zoneId,
  name: "api.example.com",
  defaultPools: [pool.poolId],
  fallbackPool: pool.poolId,
});