faas Documentation

1. Project Overview & Quickstart (openfaas/faas)

File: README.md

OpenFaaS ® - Serverless Functions Made Simple

OpenFaaS® makes it easy for developers to deploy event-driven functions and microservices to Kubernetes without repetitive, boiler-plate coding. Package your code or an existing binary in an OCI-compatible image to get a highly scalable endpoint with auto-scaling and metrics.

"OpenFaaS Community Edition (CE) is licensed for individual exploration and hobbyist use. A 60 day limit applies for commercial PoCs. Commercial and production workloads require OpenFaaS Standard or OpenFaaS for Enterprises."

Highlights

Ease of use through UI portal and one-click install
Write services and functions in any language with Template Store or a Dockerfile
Build and ship your code in an OCI-compatible/Docker image
Portable: runs on existing hardware or public/private cloud by leveraging Kubernetes
CLI available with YAML format for templating and defining functions
Auto-scales as demand increases including to zero
Commercially supported Pro distribution by the team behind OpenFaaS

Want to dig deeper into OpenFaaS?

Trigger endpoints with either HTTP or events sources such as Apache Kafka and AWS SQS
Offload tasks to the built-in queuing and background processing
Quick-start your Kubernetes journey with GitOps from OpenFaaS Cloud
Go secure or go home with 5 must-know security tips
Learn everything you need to know to go to production
Integrate with Istio or Linkerd with Featured Tutorials
Deploy to Kubernetes or OpenShift

OpenFaaS Tiers and Pricing

This repository is part of OpenFaaS Community Edition (CE), which is licensed for non-commercial use by individuals, and a time-limited trial for commercial Proof Of Concepts (PoC). Internal use within a company or business requires a license.

OpenFaaS CE:

has usage restrictions, which you can learn about in the OpenFaaS CE EULA
has basic or primitive features and capabilities compared to the commercial versions
is not licensed for commercial use of any kind beyond an initial trial period

OpenFaaS Standard and OpenFaaS for Enterprises are full and distinct commercial products.

They are maintained and developed independently, by a full-time team, with commercial support, and active maintenance for CVEs, and updates in the Kubernetes and Cloud Native ecosystem.

Learn more about the tiers at https://www.openfaas.com/pricing/

Overview of OpenFaaS (Serverless Functions Made Simple)

Conceptual architecture and stack, more detail available in the docs

Code samples

You can scaffold a new function using the faas-cli new command passing in the name of the function and the language template you want to use i.e. faas-cli new --lang node20 stripe-webhooks.

Official templates exist for many popular languages and are easily extensible with Dockerfiles.

Learn about OpenFaaS templates in the docs

Node.js (node20) example:

"use strict"

module.exports = async (event, context) => {
    return context
        .status(200)
        .headers({"Content-Type": "text/html"})
        .succeed(`
        <h1>
            👋 Hello World 🌍
        </h1>`);
}

handler.js

Python 3 example (python3-http):

python

def handle(event, context):
    return {
        "statusCode": 200,
        "body": "Hello from OpenFaaS!"
    }

handler.py

Golang example (golang-middleware)

package function

import (
     "fmt"
     "io"
     "net/http"
)

func Handle(w http.ResponseWriter, r *http.Request) {
       var input []byte
    
       if r.Body != nil {
            defer r.Body.Close()
            body, _ := io.ReadAll(r.Body)
            input = body
       }
    
       w.WriteHeader(http.StatusOK)
       w.Write([]byte(fmt.Sprintf("Body: %s", string(input))))
}

Get started with OpenFaaS

Official training resources

View our official training materials

Official eBook and video workshop

The founder of OpenFaaS wrote Serverless For Everyone Else to help developers understand the use-case for functions through practical hands-on exercises using JavaScript and Node.js. No programming experience is required to try the exercises.

The examples use the faasd project, which is an easy to use and lightweight way to start learning about OpenFaaS and functions.

Check out Serverless For Everyone Else on Gumroad

OpenFaaS and Golang

Everyday Go is a practical, hands-on guide to writing CLIs, web pages, and microservices in Go. It also features a chapter dedicated to development and testing of functions using OpenFaaS and Go.

Everyday Golang

Community blog and documentation

Read the documentation: docs.openfaas.com
Read latest news and tutorials on the Official Blog

Quickstart

Here is a screenshot of the OpenFaaS Community Edition UI which was designed for ease of use. The inception function is being run which is available on the in the store.

Deploy OpenFaaS to Kubernetes, OpenShift, or faasd now with a deployment guide

OpenFaaS Standard and OpenFaaS for Enterprises have their own, brand new dashboard with multi-tenancy support, learn more about the OpenFaaS Dashboard.

Video presentations

Community events and blog posts

Have you written a blog about OpenFaaS? Do you have a speaking event? Send a Pull Request to the community page below.

Read blogs/articles and find events about OpenFaaS

Contributing

OpenFaaS Community Edition is written in Golang. All third-party contributions to the source code are made under the MIT license, additional restrictions apply to OpenFaaS CE as a whole, where contributions from OpenFaaS Ltd are licensed under the OpenFaaS CE EULA. Various types of contributions are welcomed whether that means providing feedback, testing existing and new feature or hacking on the source code.

How do I become a contributor?

Please see the guide on community & contributing

Dashboards

Example of a Grafana dashboard linked to OpenFaaS showing auto-scaling live in action: here

OpenFaaS Pro auto-scaling dashboard with Grafana

An alternative community dashboard is available here

Press / Branding / Website Sponsorship

OpenFaaS for commercial and internal use

OpenFaaS Pro (Standard and For Enterprises) is fully featured, supported, and built for production. The Community Edition (CE) is licensed for a 60-day Proof of Concept (PoC) and limited experimentation.

Learn more about OpenFaaS editions
Website Sponsorship 🌎

If you'd like to gain visibility by displaying your logon on the openfaas.com homepage, feel free to reach out via email or browse the tiers via GitHub Sponsors.
Press / Analysts

Looking at these repositories for commit counts and activity? All public repositories are part of OpenFaaS CE, a limited version of OpenFaaS aimed at giving people a low-barrier trial experience without having to sign up with a credit card. OpenFaaS CE is maintained on a best effort basis, but is not "OpenFaaS" itself. All OpenFaaS product development is done in private repositories, and cannot be tracked by third parties or by simply browsing GitHub.

How are GitHub Stars and Forks counted? OpenFaaS CE is not a mono-repo, you cannot simply look at one repository and say "ah that's the count" - statistics are gathered from the whole GitHub organisation.

Governance

OpenFaaS ® is an independent open-source project created by Alex Ellis, which is being built and shaped by a growing community of contributors.

OpenFaaS is hosted by OpenFaaS Ltd (registration: 11076587), a company which also offers commercial services, homepage sponsorships, and support. OpenFaaS ® is a registered trademark in England and Wales.

Users

View a selection of end-user companies who have given permission to have their logo listed at openfaas.com.

File: api-docs/README.md

Exploring or editing the Swagger API documentation

The spec.openapi.yml file can be viewed and edited in the Swagger UI.

Head over to the Swagger editor
Now click File -> Import URL
Type in https://raw.githubusercontent.com/openfaas/faas/master/api-docs/spec.openapi.yml and click OK

You can now view and edit the Swagger, copy back to your fork before pushing changes.

File: docs/README.md

OpenFaaS - Serverless Functions Made Simple for Docker & Kubernetes

Please see the official documentation site or our more detailed set of workshops on GitHub

File: gateway/README.md

Gateway

The API Gateway provides an external route into your functions and collects Cloud Native metrics through Prometheus. The gateway also has a UI built-in which can be used to deploy your own functions or functions from the OpenFaaS Function Store then invoke them.

The gateway will scale functions according to demand by altering the service replica count in the Kubernetes API. Custom alerts generated by AlertManager are received on the /system/alert endpoint.

In summary:

Built-in UI Portal
Deploy functions from the Function Store or deploy your own
Instrumentation via Prometheus
Auto-scaling via AlertManager and Prometheus
Scaling up from zero
REST API available documented with Swagger

Pictured: conceptual architecture when Kubernetes is used as the orchestration provider

Function Providers

Providers for functions can be written using the faas-provider interface in Golang which provides the REST API for interacting with the gateway.

REST API

Swagger docs: https://github.com/openfaas/faas/tree/master/api-docs

CORS

