diff --git a/docs/routes.md b/docs/routes.md index 78049e03b..8534bc76a 100644 --- a/docs/routes.md +++ b/docs/routes.md @@ -1,69 +1,90 @@ # IronFunctions Routes -Routes have a many-to-one mapping to an [app](apps.md). +Routes have a many-to-one mapping to an [app](apps.md). -A good practice to get the best performance on your IronFunctions API is define the required memory for each function. +A good practice to get the best performance on your IronFunctions API is define +the required memory for each function. ## Route level configuration -When creating or updating a route, you can pass in a map of config variables. +When creating a route, you can configure it to tweak its behavior, the possible +choices are: `memory`, `type` and `config`. -Note: Route level configuration overrides app level configuration. +`memory` is number of usable MiB for this function. If during the execution it +exceeds this maximum threshold, it will halt and return an error in the logs. It +expects to be an integer. Default: `128`. + +`type` is the type of the function. Either `sync`, in which the client waits +until the request is successfully completed, or `async`, in which the clients +dispatches a new request, gets a task ID back and closes the HTTP connection. +Default: `sync`. + +`config` is a map of values passed to the route runtime in the form of +environment variables prefixed with `CONFIG_`. + +Note: Route level configuration overrides app level configuration. TODO: link to swagger doc on swaggerhub after it's updated. ## Understanding IronFunctions memory management -When IronFunctions starts it registers the total available memory in your system in order to know during its runtime if the system has the required amount of free memory to run each function. -Every function starts the runner reduces the amount of memory used by that function from the available memory register. -When the function finishes the runner returns the used memory to the available memory register. +When IronFunctions starts it registers the total available memory in your system +in order to know during its runtime if the system has the required amount of +free memory to run each function. Every function starts the runner reduces the +amount of memory used by that function from the available memory register. When +the function finishes the runner returns the used memory to the available memory +register. -Default memory is 128MB. - -## Defining function's memory requirement - -You can define the function's required memory in the route creation or updating it. - -### Creating function memory +### Creating function ``` curl -H "Content-Type: application/json" -X POST -d '{ "route": { "path":"", "image":"", - "memory": + "memory": , + "type": "", + "config": {"": } } }' http://localhost:8080/v1/apps//routes ``` -Eg. Creating `/myapp/hello` with required memory as `100mb` +Eg. Creating `/myapp/hello` with required memory as `100mb`, type `sync` and +some container configuration values. ``` curl -H "Content-Type: application/json" -X POST -d '{ "route": { "path":"/hello", "image":"iron/hello", - "memory": 100 + "memory": 100, + "type": "sync", + "config": {"APPLOG": "stderr"} } }' http://localhost:8080/v1/apps/myapp/routes ``` -### Updating function memory +### Updating function ``` curl -H "Content-Type: application/json" -X POST -d '{ "route": { - "memory": + "memory": , + "type": "", + "config": {"": } } }' http://localhost:8080/v1/apps//routes/ ``` -Eg. Updating `/myapp/hello` required memory as `100mb` +Eg. Updating `/myapp/hello` required memory as `100mb`, type `async` and changed +container configuration values. ``` curl -H "Content-Type: application/json" -X POST -d '{ "route": { - "memory": 100 + "memory": 100, + "type": "async", + "config": {"APPLOG": "stdout"} } }' http://localhost:8080/v1/apps/myapp/routes/hello -``` +``` \ No newline at end of file diff --git a/docs/swagger.yml b/docs/swagger.yml index cee971c55..0cae74cd7 100644 --- a/docs/swagger.yml +++ b/docs/swagger.yml @@ -6,7 +6,7 @@ swagger: '2.0' info: title: IronFunctions description: - version: "0.0.9" + version: "0.0.12" # the domain of the service host: "127.0.0.1:8080" # array of all schemes that your API supports @@ -276,6 +276,20 @@ definitions: headers: type: string description: Map of http headers that will be sent with the response + memory: + type: integer + format: int64 + description: Max usable memory for this route (MiB). + type: + enum: + - sync + - async + description: Route type + config: + type: object + description: Route configuration + additionalProperties: + type: string App: type: object diff --git a/fnctl/README.md b/fnctl/README.md index 6e3f5632a..0519f183b 100644 --- a/fnctl/README.md +++ b/fnctl/README.md @@ -146,3 +146,26 @@ path result their version according to [semver](http://semver.org/) rules. In their absence, it will skip. +## Route level configuration + +When creating a route, you can configure it to tweak its behavior, the possible +choices are: `memory`, `type` and `config`. + +Thus a more complete example of route creation will look like: +```sh +fnctl routes create --memory 256 --type async --config DB_URL=http://example.org/ otherapp /hello iron/hello +``` + +`--memory` is number of usable MiB for this function. If during the execution it +exceeds this maximum threshold, it will halt and return an error in the logs. + +`--type` is the type of the function. Either `sync`, in which the client waits +until the request is successfully completed, or `async`, in which the clients +dispatches a new request, gets a task ID back and closes the HTTP connection. + +`--config` is a map of values passed to the route runtime in the form of +environment variables prefixed with `CONFIG_`. + +Repeated calls to `fnctl route create` will trigger an update of the given +route, thus you will be able to change any of these attributes later in time +if necessary. diff --git a/fnctl/glide.lock b/fnctl/glide.lock index 6a30908c5..435e7c98b 100644 --- a/fnctl/glide.lock +++ b/fnctl/glide.lock @@ -1,11 +1,29 @@ -hash: 6c0bc544bcabed5a74a7eeefd53bd6e088f10f6deee1a9fa65bb8b5e512b93aa -updated: 2016-10-31T15:05:00.722579591-07:00 +hash: aed45d068e76dc473f16657f44281db6f793e4724e7305b4a6cef45a132da29f +updated: 2016-11-07T23:22:33.135398009+01:00 imports: - name: github.com/aws/aws-sdk-go - version: 32cdc88aa5cd2ba4afa049da884aaf9a3d103ef4 + version: 90dec2183a5f5458ee79cbaf4b8e9ab910bc81a6 subpackages: + - aws - aws/awserr + - aws/awsutil + - aws/client + - aws/client/metadata + - aws/corehandlers - aws/credentials + - aws/credentials/ec2rolecreds + - aws/defaults + - aws/ec2metadata + - aws/request + - aws/session + - aws/signer/v4 + - private/endpoints + - private/protocol + - private/protocol/json/jsonutil + - private/protocol/jsonrpc + - private/protocol/rest + - private/protocol/restjson + - service/lambda - name: github.com/Azure/go-ansiterm version: fa152c58bc15761d0200cb75fe958b89a9d4888e subpackages: @@ -15,7 +33,7 @@ imports: subpackages: - semver - name: github.com/docker/docker - version: 8cced8702261224ffd726774812eb50e8a600e52 + version: fae5a9e053ad06bea0429babae2507762d8cc1de subpackages: - api/types/blkiodev - api/types/container @@ -46,7 +64,7 @@ imports: - name: github.com/docker/go-units version: 8a7beacffa3009a9ac66bad506b18ffdd110cf97 - name: github.com/fsouza/go-dockerclient - version: 3162ed100df52ad76c94cdf1b8b2a45d4f5e203d + version: 5cfde1d138cd2cdc13e4aa36af631beb19dcbe9c - name: github.com/giantswarm/semver-bump version: 7ec6ac8985c24dd50b4942f9a908d13cdfe70f23 subpackages: @@ -55,11 +73,11 @@ imports: - name: github.com/go-ini/ini version: 6e4869b434bd001f6983749881c7ead3545887d8 - name: github.com/go-resty/resty - version: 1a3bb60986d90e32c04575111b1ccb8eab24a3e5 + version: 24dc7ba4bc1ef9215048b28e7248f99c42901db5 - name: github.com/hashicorp/go-cleanhttp version: ad28ea4487f05916463e2423a55166280e8254b5 - name: github.com/iron-io/functions_go - version: 584f4a6e13b53370f036012347cf0571128209f0 + version: ec65bad1ceb32b29f106483ecdd3e7588b5fde30 - name: github.com/iron-io/iron_go3 version: b50ecf8ff90187fc5fabccd9d028dd461adce4ee subpackages: @@ -67,9 +85,11 @@ imports: - config - worker - name: github.com/iron-io/lambda - version: 197598b21c6918d143244cc69d4d443f062d3c78 + version: d883e4b5ef216c3fcda72cf6628d9d72dd53be49 subpackages: - lambda +- name: github.com/jmespath/go-jmespath + version: 3433f3ea46d9f8019119e7dd41274e112a2359a9 - name: github.com/juju/errgo version: 08cceb5d0b5331634b9826762a8fd53b29b86ad8 subpackages: @@ -77,22 +97,22 @@ imports: - name: github.com/Microsoft/go-winio version: ce2922f643c8fd76b46cadc7f404a06282678b34 - name: github.com/opencontainers/runc - version: bc462c96bf7b15b68ab40e86335cefcb692707c1 + version: 49ed0a10e4edba88f9221ec730d668099f6d6de8 subpackages: - libcontainer/system - libcontainer/user - name: github.com/satori/go.uuid - version: b061729afc07e77a8aa4fad0a2fd840958f1942a + version: 879c5887cd475cd7864858769793b2ceb0d44feb - name: github.com/Sirupsen/logrus - version: 380f64d344b252a007a59baa61f31820f59cba89 + version: 4b6ea7319e214d98c938f12692336f7ca9348d6b - name: github.com/urfave/cli - version: 55f715e28c46073d0e217e2ce8eb46b0b45e3db6 + version: d86a009f5e13f83df65d0d6cee9a2e3f1445f0da - name: golang.org/x/crypto - version: 9477e0b78b9ac3d0b03822fd95422e2fe07627cd + version: c10c31b5e94b6f7a0283272dc2bb27163dcea24b subpackages: - ssh/terminal - name: golang.org/x/net - version: daba796358cd2742b75aae05761f1b898c9f6a5c + version: f315505cf3349909cdf013ea56690da34e96a451 subpackages: - context - context/ctxhttp diff --git a/fnctl/glide.yaml b/fnctl/glide.yaml index 50799b7de..a20c8436f 100644 --- a/fnctl/glide.yaml +++ b/fnctl/glide.yaml @@ -8,6 +8,7 @@ import: - bump - storage - package: github.com/iron-io/functions_go + version: ec65bad1ceb32b29f106483ecdd3e7588b5fde30 - package: github.com/iron-io/iron_go3 subpackages: - config diff --git a/fnctl/routes.go b/fnctl/routes.go index d9293aa5e..943be334b 100644 --- a/fnctl/routes.go +++ b/fnctl/routes.go @@ -43,6 +43,22 @@ func routes() cli.Command { Usage: "create a route", ArgsUsage: "appName /path image/name", Action: r.create, + Flags: []cli.Flag{ + cli.Int64Flag{ + Name: "memory", + Usage: "memory in MiB", + Value: 128, + }, + cli.StringFlag{ + Name: "type", + Usage: "route type - sync or async", + Value: "sync", + }, + cli.StringSliceFlag{ + Name: "config", + Usage: "route configuration", + }, + }, }, { Name: "delete", @@ -176,8 +192,16 @@ func (a *routesCmd) create(c *cli.Context) error { AppName: appName, Path: route, Image: image, + Memory: c.Int64("memory"), + Type_: c.String("type"), }, } + configs := make(map[string]string) + for _, v := range c.StringSlice("config") { + kv := strings.SplitN(v, "=", 2) + configs[kv[0]] = kv[1] + } + body.Route.Config = configs wrapper, _, err := a.AppsAppRoutesPost(appName, body) if err != nil { return fmt.Errorf("error creating route: %v", err)