release 0.1.20 (#552)

vmware-archive · Jul 4, 2018 · a4a302c · a4a302c
1 parent 29192f9
commit a4a302c
Show file tree

Hide file tree

Showing 3 changed files with 278 additions and 3 deletions.
diff --git 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
@@ -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
@@ -2,4 +2,211 @@
 title: Functions
 ---
 
-Coming Soon
+# 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": []
+}
+```