Build functions

The OpenFaaS CLI supports various options for building a function.

For details and examples run

faas-cli build --help

• Build images with Docker

The faas-cli build command builds a Docker image into your local Docker library, which can then be used locally or pushed into a remote Docker registry. Each change of your function requires a new faas-cli build command to be issued.

• How to do CI/CD

When it comes to continuous integration and delivery you can use the faas-cli tool on your build server to build and deploy your code using the built-in commands.

• Generate a Dockerfile with --shrinkwrap

If you are using an alternative container image builder or are automating the faas-cli then you can use the --shrinkwrap flag which will produce a folder named ./build/function-name with a Dockerfile. This bundle can be used with any container builder.

Building multi-arch images for ARM and Raspberry Pi

If you’re Raspberry Pi or ARM servers to run your OpenFaaS on Kubernetes or with faasd server, then you will need to use the publish command instead which uses emulation and in some templates cross-compilation to build an ARM image from your PC.

It is important that you do not install Docker or any build tools on your faasd instance. faasd is a server to serve your functions, and should be treated as such.

The technique used for cross-compilation relies on Docker’s buildx extension and buildkit project. This is usually pre-configured with Docker Desktop, and Docker CE when installed on an Ubuntu system.

First install the QEMU utilities which allow for cross-compilation:

$ docker run --rm --privileged multiarch/qemu-user-static --reset -p yes

The faas-cli attempts to enable Docker’s experimental flag for the CLI, but you may need to run the following, if you get an error:

export DOCKER_CLI_EXPERIMENTAL=enabled

Now run this command on your laptop or workstation, not on the Raspberry Pi:

faas-cli publish -f stack.yml --platforms linux/arm/v7

If you’re running a 64-bit ARM OS like Ubuntu, then use:

faas-cli publish -f stack.yml --platforms linux/arm64

You can also add multiple platforms to publish an image which will run on an ARM device, and on a regular Intel host:

faas-cli publish -f stack.yml --platforms linux/arm/v7,linux/amd64

Then deploy the function:

faas-cli deploy -f stack.yml

1.0 Apply build options

The OpenFaaS CLI enables functions to be built with different options, e.g. dev, debug, etc.

By default all templates provide a minimal build as this optimizes function image sizes. Where appropriate, 3rd-party dependencies can be specified via requirements.txt. In scenarios where third-party dependencies also require native (e.g. C/C++) modules, like libssh in Ruby and numpy or pandas in Python, then --build-option can be used.

• How to use

The OpenFaaS CLI provides a --build-option flag which enables named sets of native modules to be specified for inclusion in the function build.

There are two ways to achieve this:

faas-cli build --lang python3 --build-option dev [--build-option debug]

or in YAML:

    build_options:
    - debug
    - dev

Where multiple functions are being built, the YAML configuration is recommended over use of the CLI flag, as the CLI flag applies the --build-option to all functions involved in the build activity.

Currently, of the official templates, Python and Ruby templates include named build options.

• Edit templates to support additional build options

It is possible to amend build options in both official and custom templates.

Altering of official templates should be carefully considered in the context of repeatable builds

In order to modify a template to support further build options, edit the template.yml using the following pattern:

build_options: 
  - name: dev
    packages: # A list of required packages
      - make
      - automake
      - gcc
      #- etc.
  - name: debug
    packages: 
      - mg
      - iw
      #- etc.

and if not already present edit Dockerfile with:

# Add the following line
ARG ADDITIONAL_PACKAGE 
# Edit `RUN apk --no-cache add curl \` to the following
RUN apk --no-cache add curl ${ADDITIONAL_PACKAGE} \

2.0 Pass ADDITIONAL_PACKAGE through --build-arg

There may be scenarios where a single native module need to be added to a build. A single-package build option could be added as described above. Alternatively a package could be specified through a --build-arg.

faas-cli build --lang python3 --build-arg ADDITIONAL_PACKAGE=jq

In the event a build-option is set the effect will be cumulative:

faas-cli build --lang python3 --build-option dev --build-arg ADDITIONAL_PACKAGE=jq

The entries in the template’s Dockerfile described in 1.0 above need to be present for this mode of operation.

3.0 Pass custom build arguments

You can pass ARG values to Docker via the CLI.

faas-cli build --build-arg ARGNAME1=argvalue1 --build-arg ARGNAME2=argvalue2

Remeber to add any ARG values to the template’s Dockerfile:

ARG ARGNAME1
ARG ARGNAME2

For more information about passing build arguments to Docker, please visit the Docker documentation

4.0 Building with large function sets

Performing a build action against a stack.yml which contains a large suite of serverless function definitions will result in each of the defined functions being built. The CLI makes available facilities that assist in this scenario.

The --parallel flag aims to reduce total build time by enabling more than one function build action to take place concurrently. Additionally, there may be situations where building all the defined functions is undesirable - for example where only one of the functions has had its code updated. In this instance the --filter and --regex flags can be used.

Consider a project with fn1, fn2, fn3, fn22, fn33 functions all defined within a single YAML file.

4.1 Using the --parallel flag

Parallel enables the user to specify how many concurrent function build actions should be performed. The default is that functions will be built serially, one after the other.

The following will see all the project functions’ build actions performed concurrently:

faas-cli build --parallel 5

Note

Remember to add -f if using a non-default yaml file: faas-cli build --parallel 5 -f projectfile.yml

Parallel can be combined with either of the --filter and --regex flags to parallel build a subset of the functions.

4.2 Using the --filter flag

Filter performs wildcard matching against function names in YAML file so that the build action will only be performed against those that match.

The following filter would build only fn2 from stack.yml:

faas-cli build --filter "fn2"

Wildcards can be added using *. The following will result in both fn2 and fn22 being built:

faas-cli build --filter "fn2*"

4.3 Using the --regex flag

Regex performs a similar action to --filter but allows for more complex patterns to be defined through regular expressions.

The following regex would result in fn1, fn2 & fn3 being built from the earlier project’s stack.yml:

faas-cli build --regex "fn[0-9]$"