Deployment guide for Kubernetes¶
Before deploying OpenFaaS, you should provision a Kubernetes cluster.
Installing OpenFaaS (an overview)¶
There are many options for deploying a local or remote cluster. You can read about the various Kubernetes distributions here.
Once you have a cluster, you can follow the detailed instructions on this page.
- Install OpenFaaS CLI
- Deploy OpenFaaS using via helm or arkade
- Find your OpenFaaS gateway address
- Retrieve your gateway credentials
- Log in, deploy a function, and try out the UI.
From there, you should consider: adding a TLS certificate with Ingress, switching to the OIDC/OAuth2 plugin for authentication, and tuning-up for production use.
Build your cluster¶
Below are the most popular ways to run a local Kubernetes cluster, but OpenFaaS should run on any.
- k3d - makes k3s available on any computer where Docker is also running
- KinD - upstream Kubernetes running inside a Docker container.
- k3s - a light-weight Kubernetes distribution ideal for edge and development - compatible with Raspberry Pi & ARM64 (Equinix Metal, AWS Graviton, etc)
- minikube - a popular, but heavy-weight option that creates a Linux virtual machine your computer using VirtualBox or similar
- microk8s - a Kubernetes distribution, specifically for Ubuntu users.
You can run
k3d on a single node Virtual Machine so that you don't have to run Kubernetes on your own computer.
- The k3sup ("ketchup") tool can help you to do this by installing k3s onto a remote VM
- Deploy to DigitalOcean Kubernetes
- Deploy to Google Kubernetes Engine
- Deploy to Amazon EKS
- Deploy to Azure AKS
A guide is available for configuring minikube here:
Are you using Google Kubernetes Engine (GKE)? You'll need to create an RBAC role with the following command:
$ kubectl create clusterrolebinding "cluster-admin-$(whoami)" \ --clusterrole=cluster-admin \ --user="$(gcloud config get-value core/account)"
Also, ensure any default load-balancer timeouts within GKE are understood and configured appropriately.
Windows users are encouraged to download Git Bash for use with the OpenFaaS guides and tooling.
You can install the OpenFaaS CLI using
curl on MacOS, Windows (Git Bash) and Linux.
# MacOS and Linux users # If you run the script as a normal non-root user then the script # will download the faas-cli binary to the current folder $ curl -sL https://cli.openfaas.com | sudo sh # Windows users with (Git Bash) $ curl -sL https://cli.openfaas.com | sh
The CLI is also available on
brew for MacOS users, however it may lag behind by a few releases:
brew install faas-cli
Install the OpenFaaS chart using
There are three recommended ways to install OpenFaaS and you can pick whatever makes sense for you and your team.
1) Helm with
arkade install - arkade installs OpenFaaS to Kubernetes using its official helm chart and is the easiest and quickest way to get up and running.
helm client - sane defaults and easy to configure through YAML or CLI flags. Secure options such as
helm template or
helm 3 also exist for those working within restrictive environments.
3) With GitOps tooling. You can install OpenFaaS and keep it up to date with Flux or ArgoCD.
1) Deploy the Chart with
arkade (fastest option)¶
arkade install command installs OpenFaaS using its official helm chart, but without using
tiller, a component which is insecure by default. arkade can also install other important software for OpenFaaS users such as
nginx-ingress. It's the easiest and quickest way to get up and running.
You can use arkade to install OpenFaaS to a regular cloud cluster, your laptop, a VM, a Raspberry Pi, or a 64-bit ARM machine.
- Get arkade
# For MacOS / Linux: curl -SLsf https://dl.get-arkade.dev/ | sudo sh # For Windows (using Git Bash) curl -SLsf https://dl.get-arkade.dev/ | sh
- Install the OpenFaaS
If you're using a managed cloud Kubernetes service which supplies LoadBalancers, then run the following:
arkade install openfaas --load-balancer
--load-balancerflag has a default of
false, so by passing the flag, the installation will request one from your cloud provider.
If you're using a local Kubernetes cluster or a VM, then run:
arkade install openfaas
After the installation you'll receive a command to retrieve your OpenFaaS URL and password.
Other options for installation are available with
arkade install openfaas --help
For cloud users run
kubectl get -n openfaas svc/gateway-external and look for
EXTERNAL-IP. This is your gateway address.
2) Deploy the Chart with
A Helm chart is provided in the
faas-netes repository. Follow the link below then come back to this page.
Some users may have concerns about using helm charts due to security concerns with the
tillercomponent. If you fall into this category of users, then don't worry, you can still benefit from the helm chart without using
See the Chart readme for how to generate your own static YAML files using
Notes for Raspberry Pi & 32-bit ARM (armhf)¶
arkade to install OpenFaaS, it will determine the correct files to use to install OpenFaaS.
For a complete tutorial (including OpenFaaS) see:
- Tutorial: Walk-through — install Kubernetes to your Raspberry Pi in 15 minutes
- Video: Kubernetes Homelab with Raspberry Pi 4
When creating new functions you will need to run the build on an armhf host.
Note: expert users can create or use multi-arch templates which can build on a PC and deploy to an armhf host.
- You can run
faas-cli deployfrom any computer using
- But you must build Docker images on a Raspberry Pi, not on your PC or laptop.
For the Function Store, use the following:
faas-cli store list --platform armhf faas-cli store deploy NAME
Instructions are almost identical for ARM64 users, but use
--platform arm64 instead.
Getting help, expert installations and proof-of-concepts¶
- You can get help by connecting with the community on the Community Page.
- OpenFaaS Ltd offers expert installation, proof-of-concepts, and architecture reviews. Get in touch at: email@example.com to find out more.
- The OpenFaaS Premium Subscription offers enterprise-grade authentication with SSO and OpenID Connect (OIDC).
- Guidelines are also provided for preparing for production and for performance testing.
Learn the OpenFaaS fundamentals¶
The community has built a workshop with 12 self-paced hands-on labs. Use the workshop to begin learning OpenFaaS at your own pace:
You can also find a list of community tutorials, events, and videos.
A walk-through video shows auto-scaling in action and the Prometheus UI: walk-through video.
If you are running into any issues please check out the troubleshooting guide and search the documentation / past issues before raising an issue.
This section covers additional advanced topics beyond the initial deployment.
Deploy with TLS¶
To enable TLS while using Helm, try one of the following references:
Use a private registry with Kubernetes¶
If you try to deploy using
faas-cli deploy it will fail because the Kubernetes kubelet component will not have credentials to authorize the docker image pull request.
Once you have pushed an image to a private registry using
faas-cli push follow the instructions below to either create a pull secret that can be referenced by each function which needs it, or create a secret for the ServiceAccount in the
openfaas-fn namespace so that any functions which need it can make use of it.
If you need to troubleshoot the use of a private image then see the Kubernetes section of the troubleshooting guide.
You can set up your own private Docker registry using this tutorial: Get a TLS-enabled Docker registry in 5 minutes
Option 1 - use an ad-hoc image pull secret¶
To deploy your function(s) first you need to create an Image Pull Secret with the commands below.
Setup some environmental variables:
export DOCKER_USERNAME=<your_docker_username> export DOCKER_PASSWORD=<your_docker_password> export DOCKER_EMAIL=<your_docker_email>
Then run this command to create the secret:
$ kubectl create secret docker-registry dockerhub \ -n openfaas-fn \ --docker-username=$DOCKER_USERNAME \ --docker-password=$DOCKER_PASSWORD \ --docker-email=$DOCKER_EMAIL
Note if not using the Docker Hub you will also need to pass
--docker-serverand the address of your remote registry.
The secret must be created in the
openfaas-fn namespace or the equivalent if you have customised this.
Create a sample function with a
faas-cli new --lang go private-fn --prefix=registry:port/repo mv private-fn.yml stack.yml
stack.yml file and add a reference to the new secret:
secrets: - dockerhub
Now deploy the function using
Option 2 - Link an image pull secret to the namespace's ServiceAccount¶
Rather than specifying the pull secret for each function that needs it you can bind the secret to the namespace's ServiceAccount. With this option you do not need to update the
secrets: section of the
Create the image pull secret in the
openfaas-fn namespace (or equivalent):
$ kubectl create secret docker-registry my-private-repo \ --docker-username=$DOCKER_USERNAME \ --docker-password=$DOCKER_PASSWORD \ --docker-email=$DOCKER_EMAIL \ --namespace openfaas-fn
If needed, pass in the
Use the following command to edit the default ServiceAccount's configuration:
$ kubectl edit serviceaccount default -n openfaas-fn
At the bottom of the manifest add:
imagePullSecrets: - name: my-private-repo
Save the changes in the editor and this configuration will be applied.
The OpenFaaS controller will now deploy functions with images in private repositories without having to specify the secret in the
Set a custom ImagePullPolicy¶
Kubernetes allows you to control the conditions for when the Docker images for your functions are pulled onto a node. This is configured through an imagePullPolicy.
There are three options:
Always- pull the Docker image from the registry every time a deployment changes
IfNotPresent- only pull the image if it does not exist in the local registry cache
Never- never attempt to pull an image
By default, deployed functions will use an
Always, which ensures functions using static image tags (e.g. "latest" tags) are refreshed during an update. This behavior is configurable in
faas-netes via the
image_pull_policy environment variable.
If you're using helm you can pass a configuration flag:
helm upgrade openfaas openfaas/openfaas --install --set "faasnetes.imagePullPolicy=IfNotPresent"
If you're using the plain YAML files then edit
gateway-dep.yml and set the following for
- name: image_pull_policy value: "IfNotPresent"
Notes on picking an "imagePullPolicy"¶
As mentioned above, the default value is
Always. Every time a function is deployed or is scaled up, Kubernetes will pull a potentially updated copy of the image from the registry. If you are using static image tags like
latest, this is necessary.
When set to
IfNotPresent, function deployments may not be updated when using static image tags like
IfNotPresent is particularly useful when developing locally with minikube. In this case, you can set your local environment to use minikube's docker so
faas-cli build builds directly into the Docker library used by minikube.
faas-cli push is unnecessary in this workflow - use faas-cli build then faas-cli deploy.
When set to
Never, only local (or pulled) images will work. This is useful if you want to tightly control which images are available and run in your Kubernetes cluster.