By default the only CORS path allowed is for the Function Store which is served from the GitHub RAW CDN.

UI Portal

The built-in UI Portal is served through static files bound at the /ui/ path.

The UI was written in Angular 1.x and makes uses of jQuery for interactions and the Angular Material theme for visual effects and components.

View the source in the assets folder.

Function Store

The Function Store is rendered through a static JSON file served by the GitHub RAW CDN. The Function Store can also be used via the OpenFaaS CLI.

See the openfaas/store repo for more.

Logs

Logs are available at the function level via the API.

You can also install a Docker logging driver to aggregate your logs. By default functions will not write the request and response bodies to stdout. You can toggle this behaviour by setting read_debug for the request and write_debug for the response.

Tracing

An "X-Call-Id" header is applied to every incoming call through the gateway and is usable for tracing and monitoring calls. We use a UUID for this string.

Header:

text

X-Call-Id

Within a function this is available as Http_X_Call_Id.

Environmental overrides

The gateway can be configured through the following environment variables:

Option	Usage
`write_timeout`	HTTP timeout for writing a response body from your function (in seconds). Default: `8`
`read_timeout`	HTTP timeout for reading the payload from the client caller (in seconds). Default: `8`
`functions_provider_url`	URL of upstream functions provider - i.e. Swarm, Kubernetes, Nomad etc
`logs_provider_url`	URL of the upstream function logs api provider, optional, when empty the `functions_provider_url` is used
`faas_nats_address`	The host at which NATS Streaming can be reached. Required for asynchronous mode
`faas_nats_port`	The port at which NATS Streaming can be reached. Required for asynchronous mode
`faas_nats_cluster_name`	The name of the target NATS Streaming cluster. Defaults to `faas-cluster` for backwards-compatibility
`faas_nats_channel`	The name of the NATS Streaming channel to use. Defaults to `faas-request` for backwards-compatibility
`faas_prometheus_host`	Host to connect to Prometheus. Default: `"prometheus"`
`faas_prometheus_port`	Port to connect to Prometheus. Default: `9090`
`direct_functions`	`true` or `false` - functions are invoked directly over overlay network by DNS name without passing through the provider
`direct_functions_suffix`	Provide a DNS suffix for invoking functions directly over overlay network
`basic_auth`	Set to `true` or `false` to enable embedded basic auth on the /system and /ui endpoints (recommended)
`secret_mount_path`	Set a location where you have mounted `basic-auth-user` and `basic-auth-password`, default: `/run/secrets/`.
`scale_from_zero`	Enables an intercepting proxy which will scale any function from 0 replicas to the desired amount

File: sample-functions/README.md

OpenFaaS samples

This folder used to contain legacy function samples written in 2016. As you can imagine, OpenFaaS has developed significantly since then.

Language specific guides from the blog:

Official Training and eBooks:

Official Function store images:

Function Store functions

Need help? Reach out to us at openfaas.com/support

2. Official Technical Reference & Guides (openfaas/docs)

File: README.md

OpenFaaS docs repository

This is the source repository for the OpenFaaS documentation site.

For local development

shell

mkdocs serve

Or:

shell

docker run --rm -it -p 8000:8000 -v `pwd`:/docs squidfunk/mkdocs-material:latest

Published page

This page is published through the use of mkdocs and is hosted on https://netlify.com/ with a TLS cert from LetsEncrypt.

https://docs.openfaas.com/

All commits into master (or merged PRs) will appear on the front-page after being rebuilt.

mkdocs-material markdown extensions

There are several markdown extensions that can be used to create special formatting. Look at the docs here for all available extensions.

Adding OpenFaaS Users

The list of OpenFaaS users can be found within docs/index.md. Additions to this list should be made while maintaining the alphabetical ordering.

File: diagrams/README.md

Source diagrams

These diagrams are in the original vector or binary format such as Gliffy.

gliffy is a Chrome extension for building technical diagrams.

File: docs/cli/build.md

Build functions

The OpenFaaS CLI supports various options for building a function.

For details and examples run

bash

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.

Build-time secrets

When using Docker's BuildKit to build your containers, faas-cli can mount secrets into the build process using Docker's --secret flag. This prevents sensitive values from leaking into the final image, which can happen when using --build-arg.

For Go users, make use of vendoring. It's what we use and it means you do not have to resort to insecure practices like sharing Personal Access Tokens (PAT) between users.

Below we have an example for Python using the pip package manager and for node modules with npm. The approach is similar for different package managers.

Create a local file containing the secret value
Add a build_secrets entry in stack.yml pointing to the file path
Use RUN --mount=type=secret in the Dockerfile to access the secret at build time
Run faas-cli build or faas-cli publish

Private access to a Python pip repository

Download the OpenFaaS Pro template using your customer credentials:

bash

faas-cli template pull https://github.com/openfaas/customers

faas-cli new --list
Languages available as templates:
- [email protected]

Create a new function from the template:

bash

export OPENFAAS_PREFIX=docker.io/alexellis2

faas-cli new --lang [email protected] \
  withprivate

Next, set up a build secret, for instance to fetch Pip modules from a private PyPi repository:

yaml

provider:
  name: openfaas
  gateway: http://127.0.0.1:8080

functions:
  withprivate:
    lang: python3-http
    handler: ./withprivate
    image: openfaasltd/withprivate:0.0.1
    build_secrets:
      pipconf: ${HOME}/.config/pip/pip.conf

Set up the private authentication for pip.conf:

ini

[global]
index-url = https://aws:CODEARTIFACT_TOKEN@OWNER-DOMAIN.d.codeartifact.us-east-1.amazonaws.com/pypi/REPOSITORY/simple/

Then run a build with:

bash

faas-cli build

The faas-cli publish command can also be used instead of faas-cli build.

If you're cloning from a private Git repository, without using a private PyPi repository, then you can use the .netrc approach instead:

.netrc:

text

machine github.com
login username
password PAT

Then update stack.yml:

yaml

functions:
  withprivate:
..
    build_secrets:
      netrc: ${HOME}/.netrc

Bear in mind that at this time, GITHUB_TOKEN in a GitHub Action cannot be used to clone other repositories, even within the same organisation.

Private npm modules

Create a function:

bash

export OPENFAAS_PREFIX=openfaasltd
faas-cli template store pull node22
faas-cli new --lang node22 withprivatenpm

You will need to create an authentication token to install private npm modules. These instructions will differ depending on the registry you want to use:

For the npmjs registry you can generate a token using the npm cli, see: Create a new access token.
For Github Packages, see: Authenticating to GitHub Packages

Once you have an authentication token you can add a registry user account with the npm login command:

bash

npm login --scope=@OWNER --registry=https://npm.pkg.github.com

> Username: USERNAME
> Password: TOKEN
> Email: PUBLIC-EMAIL-ADDRESS

Or edit your ~/.npmrc file to include the authentication token for your npm registry.

text

//registry.npmjs.org/:_authToken=TOKEN

Add the .npmrc file as a build secret to the stack.yml file:

yaml

version: 1.0
provider:
  name: openfaas
  gateway: http://127.0.0.1:8080
functions:
  withprivatenpm:
    lang: node22
    handler: ./withprivatenpm
    image: openfaasltd/withprivatenpm:latest
    build_secrets:
      npmrc: ${HOME}/.npmrc

Run a build with:

bash

faas-cli build -f stack.yml

Update template/node22/Dockerfile and replace the second npm i command to mount the secret:

dockerfile

RUN --mount=type=secret,id=npmrc,mode=0666,dst=/home/app/.npmrc npm i

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:

bash

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

or in YAML:

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:

yaml

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:

dockerfile

# 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 needs 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.

bash

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

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

bash

faas-cli build --lang python3-http --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.

bash

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

Remember to add any ARG values to the template's Dockerfile:

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:

bash

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:

bash

faas-cli build --filter "fn2"

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

bash

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:

bash

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

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:

bash

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

Or if you're an arkade user, run arkade install qemu-static.

In addition, for CI, you can also add the --reset-qemu flag to faas-cli publish.

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:

text

export DOCKER_CLI_EXPERIMENTAL=enabled

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

bash

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

If you're running a 64-bit ARM OS like Ubuntu on an AWS Graviton or Raspberry Pi 4, then use:

bash

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:

bash

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

Then deploy the function:

bash

faas-cli deploy -f stack.yml

