README.md

IronFunctions CLI

Creating Functions

init

Init will help you create a function file (func.yaml) in the current directory.

To make things simple, we try to use convention over configuration, so init will look for a file named func.{language-extension}. For example, if you are using Node, put the code that you want to execute in the file func.js. If you are using Python, use func.py. Ruby, use func.rb. Go, func.go. Etc.

Run:

fn init <DOCKER_HUB_USERNAME>/<FUNCTION_NAME>

If you want to override the convention with configuration, you can do that as well using:

fn init [--runtime node] [--entrypoint "node hello.js"] <DOCKER_HUB_USERNAME>/<FUNCTION_NAME>

Or, if you want full control, just make a Dockerfile. If init finds a Dockerfile, it will use that instead of runtime and entrypoint.

Bump, Build, Run, Push

fn provides a few commands you'll use while creating and updating your functions: bump, build, run and push.

Bump will bump the version number in your func.yaml file. Versions must be in semver format.

fn bump

Build will build the image for your function, creating a Docker image tagged with the version number from func.yaml.

fn build

Run will help you test your function. Functions read input from STDIN, so you can pipe the payload into the function like this:

cat `payload.json` | fn run

Push will push the function image to Docker Hub.

fn push

Using the API

You can operate IronFunctions from the command line.

$ fn apps list                                  # list apps
myapp

$ fn apps create otherapp                       # create new app
otherapp created

$ fn apps inspect otherapp config               # show app-specific configuration
{ ... }

$ fn apps
myapp
otherapp

$ fn routes list myapp                          # list routes of an app
path	image
/hello	iron/hello

$ fn routes create otherapp /hello iron/hello   # create route
/hello created with iron/hello

$ fn routes delete otherapp hello              # delete route
/hello deleted

$ fn routes headers set otherapp hello header-name value         # add HTTP header to response
otherapp /hello headers updated header-name with value

$ fn version                                   # shows version both of client and server
Client version: 0.1.0
Server version: 0.1.21

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:

fn 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.

Repeated calls to fn 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:

fn routes create --memory 256 --type async --config DB_URL=http://example.org/ otherapp /hello iron/hello

You can also update existent routes configurations using the command fn routes update

For example:

fn routes update --memory 64 --type sync --image iron/hello

To know exactly what configurations you can update just use the command

fn routes update --help

To understand how each configuration affect your function checkout the Definitions document.

Changing target host

fn is configured by default to talk http://localhost:8080. You may reconfigure it to talk to a remote installation by updating a local environment variable ($API_URL):

$ export API_URL="http://myfunctions.example.org/"
$ fn ...

Bulk deploy

Also there is the deploy command that is going to scan all local directory for functions, rebuild them and push them to Docker Hub and update them in IronFunction. It will use the route entry in the existing function file to see the update in the daemon.

$ fn deploy APP

fn deploy expects that each directory to contain a file func.yaml which instructs fn on how to act with that particular update.

Testing functions

If you added tests to the func.yaml file, you can have them tested using fn test.

$ fn test

During local development cycles, you can easily force a build before test:

$ fn test -b

When preparing to deploy you application, remember adding path to func.yaml, it will simplify both the creation of the route, and the execution of remote tests:

name: me/myapp
version: 1.0.0
path: /myfunc

Once you application is done and deployed, you can run tests remotely:

# test the function locally first
$ fn test -b

# push it to Docker Hub and IronFunctions
$ fn push
$ fn routes create myapp

# test it remotely
$ fn test --remote myapp

Other examples of usage

Creating a new function from source

fn init iron/hello --runtime ruby
fn deploy myapp /hello

Updating function

fn deploy myapp (discover route path if available in func.yaml)

Testing function locally

fn run iron/hello

Testing route

fn call myapp /hello

App management

fn apps create myapp
fn apps update myapp --headers "content-type=application/json"
fn apps config set log_level info
fn apps inspect myapp
fn apps delete myapp

Route management

fn routes create myapp /hello iron/hello
# routes update will also update any changes in the func.yaml file too. 
fn routes update myapp /hello --timeout 30 --type async
fn routes config set myapp /hello log_level info
fn routes inspect myapp /hello
fn routes delete myapp /hello

Contributing

Ensure you have Go configured and installed in your environment. Once it is done, run:

$ make

It will build fn compatible with your local environment. You can test this CLI, right away with:

$ ./fn