Skip to content

Commit bc30bd9

Browse files
elithrarelithrar
committed
placement: restructure docs
1 parent b2407be commit bc30bd9

File tree

1 file changed

+89
-60
lines changed

1 file changed

+89
-60
lines changed

‎src/content/docs/workers/configuration/smart-placement.mdx‎

Lines changed: 89 additions & 60 deletions
Original file line numberDiff line numberDiff line change
@@ -1,124 +1,153 @@
11
---
22
pcx_content_type: concept
3-
title: Smart Placement
3+
title: Placement
44
head: []
5-
description: Speed up your Worker application by automatically placing your
6-
workloads in an optimal location that minimizes latency.
5+
description: Control where your Worker runs to minimize latency to back-end services.
76
sidebar:
87
badge:
98
text: Beta
109
---
1110

1211
import { WranglerConfig, DashButton } from "~/components";
1312

14-
By default, [Workers](/workers/) and [Pages Functions](/pages/functions/) are invoked in a data center closest to where the request was received. If you are running back-end logic in a Worker, it may be more performant to run that Worker closer to your back-end infrastructure rather than the end user. Smart Placement automatically places your workloads in an optimal location that minimizes latency and speeds up your applications.
13+
By default, [Workers](/workers/) and [Pages Functions](/pages/functions/) run in a data center closest to where the request was received. If your Worker makes requests to back-end infrastructure such as databases or APIs, it may be more performant to run that Worker closer to your back-end rather than the end user.
1514

16-
## Background
15+
Cloudflare provides two placement options:
1716

18-
The following example demonstrates how moving your Worker close to your back-end services could decrease application latency:
17+
| Option | Best for | Configuration |
18+
| --- | --- | --- |
19+
| **Smart Placement** | Workers that connect to multiple back-end services, or when you do not know the exact location of your infrastructure | `mode = "smart"` |
20+
| **Placement Hints** | Workers that connect to a single back-end service in a known cloud region | `region = "aws:us-east-1"` |
1921

20-
You have a user in Sydney, Australia who is accessing an application running on Workers. This application makes multiple round trips to a database located in Frankfurt, Germany in order to serve the user’s request.
22+
Both options reduce latency by minimizing round trips between your Worker and back-end services.
23+
24+
## Why placement matters
25+
26+
Consider a user in Sydney, Australia accessing an application running on Workers. This application makes multiple round trips to a database in Frankfurt, Germany.
2127

2228
![A user located in Sydney, AU connecting to a Worker in the same region which then makes multiple round trips to a database located in Frankfurt, DE. ](~/assets/images/workers/platform/workers-smart-placement-disabled.png)
2329

24-
The issue is the time that it takes the Worker to perform multiple round trips to the database. Instead of the request being processed close to the user, the Cloudflare network, with Smart Placement enabled, would process the request in a data center closest to the database.
30+
The latency from multiple round trips between Sydney and Frankfurt adds up. By placing the Worker near the database, Cloudflare reduces the total request duration.
2531

2632
![A user located in Sydney, AU connecting to a Worker in Frankfurt, DE which then makes multiple round trips to a database also located in Frankfurt, DE. ](~/assets/images/workers/platform/workers-smart-placement-enabled.png)
2733

