This guide uses practical examples to guide you through the process of writing serverless shell functions.
The shell runtime allows function developers to fork a process on every received event. Developers can choose to provide an executable script or run any executable binary in the container image. This guide walks you through both scenarios.
This example guides you through the steps for deploying a shell script that reverses the event's body. To implement this, you call rev
and pass stdin
as input; (the event body will appear to shell functions as stdin
).
Create a /tmp/nuclio-shell-script/reverser.sh file with the following code:
#!/bin/sh
# @nuclio.configure
#
# function.yaml:
# apiVersion: "nuclio.io/v1"
# kind: "NuclioFunction"
# spec:
# runtime: "shell"
# handler: "reverser.sh"
#
rev /dev/stdin
The function configuration needs to include the following:
runtime
- set toshell
.handler
- set to the name of the executable file. In this example, the file is reverser.sh.
Run the following command to deploy the function with the Nuclio CLI (nuctl
):
Note: if you're not running on top of Kubernetes, pass the
--platform local
option tonuctl
.
nuctl deploy -p /tmp/nuclio-shell-script/reverser.sh rev
And now, use the nuctl
CLI to invoke the function:
$ nuctl invoke rev -m POST -b reverse-me
> Response headers:
Date = Sun, 03 Dec 2017 12:53:51 GMT
Content-Type = text/plain; charset=utf-8
Content-Length = 10
Server = nuclio
> Response body:
em-esrever
Because the shell runtime simply forks a process, you can leverage it to run any executable binary in the container image. This means that you don't need to provide any code to the shell runtime, only a function configuration. In this example, you install the ImageMagick utility and call its convert
executable on each event. You then send the function images and use convert
to reduce the image by 50% in the response. You do this by invoking the nuctl
CLI as follows:
nuctl deploy -p /dev/null convert \
--runtime shell \
--build-command "apk --update --no-cache add imagemagick" \
--handler convert \
--runtime-attrs '{"arguments": "- -resize 50% fd:1"}'
Following is an explanation of the options used in the command:
-p /dev/null
- because you don't need to pass a path, you just instructnuctl
to read from/dev/null
.--build-command "apk --update --no-cache add imagemagick"
- instruct the builder to install ImageMagick on the build throughapk
.--handler convert
- thehandler
must be set to the name or path of the executable. In this example,convert
is in the environmentPATH
so there's no need for a full path.--runtime-attrs '{"arguments": "- -resize 50% fd:1"}'
- through runtime specific attributes, you specify the arguments for the executable. In this example,-
instructs the runtime to read fromstdin
, and the rest of the arguments specify how to convert the received image.
Because invoke
can't (yet) send images, use HTTPie to create a thumbnail file; replace the <function ip:port>
placeholder with your function-URL information:
http https://blog.golang.org/gopher/header.jpg | http <function ip:port> > thumb.jpg
The shell
runtime allows events to override the default arguments through the use of a header. This means that you can supply x-nuclio-arguments
as a header and provide any convert
arguments that you wish, per event. Thus, you can create, for example, a smaller thumbnail file by using the following invocation command; replace the <function ip:port>
placeholder with your function-URL information:
http https://blog.golang.org/gopher/header.jpg | http <function ip:port> x-nuclio-arguments:"- -resize 20% fd:1" > thumb.jpg