File: docs/cli/completion.md

Shell Completion

The OpenFaas CLI has a shell completion feature for Bash and ZSH.

Bash for Linux

Bash for Linux requires bash-completion, please follow their installation here.

Verify if it was installed correctly by executing the following command type _init_completion.

You can enable OpenFaaS completion with two different commands:

bash

$ echo 'source <(faas-cli completion --shell bash)' >>~/.bashrc

Or:

bash

$ faas-cli completion --shell bash > /etc/bash_completion.d/faas-cli

Bash for MacOS

By default MacOS comes with Bash 3.2, but the completion requires version 4.1+. See this instructions to upgrade.

Also, you'll need bash-completion v2. Install with the following commands:

bash

$ brew install bash-completion@2

And add the following to your ~/.bashrc file:

bash

export BASH_COMPLETION_COMPAT_DIR="/usr/local/etc/bash_completion.d"
[[ -r "/usr/local/etc/profile.d/bash_completion.sh" ]] && . "/usr/local/etc/profile.d/bash_completion.sh"

You can enable OpenFaaS completion with two different commands:

bash

$ echo 'source <(faas-cli completion --shell bash)' >>~/.bashrc

Or:

bash

$ faas-cli completion --shell bash > /etc/bash_completion.d/faas-cli

ZSH

ZSH completion is simpler, just execute the following command:

bash

source <(faas-cli completion --shell zsh)

File: docs/cli/install.md

Installation

We recommend installing faas-cli through arkade, for the quickest and easiest installation.

There is also a bash script for downloading the binary, and support for brew.

Installation with arkade

Install arkade:

bash

curl -sSL https://get.arkade.dev | sudo -E sh

Install faas-cli:

bash

arkade get faas-cli

You can update faas-cli at any time by running the above command again.

arkade can also be used to download around 120 different DevOps and Kubernetes tools, find out more in the arkade README

Installation with Bash

For Linux or macOS users, the following script can be used:

bash

curl -sSL https://cli.openfaas.com | sudo -E sh

The flag -E allows for any http_proxy environmental variables to be passed through to the installation bash script.

Non-root with curl downloads the binary into your current directory and will then print installation instructions:

bash

curl -sSL https://cli.openfaas.com | sh

Via brew:

bash

brew install faas-cli

!!! note
The version of faas-cli installed by brew is likely to lag behind a little, so we recommend using arkade instead.

Windows

In PowerShell:

powershell

$version = (Invoke-WebRequest "https://api.github.com/repos/openfaas/faas-cli/releases/latest" | ConvertFrom-Json)[0].tag_name
(New-Object System.Net.WebClient).DownloadFile("https://github.com/openfaas/faas-cli/releases/download/$version/faas-cli.exe", "faas-cli.exe")

Pro plugin

The OpenFaaS Pro CLI plugin provides additional features for the faas-cli including SSO and OIDC authentication.

Note: The pro plugin is available for OpenFaaS Standard & For Enterprises customers and requires activation.

Download the pro plugin:

bash

faas-cli plugin get pro

Activate with a static license

If you have a static JWT license for the CLI, you can enable the plugin without any interactive steps. This is the recommended approach for CI/CD pipelines and air-gapped environments.

Save the license to the default location. Run the following, then paste in your license, hit enter once, then Control + D to save the file.

bash

mkdir -p ~/.openfaas
cat > ~/.openfaas/LICENSE_CLI

Once the license is in place, the plugin is enabled automatically and no additional flags or environment variables are needed.

The license can also be provided through alternative sources. They are resolved in the following priority order:

--license flag — literal JWT string
--license-file flag — path to a file containing the JWT
OPENFAAS_LICENSE environment variable
Default file at $HOME/.openfaas/LICENSE_CLI

Contact the OpenFaaS team to obtain a static license for the CLI.

Activate with GitHub

For customers who have a GitHub organisation, you will need to send the OpenFaaS team an email with the name of the organisation, and make sure you can log into your account.

bash

faas-cli pro enable

A browser will open with a device challenge, once completed, the CLI will be enabled.

!!! note "Does your team not have a GitHub organisation available?"

text

