|
| 1 | +# OpenFaaS - Serverless Functions Made Simple |
| 2 | + |
| 3 | + |
| 4 | + |
| 5 | +[OpenFaaS](https://github.com/openfaas/faas) (Functions as a Service) is a framework for building serverless functions with Docker and Kubernetes which has first class support for metrics. Any process can be packaged as a function enabling you to consume a range of web events without repetitive boiler-plate coding. |
| 6 | + |
| 7 | +**Highlights** |
| 8 | + |
| 9 | +* Ease of use through UI portal and *one-click* install |
| 10 | +* Write functions in any language for Linux or Windows and package in Docker/OCI image format |
| 11 | +* Portable - runs on existing hardware or public/private cloud - [Kubernetes](https://github.com/openfaas/faas-netes) and Docker Swarm native |
| 12 | +* [CLI](http://github.com/openfaas/faas-cli) available with YAML format for templating and defining functions |
| 13 | +* Auto-scales as demand increases |
| 14 | +* Scales to zero and back again |
| 15 | +* Compatible with [Istio Service Mesh](https://istio.io). mTLS supported via `exec` health checks. |
| 16 | + |
| 17 | +## Deploy OpenFaaS |
| 18 | + |
| 19 | +**Note:** You must also pass `--set rbac=false` if your cluster is not configured with role-based access control. For further information, see [here](https://kubernetes.io/docs/admin/authorization/rbac/). |
| 20 | + |
| 21 | +**Note:** If you can not use helm with Tiller, [skip below](#deployment-with-helm-template) for alternative install instructions. |
| 22 | + |
| 23 | +--- |
| 24 | +### Install |
| 25 | + |
| 26 | +See also: [Install Helm](https://github.com/openfaas/faas-netes/blob/master/HELM.md) |
| 27 | + |
| 28 | +We recommend creating two namespaces, one for the OpenFaaS core services and one for the functions: |
| 29 | + |
| 30 | +```sh |
| 31 | +kubectl apply -f https://raw.githubusercontent.com/openfaas/faas-netes/master/namespaces.yml |
| 32 | +``` |
| 33 | + |
| 34 | +You will now have `openfaas` and `openfaas-fn`. If you want to change the names or to install into multiple installations then edit `namespaces.yml` from the `faas-netes` repo. |
| 35 | + |
| 36 | +Add the OpenFaaS `helm` chart: |
| 37 | + |
| 38 | +```sh |
| 39 | +helm repo add openfaas https://openfaas.github.io/faas-netes/ |
| 40 | +``` |
| 41 | + |
| 42 | +Generate secrets so that we can enable basic authentication for the gateway: |
| 43 | + |
| 44 | +```sh |
| 45 | +# generate a random password |
| 46 | +PASSWORD=$(head -c 12 /dev/urandom | shasum| cut -d' ' -f1) |
| 47 | + |
| 48 | +kubectl -n openfaas create secret generic basic-auth \ |
| 49 | +--from-literal=basic-auth-user=admin \ |
| 50 | +--from-literal=basic-auth-password="$PASSWORD" |
| 51 | +``` |
| 52 | + |
| 53 | +Now decide how you want to expose the services and edit the `helm upgrade` command as required. |
| 54 | + |
| 55 | +* To use NodePorts (default) pass no additional flags |
| 56 | +* To use a LoadBalancer add `--set serviceType=LoadBalancer` |
| 57 | +* To use an IngressController add `--set ingress.enabled=true` |
| 58 | + |
| 59 | +> Note: even without a LoadBalancer or IngressController you can access your gateway at any time via `kubectl port-forward`. |
| 60 | +
|
| 61 | +Now deploy OpenFaaS from the helm chart repo: |
| 62 | + |
| 63 | +```sh |
| 64 | +helm repo update \ |
| 65 | + && helm upgrade openfaas --install openfaas/openfaas \ |
| 66 | + --namespace openfaas \ |
| 67 | + --set basic_auth=true \ |
| 68 | + --set functionNamespace=openfaas-fn |
| 69 | +``` |
| 70 | + |
| 71 | +> The above command will also update your helm repo to pull in any new releases. |
| 72 | +
|
| 73 | +### Verify the installation |
| 74 | + |
| 75 | +Once all the services are up and running, log into your gateway using the OpenFaaS CLI. This will cache your credentials into your `~/.openfaas/config.yml` file. |
| 76 | + |
| 77 | +Fetch your public IP or NodePort via `kubectl get svc -n openfaas gateway-external -o wide` and set it as an environmental variable as below: |
| 78 | + |
| 79 | +```sh |
| 80 | +export OPENFAAS_URL=http://127.0.0.1:31112 |
| 81 | +``` |
| 82 | + |
| 83 | +If using a remote cluster, you can port-forward the gateway to your local machine: |
| 84 | + |
| 85 | +```sh |
| 86 | +kubectl port-forward -n openfaas svc/gateway 31112:8080 & |
| 87 | +``` |
| 88 | + |
| 89 | +Now log in with the CLI and check connectivity: |
| 90 | + |
| 91 | +```sh |
| 92 | +echo -n $PASSWORD | faas-cli login -g $OPENFAAS_URL -u admin --password-stdin |
| 93 | + |
| 94 | +faas-cli version |
| 95 | +``` |
| 96 | + |
| 97 | +## OpenFaaS Operator and Function CRD |
| 98 | + |
| 99 | +If you would like to work with Function CRDs there is an alternative controller to faas-netes named [OpenFaaS Operator](https://github.com/openfaas-incubator/openfaas-operator) which can be swapped in at deployment time. |
| 100 | +The OpenFaaS Operator is suitable for development and testing and may replace the faas-netes controller in the future. |
| 101 | +The Operator is compatible with Kubernetes 1.9 or later. |
| 102 | + |
| 103 | +To use it, add the flag: `--set operator.create=true` when installing with Helm. |
| 104 | + |
| 105 | +### faas-netes vs OpenFaaS Operator |
| 106 | + |
| 107 | +The faas-netes controller is the most tested, stable and supported version of the OpenFaaS integration with Kubernetes. In contrast the OpenFaaS Operator is based upon the codebase and features from `faas-netes`, but offers a tighter integration with Kubernetes through [CustomResourceDefinitions](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/). This means you can type in `kubectl get functions` for instance. |
| 108 | + |
| 109 | +See also: [Introducing the OpenFaaS Operator](https://www.openfaas.com/blog/kubernetes-operator-crd/) |
| 110 | + |
| 111 | +## Deployment with `helm template` |
| 112 | +This option is good for those that have issues with installing Tiller, the server/cluster component of helm. Using the `helm` CLI, we can pre-render and then apply the templates using `kubectl`. |
| 113 | + |
| 114 | +1. Clone the faas-netes repository |
| 115 | + git clone https://github.com/openfaas/faas-netes.git |
| 116 | + |
| 117 | +2. Render the chart to a Kubernetes manifest called `openfaas.yaml` |
| 118 | + helm template faas-netes/chart/openfaas \ |
| 119 | + --name openfaas \ |
| 120 | + --namespace openfaas \ |
| 121 | + --set basic_auth=true \ |
| 122 | + --set functionNamespace=openfaas-fn > $HOME/openfaas.yaml |
| 123 | + |
| 124 | + You can set the values and overrides just as you would in the install/upgrade commands above. |
| 125 | + |
| 126 | +3. Install the components using `kubectl` |
| 127 | + kubectl apply -f faas-netes/namespaces.yml |
| 128 | + kubectl apply -f $HOME/openfaas.yaml |
| 129 | + |
| 130 | +Now [verify your installation](#verify-the-installation). |
| 131 | + |
| 132 | +## Test a local helm chart |
| 133 | + |
| 134 | +You can run the following command from within the `faas-netes/chart` folder in the `faas-netes` repo. |
| 135 | + |
| 136 | +```sh |
| 137 | +helm upgrade --install openfaas openfaas/ \ |
| 138 | + --namespace openfaas \ |
| 139 | + --set basic_auth=true \ |
| 140 | + --set functionNamespace=openfaas-fn |
| 141 | +``` |
| 142 | + |
| 143 | +## Exposing services |
| 144 | + |
| 145 | +### NodePorts |
| 146 | + |
| 147 | +By default a NodePort will be created for the API Gateway. |
| 148 | + |
| 149 | +### LB |
| 150 | + |
| 151 | +If you're running on a cloud such as AKS or GKE you will need to pass an additional flag of `--set serviceType=LoadBalancer` to tell `helm` to create LoadBalancer objects instead. An alternative to using multiple LoadBalancers is to install an Ingress controller. |
| 152 | + |
| 153 | +### Deploy with an IngressController |
| 154 | + |
| 155 | +In order to make use of automatic ingress settings you will need an IngressController in your cluster such as Traefik or Nginx. |
| 156 | + |
| 157 | +Add `--set ingress.enabled` to enable ingress pass `--set ingress.enabled=true` when running the installation via `helm`. |
| 158 | + |
| 159 | +By default services will be exposed with following hostnames (can be changed, see values.yaml for details): |
| 160 | + |
| 161 | +* `gateway.openfaas.local` |
| 162 | + |
| 163 | +### SSL / TLS |
| 164 | + |
| 165 | +If you require TLS/SSL then please make use of an IngressController. A full guide is provided to [enable TLS for the OpenFaaS Gateway using cert-manager and Let's Encrypt](https://docs.openfaas.com/reference/ssl/kubernetes-with-cert-manager/). |
| 166 | + |
| 167 | +## Zero scale |
| 168 | + |
| 169 | +Scaling up from zero replicas is enabled by default, to turn it off set `zero_scale` to false in the helm chart. |
| 170 | + |
| 171 | +Scaling to zero is done by the `faas-idler` component and by default will only carry out a dry-run. Pass the following to helm to enable scaling to zero replicas of idle functions. You will also need to [read the docs](https://docs.openfaas.com/architecture/autoscaling/#zero-scale) on how to configure functions to opt into scaling down. |
| 172 | + |
| 173 | +```sh |
| 174 | +--set faasIdler.dryRun=false |
| 175 | +``` |
| 176 | + |
| 177 | +## HTTP message signing |
| 178 | +To enable message signing when using asynchronous functions we need to generate a key pair. Using HTTP message signing |
| 179 | +allows function callbacks to verify the authenticity of the callee. Only the OpenFaaS gateway should invoke the callback |
| 180 | +URL. This feature enables you to verify that. |
| 181 | + |
| 182 | +```bash |
| 183 | +rm signing.key > /dev/null 2>&1 || true && rm signing.key.pub > /dev/null 2>&1 || true |
| 184 | +ssh-keygen -t rsa -b 2048 -N "" -m PEM -f signing.key > /dev/null 2>&1 |
| 185 | +openssl rsa -in ./signing.key -pubout -outform PEM -out signing.key.pub > /dev/null 2>&1 |
| 186 | + |
| 187 | +kubectl create secret generic http-signing-private-key -n openfaas \ |
| 188 | + --from-file=http-signing-private-key=./signing.key |
| 189 | + |
| 190 | +kubectl create secret generic http-signing-public-key -n openfaas \ |
| 191 | + --from-file=http-signing-public-key=./signing.key.pub |
| 192 | + |
| 193 | +rm signing.key || true && rm signing.key.pub || true |
| 194 | +``` |
| 195 | + |
| 196 | +## Configuration |
| 197 | + |
| 198 | +Additional OpenFaaS options in `values.yaml`. |
| 199 | + |
| 200 | +| Parameter | Description | Default | |
| 201 | +| ----------------------- | ---------------------------------- | ---------------------------------------------------------- | |
| 202 | +| `functionNamespace` | Functions namespace, preferred `openfaas-fn` | `default` | |
| 203 | +| `async` | Deploys NATS | `true` | |
| 204 | +| `exposeServices` | Expose `NodePorts/LoadBalancer` | `true` | |
| 205 | +| `serviceType` | Type of external service to use `NodePort/LoadBalancer` | `NodePort` | |
| 206 | +| `basic_auth` | Enable basic authentication on the Gateway | `false` | |
| 207 | +| `rbac` | Enable RBAC | `true` | |
| 208 | +| `securityContext` | Deploy with a `securityContext` set, this can be disabled for use with Istio sidecar injection | `true` | |
| 209 | +| `http_signatures` | Enable http message signing for non-repudiation of asynchronous function callbacks | `false` | |
| 210 | +| `openfaasImagePullPolicy` | Image pull policy for openfaas components, can change to `IfNotPresent` in offline env | `Always` | |
| 211 | +| `kubernetesDNSDomain` | Domain name of the Kubernetes cluster | `cluster.local` | |
| 212 | +| `operator.create` | Use the OpenFaaS operator CRD controller, default uses faas-netes as the Kubernetes controller | `false` | |
| 213 | +| `operator.createCRD` | Create the CRD for OpenFaaS Function definition | `true` | |
| 214 | +| `ingress.enabled` | Create ingress resources | `false` | |
| 215 | +| `faasnetes.readTimeout` | Queue worker read timeout | `60s` | |
| 216 | +| `faasnetes.writeTimeout` | Queue worker write timeout | `60s` | |
| 217 | +| `faasnetes.imagePullPolicy` | Image pull policy for deployed functions | `Always` | |
| 218 | +| `gateway.replicas` | Replicas of the gateway, pick more than `1` for HA | `1` | |
| 219 | +| `gateway.readTimeout` | Queue worker read timeout | `65s` | |
| 220 | +| `gateway.writeTimeout` | Queue worker write timeout | `65s` | |
| 221 | +| `gateway.upstreamTimeout` | Maximum duration of upstream function call, should be lower than `readTimeout`/`writeTimeout` | `60s` | |
| 222 | +| `gateway.scaleFromZero` | Enables an intercepting proxy which will scale any function from 0 replicas to the desired amount | `true` | |
| 223 | +| `gateway.maxIdleConns` | Set max idle connections from gateway to functions | `1024` | |
| 224 | +| `gateway.maxIdleConnsPerHost` | Set max idle connections from gateway to functions per host | `1024` | |
| 225 | +| `queueWorker.replicas` | Replicas of the queue-worker, pick more than `1` for HA | `1` | |
| 226 | +| `queueWorker.ackWait` | Max duration of any async task/request | `60s` | |
| 227 | +| `nats.enableMonitoring` | Enable the NATS monitoring endpoints on port `8222` | `false` | |
| 228 | +| `faasIdler.create` | Create the faasIdler component | `true` | |
| 229 | +| `faasIdler.inactivityDuration` | Duration after which faas-idler will scale function down to 0 | `5m` | |
| 230 | +| `faasIdler.reconcileInterval` | The time between each of reconciliation | `30s` | |
| 231 | +| `faasIdler.dryRun` | When set to false the OpenFaaS API will be called to scale down idle functions, by default this is set to only print in the logs. | `true` | |
| 232 | +| `prometheus.create` | Create the Prometheus component | `true` | |
| 233 | +| `alertmanager.create` | Create the AlertManager component | `true` | |
| 234 | + |
| 235 | + |
| 236 | +Specify each parameter using the `--set key=value[,key=value]` argument to `helm install`. |
| 237 | +See values.yaml for detailed configuration. |
| 238 | + |
| 239 | +## Removing the OpenFaaS |
| 240 | + |
| 241 | +All control plane components can be cleaned up with helm: |
| 242 | + |
| 243 | +```sh |
| 244 | +helm delete --purge openfaas |
| 245 | +``` |
| 246 | + |
| 247 | +Follow this by the following to remove all other associated objects: |
| 248 | + |
| 249 | +```sh |
| 250 | +kubectl delete namespace openfaas openfaas-fn |
| 251 | +``` |
| 252 | + |
| 253 | +In some cases your additional functions may need to be either deleted before deleting the chart with `faas-cli` or manually deleted using `kubectl delete`. |
0 commit comments