From a4a302c92dad26c2dfa01dd43147d3b469af97f9 Mon Sep 17 00:00:00 2001 From: Berndt Jung Date: Tue, 3 Jul 2018 17:07:37 -0700 Subject: [PATCH] release 0.1.20 (#552) --- CHANGELOG.md | 15 +- docs/_posts/2018-07-03-v0-1-20-release.md | 57 ++++++ docs/_usage/functions.md | 209 +++++++++++++++++++++- 3 files changed, 278 insertions(+), 3 deletions(-) create mode 100644 docs/_posts/2018-07-03-v0-1-20-release.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 9edf89c06..c6ec2ddcc 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,12 +2,23 @@ All notable changes to this project will be documented in this file. For more information & examples, check [What's New](https://vmware.github.io/dispatch/news) section on Dispatch website. +## [Unreleased] - [[Git compare](https://github.com/vmware/dispatch/compare/v0.1.20...HEAD)] -## [Unreleased] - [[Git compare](https://github.com/vmware/dispatch/compare/v0.1.19...HEAD)] +### Added + +### Fixed + +## [0.1.20] - 2018-07-03 - [[Git compare](https://github.com/vmware/dispatch/compare/v0.1.19...v0.1.20)] ### Added -- [[Issue #465](https://github.com/vmware/dispatch/issues/465)] **Tail/follow function runs as they happen.** When retrieving runs you can now specify the `--last` flag to get the latest executed run. You can also now specify the `--follow` or `-f` flag to follow/tail runs as they occur. [PR #537](https://github.com/vmware/dispatch/pull/537) +- [[Issue #465](https://github.com/vmware/dispatch/issues/465)] **Tail/follow function runs as they happen.** When +retrieving runs you can now specify the `--last` flag to get the latest executed run. You can also now specify the +`--follow` or `-f` flag to follow/tail runs as they occur. [PR #537](https://github.com/vmware/dispatch/pull/537) + +- **API Gateway endpoints now namespaced with the org name** Creates the user-specified API paths under the org name. +This is because we share an API Gateway and the paths from different org's can overlap. For production uses, user +usually specifies a hostname for the API's. ### Fixed diff --git a/docs/_posts/2018-07-03-v0-1-20-release.md b/docs/_posts/2018-07-03-v0-1-20-release.md new file mode 100644 index 000000000..7924901b1 --- /dev/null +++ b/docs/_posts/2018-07-03-v0-1-20-release.md @@ -0,0 +1,57 @@ +--- +layout: post +title: "v0.1.20 Dispatch Release" +year: 2018 +--- + +# v0.1.20 Dispatch Release + +[Download v0.1.20](https://github.com/vmware/dispatch/releases/tag/v0.1.20) + + +## Last/Follow Support in CLI for Function Runs + +It can be a pain to track the output of function runs, especially if they are executed asynchronously or via an +event subscription. There can often me hundreds or more executions for a single function that's been running for +a while. In order to make developing and debugging a little easier the `--last` and `--follow` options have been +added to the CLI as a convenience: + +``` +$ dispatch get run --json --last +``` + +Simply returns the last function execution. Adding the function name, filters the result by function name: + +``` +$ dispatch get run [function name] --json --last +``` + +To get a stream of function executions as they happen, use the `--follow` option: + +``` +$ dispatch get run [function name] --json --follow +``` + +The CLI will poll every second for new executions. + +## API Gateway Endpoints Now Namespaced with Org Name + +Now that Dispatch supports multiple organizations, the API Gateway needs to organization aware. In order to ensure +that all API paths defined are unique per-organization, the organization name is prepended to the path. So if the +following path is defined: + +``` +$ dispatch create api get-hello hello --method GET --path /hello +``` + +The created path will show the organization name: + +``` +$ dispatch get api + NAME | FUNCTION | PROTOCOL | METHOD | DOMAIN | PATH | AUTH | STATUS | ENABLED +-------------------------------------------------------------------------------------------------- + get-hello | hello | http | GET | | /dispatch/hello | public | READY | true + | | https | | | | | | +-------------------------------------------------------------------------------------------------- +``` + diff --git a/docs/_usage/functions.md b/docs/_usage/functions.md index b20473e99..ffb176a77 100644 --- a/docs/_usage/functions.md +++ b/docs/_usage/functions.md @@ -2,4 +2,211 @@ title: Functions --- -Coming Soon \ No newline at end of file +# Functions + +Functions are code artifacts which are layered on top of [images](images.md). They should be consise, containing only +business logic. As much as possible, function dependencies should be captured within images. + +## Adding a Function + +Adding a function is simple in dispatch. Generally speaking all you need to do is point to a directory containing +source code and specify a path to the handler which represents the function entry point. The path to the handler is +language specific. For language specifics, see the base image repositories: + +* [python3-base-image](https://github.com/dispatchframework/python3-base-image#creating-functions) +* [nodejs-base-image](https://github.com/dispatchframework/nodejs-base-image#creating-functions) +* [java-base-image](https://github.com/dispatchframework/java-base-image#creating-functions) +* [powershell-base-image](https://github.com/dispatchframework/powershell-base-image#creating-functions) + +The examples below will assume python3 as the function language. + +### Create from a Source Directory + +The following is the canonical way to create functions, however see the section below for usage optimizations +for the simple (and common) cases. + +1. Create a source directory: + + ``` + $ mkdir hello + $ cd hello + ``` + +2. Add files: + + ``` + $ cat << EOF > hello.py + def handle(ctx, payload): + name = "Noone" + place = "Nowhere" + if payload: + name = payload.get("name", name) + place = payload.get("place", place) + return {"myField": "Hello, %s from %s" % (name, place)} + EOF + ``` + +2. Create Dispatch function: + + The format is `dispatch create function [function name] [source dir] --image [image name] --handler [entry point]` + + ``` + $ dispatch create function hello . --image python3 --handler hello.handle + Created function: hello + ``` + + > Note: The handler/entry point is language specifice. For instance, for a node function it is a unix path to the + file (e.g. `hello.js`) relative to the source directory + +### Create from a Single File + +Most functions are single files therefore packaging a directory seems unnecessary. Additionally, if we use standard +names for the handler function (e.g. `handle`), we can make some inferrences which make building functions simpler: + +``` +$ dispatch create function hello hello.py --image python3 +Created function: hello +``` + +Here we simply point directly to the function file and the default handler (`handle`) is used. + +### Creating and Updating via YAML + +When iterating on a function, it's easier to use the generic `dispatch create -f [YAML]` and `dispatch update -f [YAML]` +commands. Just define your function[s] in a YAML document: + +``` +$ cat function.yaml +kind: Function +name: function-1 +sourcePath: 'function-1.py' +image: python3 +schema: {} +secrets: + - example-secret +services: + - example-service +tags: + - key: role + value: example +--- +kind: Function +name: function-2 +sourcePath: 'function-2.py' +image: python3 +schema: {} +secrets: + - example-secret +services: + - example-service +tags: + - key: role + value: example +``` + +Creating and updating is now as simple as: + +``` +$ dispatch create -f function.yaml +Created function: function-1 +Created function: function-2 +$ dispatch update -f function.yaml +Updated function: function-1 +Updated function: function-2 +``` + +Even deletion works: + +``` +$ dispatch delete -f function.yaml +Deleted function: function-1 +Deleted function: function-2 +``` + +## Executing a Function + +To simply execute a function from the CLI use the `exec` command: + +``` +$ dispatch exec --wait hello --input '{"name": "Jon", "place": "Winterfell"}' +{ + "blocking": true, + "executedTime": 1530657442, + "faasId": "694d66b9-a9f0-452c-832f-40300c627991", + "finishedTime": 1530657444, + "functionId": "bb64d31e-d586-4869-8317-860098b7d751", + "functionName": "hello", + "input": { + "name": "Jon", + "place": "Winterfell" + }, + "logs": { + "stderr": null, + "stdout": null + }, + "name": "6e5acc98-ac22-4b44-8741-eb4d5ea11fb2", + "output": { + "myField": "Hello, Jon from Winterfell" + }, + "reason": null, + "secrets": [], + "services": null, + "status": "READY", + "tags": [] +} +``` + +The `--input` is presented to the function as the `payload`. The `--wait` flag was added to simulate a synchronous +execution. Function execution is actually asynchronous. To demonstrate leave off the `--wait` flag: + +``` +$ dispatch exec hello --input '{"name": "Jon", "place": "Winterfell"}' +{ + "executedTime": 1530657613, + "faasId": "694d66b9-a9f0-452c-832f-40300c627991", + "finishedTime": -62135596800, + "functionId": "bb64d31e-d586-4869-8317-860098b7d751", + "functionName": "hello", + "input": { + "name": "Jon", + "place": "Winterfell" + }, + "name": "a4fc2ee8-e007-4131-b334-ea6723b1338b", + "reason": null, + "secrets": [], + "services": null, + "status": "INITIALIZED", + "tags": [] +} +``` + +In both cases we get a `run` object back from Dispatch. However note that the status is `INITIALIZED` rather than +`READY`. We can poll on the `name` to get the result when it is ready: + +``` +$ dispatch get run hello a4fc2ee8-e007-4131-b334-ea6723b1338b --json +{ + "executedTime": 1530657613, + "faasId": "694d66b9-a9f0-452c-832f-40300c627991", + "finishedTime": 1530657615, + "functionId": "bb64d31e-d586-4869-8317-860098b7d751", + "functionName": "hello", + "input": { + "name": "Jon", + "place": "Winterfell" + }, + "logs": { + "stderr": null, + "stdout": null + }, + "name": "a4fc2ee8-e007-4131-b334-ea6723b1338b", + "output": { + "myField": "Hello, Jon from Winterfell" + }, + "reason": null, + "secrets": null, + "services": null, + "status": "READY", + "tags": [] +} +``` \ No newline at end of file