If your organisation does not use GitHub, or you are not a member of its GitHub organisation, you can use a [static license](#activate-with-a-static-license) instead.

Environment variable overrides

Several overrides exist which will be used by default if set and no other command-line flag has been set.

OPENFAAS_TEMPLATE_URL - to set the default URL to pull templates from
OPENFAAS_PREFIX - for use with faas-cli new - this can act in place of --prefix
OPENFAAS_URL - to override the default gateway URL

Running `faas-cli` with sudo

If you're running the faas-cli with sudo we recommend using sudo -E to pass through any environmental variables you may have configured such as a http_proxy, https_proxy or no_proxy entry.

Running `faas-cli` with docker

The faas-cli is also available as a Docker image making it convenient for use in CI jobs such as with a Jenkins pipeline or a task in cron.

There is no "latest" tag, so find the version of the CLI you want to use from the tags page on the Docker Hub. These correspond to the release from GitHub.

Note: the Docker image cannot be used to perform a build directly, but you can use it to generate a build context which can be used with a container builder such as the OpenFaaS Pro Function Builder API, Docker, buildkit or Kaniko in another part of your build pipeline.

Use-cases for the Docker image:

Generate the build context without running docker with the faas-cli build --shrinkwrap command
Deploy an existing image to a remote server faas-cli deploy
Manage secrets with faas-cli secret
Invoke functions via cron with faas-cli invoke
Check the health of your remote gateway with faas-cli info

Building from source

The contributing guide has instructions for building from source and for configuring a Golang development environment.

Star/fork on GitHub: faas-cli

Tutorial

5 tips and tricks for the OpenFaaS CLI by Alex Ellis

File: docs/cli/logs.md

Function Logs

Via an extensible API, OpenFaaS Provides access to function logs via the Gateway API and the CLI. This provides a simple and consistent way to access function logs regardless of your orchestration provider.

The log provider for Kubernetes faas-netes fetches records directly from the Kubernetes API, so it will give similar output to kubectl logs -n openfaas-fn deploy/function.

The faas-cli logs NAME command will stream the logs for the named function. By default, it will attempt to follow the logs, but you can control the behavior of the stream using these flags

-g, --gateway string           Gateway URL starting with http(s):// (default "http://127.0.0.1:8080")
  -h, --help                     help for logs
      --instance                 print the function instance name/id
      --lines int                number of recent log lines file to display. Defaults to -1, unlimited if <=0 (default -1)
      --name                     print the function name
  -n, --namespace string         Namespace of the function
  -o, --output logformat         output logs as (plain|keyvalue|json), JSON includes all available keys
      --since duration           return logs newer than a relative duration like 5s
      --since-time timestamp     include logs since the given timestamp (RFC3339)
  -t, --tail                     tail logs and continue printing new logs until the end of the request, up to 30s (default true)
      --time-format timeformat   string format for the timestamp, any value go time format string is allowed, empty will not print the timestamp (default 2006-01-02T15:04:05Z07:00)

Log structure

The logs for a function will look

text

<RFC8601 Timestamp> <function name> (<container instance>) <msg>

where msg is the container logs, this typically contains stdout and stderr of the container.

An example log output for nodeinfo from the function store is

2019-07-21 07:57:14.437219758 +0000 UTC nodeinfo (nodeinfo-867cc95845-p9882) 2019/07/21 07:57:14 Wrote 92 Bytes - Duration: 0.121959 seconds

You can also get logs in JSON format:

bash

$ faas-cli logs trove --format json

{"name":"trove","namespace":"openfaas-fn","instance":"9174","timestamp":"2021-02-12T17:01:03.088068Z","text":"User requested \"Insiders Update: 1st Feb 2020 - Java, KubeCon, Istio, Crossplane and more!\""}

Filter and Search

The CLI writes logs to stdout, so it can easily be chained with any of your favorite CLI tools: grep, sed, fzf etc.

For example, when you set the write_debug environment variable in the Sentiment Analysis function from the Store, it will print the function output to the logs, we can then search that output using grep. For example,

faas-cli store deploy SentimentAnalysis --env write_debug=true
echo "i like code" | faas-cli invoke sentimentanalysis
echo "i like functions" | faas-cli invoke sentimentanalysis
echo "i like containers" | faas-cli invoke sentimentanalysis

faas-cli logs sentimentanalysis | grep sentence_count
2019-07-22 12:44:08.202436478 +0000 UTC sentimentanalysis (sentimentanalysis-7887c5d8c5-5rnb5) {"polarity": 0.0, "sentence_count": 1, "subjectivity": 0.0}
2019-07-22 12:44:10.11422064 +0000 UTC sentimentanalysis (sentimentanalysis-7887c5d8c5-5rnb5) {"polarity": 0.0, "sentence_count": 1, "subjectivity": 0.0}
2019-07-22 12:44:11.882708263 +0000 UTC sentimentanalysis (sentimentanalysis-7887c5d8c5-5rnb5) {"polarity": 0.0, "sentence_count": 1, "subjectivity": 0.0}

Log Retention and History

Log retention and history will be determined by your cluster configuration and the log provider installed. The default configuration in the function provider for Kubernetes streams logs directly from the cluster. This means that you will only see logs from running function containers, and no long term history is not available. If you delete a function, you remove access to its logs.

With faasd, logs are stored in the journal, so the retention period lasts beyond the life of a function, however it may be limited by time or the number of lines.

If you want to retain logs over time, consider using a log aggregator like Elastic Search, Logz.io or Humio as an external data-store.

Grafana Loki can also provide fast access to logs without much additional overhead on the cluster. A log provider exists to enable "faas-cli" and the OpenFaaS API to query an external data-store, instead of Kubernetes itself.

Alternative Log Providers

The log system is designed to be extended with alternative providers, this means that logs could instead be supplied by a persistent storage, e.g. Loki or ElasticSearch. See the logs provider overview for more details about how providers work and available alternatives.

Structured Logs

Structured logs are a form of machine-readable logs that treats logs as data sets rather than text which allows logs to be more easily searched and analyzed. Typically, these will be in the form of a JSON object on a single line and will allow you to achieve a high level of granular detail.

Introduced in of-watchdog v0.8.2, you can set the prefix_logs environment variable to false. This will remove the log prefix for all messages received via stdout/stderr, meaning that only the <msg> will be sent to the terminal.

File: docs/cli/secrets.md

Manage secrets

The OpenFaaS CLI allows you to create, update, list and delete secrets using faas-cli instead of Docker or Kubernetes command line tools.

The reason behind this is to give you simplicity when you need to use secrets for your functions as well as to provide a layer of abstraction, as it will work for both Kubernetes and faasd.

Create

To create a secret from stdin, you can run:

bash

faas-cli secret create secret-name

Or pipe the value from a file instead:

text

cat 04385e5c413c10ed68afb010ebe8c5dd706aa20a | faas-cli secret create secret-name
cat ~/Downloads/derek.pem | faas-cli secret create secret-name

If you want to pass a value then do:

bash

faas-cli secret create secret-name \
  --from-literal="04385e5c413c10ed68afb010ebe8c5dd706aa20a"

To create it from file use:

bash

faas-cli secret create secret-name \
  --from-file=~/Downloads/derek.pem

Target a specific namespace:

bash

faas-cli secret create \ 
  --namespace staging-fn \
  secret-name \
  --from-literal="04385e5c413c10ed68afb010ebe8c5dd706aa20a"

Note: you will need to follow the instructions for multiple namespaces for the above command.

You can pass --gateway flag if you'd like to create the secret for a specific OpenFaaS instance.

See also: faas-cli secret create --help

Update

From stdin:

text

faas-cli secret update secret-name

text

cat 04385e5c413c10ed68afb010ebe8c5dd706aa20a | faas-cli secret update secret-name
cat ~/Downloads/derek.pem | faas-cli secret update secret-name

From literal:

text

faas-cli secret update secret-name --from-literal="04385e5c413c10ed68afb010ebe8c5dd706aa20a"

From file:

text

faas-cli secret update secret-name --from-file=~/Downloads/derek.pem

See also: faas-cli secret update --help

List

To list secrets in the default namespace:

bash

faas-cli secret list
faas-cli secret ls

To list secrets in an alternative namespace:

bash

faas-cli secret ls --namespace staging

To list secrets for an OpenFaaS instance use:

bash

faas-cli secret ls --gateway http://127.0.0.1:8080

If you have set $OPENFAAS_URL you can use only

bash

faas-cli secret ls

This will output:

bash

NAME
secret-name1
secret-name2
...

Delete

You can delete secrets with:

bash

faas-cli secret remove secret-name

bash

faas-cli secret remove secret-name \
  --gateway=http://127.0.0.1:8080

See also: faas-cli secret delete --help

File: docs/cli/tags.md

Working with image tags

All OpenFaaS functions are built into immutable Docker images before deployment. You can take advantage of Docker "tags" to organise your versions the CLI can also generate tags based upon Git metadata.

Option 1 - YAML file

You can define your tag in the stack YAML file. By default this tag is ":latest"

text

image: my-fn

text

image: my-fn:latest

Option 2 - `--tag` option

The --tag option works with the faas-cli sub-commands: build, push and deploy.

When using a --tag feature which relies on metadata from a Git commit then the build, push and deploy commands must be run pointing at the same Git commit.

Example usage:

text

faas-cli build --tag=sha|branch|describe
faas-cli push --tag=sha|branch|describe
faas-cli deploy --tag=sha|branch|describe

There are currently three formats for "automatic tags".

2.1 Use the SHA (`--tag=sha`)

In this example whatever tag is defined in your YAML file (or latest, if not is given) will be suffixed with "-" plus the short Git SHA. A Git repository will be required to use this feature.

Example:

text

image: my-fn:0.2

image: my-other-fn

Gives the equivalent:

text

image: my-fn:0.2-cf59cfc

image: my-other-fn:latest-cf59cfc

2.2 Use the SHA plus the branch (`--tag=branch`)

In this example you will get an output which includes the SHA and the branch name. This is useful for promotion code through environments with a continuous delivery tool. If you use one branch per environment in Git then the tool can parse the tag and match it to an environment.

Example:

(on the master branch)

text

image: my-fn:0.2

image: my-fn:latest

Gives the equivalent:

text

image: my-fn:0.2-master-cf59cfc

image: my-fn:latest-master-cf59cfc

(on the staging branch)

text

image: my-fn:0.2-staging-cf59cfc

image: my-fn:latest-staging-cf59cfc

2.3 Use the output of `git describe` (`--tag=describe`)

In this example you will get the output of git describe --tags --always. This returns a human readable name based on an available git ref. Using --tags, means that the output which can be read as <most-recent-parent-tag>-<number-of-commits-to-that-tag>-g<short-sha>. Using --always, means that if the repo does not use tags, then we will still get the short SHA as output, matching --tag=sha

Example:

If you set the image name as

text

image: my-fn:0.2

image: my-fn:latest

Then, if you have no tags in the repo, faas-cli produces the equivalent:

text

image: my-fn:0.2-b0da13a

image: my-fn:latest-cfb0da13a59cfc

If you have just tagged the current commit in the repo, then faas-cli produces the equivalent:

text

image: my-fn:0.2-v0.1.0

image: my-fn:latest-v0.1.0

Note that the middle value, <number-of-commits-to-that-tag> is omitted when it is 0, that is, when you build that tag.

If there have been several commits (e.g. 3) since the most recent tag, then faas-cli produces the equivalent:

text

image: my-fn:0.2-v0.1.0-1-gb0da13a

image: my-fn:latest-v0.1.0-3-gb0da13a

A word of caution, this can only reference the tags that your local repository knows of, make sure to run git fetch --tags to ensure that you have a copy of all remote tags.

File: docs/cli/templates.md

Create new functions

Get started

Once you've installed the faas-cli you can start creating and deploying functions via the faas-cli up command or using the individual commands:

faas-cli build - build an image into the local Docker library
faas-cli push - push that image to a remote container registry
faas-cli deploy - deploy your function into a cluster

The faas-cli up command automates all of the above in a single command.

For Raspberry Pi and Arm, you must use the publish command instead of build and push, or up.

See the notes here: Building multi-arch images for Arm and Raspberry Pi

!!! info "Information about OpenFaaS templates is moving"

text

The guide for OpenFaaS templates is moving to the ["Languages" section"](/languages/overview.md) in its own section.

Templates

The OpenFaaS CLI (faas-cli) has a template engine built-in which can create new functions in a given programming language. The way this works is by reading a list of templates from the ./template location in your current working folder.

In the past, a default templates repository contained all templates for OpenFaaS, but now they're distributed across a number of different Git repositories.

If the language you want to use is listed in the template store (faas-cli template store list), then it will be fetched automatically whenever you run faas-cli new or faas-cli build.

To create a Python function called hello-python using the python3-http template, you would run:

bash

$ faas-cli new --lang python3-http hello-python

Since this function is listed in the Templates Store, it will be downloaded automatically for you.

If you need to get a custom, or modified template from a different Git repository, you can use the faas-cli template pull command first.

The below is an example of a fictitious Rust Tokio template being pulled from GitHub and then used to create a new function:

bash

$ faas-cli template pull https://github.com/alexellis/rust-tokio-template

$ faas-cli new --lang rust-tokio-template

Version pinning

Version pinning is supported for templates as of faas-cli version 0.18.0.

You can specify the version of a template in three ways:

Latest - no pinning, always get the latest version golang-middleware - this always pulls from the default branch, using its latest commit
Git tag or branch - specify a tag after an @ symbol [email protected] or golang-middleware@debian
Commit SHA - specify a full commit SHA after an @ symbol golang-middleware@sha-4d0f102baedd9f4d618dac34ff419292e2f91578 (short SHAs are also supported i.e. golang-middleware@sha-4d0f102)

These versions can be specified when running faas-cli new, or directly in stack.yaml if the function already exists.

Here's how you'd pin an existing function to a specific version in stack.yaml:

yaml

functions:
  my-function:
-   lang: golang-middleware
+   lang: [email protected]
    handler: ./my-function
    image: my-function:latest

Authentication for private repositories

The template pull command uses your local Git client, so if you have proper authentication set up with a Git credential helper, then you'll also be able to run it against private repositories.

For GitHub specifically, we recommend:

ini

[url "ssh://[email protected]/"]
        insteadOf = https://github.com/

[credential "https://github.com"]
        helper = 
        helper = !/usr/local/bin/gh auth git-credential

This page shows how to generate functions in the most popular languages and explains how you can manage their dependencies too.

Classic vs. of-watchdog templates

The Classic Templates are held in the openfaas/templates repository and are based upon the Classic Watchdog which uses STDIO to communicate with your function. The of-watchdog uses HTTP to communicate with functions and most of its templates are available in the openfaas organisation in their own separate repositories on GitHub and in the store.

How to pick:

Use the Classic Watchdog if you're starting out or following tutorials or guides
Use the of-watchdog if you need more performance or if you need full control of the HTTP response

Template store

You can browse templates from the official store or create your own store and add your own templates there.

To see what templates are available type faas-cli template store list and you should see the following in the terminal:

$ faas-cli template store list

NAME                     RECOMMENDED DESCRIPTION        SOURCE
bash-streaming           [x]         openfaas-incubator Bash Streaming template
dockerfile               [x]         openfaas           Classic Dockerfile template
dotnet8-csharp           [x]         openfaas           C# template using WebApplication
golang-middleware        [x]         openfaas           HTTP middleware interface in Go
java11-vert-x            [x]         openfaas           Java 11 Vert.x template
node22                   [x]         openfaas           HTTP-based Node 22 template
php8                     [x]         openfaas           Classic PHP 8 template
python3-http             [x]         openfaas           Python 3 with Flask and HTTP
python3-http-debian      [x]         openfaas           Python 3 with Flask and HTTP based on Debian
ruby-http                [x]         openfaas           Ruby 2.4 HTTP template

Choose a template and retrieve it locally with the command:

$ faas-cli template store pull python3-http

Once downloaded, your chosen template and any others stored in the same repository will be available to use:

$ faas-cli new --list
Languages available as templates:
- python3-http

You can create your own template store by following the convention found in the official templates store repository, then provide the --url flag when pulling or listing templates. If you're using GitHub, you'll need to reference the raw file rather than the view in a webbrowser.

For instance:

bash

faas-cli template store pull --url https://raw.githubusercontent.com/openfaas/store/refs/heads/master/templates.json

This is the format for the file:

json

[
    {
        "template": "golang-middleware",
        "platform": "x86_64",
        "language": "Go",
        "source": "openfaas",
        "description": "HTTP middleware interface in Go",
        "repo": "https://github.com/openfaas/golang-http-template"
    }
]

As an alternative to repeating the --url flag on each command, you can also set the OPENFAAS_TEMPLATE_STORE_URL environment variable in your .zshrc or .bashrc file.

For instance, you could add these lines to override installations to use your company or team repository:

bash

export OPENFAAS_TEMPLATE_STORE_URL=https://raw.githubusercontent.com/openfaas/store/refs/heads/master/functions.json

The classic templates are held in the openfaas/templates repository.

Java

Two Java templates are provided java11 and java11-vertx, both of which use Gradle as the build system. Please note that the java8 template is deprecated, and should not be used.

If you need a different version, then please fork the templates repository, or contact [email protected] to access additional templates via your OpenFaaS Premium Subscription.

Support is made available for external code repositories via the build.gradle file where you specify dependencies to fetch from repositories or JAR files to be added via the build.

Write a function java-function:

text

$ faas-cli new --lang java11 java-function

Write your code in:

./src/main/Handler.java

Write junit tests in:

./src/tests/

Update gradle config if needed in:

./build.gradle
./settings.gradle

Working with headers (advanced)

You can view the code for the IRequest and IResponse in the OpenFaaS templates-sdk

You can use getHeader(k) on the Request interface to query a header.

To set a header such as content-type you can use setHeader(k, v) on the Response interface.

You can also run the following to create a function using Vert.x

bash

$ faas-cli new --lang java11-vertx java-vertx-function

Bash

Alex Ellis maintains a template for writing functions with Bash:

alexellis/openfaas-streaming-templates

CSharp / .NET Core

Puppeteer

Alex Ellis maintains a Node.js and Puppeteer template for generating screenshots of web-pages and for UI testing.

See: puppeteer template

Rust

Two community-maintained templates are available for Rust users, one which is forking and another which is more high performance, using a HTTP server.

Ruby

Create a function called ruby-function:

text

$ faas-cli new --lang ruby ruby-function

The directory structure is:

text

├── ruby-function
│   ├── Gemfile
│   └── handler.rb
├── ruby-function.yml

Your code should be in the handler.rb file

Ruby: Adding a Gem (Library)

Open the Gemfile in the ruby-function directory

Add the following line

gemfile

gem 'httparty'

Ruby: Using our own Gem

Replace your handler.rb code with the following

ruby

require 'httparty'

class Handler
    def run(req)
        return HTTParty.get("http://api.stackexchange.com/2.2/questions?site=stackoverflow&tagged=#{req}")
    end
end

Ruby: Building / Deploy / Run

Edit the ruby-function.yml and point your image to your dockerhub, for example
${your_user}/ruby-function

text

$ faas-cli up -f ruby-function.yml
...
Using bundler 1.16.4
Fetching multi_xml 0.6.0
Installing multi_xml 0.6.0
Fetching httparty 0.16.2
Installing httparty 0.16.2
Bundle complete! 1 Gemfile dependency, 3 gems now installed.
Bundled gems are installed into `/usr/local/bundle`
Post-install message from httparty:
When you HTTParty, you must party hard!
...

Now you can invoke the function:

$ echo 'OpenFaaS' | faas-cli invoke ruby-function
{
   "quota_remaining" : 298,
   "quota_max" : 300,
   "has_more" : false,
   "items" : [
      {
         "title" : "Scaling with GPU usage",
         "creation_date" : 1536315498,
         "answer_count" : 0,
         "view_count" : 10,
         "is_answered" : false,
...

Ruby HTTP

As an alternative to the ruby template, which uses the classic watchdog, we have an alternative where you can set HTTP response headers.

text

faas-cli template store pull ruby-http

faas-cli new --lang ruby-http k8s-get-pods

To add support for native dependencies such as kubeclient, you need to add the dev package to the build_options:

yaml

version: 1.0
provider:
  name: openfaas
  gateway: http://127.0.0.1:8080
functions:
  k8s-get-pods:
    lang: ruby-http
    handler: ./k8s-get-pods
    image: k8s-get-pods:latest
    build_options:
    - dev

Then update your Gemfile:

text

source 'https://rubygems.org'

gem "kubeclient"

text

faas-cli build -f k8s-get-pods.yml

PHP

How to Customise a template

It is recommended that you use the official templates as they are provided and if there is a short-coming that you raise a GitHub issue so we can improve the templates for everyone.

All templates are driven by a Dockerfile and can be customised by editing the files found in the ./template folder.

Update the Dockerfile

There are several reasons why you may want to update your Dockerfile, just edit ./template/<language_name>/Dockerfile.

New base image - some companies prefer to use their own base images for Docker images for compliance, support or licensing reasons
Add native package - sometimes you may want to add a native package from the Alpine Linux repository or the Debian package repository - just add a step into the Dockerfile
Try a new version of a base-image - it may be that the project is showing support for Node.js LTS, but you want the cutting-edge version, you can do that too

Update a template's configuration

The name of a template is read from a "template.yml" file kept within the template folder: ./template/<language_name>/template.yml

For csharp we have the following:

text

language: csharp
fprocess: dotnet ./root.dll

language is the display name used for faas-cli new --list.
fprocess provides the process to run for each invocation - i.e. your function

Use your own templates

You can use your own Git repository for a custom or forked set of templates. This can be public or private.

See faas-cli template pull for more information.

If you want to set up your own default template location, specify the OPENFAAS_TEMPLATE_URL environmental variable the following way:

bash

export OPENFAAS_TEMPLATE_URL=https://raw.githubusercontent.com/user/mytemplate/customtemplates

Download templates from the template store

Note: In order to access the template store you need 0.8.1 version of the CLI or higher

Check what templates are available in the template store with the CLI by typing:

bash

faas-cli template store list

Pull the desired template by specifying NAME attribute only:

bash

faas-cli template store pull go

or pull the template by mixing the REPOSITORY and NAME attributes the following way:

bash

faas-cli template store pull openfaas/go

To get more information on specific store use the describe verb like:

bash

faas-cli template store describe openfaas/go

or if there is no collision between names use only the name field:

bash

faas-cli template store describe go

If you have your own store with templates, you can set that as your default official store by setting the environmental variable OPENFAAS_TEMPLATE_STORE_URL the following way:

bash

export OPENFAAS_TEMPLATE_STORE_URL=https://raw.githubusercontent.com/user/openfaas-templates/templates.json

Now the source of the store is changed to the URL you have specified above.

Arm / Raspberry Pi

It is possible to migrate to use multi-arch templates with OpenFaaS, feel free to ask the community for direction here.

Otherwise, for Arm and Raspberry Pi you will need to build on the device, and not on your PC or CI server.

File: docs/architecture/autoscaling.md

Auto-scaling your functions

On this page:

OpenFaaS Pro Autoscaler (below)
Legacy scaling for the Community Edition (CE)

OpenFaaS Pro Autoscaler

!!! info "OpenFaaS Pro feature"
This feature is included for OpenFaaS Pro customers, and is designed for commercial use and production systems.

The OpenFaaS Pro Autoscaler scales functions horizontally between a minimum and maximum number of replicas, or to zero.

Watch Alex's overview of auto-scaling in OpenFaaS at KubeCon:

Watch now: How and Why We Rebuilt Auto-scaling in OpenFaaS with Prometheus

Configuration is via a label on the function.

Label	Description	Default
`com.openfaas.scale.type`	Scaling mode of `rps`, `capacity`, `cpu`, or the name of a custom rule added via the Helm chart.	`rps`
`com.openfaas.scale.target`	Target load per replica for scaling. This can also be set through the openfaas chart using `autoscaler.defaultTarget`.	`50`
`com.openfaas.scale.target-proportion`	Proportion as a float of the target i.e. 0.9 = 90% of target.	`0.90`
`com.openfaas.scale.min`	The lower boundary for the number of Pods whilst under load.	`1`
`com.openfaas.scale.max`	The upper boundary for the number of Pods under maximum load. Or set to same as lower boundary to disable scaling.	`20`
`com.openfaas.scale.zero`	Whether this function can be scaled to zero.	`false`
`com.openfaas.scale.zero-duration`	Idle duration before scaling to zero.	`15m`

All calls made through the gateway whether to a synchronous function /function/ route or via the asynchronous /async-function route count towards this method of auto-scaling.

Monitor what the autoscaler is doing

The best way to monitor the load on functions, and the decisions of the autoscaler is through the Grafana dashboard which is included with OpenFaaS Pro. The overview dashboard shows everything you need to know at a glance across all functions, and the spotlight dashboard shows just the one function you select.

OpenFaaS Pro auto-scaling dashboard with Grafana

In addition to the dashboards, you can monitor the calculations and decisions of the autoscaler.

By default, only API calls to the scale endpoint will be logged, to reduce the load and the amount of logs that may need to be stored. Set verbose flag to true in the Helm chart under the autoscaler section to view each turn or iteration of the [Scaler] and [Idler] Goroutines as they make decisions.

How auto-scaling works

There are three auto-scaling modes described in the next section. This is how they work.

When configuring auto-scaling for a function, you need to set a target number which is the average load per replica of your function.
Each mode can be used to record a current load for a function across all replicas in the OpenFaaS cluster.

Then, a query is run periodically to calculate the current load.

The current load is used to calculate the new number of replicas.

text

desired = ready pods * ( mean load per pod / target load per pod )

The target-proportion flag can be used to adjust how early or late scaling occurs:

text

desired = ready pods * ( mean load per pod / ( target load per pod * target-proportion ) )

For example:

sleep is running in the capacity mode and has a target load of 5 in-flight requests.
The load on the sleep function is measured as 15 inflight requests.
There is only one replica of the sleep function because its minimum range is set to 1.
We are assuming com.openfaas.scale.target-proportion is set to 1.0 (100%).

text

mean per pod = 15 / 1

3 = ceil ( 1 * ( 15 / 5 * 1 ) )

Therefore, 3 replicas will be set.

With 3 replicas and 25 ongoing requests, the load will be spread more evenly, and evaluate as follows:

text

mean per pod = 25 / 3 = 8.33

5 =  ceil( 3 * ( 8.33 / 5 * 1 ) )

When the load is no longer present, it will evaluate as follows:

text

mean per pod = 0 / 3 = 0

0 = ceil ( 3 * ( 0 / 5 * 1) )

But the function will not be set to zero yet, it will be brought up to the minimum range which is 1.

Scaling to zero is based upon traffic observed from the gateway within a set period of time defined via com.openfaas.scale.zero-duration.

If you are limiting how much concurrency goes to a function, let's say for 100 requests maximum, then you may want to set the target to 100 with a proportion of 0.7, in this instance, when there are 70 ongoing requests, the autoscaler will add more replicas:

text

total load = 90
mean per pod = 90 / 1 = 90

2 =  ceil( 1 * ( 90 / ( 100 * 0.7 ) ) )

Scaling modes

Static - disable scaling for a given function

If the minimum and maximum scaling labels are set to the same value, then the function will be ignored by the autoscaler.

This can be useful for advanced use-cases where a function may need to be stateful, act as a background worker, or where you are certain that scaling is not required.
Capacity capacity

Based upon inflight requests (or connections), ideal for: long-running functions or functions which can only handle a limited number of requests at once.

A hard limit can be enforced through the max_inflight environment variable on the function, so the caller will need to retry the request some of the time. The OpenFaaS Pro queue-worker does this automatically, see also: Retries.
RPS rps

Based upon requests per second completed by the function. A good fit for functions which execute quickly and have high throughput.

You can tune this value on a per function basis.
CPU cpu

Based upon CPU usage of the function, this strategy is idea for CPU-bound workloads, or where Capacity and RPS are not giving the optimal scaling profile. The value configured here is in milli-CPU, so 1000 accounts for 1 CPU core.
Queue-depth queue

Based upon the number of async invocations that are queued for a function. This allows you to scale functions rapidly and proactively to the desired number of replicas to process the queue as quickly as possible. Ideal for functions that are only invoked asynchronously. To use this mode, your queue-worker must be configured to scale consumers dynamically through the function mode.
Custom metrics i.e. RAM, latency, application metrics, etc

Functions can be scaled upon any custom metrics that are available in Prometheus, and which expose a "function_name label in the format of "name.namespace".

This could include RAM usage, latency, business/application metrics, etc. Learn more: Custom autoscaling rules
Scaling to zero

Scaling to zero is an opt-in feature on a per function basis. It can be used in combination with any scaling mode, including Static scaling

Examples of scaling modes

A quick primer on hey a load testing tool written in Go.

We maintain a forked version of hey with recent binaries at: https://github.com/alexellis/hey/.

-c - concurrent connections
-z - duration of the test as a Go duration
-t timeout in seconds
q - limit queries per second

You can install the forked version of hey via arkade using: arkade get hey.

1) Capacity-based scaling:

This function takes 1-2 seconds to complete, and uses a target, or soft limit of 5 concurrent requests.

bash

# target: 5 inflight
# 100% utilization of target

faas-cli store deploy sleep \
--label com.openfaas.scale.max=10 \
--label com.openfaas.scale.target=5 \
--label com.openfaas.scale.type=capacity \
--label com.openfaas.scale.target-proportion=1.0 \
--label com.openfaas.scale.zero=true \
--label com.openfaas.scale.zero-duration=5m

# With a timeout of 10 seconds
# Run for 3 minutes
# With 5 concurrent callers
# Limited to 5 QPS per caller
hey -t 10 -z 3m -c 5 -q 5 \
  http://127.0.0.1:8080/function/sleep

To apply a hard limit, add --env max_inflight=5 to the faas-cli store deploy command.

What if you need to limit a function to processing only one request at a time?

Change the target to 1, target-proportion to 0.95 and set the max_inflight to 1.

bash

faas-cli store deploy sleep \
--label com.openfaas.scale.max=10 \
--label com.openfaas.scale.target=1 \
--label com.openfaas.scale.type=capacity \
--label com.openfaas.scale.target-proportion=0.95 \
--env max_inflight=1

# With a timeout of 10 seconds
# Run for 3 minutes
# With 5 concurrent callers
# Limited to 5 QPS per caller
hey -t 10 -z 3m -c 5 -q 5 \
  http://127.0.0.1:8080/function/sleep

You'll see the replicas scale up to 5 over time, and back to 1 when the test is complete. No pod will serve more than one request at a time.

2) RPS-based scaling:

bash

# target: 50 RPS
# 90% utilization of target

faas-cli store deploy nodeinfo \
--label com.openfaas.scale.max=10 \
--label com.openfaas.scale.target=50 \
--label com.openfaas.scale.type=rps \
--label com.openfaas.scale.target-proportion=0.90 \
--label com.openfaas.scale.zero=true \
--label com.openfaas.scale.zero-duration=10m

# Run for 3 minutes
# With 5 concurrent callers
# Limited to 20 QPS per caller
hey -z 3m -c 5 -q 20 \
  http://127.0.0.1:8080/function/nodeinfo

3) CPU-based scaling:

bash

# target: 100 Mi
# 50% utilization of target

faas-cli store deploy figlet \
--label com.openfaas.scale.max=10 \
--label com.openfaas.scale.target=100 \
--label com.openfaas.scale.type=cpu \
--label com.openfaas.scale.target-proportion=0.50 \
--label com.openfaas.scale.zero=true \
--label com.openfaas.scale.zero-duration=30m

# Run for 3 minutes
# With 5 concurrent callers
# Limited to 20 QPS per caller
hey -m POST -d data -z 3m -c 5 -q 20 \
  http://127.0.0.1:8080/function/figlet

3) CPU-based scaling w/o scale to zero:

bash

# target: 50 Mi
# 90% utilization of target

faas-cli store deploy cows \
--label com.openfaas.scale.max=5 \
--label com.openfaas.scale.target=50 \
--label com.openfaas.scale.type=cpu \
--label com.openfaas.scale.target-proportion=0.70 \
--label com.openfaas.scale.zero=false

hey -m POST -d data -z 3m -c 5 -q 10 \
  http://127.0.0.1:8080/function/cows

Note that com.openfaas.scale.zero=false is a default, so this is not strictly required.

4) Queue-depth based scaling

Scaling based upon the queue depth for a function is a perfect match for asynchronous invocations.

Rather than measuring load upon the function as the other strategies do, the queue depth can be measured, and the number of target replicas can be set immediately.

This example limits concurrent requests to 1 for a long running sleep function.

bash

faas-cli store deploy sleep \
--label com.openfaas.scale.max=10 \
--label com.openfaas.scale.target=1 \
--label com.openfaas.scale.type=queue \
--label com.openfaas.scale.target-proportion=1 \
--label com.openfaas.scale.zero=true \
--env max_inflight=1

hey -m POST -n 30 -c 30 \
  http://127.0.0.1:8080/async-function/sleep

The sleep function we've deployed has a hard limit that means it will only process 1 concurrent request at a time because of the max_inflight environment variable.

When 30 invocations are queued, the scaling parameters will mean that 30 replicas will be required to process the backlog, however the upper limit is 10 replicas. So it will scale to 10 replicas, and process up to queued requests in parallel.

The com.openfaas.scale.zero=true label is set to ensure that the function scales to zero when the queue is empty.

Smoothing out scaling down with a stable window

If traffic to a function oscillates, the autoscaler will attempt to match that load and the number of replicas will also oscillate and mirror the load. This can be smoothed out through a stable window.

The com.openfaas.scale.down.window label can be set with a Go duration up to a maximum of 5m or 300s. When set, the autoscaler will record recommendations on each cycle, and only scale down a function to the highest recorded recommendation of replicas.

