Merge pull request #6122 from tbarlow12/azure-template-update

Azure template update

docs/providers/azure/guide/quick-start.md

@@ -6,7 +6,7 @@ description: Getting started with the Serverless Framework on Azure Functions
 layout: Doc
 -->
 
-# Azure - Quick Start
+# Azure Functions - Quick Start
 
 ## Pre-requisites
 
@@ -28,7 +28,28 @@ $ cd my-service
 $ npm install
 ```
 
-*Important to note that the file `{name}/function.json` is included in the template, but that will be generated by the `serverless-azure-functions` plugin at deployment. The two should be equivalent.
+Note: This template contains **two** Azure functions to demonstrate how that would be configured within `serverless.yml`.
+
+Note: The `serverless.yml` file supports **inbound** and **outbound** function bindings by specifying the `direction` property.
+
+## Running Locally
+
+In order to run & test your Azure Function(s) locally, run a one-time install of the Azure Functions Core Tools:
+
+```bash
+npm install azure-functions-core-tools -g
+```
+
+From there, run the start script:
+
+```bash
+# Start Function app
+npm start
+```
+
+You will be provided with local URLs for each function for testing.
+
+Note: The file `{function name}/function.json` is included in the template for the quickstart, but this will be replaced by a generated file from the `serverless-azure-functions` plugin at deployment. There will soon be an option in the plugin for generating this file before deployment for local testing, but that scenario is not currently supported. If you want to test different function bindings locally before deploying, make the changes manually in `function.json` and update the `serverless.yml` to reflect the same.
 
 ## Deploy and test
 
@@ -110,18 +131,3 @@ $env:azureServicePrincipalTenantId='<tenantId>'
 $env:azureServicePrincipalClientId='<servicePrincipalName>'
 $env:azureServicePrincipalPassword='<password>'
 ```
-
-**Run the Function Locally**
-
-In order to run & test your Azure Function locally, run a one-time install of the Azure Functions Core Tools:
-
-```bash
-npm install azure-functions-core-tools -g
-```
-
-From there, run the start script:
-
-```bash
-# Start Function app
-npm start
-```

lib/plugins/create/create.test.js

@@ -614,12 +614,18 @@ describe('Create', () => {
         expect(vsCodeDirContent).to.include('launch.json');
         expect(vsCodeDirContent).to.include('settings.json');
         expect(vsCodeDirContent).to.include('tasks.json');
-        // Directory containing function handler and bindings
+        // Directory containing first function handler and bindings
         expect(dirContent).to.include('hello');
-        const functionDirContent = fs.readdirSync(`${tmpDir}/hello`);
-        expect(functionDirContent).to.include('function.json');
-        expect(functionDirContent).to.include('index.js');
-        expect(functionDirContent).to.include('sample.dat');
+        const helloFunctionDirContent = fs.readdirSync(`${tmpDir}/hello`);
+        expect(helloFunctionDirContent).to.include('function.json');
+        expect(helloFunctionDirContent).to.include('index.js');
+        expect(helloFunctionDirContent).to.include('sample.dat');
+        // Directory containing second function handler and bindings
+        expect(dirContent).to.include('goodbye');
+        const goodbyeFunctionDirContent = fs.readdirSync(`${tmpDir}/goodbye`);
+        expect(goodbyeFunctionDirContent).to.include('function.json');
+        expect(goodbyeFunctionDirContent).to.include('index.js');
+        expect(goodbyeFunctionDirContent).to.include('sample.dat');
       });
     });
 

lib/plugins/create/templates/azure-nodejs/README.md

@@ -1,53 +1,131 @@
-# Serverless Azure Functions Node.js Template
+# Azure Functions - Quick Start
 
-This starter template allows quickly creating a Node.js-based service to Azure Functions. It relies on the `serverless-azure-functions` plugin, and therefore, before you can deploy it, you simply need to run `npm install` in order to acquire it (this dependency is already saved in the `package.json` file).
+## Pre-requisites
 
