From 5219227393840e7a0040d68afabd6f0f88c671a7 Mon Sep 17 00:00:00 2001 From: Travis Reeder Date: Fri, 29 Sep 2017 16:20:46 -0700 Subject: [PATCH] Updated docs on configuration and required env vars. (#285) * Updated docs on configuration and required env vars. * minor --- docs/README.md | 6 +++- docs/developers/configs.md | 20 ++++++++++++ docs/function-file.md | 49 +++++++++-------------------- docs/packaging.md | 12 +++---- examples/inputs/.gitignore | 6 ++++ examples/inputs/README.md | 15 +++++++++ examples/inputs/func.go | 21 +++++++++++++ examples/inputs/sample.payload.json | 3 ++ examples/inputs/test.json | 26 +++++++++++++++ 9 files changed, 117 insertions(+), 41 deletions(-) create mode 100644 docs/developers/configs.md create mode 100644 examples/inputs/.gitignore create mode 100644 examples/inputs/README.md create mode 100644 examples/inputs/func.go create mode 100644 examples/inputs/sample.payload.json create mode 100644 examples/inputs/test.json diff --git a/docs/README.md b/docs/README.md index 3c88959d0..cd0a6b133 100644 --- a/docs/README.md +++ b/docs/README.md @@ -7,6 +7,10 @@ If you are a developer using Fn through the API, this section is for you. * [Quickstart](https://github.com/fnproject/fn) * [Usage](usage.md) * [Writing functions](writing.md) +* [Testing functions](testing.md) +* [Hot functions](hot-functions.md) +* [Async functions](async.md) +* [Configuration](developers/configs.md) * [fn (CLI Tool)](https://github.com/fnproject/cli/blob/master/README.md) * [Hot functions](hot-functions.md) * [Async functions](async.md) @@ -15,7 +19,7 @@ If you are a developer using Fn through the API, this section is for you. * [Client Libraries](developers/clients.md) * [Packaging functions](packaging.md) * [Open Function Format](function-format.md) -* API Reference (coming soon) +* [API Reference](http://petstore.swagger.io/?url=https://raw.githubusercontent.com/fnproject/fn/master/docs/swagger.yml) * [Object Model](developers/model.md) * [FAQ](faq.md) diff --git a/docs/developers/configs.md b/docs/developers/configs.md new file mode 100644 index 000000000..920d3329f --- /dev/null +++ b/docs/developers/configs.md @@ -0,0 +1,20 @@ +# Function Config Vars + +There are three ways to get configuration variables into a function, all of which will be available as environment variables. +These are ordered in order of preference, the later ones overriding the previous ones. + +## 1. Application level configuration + +```sh +fn apps config set myapp LOG_LEVEL debug +``` + +## 2. Function configuration from func.yaml + +See [Function file](../function-file.md) for more info. + +## 3. Route level configuration + +```sh +fn routes config set myapp hello2 LOG_LEVEL info +``` diff --git a/docs/function-file.md b/docs/function-file.md index 0c1373749..4d9410b22 100644 --- a/docs/function-file.md +++ b/docs/function-file.md @@ -19,11 +19,16 @@ config: key2: value2 keyN: valueN headers: - content-type: - - text/plain + Content-Type: text/plain build: - make - make test +expects: + config: + - name: SECRET_1 + required: true + - name: SECRET_2 + required: false ``` `name` is the name and tag to which this function will be pushed to and the @@ -40,7 +45,7 @@ appended to the image as a tag. 'go', 'python', 'java', etc. The runtime 'docker' will use the existing Dockerfile if one exists. `build` (optional) is an array of local shell calls which are used to help -building the function. +building the function. TODO: Deprecate this? `type` (optional) allows you to set the type of the route. `sync`, for functions whose response are sent back to the requester; or `async`, for functions that @@ -56,9 +61,12 @@ and error message is logged. Default: `128`. `headers` (optional) is a set of HTTP headers to be returned in the response of this function calls. -`config` (optional) is a set of configurations to be passed onto the route -setup. These configuration options shall override application configuration -during functions execution. +`config` (optional) is a set of configuration variables to be passed onto the function as environment variables. +These configuration options shall override application configuration during functions execution. See [Configuration](developers/configs.md) +for more information. + +`expects` (optional) a list of config/env vars that are required to run this function. These vars will be used when running/testing locally, +if found in your local environment. If these vars are not found, local testing will fail. ## Hot functions @@ -67,31 +75,4 @@ hot functions support also adds two extra options to this configuration file. `format` (optional) is one of the streaming formats covered at [function-format.md](function-format.md). `idle_timeout` (optional) is the time in seconds a container will remain alive without receiving any new requests; -hot functions will stay alive as long as they receive a request in this interval. Default: `30`. - -## Testing functions - -`tests` (optional) is an array of tests that can be used to valid functions both -locally and remotely. It has the following structure - -```yaml -tests: -- name: envvar - in: "inserted stdin" - out: "expected stdout" - err: "expected stderr" - env: - envvar: trololo -``` - -`in` (optional) is a string that is going to be sent to the file's declared -function. - -`out` (optional) is the expected output for this function test. It is present -both in local and remote executions. - -`err` (optional) similar to `out`, however it read from `stderr`. It is only -available for local machine tests. - -`env` (optional) is a map of environment variables that are injected during -tests. +hot functions will stay alive as long as they receive a request in this interval. Default: `30`. diff --git a/docs/packaging.md b/docs/packaging.md index 17fa845aa..ca8e5600c 100644 --- a/docs/packaging.md +++ b/docs/packaging.md @@ -20,25 +20,25 @@ The basic Dockerfile for most languages is along these lines: ``` # Choose base image -FROM funcy/node:dev +FROM node:alpine # Set the working directory WORKDIR /function # Add your binary or code to the working directory -ADD funcbin /function/ +ADD . /function/ # Set what will run when a container is started for this image -ENTRYPOINT ["./funcbin"] +ENTRYPOINT ["node func.js"] ``` Then build your function image: ```sh -docker build -t $USERNAME/myfunction . +fn build ``` ### Push your image ```sh -docker push $USERNAME/myfunction +fn push ``` -Now you can use that image when creating or updating routes. +Now you can use that image when creating or updating routes. \ No newline at end of file diff --git a/examples/inputs/.gitignore b/examples/inputs/.gitignore new file mode 100644 index 000000000..d450e309c --- /dev/null +++ b/examples/inputs/.gitignore @@ -0,0 +1,6 @@ +vendor/ +/go +/app +/__uberscript__ + +func.yaml diff --git a/examples/inputs/README.md b/examples/inputs/README.md new file mode 100644 index 000000000..00074ac06 --- /dev/null +++ b/examples/inputs/README.md @@ -0,0 +1,15 @@ +# Tutorial 1: Go Function w/ Input (3 minutes) + +Example for putting required vars into the func.yaml file. + +Try running the following: + +```sh +fn run +# > ERROR: required env var SECRET_1 not found, please set either set it in your environment or pass in `-e SECRET_1=X` flag. +SECRET_1=YOOO fn run +# > info: optional env var SECRET_2 not found. +# > {"SECRET_1":"YOOO","SECRET_2":"","message":"Hello World"} +SECRET_1=YOOO SECRET_2=DAWG fn run +# > {"SECRET_1":"YOOO","SECRET_2":"DAWG","message":"Hello World"} +``` diff --git a/examples/inputs/func.go b/examples/inputs/func.go new file mode 100644 index 000000000..66e136f2c --- /dev/null +++ b/examples/inputs/func.go @@ -0,0 +1,21 @@ +package main + +import ( + "encoding/json" + "fmt" + "os" +) + +type Person struct { + Name string +} + +func main() { + p := &Person{Name: "World"} + json.NewDecoder(os.Stdin).Decode(p) + mapD := map[string]string{"message": fmt.Sprintf("Hello %s", p.Name)} + mapD["SECRET_1"] = os.Getenv("SECRET_1") + mapD["SECRET_2"] = os.Getenv("SECRET_2") + mapB, _ := json.Marshal(mapD) + fmt.Println(string(mapB)) +} diff --git a/examples/inputs/sample.payload.json b/examples/inputs/sample.payload.json new file mode 100644 index 000000000..97e136b69 --- /dev/null +++ b/examples/inputs/sample.payload.json @@ -0,0 +1,3 @@ +{ + "name": "Johnny" +} diff --git a/examples/inputs/test.json b/examples/inputs/test.json new file mode 100644 index 000000000..391d9b42f --- /dev/null +++ b/examples/inputs/test.json @@ -0,0 +1,26 @@ +{ + "tests": [ + { + "input": { + "body": { + "name": "Johnny" + } + }, + "output": { + "body": { + "message": "Hello Johnny" + } + } + }, + { + "input": { + "body": "" + }, + "output": { + "body": { + "message": "Hello World" + } + } + } + ] +}