28-
## Understand how Smart Placement works
29-
30-
Smart Placement is enabled on a per-Worker basis. Once enabled, Smart Placement analyzes the [request duration](/workers/observability/metrics-and-analytics/#request-duration) of the Worker in different Cloudflare locations around the world on a regular basis. Smart Placement decides where to run the Worker by comparing the estimated request duration in the location closest to where the request was received (the default location where the Worker would run) to a set of candidate locations around the world. For each candidate location, Smart Placement considers the performance of the Worker in that location as well as the network latency added by forwarding the request to that location. If the estimated request duration in the best candidate location is significantly faster than the location where the request was received, the request will be forwarded to that candidate location. Otherwise, the Worker will run in the default location closest to where the request was received.
34+
## Smart Placement
3135

32-
Smart Placement only considers candidate locations where the Worker has previously run, since the estimated request duration in each candidate location is based on historical data from the Worker running in that location. This means that Smart Placement cannot run the Worker in a location that it does not normally receive traffic from.
36+
Smart Placement automatically analyzes your Worker's traffic patterns and places it in an optimal location. Use Smart Placement when your Worker connects to multiple back-end services or when you do not know the exact location of your infrastructure.
3337

34-
Smart Placement only affects the execution of [fetch event handlers](/workers/runtime-apis/handlers/fetch/). Smart Placement does not affect the execution of [RPC methods](/workers/runtime-apis/rpc/) or [named entrypoints](/workers/runtime-apis/bindings/service-bindings/rpc/#named-entrypoints). Workers without a fetch event handler will be ignored by Smart Placement. For Workers with both fetch and non-fetch event handlers, Smart Placement will only affect the execution of the fetch event handler.
38+
### How Smart Placement works
3539

36-
Similarly, Smart Placement will not affect where [static assets](/workers/static-assets/) are served from. Static assets will continue to be served from the location nearest to the incoming request. If a Worker is invoked and your code retrieves assets via the [static assets binding](https://developers.cloudflare.com/workers/static-assets/binding/), then assets will be served from the location that your Worker runs in.
40+
Smart Placement is enabled on a per-Worker basis. Once enabled, Smart Placement analyzes the [request duration](/workers/observability/metrics-and-analytics/#request-duration) of the Worker in different Cloudflare locations on a regular basis. Smart Placement compares the estimated request duration in the location closest to where the request was received to a set of candidate locations around the world. For each candidate location, Smart Placement considers the performance of the Worker in that location and the network latency added by forwarding the request.
3741

38-
## Enable Smart Placement
42+
If the estimated request duration in the best candidate location is significantly faster, the request is forwarded to that location. Otherwise, the Worker runs in the default location closest to where the request was received.
3943

40-
Smart Placement is available to users on all Workers plans.
44+
Smart Placement only considers candidate locations where the Worker has previously run. This means that Smart Placement cannot run the Worker in a location that it does not normally receive traffic from.
4145

42-
### Enable Smart Placement via Wrangler
46+
### Limitations
4347

44-
To enable Smart Placement via Wrangler:
48+
- Smart Placement only affects the execution of [fetch event handlers](/workers/runtime-apis/handlers/fetch/). It does not affect [RPC methods](/workers/runtime-apis/rpc/) or [named entrypoints](/workers/runtime-apis/bindings/service-bindings/rpc/#named-entrypoints).
49+
- Workers without a fetch event handler are ignored by Smart Placement.
50+
- [Static assets](/workers/static-assets/) are always served from the location nearest to the incoming request. If your code retrieves assets via the [static assets binding](/workers/static-assets/binding/), assets are served from the location where your Worker runs.
4551

46-
1. Make sure that you have `[email protected]` or later [installed](/workers/wrangler/install-and-update/).
52+
### Enable Smart Placement
4753

48-
2. Add the following to your Worker project's Wrangler file:
54+
Smart Placement is available on all Workers plans.
4955

50-
<WranglerConfig>
56+
#### Enable via Wrangler
5157

52-
```toml
53-
[placement]
54-
mode = "smart"
55-
```
58+
Add the following to your Wrangler configuration file:
5659

57-
</WranglerConfig>
60+
<WranglerConfig>
5861

59-
3. Wait for Smart Placement to analyze your Worker. This process may take up to 15 minutes.
62+
```toml
63+
[placement]
64+
mode = "smart"
65+
```
6066

61-
4. View your Worker's [request duration analytics](/workers/observability/metrics-and-analytics/#request-duration).
67+
</WranglerConfig>
6268

63-
### Enable Smart Placement via the dashboard
69+
Smart Placement may take up to 15 minutes to analyze your Worker after deployment.
6470

65-
To enable Smart Placement via the dashboard:
71+
#### Enable via the dashboard
6672

67-
1. In the Cloudflare dashboard, go to the **Workers & Pages** page.
73+
1. Go to **Workers & Pages**.
6874

6975
<DashButton url="/?to=/:account/workers-and-pages" />
7076

71-
2. In **Overview**,select your Worker.
72-
3. Select **Settings** > **General**.
73-
4. Under **Placement**, choose **Smart**.
74-
5. Wait for Smart Placement to analyze your Worker. Smart Placement requires consistent traffic to the Worker from multiple locations around the world to make a placement decision. The analysis process may take up to 15 minutes.
75-
6. View your Worker's [request duration analytics](/workers/observability/metrics-and-analytics/#request-duration)
77+
2. Select your Worker.
78+
3. Go to **Settings** > **General**.
79+
4. Under **Placement**, select **Smart**.
7680

77-
## Observability
81+
Smart Placement requires consistent traffic to the Worker from multiple locations to make a placement decision. The analysis process may take up to 15 minutes.
7882

79-
### Placement Status
83+
### Placement status
8084

81-
A Worker's metadata contains details about a Worker's placement status. Query your Worker's placement status through the following Workers API endpoint:
85+
Query your Worker's placement status through the Workers API:
8286

8387
```bash
84-
curl -X GET https://api.cloudflare.com/client/v4/accounts/{ACCOUNT_ID}/workers/services/{WORKER_NAME} \
85-
-H "Authorization: Bearer <TOKEN>" \
88+
curl -X GET https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/workers/services/$WORKER_NAME \
89+
-H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
8690
-H "Content-Type: application/json" | jq .
8791
```
8892

89-
Possible placement states include:
93+
Possible placement states:
9094

91-
- _(not present)_: The Worker has not been analyzed for Smart Placement yet. The Worker will always run in the default Cloudflare location closest to where the request was received.
92-
- `SUCCESS`: The Worker was successfully analyzed and will be optimized by Smart Placement. The Worker will run in the Cloudflare location that minimizes expected request duration, which may be the default location closest to where the request was received or may be a faster location elsewhere in the world.
93-
- `INSUFFICIENT_INVOCATIONS`: The Worker has not received enough requests to make a placement decision. Smart Placement requires consistent traffic to the Worker from multiple locations around the world. The Worker will always run in the default Cloudflare location closest to where the request was received.
94-
- `UNSUPPORTED_APPLICATION`: Smart Placement began optimizing the Worker and measured the results, which showed that Smart Placement made the Worker slower. In response, Smart Placement reverted the placement decision. The Worker will always run in the default Cloudflare location closest to where the request was received, and Smart Placement will not analyze the Worker again until it's redeployed. This state is rare and accounts for less that 1% of Workers with Smart Placement enabled.
95+
| Status | Description |
96+
| --- | --- |
97+
| _(not present)_ | The Worker has not been analyzed yet. It runs in the default location closest to the request. |
98+
| `SUCCESS` | The Worker was analyzed and will be optimized by Smart Placement. |
99+
| `INSUFFICIENT_INVOCATIONS` | The Worker has not received enough requests from multiple locations to make a placement decision. |
100+
| `UNSUPPORTED_APPLICATION` | Smart Placement made the Worker slower and reverted the placement. This state is rare (less than 1% of Workers). |
95101

96-
### Request Duration Analytics
102+
### Request duration analytics
97103

98-
Once Smart Placement is enabled, data about request duration gets collected. Request duration is measured at the data center closest to the end user.
104+
Once Smart Placement is enabled, data about request duration is collected. Request duration is measured at the data center closest to the end user. By default, 1% of requests are not routed with Smart Placement to serve as a baseline for comparison.
99105

100-
By default, one percent (1%) of requests are not routed with Smart Placement. These requests serve as a baseline to compare to.
106+
View your Worker's [request duration analytics](/workers/observability/metrics-and-analytics/#request-duration) to measure the impact of Smart Placement.
101107

102108
### `cf-placement` header
103109

104-
Once Smart Placement is enabled, Cloudflare adds a `cf-placement` header to all requests. This can be used to check whether a request has been routed with Smart Placement and where the Worker is processing the request (which is shown as the nearest airport code to the data center).
105-
106-
For example, the `cf-placement: remote-LHR` header's `remote` value indicates that the request was routed using Smart Placement to a Cloudflare data center near London. The `cf-placement: local-EWR` header's `local` value indicates that the request was not routed using Smart Placement and the Worker was invoked in a data center closest to where the request was received, close to Newark Liberty International Airport (EWR).
110+
Cloudflare adds a `cf-placement` header to all requests when placement is enabled. Use this header to check whether a request was routed with Smart Placement and where the Worker processed the request.
107111

108-
:::caution[Beta use only]
112+
The header value includes a placement type and an airport code indicating the data center location:
109113

110-
We may remove the `cf-placement` header before Smart Placement enters general availability.
114+
- `remote-LHR` — The request was routed using Smart Placement to a data center near London.
115+
- `local-EWR` — The request was not routed using Smart Placement. The Worker ran in the default location near Newark.
111116

117+
:::caution
118+
The `cf-placement` header may be removed before Smart Placement exits beta.
112119
:::
113120

114-
## Best practices
121+
## Placement Hints
115122

116-
If you are building full-stack applications on Workers, we recommend splitting up the front-end and back-end logic into different Workers and using [Service Bindings](/workers/runtime-apis/bindings/service-bindings/) to connect your front-end logic and back-end logic Workers.
123+
Placement Hints let you explicitly specify a cloud region where your Worker should run. Use Placement Hints when your Worker connects to a single back-end service in a known cloud region.
117124

118-
![Smart Placement and Service Bindings](~/assets/images/workers/platform/smart-placement-service-bindings.png)
125+
### Configure Placement Hints
126+
127+
Set the `placement.region` property in your Wrangler configuration file:
119128

120-
Enabling Smart Placement on your back-end Worker will 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 also improving latency when the back-end Worker is called.
129+
<WranglerConfig>
130+
131+
```toml
132+
[placement]
133+
region = "aws:us-east-1"
134+
```
121135

122-
## Give feedback on Smart Placement
136+
</WranglerConfig>
137+
138+
Placement Hints support AWS and GCP region identifiers. Your Worker runs in the [Cloudflare data center](https://www.cloudflare.com/network/) with the lowest latency to the specified cloud region.
139+
140+
### Supported regions
141+
142+
Specify regions using the cloud provider prefix followed by the region identifier:
143+
144+
- **AWS**: `aws:us-east-1`, `aws:eu-west-1`, `aws:ap-southeast-1`, and other [AWS region codes](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html)
145+
- **GCP**: `gcp:us-central1`, `gcp:europe-west1`, `gcp:asia-east1`, and other [GCP region codes](https://cloud.google.com/compute/docs/regions-zones)
146+
147+
## Best practices
148+
149+
If you are building full-stack applications on Workers, split your front-end and back-end logic into separate Workers. Use [Service Bindings](/workers/runtime-apis/bindings/service-bindings/) to connect them.
150+
151+
![Smart Placement and Service Bindings](~/assets/images/workers/platform/smart-placement-service-bindings.png)
123152

124-
Smart Placement is in beta. To share your thoughts and experience with Smart Placement, join the [Cloudflare Developer Discord](https://discord.cloudflare.com).
153+
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.

0 commit comments

Comments
 (0)