-### Setting up your Azure credentials
+1. Node.js `v6.5.0` or later. *(v6.5.0 is the minimum runtime version supported by Azure Functions)*
+2. Serverless CLI `v1.9.0` or later. You can run
+`npm install -g serverless` to install it.
+3. Azure plugin that allows you to work with Azure Functions `npm install -g serverless-azure-functions`
+4. An Azure account. If you don't already have one, you can sign up for a [free trial](https://azure.microsoft.com/en-us/free/) that includes $200 of free credit.
+5. **Set-up your [Provider Credentials](./credentials.md)**.
 
-Once the `serverless-azure-functions` plugin is installed, it expects to find your Azure credentials via a set of well-known environment variables. These will be used to actually authenticate with your Azure account, so that the Serverless CLI can generate the necessary Azure resources on your behalf when you request a deployment (see below).
+## Create a new service
 
-The following environment variables must be set, with their respective values:
+Create a new service using the Node.js template, specifying a unique name and an
+optional path for your service. Make sure you enter a globally unique name for the `--name` argument.
 
-- *azureSubId* - ID of the Azure subscription you want to create your service within
-- *azureServicePrincipalTenantId* - ID of the tenant that your service principal was created within
-- *azureServicePrincipalClientId* - ID of the service principal you want to use to authenticate with Azure
-- *azureServicePrincipalPassword* - Password of the service principal you want to use to authenticate with Azure
-
-For details on how to create a service principal and/or acquire your Azure account's subscription/tenant ID, refer to the [Azure credentials](https://serverless.com/framework/docs/providers/azure/guide/credentials/) documentation.
-
-### Deploying the service
-
-Once your Azure credentials are set, you can immediately deploy your service via the following command:
-
-```shell
-serverless deploy
+```bash
+$ serverless create --template azure-nodejs --path my-service --name my-unique-name
+$ cd my-service
+$ npm install
 ```
 
-This will create the necessary Azure resources to support the service and events that are defined in your `serverless.yml` file.
+Note: This template contains **two** Azure functions to demonstrate how that would be configured within `serverless.yml`.
 
-### Invoking and inspecting a function
+Note: The `serverless.yml` file supports **inbound** and **outbound** function bindings by specifying the `direction` property.
 
-With the service deployed, you can test it's functions using the following command:
+## Running Locally
 
-```shell
-serverless invoke -f hello
+In order to run & test your Azure Function(s) locally, run a one-time install of the Azure Functions Core Tools:
+
+```bash
+npm install azure-functions-core-tools -g
 ```
 
-Additionally, if you'd like to view the logs that a function generates (either via the runtime, or create by your handler by calling `context.log`), you can simply run the following command:
+From there, run the start script:
 