There is variable load every 2.5 minutes, however the autoscaler does not scale down due to the stable window picking the highest recommendation over the past 5 minutes.

For example, a function receives a peak in traffic and scales to 10 replicas. The recommendations built up may include 8, 8, 7, 6, 5, 4, 5, 5 replicas, in this case, even if the autoscaler would pick something as low as 2 replicas, based upon the current load, it will only be allowed to scale down to 8 replicas. Once scale down window moves along, and the maximum recommendation decreases, then the value will eventually land on something that matches the current load being received.

In the above scenario, if you were to turn on verbose autoscaling, you'd have seen the following log message, showing the traffic demands 2x replicas, however the stable window is smoothing the decrease out.

text

2024/08/05 15:16:25 [Scaler] cows.openfaas-fn 10 => 2 (want: 8)

The purpose of this option is to slow down the rate of scaling down, when a function receives variable traffic over a relatively long period of time.

Scaling up, and scale to zero are unaffected, by default this setting is turned off.

Custom autoscaling rules

In addition to the built-in scaling types, custom Prometheus expressions can be used to scale functions. For instance you may want to scale based upon queue-depth, Kafka consumer lag, latency, RAM used by a function (example in linked blog post), or a custom business metric exposed by your function's handler.

Blog post / walk-through: How to scale OpenFaaS Functions with Custom Metrics.

