User guide for OpenFaaS Cloud

This guide applies to:

The guide

We'll be creating a Node.js API or microservice using the node10-express template. It does a HTTP redirect for a number of hard-coded routes and could be extended into a fully-functional url shortener in the future.

You can use any of the official OpenFaaS templates, the incubator templates for Node.js and Golang, or even your own custom templates.

If you have the dockerfile language enabled, you can deploy an API or web application which can be packaged in a Docker image.

Create a test repo

First of all create a test repo in the GitHub UI, call it goto.

Create a repo

This can be public or private.

Install the GitHub App

Now find your GitHub App URL. If you're using The Community Cluster, you will find that here.

Otherwise, click Settings -> Developer Settings -> GitHub Apps. Find yours and click "Edit" and then "Install App"

User Guide - 图2

Pick the account you want to install it on, it should match the organisation or username where you created your repo.

Install the GitHub App on a single repository, or if you have multiple, check each of them:

User Guide - 图3

Your GitHub repo will now send webhooks to OpenFaaS Cloud whenever:

  • there is a git push event
  • or whenever you delete a repo or remove the integration

Clone the repo and add the source code

  • Clone your repo
  1. git clone https://github.com/alexellis/goto
  2. cd goto
  • Pull in the OpenFaaS template for node10 and Express.js:
  1. faas-cli template store pull node10-express

You can find other templates with faas-cli template store list

  • Create a new API
  1. faas-cli new --lang node10-express goto
  • Rename its YAML file to stack.yml
  1. mv goto.yml stack.yml

Now add some code to do a redirect into goto/handler.js.

  • If we hit / then we'll print an error
  • If we hit /home/ then we'll send the user to my homepage.
  1. "use strict"
  2.  
  3. module.exports = (event, context) => {
  4.     let redirect;
  5.  
  6.     /* Use a switch statement, or look up the routes in a database
  7.      * such as MongoDB, Redis or Postgres. AWS and DigitalOcean provide
  8.      * remote, managed databases that would work here and maintain
  9.      * a connection pool */
  10.     if(event.path == "/home") {
  11.         redirect = "https://www.alexellis.io/";
  12.     } else if(event.path == "/sponsors" || event.path == "/insiders") {
  13.         redirect = "https://github.com/users/alexellis/sponsorship";
  14.     }
  15.  
  16.     /* Let the user know we couldn't find the URL, we could
  17.      * also return a HTML page and set the correct encoding for the
  18.      * browser to understand. */
  19.     if(!redirect) {
  20.         return context
  21.             .status(400)
  22.             .fail("Unknown short URL");
  23.     }
  24.  
  25.     /* 302 Moved Temporarily
  26.      * Prevents the browser from caching the redirection
  27.      * https://en.wikipedia.org/wiki/HTTP_302 */
  28.     context
  29.         .status(302)
  30.         .headers({"location": redirect})
  31.         .succeed();
  32. }

Now rather than having to build this or test it locally, we can push it straight up to GitHub.

  1. git add .
  2. git commit -s -m "Initial commit"
  3. git push origin master

Check the status of the build

Now check the status of the build by viewing the Commits page.

https://github.com/alexellis/goto/commits/

You will see your build queued up:

User Guide - 图4

Then in a few moments, you should see a pass or failure and a link you can click to find out more.

User Guide - 图5

The detailed view will provide any logs that are available from the build, this would include unit test failures or linting errors.

User Guide - 图6

Checkout the dashboard

Head over to your dashboard and prepare to log into GitHub with 2FA

Go to:

  1. https://system.example.com/

Replace example.com with the OFC installation, i.e. o6s.io for The Community Cluster, this will redirect you to your own personal dashboard for instance: https://system.example.com/dashboard/username

If you're a member of a GitHub organisation with your visibility set to Public, then you can also view its dashboard with: https://system.example.com/dashboard/organisation

  • Enter your 2FA details if you have that enabled User Guide - 图7

  • Authorize the OAuth login User Guide - 图8

  • Checkout the overview page

You have a complete list of your functions available here

User Guide - 图9

  • Checkout the details page

Click on one of the functions to view its details page.

User Guide - 图10

From here you can get metrics, find the latest diff, Docker image artifact and see how many replicas of the function are active.

  • View the build logs from the dashboard User Guide - 图11

  • You can also download a badge for your GitHub repo User Guide - 图12

Now get the Endpoint for your API and then open it in a browser.

The default behaviour with no short-path is to return an error, and the success behaviour is to redirect the browser to my homepage. So you can see after visiting these two URLs, we have a 50/50 split.

  • You can view runtime logs for your function using the "Invocation Logs" button Function logs

Using of-watchdog (http) templates, or a plain Dockerfile, anything written to stdout will show up here.

If you're using the classic watchdog or a legacy template, then you need to set the environment variable of combine_output: false and then to write to stderr.

Delete your function

There are three ways to delete your function:

  • Uninstall the GitHub App from your repository, go to the repo settings then Apps and uninstall OpenFaaS Cloud
  • Edit your stack.yml and comment out, or delete the entry for the function you no-longer require
  • Use faas-cli delete <function-name>

Appendix

Restrictions on stack.yml

The stack.yml file is filtered by the CI/CD pipeline using the git-tar and buildshiprun functions. They remove certain settings and replace them with those set for the whole cluster by the administrator.

  • Memory & CPU limits - set for the cluster
  • Secrets (these are limited to only those added by your account or organisation)
  • Read-only file-system - set for the cluster
  • Annotations - allowed are: topic, schedule, com.openfaas.health.http.path, com.openfaas.health.http.initialDelay
  • Labels - only allowed label is: com.openfaas.scale
  • Scaling - set for the cluster
  • Env-vars - not filtered
  • Registry - set for the cluster

For more about the stack.yml file, see the documentation

Next steps

It is likely that you will need to add a secret or some confidential data to your API or function.