From d689061b40022686c9d5171f2efb83cd8a0bb0b1 Mon Sep 17 00:00:00 2001 From: Victoria Date: Mon, 6 May 2019 14:45:28 -0500 Subject: [PATCH 01/11] Imported old serverless docs --- reference/tooling/serverless.md | 94 +++++++++++++++++++++++++++++++++ 1 file changed, 94 insertions(+) create mode 100644 reference/tooling/serverless.md diff --git a/reference/tooling/serverless.md b/reference/tooling/serverless.md new file mode 100644 index 000000000..818de4327 --- /dev/null +++ b/reference/tooling/serverless.md @@ -0,0 +1,94 @@ +--- +title: Serverless Framework +weight: 50 +--- + +The [Serverless Framework](https://github.com/serverless/serverless) helps you develop and deploy serverless applications using [Cloudflare Workers](https://www.cloudflare.com/products/cloudflare-workers/). It's a CLI that offers structure, automation, and best practices out-of-the-box, allowing you to focus on building sophisticated, event-driven, serverless architectures, comprised of Functions and Events. + +The Serverless Framework manages your code as well as your infrastructure. It lets you manage your Worker routing in a flat configuration file that you can keep alongside the rest of your code in version control. And it intelligently manages your routes as you edit them and re-deploy your application. + +### Additional Documentation + +[Learn more](https://serverless.com/framework/docs/providers/cloudflare/) about using Cloudflare Workers with Serverless. + +### Core Concepts + +#### Functions +A Function is a Cloudflare Worker. It's an independent unit of deployment, like a microservice. It's merely code, deployed on Cloudflare’s 152+ PoPs (points of presence), that is most often written to perform a single job, such as: + +- Performing A/B Testing +- Custom routing based on user location, custom headers, etc. +- Hosting webhook endpoints +- Rendering a page + +#### Events +Anything that triggers a Cloudflare Worker to execute is regarded by the Framework as an **Event**. Since the only event that can trigger a Worker is an HTTP request, declaring events is optional, and only used to declare specific endpoints that can be called by [`serverless invoke`](https://serverless.com/framework/docs/providers/cloudflare/cli-reference/invoke/). This is useful for defining specific hooks into your application for testing. + +#### Services +A **Service** is the Serverless Framework's unit of organization. You can think of it as a project file, though you can have multiple services for a single application. It's where you define your Functions and the routes they will live on, all in one file entitled `serverless.yml`. Non-Enterprise Cloudflare accounts can only deploy one Function (that can be deployed to multiple routes), while Enterprise Cloudflare accounts can deploy multiple Functions at once: + +```yml +# serverless.yml + +service: + name: hello-world + config: + accountId: CLOUDFLARE_ACCOUNT_ID + zoneId: CLOUDFLARE_ZONE_ID + +provider: + name: cloudflare + +plugins: + - serverless-cloudflare-workers + +functions: + helloWorld: + # What the script will be called on Cloudflare + worker: hello + # The name of the script on your machine, omitting the .js file extension + script: helloWorld + # Events are only relevant to the `serverless invoke` command and don’t affect deployment in any way + events: + - http: + url: example.com/hello/user + method: GET + headers: + someKey: someValue + + + # Only Enterprise accounts would be allowed to add this second function and its corresponding route above + foo: + worker: foo_script + script: bar + events: + - http: + url: example.com/foo/bar + method: GET +``` + +You get your `accountId` by grabbing it from the URL when using the [Cloudflare dashboard](https://dash.cloudflare.com), and your `zoneId` from the `overview` tab after selecting the desired zone from the [Cloudflare dashboard](https://dash.cloudflare.com). + +You will also need to set your Global API key from Cloudflare as an environmental variable named `CLOUDFLARE_AUTH_KEY`, and your Cloudflare account email as an environmental variable named `CLOUDFLARE_AUTH_EMAIL`. You can get your Global API key from your [Cloudflare profile](https://dash.cloudflare.com/profile) page. + +Environmental variables are variables that live inside your terminal. + +For Mac and Linux users, you can set environmental variables like this: + +```bash +export CLOUDFLARE_AUTH_KEY=YOUR_API_KEY_HERE +export CLOUDFLARE_AUTH_EMAIL=YOUR_CLOUDFLARE_EMAIL +``` + +And for Windows (CMD) users, you can set environmental variables like this: + +```bash +set CLOUDFLARE_AUTH_KEY=YOUR_API_KEY_HERE +set CLOUDFLARE_AUTH_EMAIL=YOUR_CLOUDFLARE_EMAIL +``` + +You’ll need to redefine your environmental variables each time you open a new terminal. + +If you’re not an enterprise customer and you want to execute different code on multiple routes with only one function, we recommend writing code based on our [conditional routing](https://developers.cloudflare.com/workers/recipes/conditional-routing/) template to check your route and execute different code accordingly. You can also write Workers in separate files and compile it into one Worker with [webpack](https://developers.cloudflare.com/workers/writing-workers/using-npm-modules/). + +When you deploy with the Framework by running `serverless deploy`, everything in `serverless.yml` is deployed at once. \ No newline at end of file From 2e47ac740d0c49365323952b15afdeb987cdd645 Mon Sep 17 00:00:00 2001 From: Victoria Date: Mon, 6 May 2019 17:15:33 -0500 Subject: [PATCH 02/11] changes to existing serverless docs lots of TODOs stil --- reference/tooling/index.md | 1 + reference/tooling/serverless.md | 164 ++++++++++++++++++++++++-------- 2 files changed, 123 insertions(+), 42 deletions(-) diff --git a/reference/tooling/index.md b/reference/tooling/index.md index 2ab796ee1..a9fe86a74 100644 --- a/reference/tooling/index.md +++ b/reference/tooling/index.md @@ -2,3 +2,4 @@ ## Official CLI Reference ## Ecosystem Tooling + diff --git a/reference/tooling/serverless.md b/reference/tooling/serverless.md index 818de4327..dbf817718 100644 --- a/reference/tooling/serverless.md +++ b/reference/tooling/serverless.md @@ -1,11 +1,23 @@ ---- -title: Serverless Framework -weight: 50 ---- +TODO: question for Jonathan: + +- why are there three levels of naming? e.g. scriptname = `func-foo-bar` ? +- are all urls -> routes not have wildcards? +- is event.http a Request object/ +- who owns the docs on serverless? + +TODO: missing concepts: + +- environment variables in the serverless.yml +- bindings +- webpack +- CLI ref documentation +- rearrange service and additional documentation + + The [Serverless Framework](https://github.com/serverless/serverless) helps you develop and deploy serverless applications using [Cloudflare Workers](https://www.cloudflare.com/products/cloudflare-workers/). It's a CLI that offers structure, automation, and best practices out-of-the-box, allowing you to focus on building sophisticated, event-driven, serverless architectures, comprised of Functions and Events. -The Serverless Framework manages your code as well as your infrastructure. It lets you manage your Worker routing in a flat configuration file that you can keep alongside the rest of your code in version control. And it intelligently manages your routes as you edit them and re-deploy your application. +The Serverless Framework manages the infrastructure that turns your version controlled code into a Worker(s) deployed globally with one command. One config file directs where exactly this Worker will live, so you can modify code and have it re-built and re-deployed in moments. No visits to the browser required. ### Additional Documentation @@ -13,25 +25,107 @@ The Serverless Framework manages your code as well as your infrastructure. It l ### Core Concepts +The `serverless.yml` file is what molds the Worker(s) of your project + #### Functions -A Function is a Cloudflare Worker. It's an independent unit of deployment, like a microservice. It's merely code, deployed on Cloudflare’s 152+ PoPs (points of presence), that is most often written to perform a single job, such as: +A Function is a Cloudflare Worker - a single script including its bindings, routes and other config. It's an independent unit of deployment, like a microservice. It's merely code, deployed on Cloudflare’s 155+ PoPs (points of presence)[TODO: can we reference this PoPsnumber somewhere instead of hard coding it? ], that is most often written to perform a single job as a Worker. + + `serverless.yml`: + +``` +... +functions: + functionName: + worker: scriptName + script: filename + webpack: true + environment: + CLOUDFLARE_AUTH_KEY: + CLOUDFLARE_AUTH_EMAIL: + resources: ... + events: ... +``` + +`worker`: the name of which the script will be as in this case`scriptName` + +`script`: the path to the script from the current directory + +`webpack`(*optional*): specifies what webpack operation to perform on this individual Worker script. See webpack + +`environment`(*optional*) : any environment variables set before deploy this will be passed as a binding as a secret [TODO: link to kv secrets ]to the scripts deployed. If `CLOUDFLARE_AUTH_KEY` and `CLOUDFLARE_AUTH_EMAIL` are omitted make sure to set them in your environment variables. **Please don't commit a file with your API key**. See more in Auth[TODO: link] + +`resources`(*optional*) : see Resources below -- Performing A/B Testing -- Custom routing based on user location, custom headers, etc. -- Hosting webhook endpoints -- Rendering a page +`events`(*optional*) : Any routing for a Worker is configured here. See Events below -#### Events -Anything that triggers a Cloudflare Worker to execute is regarded by the Framework as an **Event**. Since the only event that can trigger a Worker is an HTTP request, declaring events is optional, and only used to declare specific endpoints that can be called by [`serverless invoke`](https://serverless.com/framework/docs/providers/cloudflare/cli-reference/invoke/). This is useful for defining specific hooks into your application for testing. +#####Webpack + +The webpack option under functions allows you to easily use multiple scripts or libraries and not worry about a complicated build pipeline. + +It can accept a boolean or a string. Possible behaviors: + +`boolean`: will automatically bundle the function if set to "true" + +`string`: web pack config path for this function[TODO: clean] add a function level webpack configuration in addition to a global webpack configuration. This helps you to process bundling different for an individual function than the global webpack config explained earlier. To use this, set the webpack config path to the function level `webpack` variable. Setting function level `webpack` variable to `true` will force webpack to bundle the function script with a default web pack configuration. Setting `webpack` key to `false` will turn off webpack for the function. (i.e the function script will not be fetched from dist folder) + +Simply add `webpack: true | ` to your config block. + +For example in your script you can now use `import`: + +``` +addEventListener('fetch', event => { + event.respondWith(handleRequest(event.request)) +}); + +import hello from './includeMe'; + +async function handleRequest(request) { + return new Response(hello.hello()) +} +``` + +If your handler script looks like the above, the includeMe script will be packed into the final script on deployment. + +[View the Cloudflare Workers events section for more information on HTTP events](https://serverless.com/framework/docs/providers/cloudflare/events). + +#####Resources + +``` +resources: + wasm: + kv: +``` + +[TODO] + +#####Events + +Anything that triggers a Cloudflare Worker to execute is regarded by the Framework as an **Event**. + +``` + events: + - http: + url: example.com/hello/user + method: GET + headers: + someKey: someValue +``` + +Each event implements two behaviors: + + `serverless invoke ` will deploy your worker and run the HTTP request(s) specified by the event(s) against this deployed worker. This is useful for defining specific hooks into your application for testing. + + `serverless deploy` will parse out all the `url`(s) from the events in a function and deploy routes all pointing to that specific script. The routes will not contain wildcards, but be the [TODO verify this] You cannot have multiple routes that are identical + +TODO: link to CLI section #### Services -A **Service** is the Serverless Framework's unit of organization. You can think of it as a project file, though you can have multiple services for a single application. It's where you define your Functions and the routes they will live on, all in one file entitled `serverless.yml`. Non-Enterprise Cloudflare accounts can only deploy one Function (that can be deployed to multiple routes), while Enterprise Cloudflare accounts can deploy multiple Functions at once: +A **Service** is the Serverless Framework's unit of organization. You can think of it as a project file, though you can have multiple services for a single application. It's where you define your Functions and the routes they will live on, all in one file entitled `serverless.yml`: ```yml # serverless.yml - service: - name: hello-world + name: hello config: accountId: CLOUDFLARE_ACCOUNT_ID zoneId: CLOUDFLARE_ZONE_ID @@ -42,34 +136,22 @@ provider: plugins: - serverless-cloudflare-workers -functions: - helloWorld: - # What the script will be called on Cloudflare - worker: hello - # The name of the script on your machine, omitting the .js file extension - script: helloWorld - # Events are only relevant to the `serverless invoke` command and don’t affect deployment in any way - events: - - http: - url: example.com/hello/user - method: GET - headers: - someKey: someValue +functions: .. +``` +`name`: the project name which will prefix the function and script names that will show on Cloudflare as script name (e.g script with the name `hello` will look like a script with the name `hello-blah-foo` on Cloudflare) - # Only Enterprise accounts would be allowed to add this second function and its corresponding route above - foo: - worker: foo_script - script: bar - events: - - http: - url: example.com/foo/bar - method: GET -``` +`config`: + +* `accountId`: the account that *owns* the zone that you wish to deploy Workers too. Note: this may not be the account ID you are signed in as, but will be the account ID you see in the URL once you've selected the zone -You get your `accountId` by grabbing it from the URL when using the [Cloudflare dashboard](https://dash.cloudflare.com), and your `zoneId` from the `overview` tab after selecting the desired zone from the [Cloudflare dashboard](https://dash.cloudflare.com). +* `zoneId`: the zone desired to deploy Workers to -You will also need to set your Global API key from Cloudflare as an environmental variable named `CLOUDFLARE_AUTH_KEY`, and your Cloudflare account email as an environmental variable named `CLOUDFLARE_AUTH_EMAIL`. You can get your Global API key from your [Cloudflare profile](https://dash.cloudflare.com/profile) page. + To find your zoneId and accountId, please see [API documentation on resource IDs](https://api.cloudflare.com/#getting-started-resource-ids) + +#####Auth + +You will also need to set your Global API key from Cloudflare as an environmental variable named `CLOUDFLARE_AUTH_KEY`, and your Cloudflare account email as an environmental variable named `CLOUDFLARE_AUTH_EMAIL`. You can get your Global API key from your [Cloudflare profile](https://dash.cloudflare.com/profile) page. Unlike `accountId` this will always be the API key that *you* are signed in on, not necassarily the account the owns the zone. For more information see [Where do I find my API key?]( Date: Mon, 6 May 2019 17:51:13 -0500 Subject: [PATCH 03/11] reorganize serverless tooling --- reference/tooling/serverless/cli.md | 0 .../{serverless.md => serverless/config.md} | 147 +++++++----------- reference/tooling/serverless/index.md | 30 ++++ reference/tooling/serverless/quick-start.md | 25 +++ 4 files changed, 114 insertions(+), 88 deletions(-) create mode 100644 reference/tooling/serverless/cli.md rename reference/tooling/{serverless.md => serverless/config.md} (59%) create mode 100644 reference/tooling/serverless/index.md create mode 100644 reference/tooling/serverless/quick-start.md diff --git a/reference/tooling/serverless/cli.md b/reference/tooling/serverless/cli.md new file mode 100644 index 000000000..e69de29bb diff --git a/reference/tooling/serverless.md b/reference/tooling/serverless/config.md similarity index 59% rename from reference/tooling/serverless.md rename to reference/tooling/serverless/config.md index dbf817718..db71145d6 100644 --- a/reference/tooling/serverless.md +++ b/reference/tooling/serverless/config.md @@ -1,49 +1,72 @@ -TODO: question for Jonathan: +### Core Concepts -- why are there three levels of naming? e.g. scriptname = `func-foo-bar` ? -- are all urls -> routes not have wildcards? -- is event.http a Request object/ -- who owns the docs on serverless? +The `serverless.yml` file is what molds the Worker(s) of your project. Using the [Server Cloudflare Workers plugin](TODO link), a `serverless.yml` will look like: -TODO: missing concepts: +``` +# serverless.yml +service: + name: hello + config: + accountId: CLOUDFLARE_ACCOUNT_ID + zoneId: CLOUDFLARE_ZONE_ID -- environment variables in the serverless.yml -- bindings -- webpack -- CLI ref documentation -- rearrange service and additional documentation +provider: + name: cloudflare +plugins: + - serverless-cloudflare-workers +functions: .. +``` -The [Serverless Framework](https://github.com/serverless/serverless) helps you develop and deploy serverless applications using [Cloudflare Workers](https://www.cloudflare.com/products/cloudflare-workers/). It's a CLI that offers structure, automation, and best practices out-of-the-box, allowing you to focus on building sophisticated, event-driven, serverless architectures, comprised of Functions and Events. +#### Services -The Serverless Framework manages the infrastructure that turns your version controlled code into a Worker(s) deployed globally with one command. One config file directs where exactly this Worker will live, so you can modify code and have it re-built and re-deployed in moments. No visits to the browser required. +A **Service** is the Serverless Framework's unit of organization. You can think of it as a project file, though you can have multiple services for a single application. It's where you define your Functions and the routes they will live on, all in one file entitled `serverless.yml`: -### Additional Documentation +```yml +# serverless.yml +service: + name: hello + config: + accountId: CLOUDFLARE_ACCOUNT_ID + zoneId: CLOUDFLARE_ZONE_ID -[Learn more](https://serverless.com/framework/docs/providers/cloudflare/) about using Cloudflare Workers with Serverless. +provider: + name: cloudflare -### Core Concepts +plugins: + - serverless-cloudflare-workers -The `serverless.yml` file is what molds the Worker(s) of your project +functions: .. +``` + +`name`: the project name which will prefix the function and script names that will show on Cloudflare as script name (e.g script with the name `hello` will look like a script with the name `hello-blah-foo` on Cloudflare) + +`config`: + +- `accountId`: the account that *owns* the zone that you wish to deploy Workers too. Note: this may not be the account ID you are signed in as, but will be the account ID you see in the URL once you've selected the zone + +- `zoneId`: the zone desired to deploy Workers to + + To find your zoneId and accountId, please see [API documentation on resource IDs](https://api.cloudflare.com/#getting-started-resource-ids) #### Functions -A Function is a Cloudflare Worker - a single script including its bindings, routes and other config. It's an independent unit of deployment, like a microservice. It's merely code, deployed on Cloudflare’s 155+ PoPs (points of presence)[TODO: can we reference this PoPsnumber somewhere instead of hard coding it? ], that is most often written to perform a single job as a Worker. + +A Function is a Cloudflare Worker - a single script including its bindings, routes and other config. It's an independent unit of deployment, like a microservice. It's merely code, deployed on Cloudflare’s 155+ PoPs [points of presence](TODO: can we reference this PoPsnumber somewhere instead of hard coding it? ), that is most often written to perform a single job as a Worker. `serverless.yml`: ``` -... -functions: - functionName: - worker: scriptName - script: filename - webpack: true - environment: - CLOUDFLARE_AUTH_KEY: - CLOUDFLARE_AUTH_EMAIL: - resources: ... - events: ... + functions: + functionName: + worker: scriptName + script: filename + webpack: true + environment: + CLOUDFLARE_AUTH_KEY: + CLOUDFLARE_AUTH_EMAIL: + resources: ... + events: ... ``` `worker`: the name of which the script will be as in this case`scriptName` @@ -58,7 +81,7 @@ functions: `events`(*optional*) : Any routing for a Worker is configured here. See Events below -#####Webpack +##### Webpack The webpack option under functions allows you to easily use multiple scripts or libraries and not worry about a complicated build pipeline. @@ -88,17 +111,17 @@ If your handler script looks like the above, the includeMe script will be packed [View the Cloudflare Workers events section for more information on HTTP events](https://serverless.com/framework/docs/providers/cloudflare/events). -#####Resources +##### Resources ``` -resources: - wasm: - kv: + resources: + wasm: + kv: ``` [TODO] -#####Events +##### Events Anything that triggers a Cloudflare Worker to execute is regarded by the Framework as an **Event**. @@ -119,56 +142,4 @@ Each event implements two behaviors: TODO: link to CLI section -#### Services -A **Service** is the Serverless Framework's unit of organization. You can think of it as a project file, though you can have multiple services for a single application. It's where you define your Functions and the routes they will live on, all in one file entitled `serverless.yml`: - -```yml -# serverless.yml -service: - name: hello - config: - accountId: CLOUDFLARE_ACCOUNT_ID - zoneId: CLOUDFLARE_ZONE_ID - -provider: - name: cloudflare - -plugins: - - serverless-cloudflare-workers - -functions: .. -``` - -`name`: the project name which will prefix the function and script names that will show on Cloudflare as script name (e.g script with the name `hello` will look like a script with the name `hello-blah-foo` on Cloudflare) - -`config`: - -* `accountId`: the account that *owns* the zone that you wish to deploy Workers too. Note: this may not be the account ID you are signed in as, but will be the account ID you see in the URL once you've selected the zone - -* `zoneId`: the zone desired to deploy Workers to - - To find your zoneId and accountId, please see [API documentation on resource IDs](https://api.cloudflare.com/#getting-started-resource-ids) - -#####Auth - -You will also need to set your Global API key from Cloudflare as an environmental variable named `CLOUDFLARE_AUTH_KEY`, and your Cloudflare account email as an environmental variable named `CLOUDFLARE_AUTH_EMAIL`. You can get your Global API key from your [Cloudflare profile](https://dash.cloudflare.com/profile) page. Unlike `accountId` this will always be the API key that *you* are signed in on, not necassarily the account the owns the zone. For more information see [Where do I find my API key?]( routes not have wildcards? +- is event.http a Request object/ +- who owns the docs on serverless? + +TODO: missing concepts: + +- environment variables in the serverless.yml +- bindings +- webpack +- CLI ref documentation +- rearrange service and additional documentation + +# Serverless Plugin + +The [Serverless Framework](https://github.com/serverless/serverless) helps you develop and deploy serverless applications using [Cloudflare Workers](https://www.cloudflare.com/products/cloudflare-workers/). It's a CLI that offers structure, automation, and best practices out-of-the-box, allowing you to focus on building sophisticated, event-driven, serverless architectures, comprised of Functions and Events. + +The Serverless Framework manages the infrastructure that turns your version controlled code into a Worker(s) deployed globally with one command. One config file directs where exactly this Worker will live, so you can modify code and have it re-built and re-deployed in moments. No visits to the browser required. + +TODO: link to quick start and ref + +### Additional Documentation + +[The Documentation on Serverless](https://serverless.com/framework/docs/providers/cloudflare/) + +[Plugin on Github]() \ No newline at end of file diff --git a/reference/tooling/serverless/quick-start.md b/reference/tooling/serverless/quick-start.md new file mode 100644 index 000000000..d535995b8 --- /dev/null +++ b/reference/tooling/serverless/quick-start.md @@ -0,0 +1,25 @@ +# Quick Start + +##### Auth + +You will also need to set your Global API key from Cloudflare as an environmental variable named `CLOUDFLARE_AUTH_KEY`, and your Cloudflare account email as an environmental variable named `CLOUDFLARE_AUTH_EMAIL`. You can get your Global API key from your [Cloudflare profile](https://dash.cloudflare.com/profile) page. Unlike `accountId` this will always be the API key that *you* are signed in on, not necassarily the account the owns the zone. For more information see [Where do I find my API key?]( Date: Mon, 6 May 2019 17:56:28 -0500 Subject: [PATCH 04/11] add quick start from offical serverless docs --- reference/tooling/serverless/quick-start.md | 97 +++++++++++++++++++++ 1 file changed, 97 insertions(+) diff --git a/reference/tooling/serverless/quick-start.md b/reference/tooling/serverless/quick-start.md index d535995b8..0c338833a 100644 --- a/reference/tooling/serverless/quick-start.md +++ b/reference/tooling/serverless/quick-start.md @@ -1,5 +1,102 @@ # Quick Start +To get started you'll first want to + +## Pre-requisites +Node.js `v6.5.0` or later. +Serverless CLI `v1.31.0` or later. You can run `npm install -g serverless` to install it. you also need our `serverless-cloudflare-workers` plugin. You can install it in your project with `npm install --save serverless-cloudflare-workers`. + +## Create a new service +Create a new service using either the `cloudflare-workers` or `cloudflare-workers-enterprise` template, depending on your Cloudflare domain’s plan level, and specifying a unique name and an optional path for your service. + +```bash +# Create a new Serverless Service/Project +$ serverless create --template cloudflare-workers --path new-project +# Change into the newly created directory +$ cd new-project +# Install npm dependencies +$ npm install +``` + +Note: there are two templates for [Cloudflare Workers](https://www.cloudflare.com/products/cloudflare-workers/): `cloudflare-workers` and `cloudflare-workers-enterprise`. The enterprise template sets up a project that can natively deploy [multiple scripts](https://developers.cloudflare.com/workers/api/config-api-for-enterprise/), each with their own routes. It requires an enterprise Cloudflare account to use. + +The `cloudflare-workers` template still supports [conditional routing](https://developers.cloudflare.com/workers/recipes/conditional-routing/) and multiple scripts if you use a tool like [webpack](https://developers.cloudflare.com/workers/writing-workers/using-npm-modules/). + +## Deploy, test and diagnose your service + +You will need to set your Global API key from Cloudflare as an environmental variable named `CLOUDFLARE_AUTH_KEY`, and your Cloudflare account email as an environmental variable named `CLOUDFLARE_AUTH_EMAIL`. You can get your Global API key from your [Cloudflare profile](https://dash.cloudflare.com/profile) page. You will also need to set `accountId` and `zoneId` in `serverless.yml` under `service.config`. The first part of the path when you open [Cloudflare dashboard](https://dash.cloudflare.com/) as a logged in user is your `accountId`, e.g. `dash.cloudflare.com/{accountId}`. And the `zoneId` can be found from the overview tab after selecting the desired zone from the [Cloudflare dashboard](https://dash.cloudflare.com/). + +Environmental variables are variables that live inside your terminal. + +For Mac and Linux users, you can set environmental variables like this: + +```bash +export CLOUDFLARE_AUTH_KEY=YOUR_API_KEY_HERE +export CLOUDFLARE_AUTH_EMAIL=YOUR_CLOUDFLARE_EMAIL +``` + +And for Windows (CMD) users, you can set environmental variables like this: + +```bash +set CLOUDFLARE_AUTH_KEY=YOUR_API_KEY_HERE +set CLOUDFLARE_AUTH_EMAIL=YOUR_CLOUDFLARE_EMAIL +``` + +You’ll need to redefine your environmental variables after each time you close your terminal. + +1. **Deploy the Service** + +Use this when you have made changes to your Functions, Events or Resources in `serverless.yml` or you simply want to deploy all changes within your Service at the same time. If you've made changes to your routes since last deploying, the Serverless Framework will update them on the server for you. + +```bash +serverless deploy +``` + +2. **Deploy the Function** + +Use this to quickly upload and overwrite your function code, allowing you to develop faster. + +```bash +serverless deploy -f hello +``` + +3. **Invoke the Function** + +Invokes the Function and returns results. + +```bash +serverless invoke --function helloWorld + +Hello world +``` + +Your Function must have the `events` field populated in order for the `serverless` tool to know exactly which route to request. Defining the `headers` field is optional. + +```yml +# serverless.yml +... +foo: + name: foo + script: bar + events: + - http: + url: example.com/foo/bar + # Defines the method used by serverless when the `invoke` command is used. Cloudflare Workers only support GET requests for now + method: GET + headers: + someKey: someValue +``` + + +## Cleanup +If at any point, you no longer need your service, you can run the following command to remove the Functions, Events and Resources that were created. + +```bash +serverless remove +``` + +set up your `serverless.yml` + ##### Auth You will also need to set your Global API key from Cloudflare as an environmental variable named `CLOUDFLARE_AUTH_KEY`, and your Cloudflare account email as an environmental variable named `CLOUDFLARE_AUTH_EMAIL`. You can get your Global API key from your [Cloudflare profile](https://dash.cloudflare.com/profile) page. Unlike `accountId` this will always be the API key that *you* are signed in on, not necassarily the account the owns the zone. For more information see [Where do I find my API key?]( Date: Mon, 6 May 2019 18:35:18 -0500 Subject: [PATCH 05/11] made quick start humanable --- reference/tooling/serverless/cli.md | 2 + reference/tooling/serverless/config.md | 32 +++---- reference/tooling/serverless/index.md | 7 +- reference/tooling/serverless/quick-start.md | 100 +++++++++++++------- 4 files changed, 88 insertions(+), 53 deletions(-) diff --git a/reference/tooling/serverless/cli.md b/reference/tooling/serverless/cli.md index e69de29bb..23c4940fb 100644 --- a/reference/tooling/serverless/cli.md +++ b/reference/tooling/serverless/cli.md @@ -0,0 +1,2 @@ +TODO:... + diff --git a/reference/tooling/serverless/config.md b/reference/tooling/serverless/config.md index db71145d6..b85dc1749 100644 --- a/reference/tooling/serverless/config.md +++ b/reference/tooling/serverless/config.md @@ -1,8 +1,8 @@ -### Core Concepts +# Serverless.yml The `serverless.yml` file is what molds the Worker(s) of your project. Using the [Server Cloudflare Workers plugin](TODO link), a `serverless.yml` will look like: -``` +```yml # serverless.yml service: name: hello @@ -54,19 +54,19 @@ functions: .. A Function is a Cloudflare Worker - a single script including its bindings, routes and other config. It's an independent unit of deployment, like a microservice. It's merely code, deployed on Cloudflare’s 155+ PoPs [points of presence](TODO: can we reference this PoPsnumber somewhere instead of hard coding it? ), that is most often written to perform a single job as a Worker. - `serverless.yml`: + `serverless.yml`: (TODO: make this yml pretty) ``` functions: - functionName: - worker: scriptName - script: filename - webpack: true - environment: - CLOUDFLARE_AUTH_KEY: - CLOUDFLARE_AUTH_EMAIL: - resources: ... - events: ... + functionName: + worker: scriptName + script: filename + webpack: true + environment: + CLOUDFLARE_AUTH_KEY: + CLOUDFLARE_AUTH_EMAIL: + resources: ... + events: ... ``` `worker`: the name of which the script will be as in this case`scriptName` @@ -87,13 +87,13 @@ The webpack option under functions allows you to easily use multiple scripts or It can accept a boolean or a string. Possible behaviors: -`boolean`: will automatically bundle the function if set to "true" +`boolean`: will automatically bundle the function if set to "true" with the global webpack config -`string`: web pack config path for this function[TODO: clean] add a function level webpack configuration in addition to a global webpack configuration. This helps you to process bundling different for an individual function than the global webpack config explained earlier. To use this, set the webpack config path to the function level `webpack` variable. Setting function level `webpack` variable to `true` will force webpack to bundle the function script with a default web pack configuration. Setting `webpack` key to `false` will turn off webpack for the function. (i.e the function script will not be fetched from dist folder) +`string`: a function level webpack configuration in addition to a global webpack configuration. This helps you to process bundling different for an individual function than the global webpack config . To use this, set the webpack config path to the function level `webpack` variable. Setting function level `webpack` variable to `true` will force webpack to bundle the function script with a default web pack configuration. Setting `webpack` key to `false` will turn off webpack for the function. (i.e the function script will not be fetched from dist folder) Simply add `webpack: true | ` to your config block. -For example in your script you can now use `import`: +For example in your script you can now use `import`: ``` addEventListener('fetch', event => { @@ -119,7 +119,7 @@ If your handler script looks like the above, the includeMe script will be packed kv: ``` -[TODO] +[TODO: fill in ] ##### Events diff --git a/reference/tooling/serverless/index.md b/reference/tooling/serverless/index.md index 827dece7b..7bcee00db 100644 --- a/reference/tooling/serverless/index.md +++ b/reference/tooling/serverless/index.md @@ -4,7 +4,8 @@ TODO: question for Jonathan: - why are there three levels of naming? e.g. scriptname = `func-foo-bar` ? - are all urls -> routes not have wildcards? -- is event.http a Request object/ +- is event.http a Request object? +- webpack config global means webpack.config.js? and that's applied at all functions - who owns the docs on serverless? TODO: missing concepts: @@ -19,9 +20,9 @@ TODO: missing concepts: The [Serverless Framework](https://github.com/serverless/serverless) helps you develop and deploy serverless applications using [Cloudflare Workers](https://www.cloudflare.com/products/cloudflare-workers/). It's a CLI that offers structure, automation, and best practices out-of-the-box, allowing you to focus on building sophisticated, event-driven, serverless architectures, comprised of Functions and Events. -The Serverless Framework manages the infrastructure that turns your version controlled code into a Worker(s) deployed globally with one command. One config file directs where exactly this Worker will live, so you can modify code and have it re-built and re-deployed in moments. No visits to the browser required. +The Serverless Framework manages the infrastructure that turns your version controlled code into a Worker(s) deployed globally with one command. [One config file](TODO link to config) directs where exactly this Worker will live, so you can modify code and have it re-built and re-deployed in moments. No visits to the browser required. -TODO: link to quick start and ref +Get started using serverless with Cloudflare Workers in this [quick start guide](TODO: link to quick start and ref (maybe will look similar to entry to docs? ) ### Additional Documentation diff --git a/reference/tooling/serverless/quick-start.md b/reference/tooling/serverless/quick-start.md index 0c338833a..987c4e842 100644 --- a/reference/tooling/serverless/quick-start.md +++ b/reference/tooling/serverless/quick-start.md @@ -1,13 +1,15 @@ # Quick Start -To get started you'll first want to +This guide is a walk through of using the Serverless Plugin to deploy Cloudflare Workers to a zone already proxied on Cloudflare. + +*Note:`workers.dev` domains are not currently supported using Serverless, but you can track our progress on [this Github issue](TODO: open a link Github issue).* ## Pre-requisites Node.js `v6.5.0` or later. Serverless CLI `v1.31.0` or later. You can run `npm install -g serverless` to install it. you also need our `serverless-cloudflare-workers` plugin. You can install it in your project with `npm install --save serverless-cloudflare-workers`. ## Create a new service -Create a new service using either the `cloudflare-workers` or `cloudflare-workers-enterprise` template, depending on your Cloudflare domain’s plan level, and specifying a unique name and an optional path for your service. +To create a new service, you can use the `cloudflare-workers` template. Optionally specify a unique name and an optional path for your service. ```bash # Create a new Serverless Service/Project @@ -18,13 +20,31 @@ $ cd new-project $ npm install ``` -Note: there are two templates for [Cloudflare Workers](https://www.cloudflare.com/products/cloudflare-workers/): `cloudflare-workers` and `cloudflare-workers-enterprise`. The enterprise template sets up a project that can natively deploy [multiple scripts](https://developers.cloudflare.com/workers/api/config-api-for-enterprise/), each with their own routes. It requires an enterprise Cloudflare account to use. +# Setup -The `cloudflare-workers` template still supports [conditional routing](https://developers.cloudflare.com/workers/recipes/conditional-routing/) and multiple scripts if you use a tool like [webpack](https://developers.cloudflare.com/workers/writing-workers/using-npm-modules/). +### Config -## Deploy, test and diagnose your service +To deploy, you will need to set the `accountId` and `zoneId` in your[`serverless.yml`](TODO link to ref docs) according to the *zone* you wish the Worker(s) to deploy to. + +```yaml +# serverless.yml +service: + name: hello + config: + accountId: CLOUDFLARE_ACCOUNT_ID + zoneId: CLOUDFLARE_ZONE_ID + functions: + functionName: + worker: scriptName + script: filename + events: ... +``` + +Configure the [functions]() according to your specific routing and naming conventions or leave `functions` as is from what the template generated. When you deploy with the Framework by running `serverless deploy`, everything in `serverless.yml` will be deployed at once. -You will need to set your Global API key from Cloudflare as an environmental variable named `CLOUDFLARE_AUTH_KEY`, and your Cloudflare account email as an environmental variable named `CLOUDFLARE_AUTH_EMAIL`. You can get your Global API key from your [Cloudflare profile](https://dash.cloudflare.com/profile) page. You will also need to set `accountId` and `zoneId` in `serverless.yml` under `service.config`. The first part of the path when you open [Cloudflare dashboard](https://dash.cloudflare.com/) as a logged in user is your `accountId`, e.g. `dash.cloudflare.com/{accountId}`. And the `zoneId` can be found from the overview tab after selecting the desired zone from the [Cloudflare dashboard](https://dash.cloudflare.com/). +###Environment Variables + +You will need to set your Global API key from Cloudflare as an environmental variable named `CLOUDFLARE_AUTH_KEY`, and your Cloudflare account email as an environmental variable named `CLOUDFLARE_AUTH_EMAIL`. You can get your Global API key from your [Cloudflare profile](https://dash.cloudflare.com/profile) page. Unlike `accountId` this will always be the API key that *you* are signed in on, not necassarily the account the owns the zone. For more information see [Where do I find my API key?]( { + event.respondWith(helloWorld(event.request)) +}) + +async function helloWorld(request) { + return new Response('hello world') +} +``` + +*Note: Serverless plugin omits the extension `.js` in the `serverless.yml` file when referring to what script to run* + +## Deploy, test and diagnose your service 1. **Deploy the Service** -Use this when you have made changes to your Functions, Events or Resources in `serverless.yml` or you simply want to deploy all changes within your Service at the same time. If you've made changes to your routes since last deploying, the Serverless Framework will update them on the server for you. +To have the Worker(s) deployed globally run: ```bash serverless deploy ``` +You can use this when you have made changes to your Functions, Events or Resources in `serverless.yml` or when you simply want to deploy all changes within your Service at the same time. If you've made changes to your routes since last deploying, the Serverless Framework will update them on the server for you. + 2. **Deploy the Function** Use this to quickly upload and overwrite your function code, allowing you to develop faster. ```bash -serverless deploy -f hello +serverless deploy -f someName ``` 3. **Invoke the Function** @@ -70,7 +125,7 @@ serverless invoke --function helloWorld Hello world ``` -Your Function must have the `events` field populated in order for the `serverless` tool to know exactly which route to request. Defining the `headers` field is optional. +Your Function must have the `events` field populated in order for the `serverless` tool to know exactly which route to request. TODO: make snippet below mirror what is in the examples above ```yml # serverless.yml @@ -95,28 +150,5 @@ If at any point, you no longer need your service, you can run the following comm serverless remove ``` -set up your `serverless.yml` - -##### Auth - -You will also need to set your Global API key from Cloudflare as an environmental variable named `CLOUDFLARE_AUTH_KEY`, and your Cloudflare account email as an environmental variable named `CLOUDFLARE_AUTH_EMAIL`. You can get your Global API key from your [Cloudflare profile](https://dash.cloudflare.com/profile) page. Unlike `accountId` this will always be the API key that *you* are signed in on, not necassarily the account the owns the zone. For more information see [Where do I find my API key?]( Date: Wed, 8 May 2019 12:35:45 -0500 Subject: [PATCH 06/11] CLI directly imported from the serverless docs --- reference/tooling/serverless/cli.md | 210 +++++++++++++++++++++++++++- 1 file changed, 209 insertions(+), 1 deletion(-) diff --git a/reference/tooling/serverless/cli.md b/reference/tooling/serverless/cli.md index 23c4940fb..3008c5a73 100644 --- a/reference/tooling/serverless/cli.md +++ b/reference/tooling/serverless/cli.md @@ -1,2 +1,210 @@ -TODO:... +# Cloudflare Workers - Create +Creates a new Serverless service in the current working directory based on the provided template. + +**Create service in current working directory:** + +```bash +serverless create --template cloudflare-workers +``` + +Or for Enterprise Cloudflare accounts: + +```bash +serverless create --template cloudflare-workers-enterprise +``` + +**Create service in new folder:** + +```bash +serverless create --template cloudflare-workers --path my-service +``` + +Or for Enterprise Cloudflare accounts: + +```bash +serverless create --template cloudflare-workers-enterprise --path my-service +``` + +## Options +- `--template` or `-t` The name of one of the available templates. Required if --template-url and --template-path are not present. +- `--template-url` or `-u` The name of one of the available templates. Required if --template and --template-path are not present. +- `--template-path` The local path of your template. Required if --template and --template-url are not present. +- `--path` or `-p` The path where the service should be created. +- `--name` or `-n` the name of the service in `serverless.yml`. +## Provided lifecycle events +- `create:create` +## Available Templates for Cloudflare Workers +To see a list of available templates run `serverless create --help` +These are the current available templates for Cloudflare Workers: + +- cloudflare-workers +- cloudflare-workers-enterprise +- cloudflare-workers-rust + +## Examples +### Creating a new service +```bash +serverless create --template cloudflare-workers --name my-special-service +``` + +This example will generate scaffolding for a service with `Cloudflare` as a provider. The scaffolding will be generated in the current working directory. + +### Creating a named service in a (new) directory +```bash +serverless create --template cloudflare-workers --path my-new-service +``` + +This example will generate scaffolding for a service with `Cloudflare` as a provider. The scaffolding will be generated in the `my-new-service` directory. This directory will be created if not present. Otherwise, Serverless will use the already present directory. +Additionally, Serverless will rename the service according to the path you provide. In this example, the service will be renamed to `my-new-service`. + +### Creating a new service using a local template +```bash +serverless create --template-path path/to/my/template/folder --path path/to/my/service --name my-new-service +``` +This will copy the `path/to/my/template/folder` folder into `path/to/my/service` and rename the service to `my-new-service`. + + + + +### [Read this on the main serverless docs site](https://www.serverless.com/framework/docs/providers/cloudflare/cli-reference/deploy) + + + +# Cloudflare Workers - Deploy +In order to be able to deploy any Cloudflare Workers, You will need to set your Global API key from Cloudflare as an environmental variable named `CLOUDFLARE_AUTH_KEY`, and your Cloudflare account email as an environmental variable named `CLOUDFLARE_AUTH_EMAIL`. You can get your Global API key from your [Cloudflare profile](https://dash.cloudflare.com/profile) page. You will also need to set `accountId` and `zoneId` in `serverless.yml` under `service.config`. The first part of the path when you open [Cloudflare dashboard](https://dash.cloudflare.com/) as a logged in user is your `accountId`, e.g. `dash.cloudflare.com/{accountId}`. And the `zoneId` can be found from the overview tab after selecting the desired zone from the [Cloudflare dashboard](https://dash.cloudflare.com/). + +Environmental variables are variables that live inside your terminal. + +For Mac and Linux users, you can set environmental variables like this: + +```bash +export CLOUDFLARE_AUTH_KEY=YOUR_API_KEY_HERE +export CLOUDFLARE_AUTH_EMAIL=YOUR_CLOUDFLARE_EMAIL +``` + +And for Windows (CMD) users, you can set environmental variables like this: + +```bash +set CLOUDFLARE_AUTH_KEY=YOUR_API_KEY_HERE +set CLOUDFLARE_AUTH_EMAIL=YOUR_CLOUDFLARE_EMAIL +``` + +You’ll need to redefine your environmental variables after each time you close your terminal. + +The `serverless deploy` command deploys your entire service via the Cloudflare Workers API. Run this command when you have made service changes (i.e., you edited `serverless.yml`). +Use `serverless deploy -f my-function` when you have made code changes and you want to quickly upload your updated code to Cloudflare. + +```bash +serverless deploy +``` + +This is the simplest deployment usage possible. With this command, Serverless will deploy your service to Cloudflare. + +## Options +- `--verbose` or `-v`: Shows all stack events during deployment, and display any Stack Output. +- `--function` or `-f`: Invokes `deploy function` (see above). Convenience shortcut + +## Provided lifecycle events +- `deploy:deploy` +- `deploy:function:deploy` + + + + +### [Read this on the main serverless docs site](https://www.serverless.com/framework/docs/providers/cloudflare-workers/cli-reference/invoke) + + + +# Cloudflare Workers - Invoke +Invokes a deployed function. It allows you to send an event to a deployed function, which can be useful for testing. Cloudflare Workers only support `GET` requests for now. The optional `headers` field allows you to specify headers that will be sent to your Worker along with your request. + +```bash +serverless invoke --function functionName +``` + +In the following example, you could run: + +```bash +serverless invoke --function helloWorld +``` + +```yml +# serverless.yml + ... +functions: + helloWorld: + # What the script will be called on Cloudflare (this property value must match the function name one line above) + name: helloWorld + # The name of the script on your machine, omitting the .js file extension + script: helloWorld + events: + - http: + url: example.com/hello/user + # Defines the method used by serverless when the `invoke` command is used. Cloudflare Workers only support GET requests for now + method: GET + headers: + greeting: hi +``` + +## Options +* `--function` or `-f` The name of the function in your service that you want to invoke. Required. +* `--data` or `-d` String data to be passed as an event to your function. By default data is read from standard input. +* `--path` or `-p` The path to a json file with input data to be passed to the invoked function. This path is relative to the root directory of the service. + +## Provided lifecycle events +- `invoke:invoke` + +## Examples + +### Cloudflare Workers +```bash +serverless invoke --function functionName +``` + +This example will invoke your deployed function on the configured Cloudflare Workers API URL endpoint. This will output the result of the request in your terminal. + +#### Function invocation with data +```bash +serverless invoke --function functionName +``` + + + + +### [Read this on the main serverless docs site](https://www.serverless.com/framework/docs/providers/cloudflare/cli-reference/remove) + + +# Cloudflare Workers - Remove +The `serverless remove` command will remove the deployed service, defined in your current working directory, from the provider. + +```bash +serverless remove +``` +It will remove the Cloudflare Worker functions from the Cloudflare. +## Provided lifecycle events +- `remove:remove` + +#Plugin + +For other commands related to what's going on under the hood of the Serverless plugin see the [Cloudflare Serverless Docs]() + +\* *`workers.dev` domains are not currently supported using Serverless, but you can track our progress on [this Github issue](TODO: open a link Github issue).* \ No newline at end of file From 4e05385daa02fcca76bbe6b334be3cee339809fa Mon Sep 17 00:00:00 2001 From: Victoria Date: Wed, 8 May 2019 13:38:15 -0500 Subject: [PATCH 07/11] validated the config and quick start --- reference/tooling/index.md | 1 + reference/tooling/serverless/cli.md | 25 +----- reference/tooling/serverless/config.md | 86 ++++++++++++++------- reference/tooling/serverless/index.md | 24 +----- reference/tooling/serverless/quick-start.md | 2 +- 5 files changed, 63 insertions(+), 75 deletions(-) diff --git a/reference/tooling/index.md b/reference/tooling/index.md index a9fe86a74..7ff72c3be 100644 --- a/reference/tooling/index.md +++ b/reference/tooling/index.md @@ -2,4 +2,5 @@ ## Official CLI Reference ## Ecosystem Tooling +## Serverless diff --git a/reference/tooling/serverless/cli.md b/reference/tooling/serverless/cli.md index 3008c5a73..7eec3d148 100644 --- a/reference/tooling/serverless/cli.md +++ b/reference/tooling/serverless/cli.md @@ -1,6 +1,6 @@ # Cloudflare Workers - Create -Creates a new Serverless service in the current working directory based on the provided template. +Creates a new Serverless service in the current working directory based on the provided template. [Read full documentation on the main serverless docs site](https://www.serverless.com/framework/docs/providers/cloudflare/cli-reference/deploy). **Create service in current working directory:** @@ -64,17 +64,7 @@ serverless create --template-path path/to/my/template/folder --path path/to/my/s ``` This will copy the `path/to/my/template/folder` folder into `path/to/my/service` and rename the service to `my-new-service`. - - -### [Read this on the main serverless docs site](https://www.serverless.com/framework/docs/providers/cloudflare/cli-reference/deploy) - # Cloudflare Workers - Deploy @@ -181,18 +171,6 @@ This example will invoke your deployed function on the configured Cloudflare Wor serverless invoke --function functionName ``` - - - -### [Read this on the main serverless docs site](https://www.serverless.com/framework/docs/providers/cloudflare/cli-reference/remove) - - # Cloudflare Workers - Remove The `serverless remove` command will remove the deployed service, defined in your current working directory, from the provider. @@ -207,4 +185,3 @@ It will remove the Cloudflare Worker functions from the Cloudflare. For other commands related to what's going on under the hood of the Serverless plugin see the [Cloudflare Serverless Docs]() -\* *`workers.dev` domains are not currently supported using Serverless, but you can track our progress on [this Github issue](TODO: open a link Github issue).* \ No newline at end of file diff --git a/reference/tooling/serverless/config.md b/reference/tooling/serverless/config.md index b85dc1749..76f9adb16 100644 --- a/reference/tooling/serverless/config.md +++ b/reference/tooling/serverless/config.md @@ -6,9 +6,10 @@ The `serverless.yml` file is what molds the Worker(s) of your project. Using the # serverless.yml service: name: hello + webpack: true | PATH_TO_CONFIG config: accountId: CLOUDFLARE_ACCOUNT_ID - zoneId: CLOUDFLARE_ZONE_ID + zoneId: CLOUDFLARE_ZONE_ID* provider: name: cloudflare @@ -50,6 +51,24 @@ functions: .. To find your zoneId and accountId, please see [API documentation on resource IDs](https://api.cloudflare.com/#getting-started-resource-ids) +#### Provider + +A Provider tells the serverless frame what cloud provider you are using, in this case Cloudflare. + +``` +provider: + name: cloudflare + stage: prod + environment: + SOME_KEY: some_info +``` + +`stage`: meant to be the stage of your project (`dev`, `prod`..). Will be used in the [`name`](TODO: link) of the scripts on deployed to Cloudflare. If unset defaults to `dev`. + +`environment`: variables that can be referenced in your throughout your worker scripts. These will get added to every function. If a [`function`](TODO: link) defines the same variable, the function defintion will overwrite the provider block definition. + +`name`: the name of the cloud provider, in this case `cloudflare` + #### Functions A Function is a Cloudflare Worker - a single script including its bindings, routes and other config. It's an independent unit of deployment, like a microservice. It's merely code, deployed on Cloudflare’s 155+ PoPs [points of presence](TODO: can we reference this PoPsnumber somewhere instead of hard coding it? ), that is most often written to perform a single job as a Worker. @@ -59,7 +78,7 @@ A Function is a Cloudflare Worker - a single script including its bindings, rout ``` functions: functionName: - worker: scriptName + name: scriptName #TODO might be called name with is optional? script: filename webpack: true environment: @@ -69,13 +88,13 @@ A Function is a Cloudflare Worker - a single script including its bindings, rout events: ... ``` -`worker`: the name of which the script will be as in this case`scriptName` +`name`: the name of which the script will be as in this case `scriptName` -`script`: the path to the script from the current directory +`script`: the path to the script from the current directory omitting the extension `.js` `webpack`(*optional*): specifies what webpack operation to perform on this individual Worker script. See webpack -`environment`(*optional*) : any environment variables set before deploy this will be passed as a binding as a secret [TODO: link to kv secrets ]to the scripts deployed. If `CLOUDFLARE_AUTH_KEY` and `CLOUDFLARE_AUTH_EMAIL` are omitted make sure to set them in your environment variables. **Please don't commit a file with your API key**. See more in Auth[TODO: link] +`environment`(*optional*) : any environment variables set before deploy this will be passed as a binding as a secret [TODO: link to kv secrets ]to the scripts deployed. If `CLOUDFLARE_AUTH_KEY` and `CLOUDFLARE_AUTH_EMAIL` are omitted make sure to set them in your environment variables. **Please don't commit a file with your API key**. See more in Environment[TODO: link] `resources`(*optional*) : see Resources below @@ -83,33 +102,25 @@ A Function is a Cloudflare Worker - a single script including its bindings, rout ##### Webpack -The webpack option under functions allows you to easily use multiple scripts or libraries and not worry about a complicated build pipeline. - -It can accept a boolean or a string. Possible behaviors: - -`boolean`: will automatically bundle the function if set to "true" with the global webpack config - -`string`: a function level webpack configuration in addition to a global webpack configuration. This helps you to process bundling different for an individual function than the global webpack config . To use this, set the webpack config path to the function level `webpack` variable. Setting function level `webpack` variable to `true` will force webpack to bundle the function script with a default web pack configuration. Setting `webpack` key to `false` will turn off webpack for the function. (i.e the function script will not be fetched from dist folder) - -Simply add `webpack: true | ` to your config block. +[Webpack](TODO: link) allows you to easily use multiple files or libraries and not worry about a complicated build pipeline. For example in your script you can now use `import`: ``` +import hello from './includeMe'; addEventListener('fetch', event => { - event.respondWith(handleRequest(event.request)) + event.respondWith(hello(event.request)) }); +``` -import hello from './includeMe'; +If your handler script looks like the above, the includeMe script will be packed into the final script on deployment. Learn more about how webpack works in [this article](TODO: link). -async function handleRequest(request) { - return new Response(hello.hello()) -} -``` +To get this working in your worker project, simply add `webpack: true | ` under the functions that you wish to bundle. Webpack will run on these functions, bundle the resulting file to `/dist`, and deploy the bundled file in `/dist`. -If your handler script looks like the above, the includeMe script will be packed into the final script on deployment. +It can accept a boolean or a string. Possible behaviors: -[View the Cloudflare Workers events section for more information on HTTP events](https://serverless.com/framework/docs/providers/cloudflare/events). +- `boolean`: will automatically bundle the function if set to "true" with the default webpack config. If false or omitted no bundling will occur. +- `string`: a function level webpack configuration in addition to a global webpack configuration. This helps you to process bundling different for an individual function than the global webpack config . ##### Resources @@ -119,7 +130,25 @@ If your handler script looks like the above, the includeMe script will be packed kv: ``` -[TODO: fill in ] +[TODO: test this and fill in ] + +##### Environment + +While Cloudflare Workers doesn't exactly offer environment vairables, we can bind global variables to values, essentially giving the same capabilities. In your function configuration, add key value pairs in `environment` + +```yaml +functions: + myFunction: + environment: + MYKEY: value_of_my_key + ANOTHER_KEY_OF_MINE: sweet_child_o_mine + myOtherFunc: + name: ${env:ANOTHER_KEY_OF_MINE} +``` + +Then in your script, you can reference `MYKEY` to access the value. Within the `serverless.yml`, you can reference the variables as well `${env: key`. + +To add a variable to every function use `provider`. ##### Events @@ -128,18 +157,15 @@ Anything that triggers a Cloudflare Worker to execute is regarded by the Framewo ``` events: - http: - url: example.com/hello/user + url: example.com/hello/user* #serverless invoke -f? fun1 method: GET - headers: - someKey: someValue ``` Each event implements two behaviors: - `serverless invoke ` will deploy your worker and run the HTTP request(s) specified by the event(s) against this deployed worker. This is useful for defining specific hooks into your application for testing. + `serverless deploy` will parse out all the `url`(s) from the events in a function and deploy routes all pointing to that specific script. The routes may contain wildcards `*`. You cannot have multiple routes that are identical. The routes must be paths for the the zone specified by `CLOUDFLARE_ZONE_ID`. - `serverless deploy` will parse out all the `url`(s) from the events in a function and deploy routes all pointing to that specific script. The routes will not contain wildcards, but be the [TODO verify this] You cannot have multiple routes that are identical + `serverless invoke ` will deploy your worker and run the HTTP request(s) specified by the `url` and `method` against this deployed worker. This is useful for defining specific hooks into your application for testing. To truly test your worker, you can run [`cURL`](TODO: link to curl) against your domain since the Worker will be deployed. -TODO: link to CLI section +\* *`workers.dev` domains are not currently supported using Serverless, but you can track our progress on [this Github issue](TODO: open a link Github issue).* -### \ No newline at end of file diff --git a/reference/tooling/serverless/index.md b/reference/tooling/serverless/index.md index 7bcee00db..f975d7307 100644 --- a/reference/tooling/serverless/index.md +++ b/reference/tooling/serverless/index.md @@ -1,28 +1,12 @@ - - -TODO: question for Jonathan: - -- why are there three levels of naming? e.g. scriptname = `func-foo-bar` ? -- are all urls -> routes not have wildcards? -- is event.http a Request object? -- webpack config global means webpack.config.js? and that's applied at all functions -- who owns the docs on serverless? - -TODO: missing concepts: - -- environment variables in the serverless.yml -- bindings -- webpack -- CLI ref documentation -- rearrange service and additional documentation - # Serverless Plugin The [Serverless Framework](https://github.com/serverless/serverless) helps you develop and deploy serverless applications using [Cloudflare Workers](https://www.cloudflare.com/products/cloudflare-workers/). It's a CLI that offers structure, automation, and best practices out-of-the-box, allowing you to focus on building sophisticated, event-driven, serverless architectures, comprised of Functions and Events. -The Serverless Framework manages the infrastructure that turns your version controlled code into a Worker(s) deployed globally with one command. [One config file](TODO link to config) directs where exactly this Worker will live, so you can modify code and have it re-built and re-deployed in moments. No visits to the browser required. +The Serverless Framework manages the infrastructure as a [Serverless Plugin](TODO: link to plugin) that turns your version controlled code into a Worker(s) deployed globally with one command. [One config file](TODO link to config) directs where exactly this Worker will live, so you can modify code and have it re-built and re-deployed in moments. No visits to the browser required. + +Get started using serverless with Cloudflare Workers in this [quick start guide to the plugin](TODO: link to quick start and ref (maybe will look similar to entry to docs? ) -Get started using serverless with Cloudflare Workers in this [quick start guide](TODO: link to quick start and ref (maybe will look similar to entry to docs? ) +*Note:`workers.dev` domains are not currently supported using Serverless, but you can track our progress on [this Github issue](TODO: open a link Github issue).* ### Additional Documentation diff --git a/reference/tooling/serverless/quick-start.md b/reference/tooling/serverless/quick-start.md index 987c4e842..8e9cf956f 100644 --- a/reference/tooling/serverless/quick-start.md +++ b/reference/tooling/serverless/quick-start.md @@ -62,7 +62,7 @@ set CLOUDFLARE_AUTH_KEY=YOUR_API_KEY_HERE set CLOUDFLARE_AUTH_EMAIL=YOUR_CLOUDFLARE_EMAIL ``` -You’ll need to redefine your environmental variables each time you open a new terminal. Optionally, you can set the environment variables in your [`serverless.yml`](TODO link) +You’ll need to redefine your environmental variables each time you open a new terminal. ## Write Code From a25e4b0dca502021f658e01ec23755e5bc488509 Mon Sep 17 00:00:00 2001 From: Victoria Date: Wed, 8 May 2019 17:13:38 -0500 Subject: [PATCH 08/11] remove CLI documentation --- reference/tooling/serverless/cli.md | 187 -------------------------- reference/tooling/serverless/index.md | 4 +- 2 files changed, 3 insertions(+), 188 deletions(-) delete mode 100644 reference/tooling/serverless/cli.md diff --git a/reference/tooling/serverless/cli.md b/reference/tooling/serverless/cli.md deleted file mode 100644 index 7eec3d148..000000000 --- a/reference/tooling/serverless/cli.md +++ /dev/null @@ -1,187 +0,0 @@ - -# Cloudflare Workers - Create -Creates a new Serverless service in the current working directory based on the provided template. [Read full documentation on the main serverless docs site](https://www.serverless.com/framework/docs/providers/cloudflare/cli-reference/deploy). - -**Create service in current working directory:** - -```bash -serverless create --template cloudflare-workers -``` - -Or for Enterprise Cloudflare accounts: - -```bash -serverless create --template cloudflare-workers-enterprise -``` - -**Create service in new folder:** - -```bash -serverless create --template cloudflare-workers --path my-service -``` - -Or for Enterprise Cloudflare accounts: - -```bash -serverless create --template cloudflare-workers-enterprise --path my-service -``` - -## Options -- `--template` or `-t` The name of one of the available templates. Required if --template-url and --template-path are not present. -- `--template-url` or `-u` The name of one of the available templates. Required if --template and --template-path are not present. -- `--template-path` The local path of your template. Required if --template and --template-url are not present. -- `--path` or `-p` The path where the service should be created. -- `--name` or `-n` the name of the service in `serverless.yml`. -## Provided lifecycle events -- `create:create` -## Available Templates for Cloudflare Workers -To see a list of available templates run `serverless create --help` -These are the current available templates for Cloudflare Workers: - -- cloudflare-workers -- cloudflare-workers-enterprise -- cloudflare-workers-rust - -## Examples -### Creating a new service -```bash -serverless create --template cloudflare-workers --name my-special-service -``` - -This example will generate scaffolding for a service with `Cloudflare` as a provider. The scaffolding will be generated in the current working directory. - -### Creating a named service in a (new) directory -```bash -serverless create --template cloudflare-workers --path my-new-service -``` - -This example will generate scaffolding for a service with `Cloudflare` as a provider. The scaffolding will be generated in the `my-new-service` directory. This directory will be created if not present. Otherwise, Serverless will use the already present directory. -Additionally, Serverless will rename the service according to the path you provide. In this example, the service will be renamed to `my-new-service`. - -### Creating a new service using a local template -```bash -serverless create --template-path path/to/my/template/folder --path path/to/my/service --name my-new-service -``` -This will copy the `path/to/my/template/folder` folder into `path/to/my/service` and rename the service to `my-new-service`. - - - - -# Cloudflare Workers - Deploy -In order to be able to deploy any Cloudflare Workers, You will need to set your Global API key from Cloudflare as an environmental variable named `CLOUDFLARE_AUTH_KEY`, and your Cloudflare account email as an environmental variable named `CLOUDFLARE_AUTH_EMAIL`. You can get your Global API key from your [Cloudflare profile](https://dash.cloudflare.com/profile) page. You will also need to set `accountId` and `zoneId` in `serverless.yml` under `service.config`. The first part of the path when you open [Cloudflare dashboard](https://dash.cloudflare.com/) as a logged in user is your `accountId`, e.g. `dash.cloudflare.com/{accountId}`. And the `zoneId` can be found from the overview tab after selecting the desired zone from the [Cloudflare dashboard](https://dash.cloudflare.com/). - -Environmental variables are variables that live inside your terminal. - -For Mac and Linux users, you can set environmental variables like this: - -```bash -export CLOUDFLARE_AUTH_KEY=YOUR_API_KEY_HERE -export CLOUDFLARE_AUTH_EMAIL=YOUR_CLOUDFLARE_EMAIL -``` - -And for Windows (CMD) users, you can set environmental variables like this: - -```bash -set CLOUDFLARE_AUTH_KEY=YOUR_API_KEY_HERE -set CLOUDFLARE_AUTH_EMAIL=YOUR_CLOUDFLARE_EMAIL -``` - -You’ll need to redefine your environmental variables after each time you close your terminal. - -The `serverless deploy` command deploys your entire service via the Cloudflare Workers API. Run this command when you have made service changes (i.e., you edited `serverless.yml`). -Use `serverless deploy -f my-function` when you have made code changes and you want to quickly upload your updated code to Cloudflare. - -```bash -serverless deploy -``` - -This is the simplest deployment usage possible. With this command, Serverless will deploy your service to Cloudflare. - -## Options -- `--verbose` or `-v`: Shows all stack events during deployment, and display any Stack Output. -- `--function` or `-f`: Invokes `deploy function` (see above). Convenience shortcut - -## Provided lifecycle events -- `deploy:deploy` -- `deploy:function:deploy` - - - - -### [Read this on the main serverless docs site](https://www.serverless.com/framework/docs/providers/cloudflare-workers/cli-reference/invoke) - - - -# Cloudflare Workers - Invoke -Invokes a deployed function. It allows you to send an event to a deployed function, which can be useful for testing. Cloudflare Workers only support `GET` requests for now. The optional `headers` field allows you to specify headers that will be sent to your Worker along with your request. - -```bash -serverless invoke --function functionName -``` - -In the following example, you could run: - -```bash -serverless invoke --function helloWorld -``` - -```yml -# serverless.yml - ... -functions: - helloWorld: - # What the script will be called on Cloudflare (this property value must match the function name one line above) - name: helloWorld - # The name of the script on your machine, omitting the .js file extension - script: helloWorld - events: - - http: - url: example.com/hello/user - # Defines the method used by serverless when the `invoke` command is used. Cloudflare Workers only support GET requests for now - method: GET - headers: - greeting: hi -``` - -## Options -* `--function` or `-f` The name of the function in your service that you want to invoke. Required. -* `--data` or `-d` String data to be passed as an event to your function. By default data is read from standard input. -* `--path` or `-p` The path to a json file with input data to be passed to the invoked function. This path is relative to the root directory of the service. - -## Provided lifecycle events -- `invoke:invoke` - -## Examples - -### Cloudflare Workers -```bash -serverless invoke --function functionName -``` - -This example will invoke your deployed function on the configured Cloudflare Workers API URL endpoint. This will output the result of the request in your terminal. - -#### Function invocation with data -```bash -serverless invoke --function functionName -``` - -# Cloudflare Workers - Remove -The `serverless remove` command will remove the deployed service, defined in your current working directory, from the provider. - -```bash -serverless remove -``` -It will remove the Cloudflare Worker functions from the Cloudflare. -## Provided lifecycle events -- `remove:remove` - -#Plugin - -For other commands related to what's going on under the hood of the Serverless plugin see the [Cloudflare Serverless Docs]() - diff --git a/reference/tooling/serverless/index.md b/reference/tooling/serverless/index.md index f975d7307..f887ea694 100644 --- a/reference/tooling/serverless/index.md +++ b/reference/tooling/serverless/index.md @@ -10,6 +10,8 @@ Get started using serverless with Cloudflare Workers in this [quick start guide ### Additional Documentation -[The Documentation on Serverless](https://serverless.com/framework/docs/providers/cloudflare/) +[Plugin Documentation on Serverless](https://serverless.com/framework/docs/providers/cloudflare/) + +[CLI Documentation on Serverless](https://serverless.com/framework/docs/providers/cloudflare/cli-reference/) [Plugin on Github]() \ No newline at end of file From f4c0efa9338f0d47d27e93124ab11cbf305528fa Mon Sep 17 00:00:00 2001 From: Victoria Date: Thu, 9 May 2019 11:57:16 -0500 Subject: [PATCH 09/11] Fixed with Ashleys comments --- reference/tooling/serverless/config.md | 19 +++++++++---------- reference/tooling/serverless/quick-start.md | 6 +++--- 2 files changed, 12 insertions(+), 13 deletions(-) diff --git a/reference/tooling/serverless/config.md b/reference/tooling/serverless/config.md index 76f9adb16..5cc5f70f7 100644 --- a/reference/tooling/serverless/config.md +++ b/reference/tooling/serverless/config.md @@ -1,6 +1,6 @@ # Serverless.yml -The `serverless.yml` file is what molds the Worker(s) of your project. Using the [Server Cloudflare Workers plugin](TODO link), a `serverless.yml` will look like: +The `serverless.yml` file is what molds the Worker(s) of your project. Using the [Serverless Cloudflare Workers plugin](TODO link), a `serverless.yml` will look like: ```yml # serverless.yml @@ -8,8 +8,8 @@ service: name: hello webpack: true | PATH_TO_CONFIG config: - accountId: CLOUDFLARE_ACCOUNT_ID - zoneId: CLOUDFLARE_ZONE_ID* + accountId: ${env:CLOUDFLARE_ACCOUNT_ID} + zoneId: ${env:CLOUDFLARE_ZONE_ID} provider: name: cloudflare @@ -29,8 +29,8 @@ A **Service** is the Serverless Framework's unit of organization. You can think service: name: hello config: - accountId: CLOUDFLARE_ACCOUNT_ID - zoneId: CLOUDFLARE_ZONE_ID + accountId: ${env:CLOUDFLARE_ACCOUNT_ID} + zoneId: ${env:CLOUDFLARE_ZONE_ID} provider: name: cloudflare @@ -82,19 +82,18 @@ A Function is a Cloudflare Worker - a single script including its bindings, rout script: filename webpack: true environment: - CLOUDFLARE_AUTH_KEY: - CLOUDFLARE_AUTH_EMAIL: + some_key: resources: ... events: ... ``` -`name`: the name of which the script will be as in this case `scriptName` +`name`: the name of the script in this case would be `scriptName` `script`: the path to the script from the current directory omitting the extension `.js` `webpack`(*optional*): specifies what webpack operation to perform on this individual Worker script. See webpack -`environment`(*optional*) : any environment variables set before deploy this will be passed as a binding as a secret [TODO: link to kv secrets ]to the scripts deployed. If `CLOUDFLARE_AUTH_KEY` and `CLOUDFLARE_AUTH_EMAIL` are omitted make sure to set them in your environment variables. **Please don't commit a file with your API key**. See more in Environment[TODO: link] +`environment`(*optional*) : any environment variables set as a global inside the script. See more in Environment[TODO: link] `resources`(*optional*) : see Resources below @@ -134,7 +133,7 @@ It can accept a boolean or a string. Possible behaviors: ##### Environment -While Cloudflare Workers doesn't exactly offer environment vairables, we can bind global variables to values, essentially giving the same capabilities. In your function configuration, add key value pairs in `environment` +While Cloudflare Workers doesn't exactly offer environment variables, we can bind global variables to values, essentially giving the same capabilities. In your function configuration, add key value pairs in `environment` ```yaml functions: diff --git a/reference/tooling/serverless/quick-start.md b/reference/tooling/serverless/quick-start.md index 8e9cf956f..34f3a2e2c 100644 --- a/reference/tooling/serverless/quick-start.md +++ b/reference/tooling/serverless/quick-start.md @@ -24,15 +24,15 @@ $ npm install ### Config -To deploy, you will need to set the `accountId` and `zoneId` in your[`serverless.yml`](TODO link to ref docs) according to the *zone* you wish the Worker(s) to deploy to. +To deploy, you will need either the environment variables set or manually input the `accountId` and `zoneId` in your [`serverless.yml`](TODO link to ref docs) according to the *zone* you wish the Worker(s) to deploy to. ```yaml # serverless.yml service: name: hello config: - accountId: CLOUDFLARE_ACCOUNT_ID - zoneId: CLOUDFLARE_ZONE_ID + accountId: ${env:CLOUDFLARE_ACCOUNT_ID} + zoneId: ${env:CLOUDFLARE_ZONE_ID} functions: functionName: worker: scriptName From 16c8f84ec3bff59c70ed1b3e2b547d1b8f6e48a3 Mon Sep 17 00:00:00 2001 From: Victoria Date: Thu, 9 May 2019 13:43:02 -0500 Subject: [PATCH 10/11] Fixed with Kristians comments --- .../index.md | 8 +++---- reference/tooling/serverless/config.md | 24 ++++++------------- reference/tooling/serverless/quick-start.md | 2 +- 3 files changed, 12 insertions(+), 22 deletions(-) diff --git a/reference/how-to-find-your-cloudflare-api-keys/index.md b/reference/how-to-find-your-cloudflare-api-keys/index.md index 83c798a69..85b9bfcae 100644 --- a/reference/how-to-find-your-cloudflare-api-keys/index.md +++ b/reference/how-to-find-your-cloudflare-api-keys/index.md @@ -2,9 +2,9 @@ To publish Cloudflare Workers projects and serve them from our global cloud network, you'll need to [create a Cloudflare account](https://support.cloudflare.com/hc/en-us/articles/201720164) (TODO: is this true for zoneless workers? different account?). -Once you've signed up (or if you already have an account), you'll need to find a few important keys in Cloudflare's Dashboard UI: your **Account ID**, Zone ID, and your **Global API key** – Wrangler will use these to manage uploading and publishing your Workers. +Once you've signed up (or if you already have an account), you'll need to find a few important keys in Cloudflare's Dashboard UI: your **Account ID**, Zone ID, and your **Global API key**. -**To find your Account and Zone IDs, do the following:** +The Account ID is according to the *zone* you wish the Worker(s) to deploy to. **To find your Account and Zone IDs, do the following:** 1. Login to Cloudflare with the account you'd like to use for deploying Cloudflare Workers 2. Select the "Home" button on the top navigation bar. @@ -13,11 +13,11 @@ Once you've signed up (or if you already have an account), you'll need to find a **To find your API key, do the following:** -1. Click on the Profile icon at the top-right of the screen, and select "My Profile". Your account email should also be listed underneath the "My Profile" text. +1. Click on the Profile icon at the top-right of the screen, and select "My Profile". Your account email should also be listed underneath the "My Profile" text. Unlike Account ID this will always be the API key that *you* are signed in on, not necassarily the account the owns the zone. 2. On the "My Profile" page, scroll down to "API Keys", and find "Global API Key". 3. Enter your password, and click "View" to see your Global API Key. ![Viewing Cloudflare API keys](./media/api-keys.png) -**Treat your Global API Key like a password!** You'll configure Wrangler to use this key, but by design, Wrangler does not keep this API key in version control, or inside of your code. +**Treat your Global API Key like a password!** You'll configure Wrangler to use this key, but by design, Wrangler/other tools do not keep this API key in version control, or inside of your code. diff --git a/reference/tooling/serverless/config.md b/reference/tooling/serverless/config.md index 5cc5f70f7..ca9f86f61 100644 --- a/reference/tooling/serverless/config.md +++ b/reference/tooling/serverless/config.md @@ -71,14 +71,14 @@ provider: #### Functions -A Function is a Cloudflare Worker - a single script including its bindings, routes and other config. It's an independent unit of deployment, like a microservice. It's merely code, deployed on Cloudflare’s 155+ PoPs [points of presence](TODO: can we reference this PoPsnumber somewhere instead of hard coding it? ), that is most often written to perform a single job as a Worker. +A Function is a Cloudflare Worker - a single script including its bindings, routes and other config. It's an independent unit of deployment, like a microservice. It's merely code, deployed on Cloudflare’s 155+ PoPs [points of presence](TODO: can we reference this PoPsnumber somewhere instead of hard coding it? ), that is most often written to perform a single job as a Worker script. - `serverless.yml`: (TODO: make this yml pretty) + `serverless.yml`: -``` +```yml functions: functionName: - name: scriptName #TODO might be called name with is optional? + name: scriptName script: filename webpack: true environment: @@ -87,13 +87,13 @@ A Function is a Cloudflare Worker - a single script including its bindings, rout events: ... ``` -`name`: the name of the script in this case would be `scriptName` +`name`: overwrite the default name generated (e.g. replaces [`hello-foo-bar`](TODO:link to name below)) for the Worker script name `script`: the path to the script from the current directory omitting the extension `.js` `webpack`(*optional*): specifies what webpack operation to perform on this individual Worker script. See webpack -`environment`(*optional*) : any environment variables set as a global inside the script. See more in Environment[TODO: link] +`environment`(*optional*) : any environment variables set as a global inside the script. See more in [Environment](TODO: link) `resources`(*optional*) : see Resources below @@ -119,17 +119,7 @@ To get this working in your worker project, simply add `webpack: true | Date: Thu, 9 May 2019 16:06:05 -0500 Subject: [PATCH 11/11] Remove serverless docs and just point to the updated serverless docs --- .../index.md | 8 +- .../serverless/{index.md => _index.md} | 4 +- reference/tooling/serverless/config.md | 160 ------------------ reference/tooling/serverless/quick-start.md | 154 ----------------- 4 files changed, 6 insertions(+), 320 deletions(-) rename reference/tooling/serverless/{index.md => _index.md} (88%) delete mode 100644 reference/tooling/serverless/config.md delete mode 100644 reference/tooling/serverless/quick-start.md diff --git a/reference/how-to-find-your-cloudflare-api-keys/index.md b/reference/how-to-find-your-cloudflare-api-keys/index.md index 85b9bfcae..83c798a69 100644 --- a/reference/how-to-find-your-cloudflare-api-keys/index.md +++ b/reference/how-to-find-your-cloudflare-api-keys/index.md @@ -2,9 +2,9 @@ To publish Cloudflare Workers projects and serve them from our global cloud network, you'll need to [create a Cloudflare account](https://support.cloudflare.com/hc/en-us/articles/201720164) (TODO: is this true for zoneless workers? different account?). -Once you've signed up (or if you already have an account), you'll need to find a few important keys in Cloudflare's Dashboard UI: your **Account ID**, Zone ID, and your **Global API key**. +Once you've signed up (or if you already have an account), you'll need to find a few important keys in Cloudflare's Dashboard UI: your **Account ID**, Zone ID, and your **Global API key** – Wrangler will use these to manage uploading and publishing your Workers. -The Account ID is according to the *zone* you wish the Worker(s) to deploy to. **To find your Account and Zone IDs, do the following:** +**To find your Account and Zone IDs, do the following:** 1. Login to Cloudflare with the account you'd like to use for deploying Cloudflare Workers 2. Select the "Home" button on the top navigation bar. @@ -13,11 +13,11 @@ The Account ID is according to the *zone* you wish the Worker(s) to deploy to. * **To find your API key, do the following:** -1. Click on the Profile icon at the top-right of the screen, and select "My Profile". Your account email should also be listed underneath the "My Profile" text. Unlike Account ID this will always be the API key that *you* are signed in on, not necassarily the account the owns the zone. +1. Click on the Profile icon at the top-right of the screen, and select "My Profile". Your account email should also be listed underneath the "My Profile" text. 2. On the "My Profile" page, scroll down to "API Keys", and find "Global API Key". 3. Enter your password, and click "View" to see your Global API Key. ![Viewing Cloudflare API keys](./media/api-keys.png) -**Treat your Global API Key like a password!** You'll configure Wrangler to use this key, but by design, Wrangler/other tools do not keep this API key in version control, or inside of your code. +**Treat your Global API Key like a password!** You'll configure Wrangler to use this key, but by design, Wrangler does not keep this API key in version control, or inside of your code. diff --git a/reference/tooling/serverless/index.md b/reference/tooling/serverless/_index.md similarity index 88% rename from reference/tooling/serverless/index.md rename to reference/tooling/serverless/_index.md index f887ea694..ba7fb060a 100644 --- a/reference/tooling/serverless/index.md +++ b/reference/tooling/serverless/_index.md @@ -1,10 +1,10 @@ # Serverless Plugin -The [Serverless Framework](https://github.com/serverless/serverless) helps you develop and deploy serverless applications using [Cloudflare Workers](https://www.cloudflare.com/products/cloudflare-workers/). It's a CLI that offers structure, automation, and best practices out-of-the-box, allowing you to focus on building sophisticated, event-driven, serverless architectures, comprised of Functions and Events. +The [Serverless Framework](https://github.com/serverless/serverless) helps you develop and deploy serverless applications using [Cloudflare Workers](https://www.cloudflare.com/products/cloudflare-workers/). It's a CLI that offers structure, automation, and best practices out-of-the-box, allowing you to focus on building sophisticated, event-driven, Serverless architectures, comprised of Functions and Events. The Serverless Framework manages the infrastructure as a [Serverless Plugin](TODO: link to plugin) that turns your version controlled code into a Worker(s) deployed globally with one command. [One config file](TODO link to config) directs where exactly this Worker will live, so you can modify code and have it re-built and re-deployed in moments. No visits to the browser required. -Get started using serverless with Cloudflare Workers in this [quick start guide to the plugin](TODO: link to quick start and ref (maybe will look similar to entry to docs? ) +Get started using serverless with Cloudflare Workers in this [quick start guide to the plugin]( ) *Note:`workers.dev` domains are not currently supported using Serverless, but you can track our progress on [this Github issue](TODO: open a link Github issue).* diff --git a/reference/tooling/serverless/config.md b/reference/tooling/serverless/config.md deleted file mode 100644 index ca9f86f61..000000000 --- a/reference/tooling/serverless/config.md +++ /dev/null @@ -1,160 +0,0 @@ -# Serverless.yml - -The `serverless.yml` file is what molds the Worker(s) of your project. Using the [Serverless Cloudflare Workers plugin](TODO link), a `serverless.yml` will look like: - -```yml -# serverless.yml -service: - name: hello - webpack: true | PATH_TO_CONFIG - config: - accountId: ${env:CLOUDFLARE_ACCOUNT_ID} - zoneId: ${env:CLOUDFLARE_ZONE_ID} - -provider: - name: cloudflare - -plugins: - - serverless-cloudflare-workers - -functions: .. -``` - -#### Services - -A **Service** is the Serverless Framework's unit of organization. You can think of it as a project file, though you can have multiple services for a single application. It's where you define your Functions and the routes they will live on, all in one file entitled `serverless.yml`: - -```yml -# serverless.yml -service: - name: hello - config: - accountId: ${env:CLOUDFLARE_ACCOUNT_ID} - zoneId: ${env:CLOUDFLARE_ZONE_ID} - -provider: - name: cloudflare - -plugins: - - serverless-cloudflare-workers - -functions: .. -``` - -`name`: the project name which will prefix the function and script names that will show on Cloudflare as script name (e.g script with the name `hello` will look like a script with the name `hello-blah-foo` on Cloudflare) - -`config`: - -- `accountId`: the account that *owns* the zone that you wish to deploy Workers too. Note: this may not be the account ID you are signed in as, but will be the account ID you see in the URL once you've selected the zone - -- `zoneId`: the zone desired to deploy Workers to - - To find your zoneId and accountId, please see [API documentation on resource IDs](https://api.cloudflare.com/#getting-started-resource-ids) - -#### Provider - -A Provider tells the serverless frame what cloud provider you are using, in this case Cloudflare. - -``` -provider: - name: cloudflare - stage: prod - environment: - SOME_KEY: some_info -``` - -`stage`: meant to be the stage of your project (`dev`, `prod`..). Will be used in the [`name`](TODO: link) of the scripts on deployed to Cloudflare. If unset defaults to `dev`. - -`environment`: variables that can be referenced in your throughout your worker scripts. These will get added to every function. If a [`function`](TODO: link) defines the same variable, the function defintion will overwrite the provider block definition. - -`name`: the name of the cloud provider, in this case `cloudflare` - -#### Functions - -A Function is a Cloudflare Worker - a single script including its bindings, routes and other config. It's an independent unit of deployment, like a microservice. It's merely code, deployed on Cloudflare’s 155+ PoPs [points of presence](TODO: can we reference this PoPsnumber somewhere instead of hard coding it? ), that is most often written to perform a single job as a Worker script. - - `serverless.yml`: - -```yml - functions: - functionName: - name: scriptName - script: filename - webpack: true - environment: - some_key: - resources: ... - events: ... -``` - -`name`: overwrite the default name generated (e.g. replaces [`hello-foo-bar`](TODO:link to name below)) for the Worker script name - -`script`: the path to the script from the current directory omitting the extension `.js` - -`webpack`(*optional*): specifies what webpack operation to perform on this individual Worker script. See webpack - -`environment`(*optional*) : any environment variables set as a global inside the script. See more in [Environment](TODO: link) - -`resources`(*optional*) : see Resources below - -`events`(*optional*) : Any routing for a Worker is configured here. See Events below - -##### Webpack - -[Webpack](TODO: link) allows you to easily use multiple files or libraries and not worry about a complicated build pipeline. - -For example in your script you can now use `import`: - -``` -import hello from './includeMe'; -addEventListener('fetch', event => { - event.respondWith(hello(event.request)) -}); -``` - -If your handler script looks like the above, the includeMe script will be packed into the final script on deployment. Learn more about how webpack works in [this article](TODO: link). - -To get this working in your worker project, simply add `webpack: true | ` under the functions that you wish to bundle. Webpack will run on these functions, bundle the resulting file to `/dist`, and deploy the bundled file in `/dist`. - -It can accept a boolean or a string. Possible behaviors: - -- `boolean`: will automatically bundle the function if set to "true" with the default webpack config. If false or omitted no bundling will occur. -- `string`: a function level webpack configuration in addition to a global webpack configuration. This helps you to process bundling different for an individual function than the global webpack config. Note the extension `.js` will be ignored. (e.g. `webpack.config`) - -##### Environment - -While Cloudflare Workers doesn't exactly offer environment variables, we can bind global variables to values, essentially giving the same capabilities. In your function configuration, add key value pairs in `environment` - -```yaml -functions: - myFunction: - environment: - MYKEY: value_of_my_key - ANOTHER_KEY_OF_MINE: sweet_child_o_mine - myOtherFunc: - name: ${env:ANOTHER_KEY_OF_MINE} -``` - -Then in your script, you can reference `MYKEY` to access the value. Within the `serverless.yml`, you can reference the variables as well `${env: key`. - -To add a variable to every function use `provider`. - -##### Events - -Anything that triggers a Cloudflare Worker to execute is regarded by the Framework as an **Event**. - -``` - events: - - http: - url: example.com/hello/user* #serverless invoke -f? fun1 - method: GET -``` - -Each event implements two behaviors: - - `serverless deploy` will parse out all the `url`(s) from the events in a function and deploy routes all pointing to that specific script. The routes may contain wildcards `*`. You cannot have multiple routes that are identical. The routes must be paths for the the zone specified by `CLOUDFLARE_ZONE_ID`. - - `serverless invoke ` will deploy your worker and run the HTTP request(s) specified by the `url` and `method` against this deployed worker. This is useful for defining specific hooks into your application for testing. To truly test your worker, you can run [`cURL`](TODO: link to curl) against your domain since the Worker will be deployed. - -\* *`workers.dev` domains are not currently supported using Serverless, but you can track our progress on [this Github issue](TODO: open a link Github issue).* - diff --git a/reference/tooling/serverless/quick-start.md b/reference/tooling/serverless/quick-start.md deleted file mode 100644 index fb1d88243..000000000 --- a/reference/tooling/serverless/quick-start.md +++ /dev/null @@ -1,154 +0,0 @@ -# Quick Start - -This guide is a walk through of using the Serverless Plugin to deploy Cloudflare Workers to a zone already proxied on Cloudflare. - -*Note:`workers.dev` domains are not currently supported using Serverless, but you can track our progress on [this Github issue](TODO: open a link Github issue).* - -## Pre-requisites -Node.js `v6.5.0` or later. -Serverless CLI `v1.31.0` or later. You can run `npm install -g serverless` to install it. you also need our `serverless-cloudflare-workers` plugin. You can install it in your project with `npm install --save serverless-cloudflare-workers`. - -## Create a new service -To create a new service, you can use the `cloudflare-workers` template. Optionally specify a unique name and an optional path for your service. - -```bash -# Create a new Serverless Service/Project -$ serverless create --template cloudflare-workers --path new-project -# Change into the newly created directory -$ cd new-project -# Install npm dependencies -$ npm install -``` - -# Setup - -### Config - -To deploy, you will need either the environment variables set or manually input the `accountId` and `zoneId` in your [`serverless.yml`](TODO link to ref docs) according to the *zone* you wish the Worker(s) to deploy to. - -```yaml -# serverless.yml -service: - name: hello - config: - accountId: ${env:CLOUDFLARE_ACCOUNT_ID} - zoneId: ${env:CLOUDFLARE_ZONE_ID} - functions: - functionName: - worker: scriptName - script: filename - events: ... -``` - -Configure the [functions]() according to your specific routing and naming conventions or leave `functions` as is from what the template generated. When you deploy with the Framework by running `serverless deploy`, everything in `serverless.yml` will be deployed at once. - -###Environment Variables - -You will need to set your Global API key from Cloudflare as an environmental variable named `CLOUDFLARE_AUTH_KEY`, and your Cloudflare account email as an environmental variable named `CLOUDFLARE_AUTH_EMAIL`. See: [How to find your API keys](/reference/how-to-find-your-cloudflare-api-keys) - -Environmental variables are variables that live inside your terminal. - -For Mac and Linux users, you can set environmental variables like this: - -```bash -export CLOUDFLARE_AUTH_KEY=YOUR_API_KEY_HERE -export CLOUDFLARE_AUTH_EMAIL=YOUR_CLOUDFLARE_EMAIL -``` - -And for Windows (CMD) users, you can set environmental variables like this: - -```bash -set CLOUDFLARE_AUTH_KEY=YOUR_API_KEY_HERE -set CLOUDFLARE_AUTH_EMAIL=YOUR_CLOUDFLARE_EMAIL -``` - -You’ll need to redefine your environmental variables each time you open a new terminal. - -## Write Code - -With the setup all complete we can get to the good stuff of writing code. The path to the file at which you write your Worker is expected to live in what's configured in the `serverless.yml` under `service.functions.someName.script`. In this file you can set the fetch event listener and [write Worker code in Javascript](TODO link to generic how to write a worker). - -`serverless.yaml`: - -``` -service: - name: hello - config:.. - functions: - someName: - worker: scriptName - script: path/filename - events: ... -``` - -`path/filename.js`: - -``` -addEventListener('fetch', event => { - event.respondWith(helloWorld(event.request)) -}) - -async function helloWorld(request) { - return new Response('hello world') -} -``` - -*Note: Serverless plugin omits the extension `.js` in the `serverless.yml` file when referring to what script to run* - -## Deploy, test and diagnose your service - -1. **Deploy the Service** - -To have the Worker(s) deployed globally run: - -```bash -serverless deploy -``` - -You can use this when you have made changes to your Functions, Events or Resources in `serverless.yml` or when you simply want to deploy all changes within your Service at the same time. If you've made changes to your routes since last deploying, the Serverless Framework will update them on the server for you. - -2. **Deploy the Function** - -Use this to quickly upload and overwrite your function code, allowing you to develop faster. - -```bash -serverless deploy -f someName -``` - -3. **Invoke the Function** - -Invokes the Function and returns results. - -```bash -serverless invoke --function helloWorld - -Hello world -``` - -Your Function must have the `events` field populated in order for the `serverless` tool to know exactly which route to request. TODO: make snippet below mirror what is in the examples above - -```yml -# serverless.yml -... -foo: - name: foo - script: bar - events: - - http: - url: example.com/foo/bar - # Defines the method used by serverless when the `invoke` command is used. Cloudflare Workers only support GET requests for now - method: GET - headers: - someKey: someValue -``` - - -## Cleanup -If at any point, you no longer need your service, you can run the following command to remove the Functions, Events and Resources that were created. - -```bash -serverless remove -``` - -##### -