Skip to content

Commit 161e2ef

Browse files
markjmillerkodster28
authored and
sdnts
committed
[Workers] Add getting started guide for API and IaC (cloudflare#21008)
* [Workers] Add getting started guide for API and IaC * Tweaks * remove excess file --------- Co-authored-by: kodster28 <[email protected]>
1 parent fe93f89 commit 161e2ef

File tree

4 files changed

+160
-1
lines changed

4 files changed

+160
-1
lines changed

‎src/content/docs/cloudflare-for-platforms/workers-for-platforms/get-started/user-workers.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@ For simplicity, start with wrangler when [getting started](/cloudflare-for-platf
2626

2727
### Upload user Workers via the API
2828

29-
Since you will be deploying Workers on behalf of your users, you will likely want to use the [Workers for Platforms script upload APIs](/api/resources/workers_for_platforms/subresources/dispatch/subresources/namespaces/subresources/scripts/subresources/content/methods/update/) directly instead of Wrangler to have more control over the upload process. The Workers for Platforms script upload API is the same as the [Worker upload API](/api/resources/workers/subresources/scripts/methods/update/), but it will upload the Worker to a [dispatch namespace](/cloudflare-for-platforms/workers-for-platforms/reference/how-workers-for-platforms-works/#dispatch-namespace) instead of to your account directly.
29+
Since you will be deploying Workers on behalf of your users, you will likely want to use the [Workers for Platforms script upload APIs](/api/resources/workers_for_platforms/subresources/dispatch/subresources/namespaces/subresources/scripts/subresources/content/methods/update/) directly instead of Wrangler to have more control over the upload process. The Workers for Platforms script upload API is the same as the [Worker upload API](/api/resources/workers/subresources/scripts/methods/update/), but it will upload the Worker to a [dispatch namespace](/cloudflare-for-platforms/workers-for-platforms/reference/how-workers-for-platforms-works/#dispatch-namespace) instead of to your account directly. See an example of the REST API [here](/workers/platform/infrastructure-as-code#workers-for-platforms).
3030

3131
## Bindings
3232

‎src/content/docs/terraform/additional-configurations/link-workers.mdx‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
---
2+
pcx_content_type: navigation
3+
title: Workers
4+
external_link: /workers/platform/infrastructure-as-code/
5+
sidebar:
6+
order: 12
7+
---

‎src/content/docs/workers/configuration/multipart-upload-metadata.mdx‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,11 @@ If you're using the [Workers Script Upload API](/api/resources/workers/subresour
2323
}
2424
```
2525

26+
:::note
27+
28+
See examples of metadata being used with the Workers Script Upload API [here](/workers/platform/infrastructure-as-code#cloudflare-rest-api).
29+
:::
30+
2631
## Attributes
2732

2833
The following attributes are configurable at the top-level.

‎src/content/docs/workers/platform/infrastructure-as-code.mdx‎

Lines changed: 147 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,147 @@
1+
---
2+
title: Infrastructure as Code (IaC)
3+
pcx_content_type: concept
4+
sidebar:
5+
order: 11
6+
---
7+
8+
import { GitHubCode } from "~/components";
9+
10+
Uploading and managing a Worker is easy with [Wrangler](/workers/wrangler/configuration), but sometimes you need to do it more programmatically. You might do this with IaC ("Infrastructure as Code") tools or by calling the [Cloudflare API](/api) directly. Use cases for the API include build and deploy scripts, CI/CD pipelines, custom dev tools, or testing. We provide API SDK libraries for common languages that make interacting with the API easier, such as [cloudflare-typescript](https://github.com/cloudflare/cloudflare-typescript) or [cloudflare-python](https://github.com/cloudflare/cloudflare-python). For IaC, a common tool is HashiCorp's Terraform where you can use the [Cloudflare Provider](/terraform) to create and manage Workers resources.
11+
12+
Here are examples of deploying a Worker with common tools and languages. In particular, they highlight how to upload script content and metadata which is different with each approach. Reference the Upload Worker Module API docs [here](/api/resources/workers/subresources/scripts/methods/update).
13+
14+
All of these examples need an [account id](/fundamentals/account/find-account-and-zone-ids) and [API token](/fundamentals/api/get-started/create-token) (not Global API key) to work.
15+
16+
## Terraform
17+
18+
In this example, you need a local file named `my-hello-world-script.mjs` with script content similar to the above examples. Replace `account_id` with your own. Learn more about the Cloudflare Terraform Provider [here](/terraform), and see an example with all the Workers script resource settings [here](https://github.com/cloudflare/terraform-provider-cloudflare/blob/main/examples/resources/cloudflare_workers_script/resource.tf).
19+
20+
```tf
21+
terraform {
22+
required_providers {
23+
cloudflare = {
24+
source = "cloudflare/cloudflare"
25+
version = "~> 5"
26+
}
27+
}
28+
}
29+
30+
resource "cloudflare_workers_script" "my-hello-world-script" {
31+
account_id = "<replace_me>"
32+
script_name = "my-hello-world-script"
33+
main_module = "my-hello-world-script.mjs"
34+
content = trimspace(file("my-hello-world-script.mjs"))
35+
bindings = [{
36+
name = "MESSAGE"
37+
type = "plain_text"
38+
text = "Hello World!"
39+
}]
40+
}
41+
```
42+
43+
:::note
44+
45+
- `trimspace()` removes empty lines in the file
46+
- The Workers Script resource does not have a `metadata` property like in the other examples. All of the properties found in `metadata` are instead at the top-level of the resource class, such as `bindings` or `compatibility_date`. Please see the [cloudflare_workers_script (Resource) docs](https://registry.terraform.io/providers/cloudflare/cloudflare/latest/docs/resources/workers_script).
47+
:::
48+
49+
## Cloudflare API Libraries
50+
51+
### JavaScript/TypeScript
52+
53+
This example uses the [cloudflare-typescript](https://github.com/cloudflare/cloudflare-typescript) library which provides convenient access to the Cloudflare REST API from server-side JavaScript or TypeScript.
54+
55+
<GitHubCode
56+
repo="cloudflare/cloudflare-typescript"
57+
file="examples/workers/script-upload.ts"
58+
commit="3031b3c5a7091cebbff7b18d9780a11340ee21cd"
59+
lang="ts"
60+
useTypeScriptExample={true}
61+
/>
62+
63+
### Python
64+
65+
This example uses the [cloudflare-python](https://github.com/cloudflare/cloudflare-python) library.
66+
67+
<GitHubCode
68+
repo="cloudflare/cloudflare-python"
69+
file="examples/workers/script_upload.py"
70+
commit="756dc87dde3a42c8d4c860ff2239c920c22014ec"
71+
lang="py"
72+
/>
73+
74+
## Cloudflare REST API
75+
76+
Open a terminal or create a shell script to upload a Worker easily with curl. For this example, replace `<account_id>` and `<api_token>` with your own. What's notable about interacting with the Workers Script Upload API directly is that it uses [multipart/form-data](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Methods/POST) for uploading metadata, multiple JavaScript modules, source maps, and more. This is abstracted away in Terraform and the API libraries.
77+
78+
```bash
79+
curl https://api.cloudflare.com/client/v4/accounts/<account_id>/workers/scripts/my-hello-world-script \
80+
-X PUT \
81+
-H 'Authorization: Bearer <api_token>' \
82+
-F 'metadata={
83+
"main_module": "my-hello-world-script.mjs",
84+
"bindings": [
85+
{
86+
"type": "plain_text",
87+
"name": "MESSAGE",
88+
"text": "Hello World!"
89+
}
90+
],
91+
"compatibility_date": "2025-03-11"
92+
};type=application/json' \
93+
-F 'my-hello-world-script.mjs=@-;filename=my-hello-world-script.mjs;type=application/javascript+module' <<EOF
94+
export default {
95+
async fetch(request, env, ctx) {
96+
return new Response(env.MESSAGE, { status: 200 });
97+
}
98+
};
99+
EOF
100+
```
101+
102+
:::note
103+
104+
Change `my-hello-world-script.mjs=@-;` to `my-hello-world-script.mjs=@./my-hello-world-script.mjs;` and remove everything after and including `<<EOF` to upload a local file named `my-hello-world-script.mjs` instead.
105+
:::
106+
107+
### Workers for Platforms
108+
109+
With [Workers for Platforms](/cloudflare-for-platforms/workers-for-platforms), you can upload [User Workers](/cloudflare-for-platforms/workers-for-platforms/get-started/user-workers) in a [dispatch namespace](/cloudflare-for-platforms/workers-for-platforms/reference/how-workers-for-platforms-works/#dispatch-namespace). You can use the exact same example above for that if you simply change the url to:
110+
111+
```bash
112+
curl https://api.cloudflare.com/client/v4/accounts/<account_id>/workers/dispatch/namespaces/<dispatch_namespace>/scripts/my-hello-world-script
113+
```
114+
115+
For this to work, you will first need to configure [Workers for Platforms](/cloudflare-for-platforms/workers-for-platforms/get-started/configuration), create a dispatch namespace, and replace `<dispatch_namespace>` with your own.
116+
117+
### Python Workers
118+
119+
[Python Workers](/workers/languages/python/) (open beta) have their own special `text/x-python` content type and `python_workers` compatibility flag for uploading.
120+
121+
```bash
122+
curl https://api.cloudflare.com/client/v4/accounts/<account_id>/workers/scripts/my-hello-world-script \
123+
-X PUT \
124+
-H 'Authorization: Bearer <api_token>' \
125+
-F 'metadata={
126+
"main_module": "my-hello-world-script.py",
127+
"bindings": [
128+
{
129+
"type": "plain_text",
130+
"name": "MESSAGE",
131+
"text": "Hello World!"
132+
}
133+
],
134+
"compatibility_date": "2025-03-11",
135+
"compatibility_flags": [
136+
"python_workers"
137+
]
138+
};type=application/json' \
139+
-F 'my-hello-world-script.py=@-;filename=my-hello-world-script.py;type=text/x-python' <<EOF
140+
from workers import Response
141+
142+
def on_fetch(request, env):
143+
return Response(env.MESSAGE)
144+
EOF
145+
```
146+
147+
You can upload Python Workers in any of our language SDKs, even the non-Python ones. Just modify the above SDK examples with the `text/x-python` content type, change the script file extension from `.mjs` to `.py`, change the script content to a Python Worker format, and add the `python_workers` compatibility date.

0 commit comments

Comments
 (0)