For example, to add latency-based scaling using the gateway's gateway_functions_seconds histogram, you could add the following to the openfaas chart in values-pro.yaml:

yaml

prometheus:
  recordingRules:
    - record: job:function_current_load:sum
      expr: |
        sum by (function_name) (rate(gateway_functions_seconds_sum{}[30s])) / sum by (function_name)  (rate( gateway_functions_seconds_count{}[30s]))
        and on (function_name) avg by(function_name) (gateway_service_target_load{scaling_type="latency"}) > bool 1
      labels:
        scaling_type: latency

To check the configuration of current recording rules use the Prometheus UI or run kubectl edit -n openfaas configmap/prometheus-config followed by kubectl rollout restart -n openfaas deploy/prometheus.

Scaling to Zero

Scaling functions to zero replicas can improve efficiency and reduce costs in your Kubernetes clusters:

Cost Savings: By scaling down to zero when idle, you can reduce the number of nodes required in your cluster, leading to lower infrastructure costs with fewer, or smaller nodes required.
Resource Efficiency: Scaling down to zero helps to free up resources in your cluster, this also helps with on-premises clusters where the amount of nodes may be fixed.
Security: By scaling functions down, the attack surface is also reduced to only active functions.

Scaling down to zero replicas

By default, no function will scale to zero unless you add the label com.openfaas.scale.zero=true to the function. This is a per-function setting, so you can choose which functions should scale down to zero.

Learn more: Scale to Zero

Scaling up from zero replicas

Scaling up from zero replicas or 0/0 can be toggled through the scale_from_zero environment variable for the OpenFaaS Gateway. This is turned on by default on Kubernetes and faasd.

The latency between accepting a request for an unavailable function and serving the request is sometimes called a "Cold Start".

What if I don't want a "cold start"?

