diff --git a/src/content/docs/cloudflare-for-platforms/workers-for-platforms/get-started/user-workers.mdx b/src/content/docs/cloudflare-for-platforms/workers-for-platforms/get-started/user-workers.mdx index 90e4541bf48514a..9390ba320a46ab7 100644 --- a/src/content/docs/cloudflare-for-platforms/workers-for-platforms/get-started/user-workers.mdx +++ b/src/content/docs/cloudflare-for-platforms/workers-for-platforms/get-started/user-workers.mdx @@ -26,7 +26,7 @@ For simplicity, start with wrangler when [getting started](/cloudflare-for-platf ### Upload user Workers via the API -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. +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). ## Bindings diff --git a/src/content/docs/terraform/additional-configurations/link-workers.mdx b/src/content/docs/terraform/additional-configurations/link-workers.mdx new file mode 100644 index 000000000000000..dfc46f47322e9c7 --- /dev/null +++ b/src/content/docs/terraform/additional-configurations/link-workers.mdx @@ -0,0 +1,7 @@ +--- +pcx_content_type: navigation +title: Workers +external_link: /workers/platform/infrastructure-as-code/ +sidebar: + order: 12 +--- diff --git a/src/content/docs/workers/configuration/multipart-upload-metadata.mdx b/src/content/docs/workers/configuration/multipart-upload-metadata.mdx index b95292f489e9236..ebc1828217ccf0e 100644 --- a/src/content/docs/workers/configuration/multipart-upload-metadata.mdx +++ b/src/content/docs/workers/configuration/multipart-upload-metadata.mdx @@ -23,6 +23,11 @@ If you're using the [Workers Script Upload API](/api/resources/workers/subresour } ``` +:::note + +See examples of metadata being used with the Workers Script Upload API [here](/workers/platform/infrastructure-as-code#cloudflare-rest-api). +::: + ## Attributes The following attributes are configurable at the top-level. diff --git a/src/content/docs/workers/platform/infrastructure-as-code.mdx b/src/content/docs/workers/platform/infrastructure-as-code.mdx new file mode 100644 index 000000000000000..0fa4f0855eb289e --- /dev/null +++ b/src/content/docs/workers/platform/infrastructure-as-code.mdx @@ -0,0 +1,147 @@ +--- +title: Infrastructure as Code (IaC) +pcx_content_type: concept +sidebar: + order: 11 +--- + +import { GitHubCode } from "~/components"; + +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. + +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). + +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. + +## Terraform + +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). + +```tf +terraform { + required_providers { + cloudflare = { + source = "cloudflare/cloudflare" + version = "~> 5" + } + } +} + +resource "cloudflare_workers_script" "my-hello-world-script" { + account_id = "" + script_name = "my-hello-world-script" + main_module = "my-hello-world-script.mjs" + content = trimspace(file("my-hello-world-script.mjs")) + bindings = [{ + name = "MESSAGE" + type = "plain_text" + text = "Hello World!" + }] +} +``` + +:::note + +- `trimspace()` removes empty lines in the file +- 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). + ::: + +## Cloudflare API Libraries + +### JavaScript/TypeScript + +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. + + + +### Python + +This example uses the [cloudflare-python](https://github.com/cloudflare/cloudflare-python) library. + + + +## Cloudflare REST API + +Open a terminal or create a shell script to upload a Worker easily with curl. For this example, replace `` and `` 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. + +```bash +curl https://api.cloudflare.com/client/v4/accounts//workers/scripts/my-hello-world-script \ + -X PUT \ + -H 'Authorization: Bearer ' \ + -F 'metadata={ + "main_module": "my-hello-world-script.mjs", + "bindings": [ + { + "type": "plain_text", + "name": "MESSAGE", + "text": "Hello World!" + } + ], + "compatibility_date": "2025-03-11" + };type=application/json' \ + -F 'my-hello-world-script.mjs=@-;filename=my-hello-world-script.mjs;type=application/javascript+module' </workers/dispatch/namespaces//scripts/my-hello-world-script +``` + +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 `` with your own. + +### Python Workers + +[Python Workers](/workers/languages/python/) (open beta) have their own special `text/x-python` content type and `python_workers` compatibility flag for uploading. + +```bash +curl https://api.cloudflare.com/client/v4/accounts//workers/scripts/my-hello-world-script \ + -X PUT \ + -H 'Authorization: Bearer ' \ + -F 'metadata={ + "main_module": "my-hello-world-script.py", + "bindings": [ + { + "type": "plain_text", + "name": "MESSAGE", + "text": "Hello World!" + } + ], + "compatibility_date": "2025-03-11", + "compatibility_flags": [ + "python_workers" + ] + };type=application/json' \ + -F 'my-hello-world-script.py=@-;filename=my-hello-world-script.py;type=text/x-python' <