From abb199460ee843d65794d3d19979f41b70cf34a1 Mon Sep 17 00:00:00 2001 From: Gavin Date: Tue, 26 Jun 2018 13:29:20 -0400 Subject: [PATCH] Added local testing --- ...re-Web-App-Chaos-Extension-with-Node.JS.md | 76 ++++++++++++++++--- 1 file changed, 67 insertions(+), 9 deletions(-) diff --git a/Building-an-Azure-Web-App-Chaos-Extension-with-Node.JS.md b/Building-an-Azure-Web-App-Chaos-Extension-with-Node.JS.md index 0526046..d6966c6 100644 --- a/Building-an-Azure-Web-App-Chaos-Extension-with-Node.JS.md +++ b/Building-an-Azure-Web-App-Chaos-Extension-with-Node.JS.md @@ -2,16 +2,32 @@ Chaos extensions are meant to be small, modular components built to either start or stop a chaotic event. They're meant to be the pieces of logic that directly interact with targeted cloud resources. -## Getting Started: Building the WebApp Chaos Extension ## +### Extensions As Azure functions ### -This is a simple chaos extension meant to target an Azure web app. There are two JavaScript files here: one that starts a chaotic event (shuts down a web app) and one that stops a chaotic event (restarts the web app). +As they exist now, chaotic extensions live as Azure Functions that may be run via any of their offered [triggers](https://docs.microsoft.com/en-us/azure/azure-functions/functions-triggers-bindings) (http, timers, ad hoc, and various Azure-supported sources). This would allow the developer to run these functions on-demand under a series of different conditions. -To start, create two folders - one labeled 'start' and the other labeled 'stop'. +## Getting Started: Building the WebApp Chaos Extension Locally ## + +This is a simple chaos extension meant to target an Azure Web App. There are two JavaScript files here: one that starts a chaotic event (shuts down a web app) and one that stops a chaotic event (restarts the web app). + +To start, create two folders in your root project directory - one labeled `start` and the other labeled `stop`. Then, in your root directory, run the `npm init` command to set up your `package.json` file. ### Package Dependencies ### -We recommend installing the `azure-chaos-fn` package. It offers helpers that allow extension authors to more quickly and easily build their own extensions without concerning themselves with the communication details with the orchestrator. The npm package page can be found [here](https://www.npmjs.com/package/azure-chaos-fn). +In order to get this extension running locally as an Azure Function, we'll need to install the `azure-functions-core-tools` NPM package. The npm package can be found [here](https://www.npmjs.com/package/azure-functions-core-tools) +``` +npm i azure-functions-core-tools +``` +While we're at it, we'll also execute the following command in the root of our project to define the Azure Functions project and create a local Git repository: + +``` +func init +``` +This adds the `host.json` and the `local.settings.json` required to define a Functions project. + +We also recommend installing the `azure-chaos-fn` package. It offers helpers that allow extension authors to more quickly and easily build their own extensions without concerning themselves with the communication details with the orchestrator. The npm package page can be found [here](https://www.npmjs.com/package/azure-chaos-fn). + ``` npm i --save azure-chaos-fn ``` @@ -22,9 +38,15 @@ Additionally, we'll need a means of interacting with the Azure Web App Service. npm i azure-arm-website ``` +Finally, we'll need the tool to invoke the chaos extension we're going to build. This currently exists as a CLI tool that registers extensions, manages the Azure Subscription, and invokes the extension from the command line. This tool also exists as a NPM package: + +``` +npm install platform-chaos-cli +``` + ### Starting Chaotic Events ### -In your 'start' folder, create a new `index.js` file. This is where we'll build the part of the extension that induces chaos upon an Azure Web App. In the file, we'll need to reference the 2 dependencies we installed: the `azure-chaos-fn` package to manage the token and the Azure resource and the `azure-arm-website` package to interact with the specified web app. +In your `start` folder, create a new `index.js` file. This is where we'll build the part of the extension that induces chaos upon an Azure Web App. In the file, we'll need to reference the 2 dependencies we installed: the `azure-chaos-fn` package to manage the token and the Azure resource and the `azure-arm-website` package to interact with the specified web app. ```javascript const chaosFnUtility = require('azure-chaos-fn'); @@ -72,13 +94,49 @@ module.exports = function (context, req) { }; ``` -And we've done it! We've just written a chaos extension! Find the full source file without comments [here](https://github.com/trstringer/azure-chaos-fn-webapp-startstop/blob/master/start/index.js). +And we've done it! We've just written a chaos extension! Find the full source file [here](https://github.com/trstringer/azure-chaos-fn-webapp-startstop/blob/master/start/index.js). + +### Running the Extension Locally ### + +In order to run this extension on a local machine, we'll make use of the `azure-functions-core-tools` to host our extension and the `platform-chaos-cli` tool to invoke it. + +In order to host the extension, we need to start by creating a `function.json` file in the `start` folder of our project. This file tells the Functions runtime that the contents represent a singular Azure Function as well as what sort of trigger will invoke it. We'll define ours as a `httpTrigger`. Paste this in each `function.json` files: + +``` +{ + "bindings": [ + { + "authLevel": "function", + "type": "httpTrigger", + "direction": "in", + "name": "req" + }, + { + "type": "http", + "direction": "out", + "name": "res" + } + ], + "disabled": false + } + ``` + +We're now ready to host it! From here, run the `func host start` command in your terminal. You should see a good bit of output, but what we're interested in is the final few lines that should look like the following: + +``` +Http Functions: + + start: http://localhost:7071/api/start +``` +We'll need to use this uri in order to register our chaos extension with the `platform-chaos-cli` tool. In another terminal, we'll need to run the `chaos register` command with the flags `name`, `uri`, and `description` respectively with the `uri` flag being the output from your Azure Function. Make sure the `start` folder is not in your uri path. Your command should resemble the following: +``` +chaos register WebAppExtension http://localhost:7071/api "chaos extension for a web app" +``` ### Stopping Chaotic Events ### -The process to build an extension to stop a chaotic event is virtually the same, but with one key change. In this case, we would create an `index.js` file in the 'stop' folder and instead would call the `webApps.start` function. +The process to build an extension to stop a chaotic event is virtually the same, but with one key change. In this case, we would create an `index.js` file in the `stop` folder and instead would call the `webApps.start` function. It's a bit confusing to think calling a `start` function actually stops an event, but in this case, we're restarting our web app, thus ending the chaotic event. Be sure to add another `function.json` file (the same one above) in the `stop` folder as well as it is another function. -### Extensions As Azure functions ### -As they exist now, chaotic extensions may live as Azure Functions that may be run via any of their offered [triggers](https://docs.microsoft.com/en-us/azure/azure-functions/functions-triggers-bindings) (http, timers, ad hoc, and various Azure-supported sources). This would allow the developer to run these functions on-demand under a series of different conditions. In order to create one of these, please visit the [Azure Function Quickstart](https://docs.microsoft.com/en-us/azure/azure-functions/functions-create-first-azure-function) section of the Microsoft documentation. +### Deploying Extensions to Azure ###