alihan/fn-serverless
1
0
Fork 0
mirror of https://github.com/fnproject/fn.git synced 2022-10-28 21:29:17 +03:00
Code Issues Packages Projects Releases Wiki Activity

Docs update with new fnctl commands (#273)

Browse Source 
* Added high level roadmap.

* Changed to funtion.yaml.

* Added logo

* updating quickstart code example, WIP, waiting on another merge.

* Minor updates.

* Changed function.yaml to func.yaml and updated fnctl README.
This commit is contained in:
Travis Reeder
2016-11-14 16:40:05 -08:00
committed by C Cirello
parent 2d3601c588
commit 0d71e1e38e
27 changed files with 284 additions and 182 deletions
Download Patch File Download Diff File Expand all files Collapse all files

223
fnctl/README.md
View File

@@ -1,16 +1,49 @@
# IronFunctions CLI
## Init
## Creating Functions
usage: fnctl init [--runtime node] [--entrypoint "node hello.js"] <name>
### init
Init will help you create a function.yaml file for the current directory.
Init will help you create a [function file](../docs/function-file.md) (func.yaml) in the current directory.
If there's a Dockerfile found, this will generate the basic file with just the image name.
It will then try to decipher the runtime based on the files in the current directory, if it can't figure it out, it will ask.
It will then take a best guess for what the entrypoint will be based on the language, it it can't guess, it will ask.
```sh
fnctl init [--runtime node] [--entrypoint "node hello.js"] <name>
```
## Basic
`--runtime` and `--entrypoint` are optional, init will try to figure out it out based on the files in the current directory.
If it can't figure it out, it will tell you.
If there's a Dockerfile found, it will use that as is
### Build, Bump, Run, Push
`fnctl` provides a few commands you'll use while creating and updating your functions: `build`, `bump`, `run` and `push`.
Build will build the image for your function.
```sh
fnctl build
```
Bump will bump the version number in your func.yaml file. Versions must be in [semver](http://semver.org/) format.
```sh
fnctl bump
```
Run will help you test your function. Functions read input from STDIN, so you can pipe the payload into the function like this:
```sh
cat `payload.json` | fnctl run
```
Push will push the function image to Docker Hub.
```sh
fnctl push
```
## Using the API
You can operate IronFunctions from the command line.
@@ -40,6 +73,47 @@ $ fnctl routes delete otherapp hello # delete route
/hello deleted
```
## Application level configuration
When creating an application, you can configure it to tweak its behavior and its
routes' with an appropriate flag, `config`.
Thus a more complete example of an application creation will look like:
```sh
fnctl apps create --config DB_URL=http://example.org/ otherapp
```
`--config` is a map of values passed to the route runtime in the form of
environment variables prefixed with `CONFIG_`.
Repeated calls to `fnctl apps 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.
## 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.
## Changing target host
`fnctl` is configured by default to talk http://localhost:8080.
@@ -101,142 +175,11 @@ It means that first subdirectory are always considered app names (e.g. `myapp`
and `other`), each subdirectory of these firsts are considered part of the route
(e.g. `route1/subroute1`).
`fnctl update` expects that each directory to contain a file `functions.yaml`
`fnctl update` expects that each directory to contain a file `func.yaml`
which instructs `fnctl` on how to act with that particular update, and a
Dockerfile which it is going to use to build the image and push to Docker Hub.
## Functions files (functions.yaml)
Functions files are used to assist fnctl to execute bulk updates of your
functions. The files can be named as:
- functions.yaml
- functions.yml
- function.yaml
- function.yml
- functions.json
- function.json
- fn.yaml
- fn.yml
- fn.json
An example of a function file:
```yaml
app: myapp
name: iron/hello
route: "/custom/route"
version: 0.0.1
type: sync
memory: 128
config:
key: value
key2: value2
keyN: valueN
build:
- make
- make test
```
`app` (optional) is the application name to which this function will be pushed
to.
`image` is the name and tag to which this function will be pushed to and the
route updated to use it.
`route` (optional) allows you to overwrite the calculated route from the path
position. You may use it to override the calculated route.
`version` represents current version of the function. When publishing, it is
appended to the image as a tag.
`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
are started and return a task ID to customer while it executes in background.
Default: `sync`.
`memory` (optional) allows you to set a maximum memory threshold for this
function. If this function exceeds this limit during execution, it is stopped
and error message is logged. Default: `128`.
`config` (optional) is a set of configurations to be passed onto the route
setup. These configuration options shall override application configuration
during functions execution.
`build` (optional) is an array of shell calls which are used to helping building
the image. These calls are executed before `fnctl` calls `docker build` and
`docker push`.
## Build, Bump, Push
When dealing with a lot of functions you might find yourself making lots of
individual calls. `fnctl` offers two command to help you with that: `build` and
`bump`.
```sh
$ fnctl build
path result
/app/hello done
/app/test done
```
`fnctl build` is similar to `publish` except it neither publishes the resulting
docker image to Docker Hub nor updates the routes in IronFunctions server.
```sh
$ fnctl bump
path result
/app/hello done
/app/test done
```
`fnctl bump` will scan all IronFunctions whose `version` key in function file
follows [semver](http://semver.org/) rules and bump their version according.
`fnctl push` will scan all IronFunctions and push their images to Docker Hub,
and update their routes accordingly.
## Application level configuration
When creating an application, you can configure it to tweak its behavior and its
routes' with an appropriate flag, `config`.
Thus a more complete example of an application creation will look like:
```sh
fnctl apps create --config DB_URL=http://example.org/ otherapp
```
`--config` is a map of values passed to the route runtime in the form of
environment variables prefixed with `CONFIG_`.
Repeated calls to `fnctl apps 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.
## 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.
## Build
## Contributing
Ensure you have Go configured and installed in your environment. Once it is
done, run:

8
fnctl/errors.go
View File

@@ -1,13 +1,13 @@
package main
type NotFoundError struct {
type notFoundError struct {
S string
}
func (e *NotFoundError) Error() string {
func (e *notFoundError) Error() string {
return e.S
}
func newNotFoundError(s string) *NotFoundError {
return &NotFoundError{S: s}
func newNotFoundError(s string) *notFoundError {
return &notFoundError{S: s}
}

2
fnctl/init.go
View File

@@ -75,7 +75,7 @@ func initFn() cli.Command {
func (a *initFnCmd) init(c *cli.Context) error {
if !a.force {
ff, err := findFuncfile()
if _, ok := err.(*NotFoundError); !ok && err != nil {
if _, ok := err.(*notFoundError); !ok && err != nil {
return err
}
if ff != nil {

2
fnctl/run.go
View File

@@ -38,7 +38,7 @@ func (r *runCmd) run(c *cli.Context) error {
if image == "" {
ff, err := findFuncfile()
if err != nil {
if _, ok := err.(*NotFoundError); ok {
if _, ok := err.(*notFoundError); ok {
return errors.New("error: image name is missing or no function file found")
} else {
return err