README.md

R (rstats) templates for OpenFaaS

OpenFaaS templates for the R language.

• R (rstats) templates for OpenFaaS
  • Introduction
    • Parent image
    • Watchdog type
    • Server framework (for of-watchdog only)
  • Usage
    • Setup
    • Make a new function
    • Customize your function
  • Contributing
  • License

Read the R Templates blog post and watch this useR!2021 video for a quick intro!

Introduction

The /template folder contains the following OpenFaaS templates:

Template	Base image	Watchdog	Server framework
rstats-base	rocker/r-base	classic	None (STDIO)
rstats-ubuntu	rocker/r-ubuntu	classic	None (STDIO)
rstats-minimal	rhub/r-minimal	classic	None (STDIO)
rstats-base-plumber	rocker/r-base	of-watchdog	plumber
rstats-ubuntu-plumber	rocker/r-ubuntu	of-watchdog	plumber
rstats-minimal-plumber	rhub/r-minimal	of-watchdog	plumber
rstats-base-httpuv	rocker/r-base	of-watchdog	httpuv
rstats-ubuntu-httpuv	rocker/r-ubuntu	of-watchdog	httpuv
rstats-minimal-httpuv	rhub/r-minimal	of-watchdog	httpuv
rstats-base-beakr	rocker/r-base	of-watchdog	beakr
rstats-ubuntu-beakr	rocker/r-ubuntu	of-watchdog	beakr
rstats-minimal-beakr	rhub/r-minimal	of-watchdog	beakr
rstats-base-fiery	rocker/r-base	of-watchdog	fiery
rstats-ubuntu-fiery	rocker/r-ubuntu	of-watchdog	fiery
rstats-minimal-fiery	rhub/r-minimal	of-watchdog	fiery
rstats-base-ambiorix	rocker/r-base	of-watchdog	ambiorix
rstats-ubuntu-ambiorix	rocker/r-ubuntu	of-watchdog	ambiorix
rstats-minimal-ambiorix	rhub/r-minimal	of-watchdog	ambiorix

The templates differ with respect to:

• R parent image,
• watchdog type, and
• the server framework used.

Parent image

• Debian-based rocker/r-base Docker image from the rocker project for bleeding edge,
• Ubuntu-based rocker/r-ubuntu Docker image from the rocker project for long term support (uses RSPM binaries),
• Alpine-based rhub/r-minimal Docker image from the r-hub project for smallest image sizes.

See the Rocker and the Rockerverse papers in the R Journal about the current state of the art regarding the use of container technology in R.

Watchdog type

• The classic watchdog is a tiny Golang webserver that marshals an HTTP request accepted on the API Gateway and to invoke your chosen application. This is the init process for your container. The classic watchdog passes in the HTTP request via STDIN and reads a HTTP response via STDOUT.
• The http mode of the of-watchdog provides more control over your HTTP responses ("hot functions", persistent connection pools, or caching).

The of-watchdog http mode loads the handler as a small background web server. The classic watchdog's forking mode would instead load this file for every invocation creating additional latency when loading packages, saved data, or trained models.

Server framework (for of-watchdog only)

Frameworks are listed in the order of their dependence relationships:

• httpuv
  • plumber
  • fiery
  • beakr
  • ambiorix

More server frameworks are being explored, such as the Rserve based RestRserve, or the httpuv based opencpu. See ROADMAP for details. PRs are welcome!

Usage

Setup

It is recommended to read the OpenFaaS docs first and set up a local or remote Kubernetes cluster or faasd with OpenFaaS deployed. To get going quickly, follow the official OpenFaaS workshop, or enroll into the free Introduction to Serverless on Kubernetes course.

If you are looking for the smallest footprint (single node), the book Serverless For Everyone Else by Alex Ellis is highly recommended.

See recommended setup steps for the R template examples.

Make a new function

Use the faas-cli and pull R templates:

faas-cli template pull https://github.com/analythium/openfaas-rstats-templates

Now faas-cli new --list should give you a list with the available rstats-* templates.

Create a new function called hello-rstats:

export OPENFAAS_PREFIX="" # Populate with your Docker Hub username
faas-cli new --lang rstats-base hello-rstats --prefix=$OPENFAAS_PREFIX

the OPENFAAS_PREFIX means a user or organization on e.g. Docker Hub where you have push privileges; don't forget to log in to your registry using docker login.

Your folder now should contain the following:

hello-rstats/handler.R
hello-rstats/DESCRIPTION
hello-rstats.yml

The hello-rstats/handler.R file does the heavy lifting by executing the desired functionality. hello-rstats/DESCRIPTION lists the dependencies for the handler. The hello-rstats.yml is the stack file used to configure functions (read more here).

You can build, push, and deploy the hello-rstats function using:

faas-cli up -f hello-rstats.yml

faas-cli up is a shorthand for automating faas-cli build, faas-cli push, and faas-cli deploy.

Once the function is deployed, you can test it in the UI (e.g. at OPENFAAS_URL/ui/) or using curl:

curl $OPENFAAS_URL/function/hello-rstats -d '["World"]'

Both should give the JSON output "Hello World!".

Customize your function

You can now edit hello-rstats/handler.R to your liking. Don't forget to add dependencies to the hello-rstats/DESCRIPTION file.

See worked examples for different use cases. Read more about the structure of the templates if advanced tuning is required, e.g. by editing the Dockerfile, etc.

The template installs dependencies specified in the DESCRIPTION file in this order:

1. SystemRequirements: list OS specific system requirements here, comma separated, these are then installed by the OS's package manager,
2. CRAN packages listed in Depends:, Imports:, LinkingTo: fields are installed by remotes::install_deps(),
3. Remotes: fields are installed according to remotes specifications, make sure to list the package in Imports: as well, the location specified in Remotes: will be used to get the package from,
4. VersionedPackages: this field can be used to pin package versions using remotes::install_version(), do not list these packages in other fields (spaces after operators and after commas inside parentheses are important, e.g. devtools (1.11.0), mypackage (>= 1.12.0, < 1.14)).

You can also modify the Dockerfile in the template if specific R version or further customization is needed. The R parent image is defined as a Docker ARG called R_IMAGEthat you can override. I.e. use the versioned Rocker Debian image using custom build arguments:

faas-cli new --lang rstats-base-plumber hello-rstats-2 --prefix=$OPENFAAS_PREFIX

faas-cli build -f hello-rstats-2.yml --build-arg R_IMAGE=rocker/r-base:4.0.0

You can also edit the stack YAML file:

...
functions:
  hello-rstats-2:
    lang: rstats-base-plumber
...
    build_args:
      R_IMAGE: rocker/r-base:4.0.0

System requirements for the same package might be different across Linux distributions. This is a grey area of the R package ecosystem, see these links for help:

• rstudio/r-system-requirements
• r-hub/sysreqsdb
• r-universe/
• maketools to determine run-time and build-time dependencies

Contributing

Please read the code of conduct. DCO is required, sign commits that are submitted as PR (git commit -s -m "Commit message").

License

Copyright (c) 2020, Peter Solymos, Analythium Solutions Inc. MIT