## 1. Project Overview & Quickstart (openfaas/faas)
## File: README.md
## OpenFaaS ® - Serverless Functions Made Simple
[](https://github.com/openfaas/faas/actions/workflows/build.yml)
[](https://pkg.go.dev/github.com/openfaas/faas)
[](https://www.openfaas.com)
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."
[](https://x.com/openfaas)
**Highlights**
* Ease of use through UI portal and *one-click* install
* Write services and functions in any language with [Template Store](https://www.openfaas.com/blog/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](https://github.com/openfaas/faas-netes)
* [CLI](http://github.com/openfaas/faas-cli) available with YAML format for templating and defining functions
* Auto-scales as demand increases [including to zero](https://docs.openfaas.com/architecture/autoscaling/)
* [Commercially supported Pro distribution by the team behind OpenFaaS](https://openfaas.com/pricing/)
**Want to dig deeper into OpenFaaS?**
* Trigger endpoints with either [HTTP or events sources such as Apache Kafka and AWS SQS](https://docs.openfaas.com/reference/triggers/)
* Offload tasks to the built-in [queuing and background processing](https://docs.openfaas.com/reference/async/)
* Quick-start your Kubernetes journey with [GitOps from OpenFaaS Cloud](https://docs.openfaas.com/openfaas-cloud/intro/)
* Go secure or go home [with 5 must-know security tips](https://www.openfaas.com/blog/five-security-tips/)
* Learn everything you need to know to [go to production](https://docs.openfaas.com/architecture/production/)
* Integrate with Istio or Linkerd with [Featured Tutorials](https://docs.openfaas.com/tutorials/featured/#service-mesh)
* Deploy to [Kubernetes or OpenShift](https://docs.openfaas.com/deployment/)
## 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](EULA.md)
* 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/](https://www.openfaas.com/pricing/)
## Overview of OpenFaaS (Serverless Functions Made Simple)
> Conceptual architecture and stack, [more detail available in the docs](https://docs.openfaas.com/architecture/stack/)
### 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](https://docs.openfaas.com/languages/overview/)
* Node.js (`node20`) example:
```js
"use strict"
module.exports = async (event, context) => {
return context
.status(200)
.headers({"Content-Type": "text/html"})
.succeed(`
👋 Hello World 🌍
`);
}
```
*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`)
```go
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](https://docs.openfaas.com/tutorials/training)
### Official eBook and video workshop
[](https://gumroad.com/l/serverless-for-everyone-else)
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](https://gumroad.com/l/serverless-for-everyone-else)
### 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](https://openfaas.gumroad.com/l/everyday-golang)
### Community blog and documentation
* Read the documentation: [docs.openfaas.com](https://docs.openfaas.com/deployment)
* Read latest news and tutorials on the [Official Blog](https://www.openfaas.com/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](https://docs.openfaas.com/deployment/)
OpenFaaS Standard and OpenFaaS for Enterprises have their own, brand new dashboard with multi-tenancy support, learn more about the [OpenFaaS Dashboard](https://docs.openfaas.com/openfaas-pro/dashboard/).
### Video presentations
* [Meet faasd. Look Ma’ No Kubernetes! 2020](https://www.youtube.com/watch?v=ZnZJXI377ak&feature=youtu.be)
* [Getting Beyond FaaS: The PLONK Stack for Kubernetes Developers 2019](https://www.youtube.com/watch?v=NckMekZXRt8&feature=emb_title)
* [Serverless Beyond the Hype - Alex Ellis - GOTO 2018](https://www.youtube.com/watch?v=yOpYYYRuDQ0)
* [How LivePerson is Tailoring its Conversational Platform Using OpenFaaS - Simon Pelczer 2019](https://www.youtube.com/watch?v=bt06Z28uzPA)
* [Digital Transformation of Vision Banco Paraguay with Serverless Functions @ KubeCon 2018](https://kccna18.sched.com/event/GraO/digital-transformation-of-vision-banco-paraguay-with-serverless-functions-alex-ellis-vmware-patricio-diaz-vision-banco-saeca)
* [Introducing "faas" - Cool Hacks Keynote at Dockercon 2017](https://blog.docker.com/2017/04/dockercon-2017-mobys-cool-hack-sessions/)
### 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](https://github.com/openfaas/faas/blob/master/community.md)
### 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](EULA.md). 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](https://docs.openfaas.com/community/)
#### Dashboards
Example of a Grafana dashboard linked to OpenFaaS showing auto-scaling live in action: [here](https://grafana.com/dashboards/3526)
> [OpenFaaS Pro auto-scaling](https://docs.openfaas.com/architecture/autoscaling/) dashboard with Grafana
An alternative community dashboard is [available here](https://grafana.com/dashboards/3434)
### 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)](EULA.md) is licensed for a 60-day Proof of Concept (PoC) and limited experimentation.
[Learn more about OpenFaaS editions](https://openfaas.com/pricing/)
* Website Sponsorship 🌎
If you'd like to gain visibility by displaying your logon on the [openfaas.com](https://www.openfaas.com/) homepage, feel free to reach out via email or browse the tiers via [GitHub Sponsors](https://github.com/sponsors/openfaas).
* 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](https://github.com/openfaas).
### Governance
OpenFaaS ® is an independent open-source project created by [Alex Ellis](https://www.alexellis.io), which is being built and shaped by a [growing community of contributors](https://www.openfaas.com/team/).
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](https://www.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](http://editor.swagger.io/)
* 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](https://docs.openfaas.com) or our [more detailed set of workshops on GitHub](https://github.com/openfaas/workshop#openfaas-workshop)
---
## 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](https://github.com/openfaas/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](./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](https://github.com/openfaas/faas-cli).
See the [openfaas/store](https://github.com/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:
```
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](https://github.com/openfaas/faas-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:
* [Build a Flask microservice with OpenFaaS](https://www.openfaas.com/blog/openfaas-flask/)
* [Build ASP.NET Core APIs with Kubernetes and OpenFaaS](https://www.openfaas.com/blog/asp-net-core/)
* [Serverless Node.js that you can run anywhere](https://www.openfaas.com/blog/serverless-nodejs/)
* [Simple Serverless with Golang Functions and Microservices](https://www.openfaas.com/blog/golang-serverless/)
* [Get started with Java 11 and Vert.x on Kubernetes with OpenFaaS](https://www.openfaas.com/blog/get-started-with-java-openjdk11/)
* [FaaS for the Rubyist](https://blog.alexellis.io/faas-for-the-rubyist/)
Official Training and eBooks:
* [OpenFaaS with Node.js examples](https://openfaas.gumroad.com/l/serverless-for-everyone-else)
* [OpenFaaS with Golang - Premium and Team Editions only](https://store.openfaas.com/l/everyday-golang)
* [Other Official Training](https://docs.openfaas.com/tutorials/training/)
Official Function store images:
* [Function Store functions](https://github.com/openfaas/store-functions)
Need help? Reach out to us at [openfaas.com/support](https://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](https://squidfunk.github.io/mkdocs-material/extensions/admonition/) for all available extensions.
## Adding OpenFaaS Users
The list of OpenFaaS users can be found within [docs/index.md](docs/index.md#users-of-openfaas). 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.
1. Create a local file containing the secret value
2. Add a `build_secrets` entry in `stack.yml` pointing to the file path
3. Use `RUN --mount=type=secret` in the Dockerfile to access the secret at build time
4. 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:
- python@3.8-debian
```
Create a new function from the template:
```bash
export OPENFAAS_PREFIX=docker.io/alexellis2
faas-cli new --lang python@3.8-debian \
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:
```
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](https://docs.npmjs.com/using-private-packages-in-a-ci-cd-workflow#create-a-new-access-token).
- For Github Packages, see: [Authenticating to GitHub Packages](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-npm-registry#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.
```
//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](https://docs.docker.com/engine/reference/commandline/build/)
## 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](https://docs.docker.com/buildx/working-with-buildx/) extension and [buildkit project](https://docs.docker.com/develop/develop-images/build_enhancements/). 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:
```
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](https://github.com/scop/bash-completion), please follow their installation [here](https://github.com/scop/bash-completion#installation).
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](https://itnext.io/upgrading-bash-on-macos-7138bd1066ba) 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](https://arkade.dev)
## 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](/openfaas-pro/sso/cli).
> Note: The pro plugin is available for [OpenFaaS Standard & For Enterprises](https://openfaas.com/pricing/) 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:
1. `--license` flag — literal JWT string
2. `--license-file` flag — path to a file containing the JWT
3. `OPENFAAS_LICENSE` environment variable
4. 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?"
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](/community/#contribute) has instructions for building from source and for configuring a Golang development environment.
* **Star/fork** on GitHub: [faas-cli](https://github.com/openfaas/faas-cli)
## Tutorial
[5 tips and tricks for the OpenFaaS CLI by Alex Ellis](https://www.openfaas.com/blog/five-cli-tips/)
---
## 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
```sh
-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
```
()
```
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
```sh
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`](https://github.com/junegunn/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,
```sh
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](https://wiki.archlinux.org/index.php/Systemd/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](https://www.elastic.co/), [Logz.io](https://logz.io) or [Humio](https://www.humio.com) as an external data-store.
[Grafana Loki](https://grafana.com/oss/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](../architecture/logs-provider.md) 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 `` 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](/deployment/edge/).
See also: `faas-cli secret --help`
## 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:
```
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](/reference/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:
```
faas-cli secret update secret-name
```
or
```
cat 04385e5c413c10ed68afb010ebe8c5dd706aa20a | faas-cli secret update secret-name
cat ~/Downloads/derek.pem | faas-cli secret update secret-name
```
From literal:
```
faas-cli secret update secret-name --from-literal="04385e5c413c10ed68afb010ebe8c5dd706aa20a"
```
From file:
```
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
...
```
See also: `faas-cli secret list --help`
## Delete
You can delete secrets with:
```bash
faas-cli secret remove secret-name
```
or
```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"
```
image: my-fn
```
or
```
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:
```
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:
```
image: my-fn:0.2
image: my-other-fn
```
Gives the equivalent:
```
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)
```
image: my-fn:0.2
image: my-fn:latest
```
Gives the equivalent:
```
image: my-fn:0.2-master-cf59cfc
image: my-fn:latest-master-cf59cfc
```
(on the staging branch)
```
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 `--g`. 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
```
image: my-fn:0.2
image: my-fn:latest
```
Then, if you have no tags in the repo, `faas-cli` produces the equivalent:
```
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:
```
image: my-fn:0.2-v0.1.0
image: my-fn:latest-v0.1.0
```
Note that the middle value, `` 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:
```
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](/cli/build/)
!!! info "Information about OpenFaaS templates is moving"
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](https://github.com/openfaas/templates) 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 `golang-middleware@0.20.0` 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: golang-middleware@0.9.0
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://git@github.com/"]
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](https://github.com/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](https://github.com/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
See also: [watchdog design](/architecture/watchdog/)
### 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:
```sh
$ 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:
```sh
$ 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:
```sh
$ 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](https://github.com/openfaas/templates) repository.
#### Go templates
See: [Go template](/languages/go)
#### Python 3 templates
See: [Python template](/languages/python)
#### Node.js templates (of-watchdog template)
See: [Node template](/languages/node)
#### 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 sales@openfaas.com 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`:
```
$ 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](https://github.com/openfaas/templates-sdk/tree/master/java11/model/src/main/java/com/openfaas/model)
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](https://github.com/alexellis/openfaas-streaming-templates)
#### CSharp / .NET Core
See also: [C# template](/languages/csharp)
For a function based upon an existing project or Dockerfile, see: [Build ASP.NET Core APIs with Kubernetes and OpenFaaS](https://www.openfaas.com/blog/asp-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](https://github.com/alexellis/openfaas-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.
See also: [Rust templates](https://github.com/openfaas-incubator/rust-http-template)
#### Ruby
Create a function called `ruby-function`:
```
$ faas-cli new --lang ruby ruby-function
```
The directory structure is:
```
├── 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`
```
$ 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:
```sh
$ 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.
```
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:
```
source 'https://rubygems.org'
gem "kubeclient"
```
```
faas-cli build -f k8s-get-pods.yml
```
#### PHP
See also: [PHP 8.2](/languages/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//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//template.yml`
For `csharp` we have the following:
```
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)](#legacy-scaling-for-the-community-edition-ce)
## OpenFaaS Pro Autoscaler
!!! info "OpenFaaS Pro feature"
This feature is included for [OpenFaaS Pro](/openfaas-pro/introduction) customers, and is designed for commercial use and production systems.
The [OpenFaaS Pro](/openfaas-pro/introduction/) 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:
[](https://www.youtube.com/watch?v=ka5QjX0JgFo)
Watch now: [How and Why We Rebuilt Auto-scaling in OpenFaaS with Prometheus](https://www.youtube.com/watch?v=ka5QjX0JgFo)
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/grafana-dashboards)
> 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.
```
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:
```
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%).
```
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:
```
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:
```
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:
```
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](/openfaas-pro/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](/openfaas-pro/jetstream) 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](#custom-autoscaling-rules)
* Scaling to zero
[Scaling to zero](/openfaas-pro/scale-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](https://github.com/rakyll/hey) a load testing tool written in Go.
We maintain a forked version of hey with recent binaries at: [https://github.com/alexellis/hey/](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](https://arkade.dev) 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.
```
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](https://www.openfaas.com/blog/custom-metrics-scaling/).
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:
1. **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.
2. **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.
3. **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](/openfaas-pro/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](https://github.com/openfaas/faas-netes/tree/master/chart/openfaas).
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?](https://www.openfaas.com/blog/what-serverless-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](https://www.openfaas.com/blog/long-running-jobs/)
## 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](https://github.com/openfaas/faas-netes/blob/master/chart/openfaas/templates/prometheus-cfg.yaml#L164) 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.