The cold start in OpenFaaS is strictly optional and it is recommended that for time-sensitive operations you avoid one by having a minimum scale of 1 or more replicas. This can be achieved by not scaling critical functions down to zero replicas, or by invoking them through the asynchronous route which decouples the request time from the caller.
What exactly happens in a "cold start"?

The "Cold Start" consists of the following: creating a request to schedule a container on a node, finding a suitable node, pulling the Docker image and running the initial checks once the container is up and running. This "running" or "ready" state also has to be synchronised between all nodes in the cluster. The total value can be reduced by pre-pulling images on each node and by setting the Kubernetes Liveness and Readiness Probes to run at a faster cadence.

Instructions for optimizing for a low cold-start are provided in the helm chart for Kubernetes.

When scale_from_zero is enabled a cache is maintained in memory indicating the readiness of each function. If when a request is received a function is not ready, then the HTTP connection is blocked, the function is scaled to min replicas, and as soon as a replica is available the request is proxied through as per normal. You will see this process taking place in the logs of the gateway component.

For an overview of cold-starts in OpenFaaS see: Dude where's my coldstart?
What if my function is still running when it gets scaled down?

That shouldn't happen, providing that you've set an adequate value for the idle detection for your function. But if it does, the OpenFaaS watchdog and our official function templates will allow a graceful termination of the function. See also: Improving long-running jobs for OpenFaaS users

Legacy scaling for the Community Edition (CE)

!!! warning "Legacy scaling for the Community Edition (CE)"
The Community Edition (CE) is meant for development only, or internal use in non-business use-cases.

A single auto-scaling rule defined in the mounted configuration file for AlertManager, which is used for all functions. AlertManager reads usage (requests per second) metrics from Prometheus in order to know when to fire an alert to the API Gateway.

The API Gateway handles AlertManager alerts through its /system/alert route.

The auto-scaling provided by this method can be disabled by either deleting the AlertManager deployment or by scaling the deployment to zero replicas.

The AlertManager rule used in the Community Edition can be viewed here.

All calls made through the gateway whether to a synchronous function /function/ route or via the asynchronous /async-function route count towards this method of auto-scaling.

Min/max replicas

The minimum (initial) and maximum replica count can be set at deployment time by adding a label to the function.

com.openfaas.scale.min - by default this is set to 1, which is also the lowest value and unrelated to scale-to-zero
com.openfaas.scale.max - the default and maximum value is 5 for 5/5 Pods
com.openfaas.scale.factor by default this is set to 20% and has to be a value between 0-100 (including borders)

Note:
Setting com.openfaas.scale.min and com.openfaas.scale.max to the same value, allows to disable the auto-scaling functionality of openfaas.
Setting com.openfaas.scale.factor=0 also allows to disable the auto-scaling functionality of openfaas.

For each alert fired the auto-scaler will add a number of replicas, which is a defined percentage of the max replicas. This percentage can be set using com.openfaas.scale.factor. For example setting com.openfaas.scale.factor=100 will instantly scale to max replicas. This label enables to define the overall scaling behavior of the function.

Note: Active alerts can be viewed in the "Alerts" tab of Prometheus which is deployed with OpenFaaS.

Docker & Self-Hosted Deployment Verified OCI

1. Project Overview & Quickstart (openfaas/faas) Copy Chapter

File: README.md Copy Chapter

OpenFaaS ® - Serverless Functions Made Simple Copy Chapter

OpenFaaS Tiers and Pricing Copy Chapter

Overview of OpenFaaS (Serverless Functions Made Simple) Copy Chapter

Code samples Copy Section

Get started with OpenFaaS Copy Chapter

Official training resources Copy Section

Official eBook and video workshop Copy Section

OpenFaaS and Golang Copy Section

Community blog and documentation Copy Section

Quickstart Copy Section

Video presentations Copy Section

Community events and blog posts Copy Section

Contributing Copy Section

How do I become a contributor?

Dashboards

Press / Branding / Website Sponsorship Copy Section

Governance Copy Section

Users Copy Section

File: api-docs/README.md Copy Chapter

Exploring or editing the Swagger API documentation Copy Chapter

File: docs/README.md Copy Chapter

OpenFaaS - Serverless Functions Made Simple for Docker & Kubernetes Copy Chapter

File: gateway/README.md Copy Chapter

Gateway

Function Providers Copy Chapter

REST API Copy Chapter

CORS Copy Chapter

UI Portal Copy Chapter

Function Store Copy Section

Logs Copy Chapter

Tracing Copy Chapter

Environmental overrides Copy Chapter

File: sample-functions/README.md Copy Chapter

OpenFaaS samples

2. Official Technical Reference & Guides (openfaas/docs) Copy Chapter

File: README.md Copy Chapter

OpenFaaS docs repository

Published page Copy Chapter

mkdocs-material markdown extensions Copy Chapter

Adding OpenFaaS Users Copy Chapter

File: diagrams/README.md Copy Chapter

Source diagrams Copy Chapter

File: docs/cli/build.md Copy Chapter

Build functions

Build-time secrets Copy Chapter

Private access to a Python pip repository Copy Section

Private npm modules Copy Section

1.0 Apply build options Copy Chapter

2.0 Pass ADDITIONAL_PACKAGE through `--build-arg` Copy Chapter

3.0 Pass custom build arguments Copy Chapter

4.0 Building with large function sets Copy Chapter

4.1 Using the `--parallel` flag Copy Section

4.2 Using the `--filter` flag Copy Section

4.3 Using the `--regex` flag Copy Section

Building multi-arch images for ARM and Raspberry Pi Copy Chapter

File: docs/cli/completion.md Copy Chapter

Shell Completion

Bash for Linux Copy Chapter

Bash for MacOS Copy Chapter

ZSH Copy Chapter

File: docs/cli/install.md Copy Chapter

Installation

Installation with arkade Copy Chapter

Installation with Bash Copy Chapter

Windows Copy Chapter

Pro plugin Copy Chapter

Activate with a static license Copy Section

Activate with GitHub Copy Section

Environment variable overrides Copy Chapter

Running `faas-cli` with sudo Copy Chapter

Running `faas-cli` with docker Copy Chapter

Building from source Copy Chapter

Tutorial Copy Chapter

File: docs/cli/logs.md Copy Chapter

Function Logs

Log structure Copy Chapter

Filter and Search Copy Chapter

1. Project Overview & Quickstart (openfaas/faas)

File: README.md

OpenFaaS ® - Serverless Functions Made Simple

OpenFaaS Tiers and Pricing

Overview of OpenFaaS (Serverless Functions Made Simple)

Code samples

Get started with OpenFaaS

Official training resources

Official eBook and video workshop

OpenFaaS and Golang

Community blog and documentation

Quickstart

Video presentations

Community events and blog posts

Contributing

Press / Branding / Website Sponsorship

Governance

Users

File: api-docs/README.md

Exploring or editing the Swagger API documentation

File: docs/README.md

OpenFaaS - Serverless Functions Made Simple for Docker & Kubernetes

File: gateway/README.md

Function Providers

REST API

CORS

UI Portal

Function Store

Logs

Tracing

Environmental overrides

File: sample-functions/README.md

2. Official Technical Reference & Guides (openfaas/docs)

File: README.md

Published page

mkdocs-material markdown extensions

Adding OpenFaaS Users

File: diagrams/README.md

Source diagrams

File: docs/cli/build.md

Build-time secrets

Private access to a Python pip repository

Private npm modules

1.0 Apply build options

2.0 Pass ADDITIONAL_PACKAGE through `--build-arg`

3.0 Pass custom build arguments

4.0 Building with large function sets

4.1 Using the `--parallel` flag

4.2 Using the `--filter` flag

4.3 Using the `--regex` flag

Building multi-arch images for ARM and Raspberry Pi

File: docs/cli/completion.md

Bash for Linux

Bash for MacOS

ZSH

File: docs/cli/install.md

Installation with arkade

Installation with Bash

Windows

Pro plugin

Activate with a static license

Activate with GitHub

Environment variable overrides

Running `faas-cli` with sudo

Running `faas-cli` with docker

Building from source

Tutorial

File: docs/cli/logs.md

Log structure

Filter and Search

Log Retention and History

Alternative Log Providers

Structured Logs

File: docs/cli/secrets.md

Create

Update

List

Delete

File: docs/cli/tags.md

Option 1 - YAML file