diff --git a/src/content/changelog/workers/2025-12-22-explicit-placement-hints.mdx b/src/content/changelog/workers/2025-12-22-explicit-placement-hints.mdx index 58d87a031953f7..8a5d33d48cadee 100644 --- a/src/content/changelog/workers/2025-12-22-explicit-placement-hints.mdx +++ b/src/content/changelog/workers/2025-12-22-explicit-placement-hints.mdx @@ -1,6 +1,6 @@ --- title: New Placement Hints for Workers -description: You can now explicitly place Workers close to your existing cloud infrastructure in order to minimize network latency to existing services and databases. +description: You can now explicitly place Workers close to your existing infrastructure in order to minimize network latency to existing services and databases. products: - workers date: 2025-12-22 @@ -24,7 +24,36 @@ To [set a placement hint](/workers/configuration/smart-placement/#placement-hint -Placement hints support GCP and AWS region identifiers, and will run your Workers in the [Cloudflare datacenter](https://www.cloudflare.com/network/) with the lowest latency to the specified cloud region. +Placement hints support GCP, AWS, and Azure region identifiers, and will run your Workers in the [Cloudflare datacenter](https://www.cloudflare.com/network/) with the lowest latency to the specified cloud region. + +If your existing infrastructure is not in one of these legacy clouds, you may instead expose it to placement probes by setting the `placement.host` field for layer 4 probes, or `placement.hostname` field for layer 7 probes. + +Note that these probes are designed to locate single-homed infrastructure, and so are not suitable for anycasted or multicasted resources. + + + +```jsonc +{ + "placement": { + "host": "my_database_host.com:5432" + } +} +``` + + + + + +```jsonc +{ + "placement": { + "hostname": "my_api_server.com" + } +} +``` + + + This is an extension of [Smart Placement](/workers/configuration/smart-placement/), which automatically places your Workers closer to the backend APIs based on measured latency. When you don't know the location of your backend APIs, and/or where there are multiple backend APIs, we recommend setting `mode: "smart"`: @@ -38,4 +67,4 @@ This is an extension of [Smart Placement](/workers/configuration/smart-placement } ``` - + \ No newline at end of file diff --git a/src/content/docs/workers/configuration/smart-placement.mdx b/src/content/docs/workers/configuration/smart-placement.mdx index 054bb475cc8a07..def0bdd8a8eb5d 100644 --- a/src/content/docs/workers/configuration/smart-placement.mdx +++ b/src/content/docs/workers/configuration/smart-placement.mdx @@ -17,7 +17,7 @@ Cloudflare provides two placement options: | Option | Best for | Configuration | | --- | --- | --- | | **Smart Placement** | Workers that connect to multiple back-end services, or when you do not know the exact location of your infrastructure | `mode = "smart"` | -| **Placement Hints** | Workers that connect to infrastructure in a specific AWS or GCP region | `region = "aws:us-east-1"` | +| **Placement Hints** | Workers that connect to infrastructure in a specific location | `region = "aws:us-east-1"` OR `host = "my_api_server.com:8080"` | Both options reduce latency by minimizing round trips between your Worker and back-end services. With placement, you can achieve single-digit millisecond latency to databases, APIs, and other services running in legacy cloud infrastructure. @@ -123,12 +123,12 @@ The `cf-placement` header may be removed before Smart Placement exits beta. ## Placement Hints -Placement Hints let you explicitly specify a cloud region where your Worker should run. Use Placement Hints when your Worker connects to infrastructure in a known cloud region, such as databases, services running on virtual machines, or Kubernetes clusters. By placing your Worker near this infrastructure, you can achieve single-digit millisecond latency to your back-end services — as if your Worker is co-located in the same cloud region. +Placement Hints let you explicitly specify where your Worker should run. Use Placement Hints when your Worker connects to inherently single-homed infrastructure such as databases, services running on virtual machines, or Kubernetes clusters. By placing your Worker near this infrastructure, you can achieve single-digit millisecond latency to your back-end services — as if your Worker is co-located in the same cloud region. Placement Hints are ideal when back-end requests are on the critical path for your users. For example, if your Worker queries a database on every request, reducing that round-trip latency from 20-30ms per query to 1-3ms significantly improves overall response times. :::note -Workers run on [Cloudflare's global network](https://www.cloudflare.com/network/), not inside cloud provider regions. Placement Hints run your Worker in the Cloudflare data center with the lowest latency to your specified cloud region. +Workers run on [Cloudflare's global network](https://www.cloudflare.com/network/), not inside cloud provider regions. Placement Hints run your Worker in the Cloudflare data center with the lowest latency to your specified cloud region or service. ::: :::note @@ -139,6 +139,8 @@ At extremely high request and query volumes (hundreds of thousands of requests p Set the `placement.region` property in your Wrangler configuration file using the format `{provider}:{region}`: +Cloudflare maps your specified cloud region to the data center with the lowest latency to that region. + ```jsonc @@ -151,7 +153,35 @@ Set the `placement.region` property in your Wrangler configuration file using th -Cloudflare maps your specified cloud region to the data center with the lowest latency to that region. Cloudflare automatically adjusts placement to account for network maintenance or changes, so you do not need to specify failover regions or take manual action. +Identify a layer 4 service that your Worker will want to communicate with using the `placement.host` property. Cloudlfare will use TCP CONNECT requests to measure latency to your service and determine the most performant datacenter to run your Worker within. Identify a layer 7 service that your Worker will want to communicate with using the `placement.hostname` property. Cloudlfare will use HTTP HEAD requests to measure latency to your service and determine the most performant datacenter to run your Worker within. + +Probes to these services will be sent from public IP ranges, not the Cloudflare ranges. Serivce location will be re-checked at regular intervals. These probes are designed to locate single-homed resources, and will not perform as expected when searching for broadcast, anycast, multicast, or replicated resources. + + + +```jsonc +{ + "placement": { + "hostname": "my_api_server.com" + } +} +``` + + + + + +```jsonc +{ + "placement": { + "host": "my_database_host.com:5432" + } +} +``` + + + +Cloudflare automatically adjusts placement to account for network maintenance or changes, so you do not need to specify failover regions or take manual action. ### Supported regions @@ -161,8 +191,9 @@ Placement Hints support AWS and GCP region identifiers: | --- | --- | --- | | AWS | `aws:{region}` | `aws:us-east-1`, `aws:eu-west-1`, `aws:ap-southeast-1` | | GCP | `gcp:{region}` | `gcp:us-central1`, `gcp:europe-west1`, `gcp:asia-east1` | +| Azure | `azure:{region}` | `azure:eastus`, `azure:westeurope`, `azure:southeastasia` | -For a full list of region codes, refer to [AWS regions](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html) or [GCP regions](https://cloud.google.com/compute/docs/regions-zones). +For a full list of region codes, refer to [AWS regions](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html), [GCP regions](https://cloud.google.com/compute/docs/regions-zones), or [Azure regions](https://learn.microsoft.com/en-us/azure/reliability/regions-list). ## Best practices @@ -170,4 +201,4 @@ If you are building full-stack applications on Workers, split your front-end and ![Smart Placement and Service Bindings](~/assets/images/workers/platform/smart-placement-service-bindings.png) -Enable placement on your back-end Worker to invoke it close to your back-end service, while the front-end Worker serves requests close to the user. This architecture maintains fast, reactive front-ends while improving latency when the back-end Worker is called. +Enable placement on your back-end Worker to invoke it close to your back-end service, while the front-end Worker serves requests close to the user. This architecture maintains fast, reactive front-ends while improving latency when the back-end Worker is called. \ No newline at end of file diff --git a/src/content/docs/workers/wrangler/configuration.mdx b/src/content/docs/workers/wrangler/configuration.mdx index 21c6ec928f6843..38ce6d86f2b504 100644 --- a/src/content/docs/workers/wrangler/configuration.mdx +++ b/src/content/docs/workers/wrangler/configuration.mdx @@ -218,6 +218,8 @@ The `main` key is optional for assets-only Workers. - Configures where your Worker runs to minimize latency to back-end services. Refer to [Placement](/workers/configuration/smart-placement/). - `mode` — Set to `"smart"` to automatically place your Worker near back-end services based on observed latency. - `region` — Specify a cloud region (for example, `"aws:us-east-1"` or `"gcp:europe-west1"`) to place your Worker near infrastructure in that region. + - `host` — Specify a hostname and port for a single-homed layer 4 service (for example, `"my_database_host.com:5432"`) to place your Worker near that service. + - `hostname` — Specify a hostname for a single-homed layer 7 service (for example, `"my_api_server.com"`) to place your Worker near that service. ## Non-inheritable keys @@ -1486,4 +1488,4 @@ And the `.wrangler/deploy/config.json` contains the path to the generated config { "configPath": "../../dist/wrangler.jsonc" } -``` +``` \ No newline at end of file