YAML format reference

    The YAML file can hold one to many functions separated by separate entries.

    Example:

    Produces:

    1. provider:
    2.   name: faas
    3.   gateway: http://127.0.0.1:8080
    4.  
    5. functions:
    6.   fn1:
    7.     lang: go
    8.     handler: ./fn1
    9.     image: fn1:latest
    10.   fn2:
    11.     handler: ./fn2
    12.     image: fn2:latest

    The only valid value for provider is faas.

    Gateway

    The gateway URL can be hard-coded into the YAML file or overriden at deployment time with the —gateway flag or OPENFAAS_URL env-var.

    The functions element holds a map of functions, by default all functions are acted on with CLI verbs, but you can filter them with —filter or —regex.

    Function Name

    The function Name is specified by a key in the functions map, i.e. fn1 in the above example. Function name must be unique within a stack.yml file.

    Valid function names follow ietf which is also used for DNS sub-domains.

    Function: Language

    The lang field refers to which template is going to be used to build the function. The templates are expected to be found in the ./template folder and will be pulled from GitHub if not present.

    Function: Handler

    The function handler field refers to a folder where the function's source code can be found, it must always be a folder and not a filename.

    Function: Image

    The image field refers to a Docker image reference, this could be on the Docker Hub, in your local Docker library or on another remote server.

    Function: Skip build

    The skip_build field controls whether the CLI will attempt to build the Docker image for the function. When true, the build step is skipped and you should see a message printed to the terminal .

    This an optional boolean field, set to false by default.

    Function: Build Options

    For example, the official python3 language template can be used to additional Alpine apk packages to be installed during build process. To install the package for your python3 function, you can specify

    1. build_options:
    2. - ca-certificates

    Important note: that the configuration of this value is dependent on the language template. The template author must specify one or more ARG in the Dockerfile.

    Function: Environmental variables

    You can set configuration via environmental variables either in-line within the YAML file or in a separate external file. Do not store confidential or private data in environmental variables. See: secrets.

    • Define environment in-line within the file:Imagine you needed to define a http_proxy variable to operate within a corporate network:
    1. functions:
    2.   url-ping:
    3.     lang: python
    4.     handler: ./sample/url-ping
    5.     image: alexellis2/faas-urlping
    6.     environment:
    7.       http_proxy: http://proxy1.corp.com:3128
    8.       no_proxy: http://gateway/
    • environment_file - defined in zero to many external files
    1.   environment_file:
    2.     - file1.yml
    3.     - file2.yml

    If you specify a variable such as "rss_feed_url" in more than one environment_file file then the last file in the list will take priority.

    Environment file format:

    1. environment:
    2.   rss_feed_url: key1
    3.   include_images: key2

    Function: Secure secrets

    OpenFaaS functions can make use of secure secrets using the secret store from Kubernetes or Docker Swarm. This is the recommended way to store secure access keys, tokens and other private data.

    Create the secret with your orchestration tool i.e. kubectl or docker secret create then list the secret name as part of an array of secrets.

    Function: Read-Only Root Filesystem

    The indicates that the function file system will be set to read-only except for the temporary folder /tmp. This prevents the function from writing to or modifying the filesystem (e.g. system files). This is used to provide tighter security for your functions. You can set this value as a boolean:

    1. readonly_root_filesystem: true

    This an optional boolean field, set to false by default.

    Function: Constraints

    Constraints are passed directly to the underlying container orchestrator. They allow you to pin a function to certain host or type of host.

    Here is an example of picking only hosts with a Linux OS in Docker Swarm:

    1.    constraints:
    2.      - "node.platform.os == linux"

    Or only using nodes running with Windows:

    1.    constraints:
    2.      - "node.platform.os == windows"

    Function: Labels

    Labels can be applied through a map which is passed directly to the container scheduler.Labels are also available from the OpenFaaS REST API for querying or grouping functions.

    1.    labels:
    2.      canary: true

    Function: Annotations

    Annotations are a collection of meta-data which is stored with the function by the provider.Annotations are also available from the OpenFaaS REST API for querying.

    Example of setting a "topic" for the Kafka event connector:

    1.    annotations:
    2.      topic: "kafka.payments-received"
    3.      expire-date: "Wed Aug  8 07:40:18 BST 2018"

    Example of setting a custom HTTP health check path and initial check delay:

    Function: Memory/CPU limits

    Applying memory and CPU limits can be done through the limits and requests . It is advisable to always set a limit for your functions to prevent them consuming too many resources in your system.

    Here we constrain the url-ping function to only use 40Mb of RAM at a maximum.

    1.   url-ping:
    2.     lang: python
    3.     handler: ./sample/url-ping
    4.     image: alexellis/faas-url-ping:0.2
    5.     limits:
    6.       memory: 40Mi
    7.     requests:
    8.       memory: 20Mi

    Here we constrain a function to use only 100m which is equivalent to 1/10 of an Intel Hyperthread core.

    1.   url-ping:
    2.     lang: python
    3.     handler: ./sample/url-ping
    4.     image: alexellis/faas-url-ping:0.2
    5.     limits:
    6.       cpu: 100m
    7.     requests:
    8.       cpu: 100m

    The meanings and formats of limits and requests may vary depending on whether you are using Kubernetes or Docker Swarm. In general:

    • Requests ensures the stated host resource is available for the container to use
    • Limits specify the maximum amount of host resources that a container can consumeSee docs for or for Kubernetes.

    The YAML stack format supports the use of envsubst-style templates. This means that you can have a single file with multiple configuration options such as for different user accounts, versions or environments.

    Here is an example use-case, in your project there is an official and a development Docker Hub username/account. For the CI server images are always pushed to exampleco, but in development you may want to push to your own account such as alexellis2.

    1. functions:
    2.   url-ping:
    3.     lang: python
    4.     handler: ./sample/url-ping
    5.     image: ${DOCKER_USER:-exampleco}/faas-url-ping:0.2

    Use the default (exampleco):

    1. $ faas-cli build

    Override with "alexellis2" through an environment variable:

    1. $ DOCKER_USER="alexellis2" faas-cli build