-```shell
-serverless logs -f hello
+```bash
+# Start Function app
+npm start
 ```
 
-### Cleaning up
+You will be provided with local URLs for each function for testing.
 
-Once you're finished with your service, you can remove all of the generated Azure resources by simply running the following command:
+Note: The file `{function name}/function.json` is included in the template for the quickstart, but this will be replaced by a generated file from the `serverless-azure-functions` plugin at deployment. There will soon be an option in the plugin for generating this file before deployment for local testing, but that scenario is not currently supported. If you want to test different function bindings locally before deploying, make the changes manually in `function.json` and update the `serverless.yml` to reflect the same.
 
-```shell
+## Deploy and test
+
+1. **Deploy the Service:**
+
+  Deploy your new service to Azure! The first time you do this, you will be asked
+  to authenticate with your Azure account, so the `serverless` CLI can manage
+  Functions on your behalf. Simply follow the provided instructions, and the
+  deployment will continue as soon as the authentication process is completed.
+
+  ```bash
+  serverless deploy
+  ```
+
+  > Note: Once you've authenticated, a new Azure "service principal" will be
+  created, and used for subsequent deployments. This prevents you from needing to
+  manually login again. See [below](#advanced-authentication) if you'd prefer to
+  use a custom service principal instead.
+
+2. **Deploy the Function**
+
+  Use this to quickly upload and overwrite your function code,allowing you to
+  develop faster. If you're working on a single function, you can simply deploy
+  the specified function instead of the entire service.
+
+  ```bash
+  serverless deploy function -f hello
+  ```
+
+3. **Invoke the Function**
+
+  Invoke a function, in order to test that it works:
+
+  ```bash
+  serverless invoke -f hello
+  ```
+
+4. **Fetch the Function Logs**
+
+  Open up a separate tab in your console and stream all logs for a specific
+  Function using this command.
+
+  ```bash
+  serverless logs -f hello -t
+  ```
+
+## 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, and
+ensure that you don't incur any unexpected charges.
+
+```bash
 serverless remove
 ```
 
-### Issues / Feedback / Feature Requests?
+Check out the [Serverless Framework Guide](./README.md) for more information.
+
+## Advanced Authentication
+
+The getting started walkthrough illustrates the interactive login experience,
+which is recommended for most users. However, if you'd prefer to create an Azure
+["service principal"](http://bit.ly/2wLVE7k)
+yourself, you can indicate that this plugin should use its credentials instead,
+by setting the following environment variables:
+
+**Bash**
+```bash
+export azureSubId='<subscriptionId>'
+export azureServicePrincipalTenantId='<tenantId>'
+export azureServicePrincipalClientId='<servicePrincipalName>'
+export azureServicePrincipalPassword='<password>'
+```
+
+**Powershell**
+```powershell
+$env:azureSubId='<subscriptionId>'
+$env:azureServicePrincipalTenantId='<tenantId>'
+$env:azureServicePrincipalClientId='<servicePrincipalName>'
+$env:azureServicePrincipalPassword='<password>'
+```
+
+
+## Issues / Feedback / Feature Requests?
 
 If you have any issues, comments or want to see new features, please file an issue in the project repository:
 

lib/plugins/create/templates/azure-nodejs/goodbye/function.json

@@ -0,0 +1,19 @@
+{
+  "bindings": [
+    {
+      "authLevel": "anonymous",
+      "type": "httpTrigger",
+      "direction": "in",
+      "name": "req",
+      "methods": [
+        "get",
+        "post"
+      ]
+    },
+    {
+      "type": "http",
+      "direction": "out",
+      "name": "res"
+    }
+  ]
+}

lib/plugins/create/templates/azure-nodejs/goodbye/index.js

@@ -0,0 +1,18 @@
+'use strict';
+
+module.exports.handler = async function (context, req) {
+    context.log('JavaScript HTTP trigger function processed a request.');
+
+    if (req.query.name || (req.body && req.body.name)) {
+        context.res = {
+            // status: 200, /* Defaults to 200 */
+            body: "Goodbye " + (req.query.name || req.body.name)
+        };
+    }
+    else {
+        context.res = {
+            status: 400,
+            body: "Please pass a name on the query string or in the request body"
+        };
+    }
+};

lib/plugins/create/templates/azure-nodejs/goodbye/sample.dat

@@ -0,0 +1,3 @@
+{
+    "name": "Azure"
+}

lib/plugins/create/templates/azure-nodejs/hello/index.js

@@ -1,6 +1,6 @@
 'use strict';
 
-module.exports = async function (context, req) {
+module.exports.handler = async function (context, req) {
     context.log('JavaScript HTTP trigger function processed a request.');
 
     if (req.query.name || (req.body && req.body.name)) {

lib/plugins/create/templates/azure-nodejs/serverless.yml

@@ -35,7 +35,17 @@ plugins:
 
 functions:
   hello:
-    handler: handler.hello
+    handler: hello/index.handler
+    events:
+      - http: true
+        x-azure-settings:
+          authLevel : anonymous
+      - http: true
+        x-azure-settings:
+          direction: out
+          name: res
+  goodbye:
+    handler: goodbye/index.handler
     events:
       - http: true
         x-azure-settings: