From 57163e27cf435258c00552f2d82a17104e871004 Mon Sep 17 00:00:00 2001 From: "Alex Ellis (OpenFaaS Ltd)" Date: Fri, 21 Feb 2025 10:38:19 +0000 Subject: [PATCH] Revised README Signed-off-by: Alex Ellis (OpenFaaS Ltd) --- README.md | 184 ++++++++++-------------------------------------- docs/ROADMAP.md | 16 ++--- 2 files changed, 45 insertions(+), 155 deletions(-) diff --git a/README.md b/README.md index b29487f7..fb1c35bb 100644 --- a/README.md +++ b/README.md @@ -1,16 +1,38 @@ -# faasd - a lightweight & portable faas engine - -[![Sponsor faasd](https://img.shields.io/static/v1?label=Sponsor&message=%E2%9D%A4&logo=GitHub&link=https://github.com/sponsors/openfaas)](https://github.com/sponsors/openfaas) -[![Build Status](https://github.com/openfaas/faasd/workflows/build/badge.svg?branch=master)](https://github.com/openfaas/faasd/actions) -![Downloads](https://img.shields.io/github/downloads/openfaas/faasd/total) +# faasd - a lightweight and portable version of OpenFaaS faasd is [OpenFaaS](https://github.com/openfaas/) reimagined, but without the cost and complexity of Kubernetes. It runs on a single host with very modest requirements, making it fast and easy to manage. Under the hood it uses [containerd](https://containerd.io/) and [Container Networking Interface (CNI)](https://github.com/containernetworking/cni) along with the same core OpenFaaS components from the main project. ![faasd logo](docs/media/social.png) -## Use-cases and tutorials +## Features & Benefits + +- **Lightweight** - faasd is a single Go binary, which runs as a systemd service making it easy to manage +- **Portable** - it runs on any Linux host with containerd and CNI, on as little as 2x vCPU and 2GB RAM - x86_64 and Arm64 supported +- **Easy to manage** - unlike Kubernetes, its API is stable and requires little maintenance +- **Low cost** - it's licensed per installation, so you can invoke your functions as much as you need, without additional cost +- **Stateful containers** - faasd supports stateful containers with persistent volumes such as PostgreSQL, Grafana, Prometheus, etc +- **Built on OpenFaaS** - uses the same containers that power OpenFaaS on Kubernetes for the Gateway, Queue-Worker, Event Connectors, Dashboards, Scale To Zero, etc +- **Ideal for internal business use** - use it to build internal tools, automate tasks, and integrate with existing systems +- **Deploy it for a customer** - package your functions along with OpenFaaS Edge into a VM image, and deploy it to your customers to run in their own datacenters + +faasd does not create the same maintenance burden you'll find with installing, upgrading, and securing a Kubernetes cluster. You can deploy it and walk away, in the worst case, just deploy a new VM and deploy your functions again. + +You can learn more about supported OpenFaaS features in the [ROADMAP.md](/docs/ROADMAP.md) + +## Getting Started + +There are two versions of faasd: + +* faasd CE - for non-commercial, personal use only licensed under [the faasd CE EULA](/EULA.md) +* OpenFaaS Edge (faasd-pro) - fully licensed for commercial use + +You can install either edition using the instructions in the [OpenFaaS docs](https://docs.openfaas.com/deployment/edge/). + +You can request a license for [OpenFaaS Edge using this form](https://forms.gle/g6oKLTG29mDTSk5k9) -faasd is just another way to run OpenFaaS, so many things you read in the docs or in blog posts will work the same way. +## Further resources + +There are many blog posts and documentation pages about OpenFaaS on Kubernetes, which also apply to faasd. Videos and overviews: @@ -33,64 +55,25 @@ Additional resources: * For use-cases and tutorials: [OpenFaaS blog](https://openfaas.com/blog/) * For self-paced learning: [OpenFaaS workshop](https://github.com/openfaas/workshop/) -### About faasd - -* faasd is a single static Golang binary, which runs on Linux with systemd -* uses the same core components and ecosystem of OpenFaaS -* uses containerd for its runtime and CNI for networking -* is multi-arch, so works on Intel `x86_64` and Arm out the box -* runs stateful containers through its `docker-compose.yaml` file like Grafana, MongoDB, InfluxDB, or Postgres, etc - -Most importantly, it's easy to manage so you can set it up and leave it alone to run your functions. - -[![demo](https://pbs.twimg.com/media/EPNQz00W4AEwDxM?format=jpg&name=medium)](https://www.youtube.com/watch?v=WX1tZoSXy8E) - -> Demo of faasd running asynchronous functions - -Watch the video: [faasd walk-through with cloud-init and Multipass](https://www.youtube.com/watch?v=WX1tZoSXy8E) - -### What does faasd deploy? - -* faasd - itself, and its [faas-provider](https://github.com/openfaas/faas-provider) for containerd - CRUD for functions and services, implements the OpenFaaS REST API -* [Prometheus](https://github.com/prometheus/prometheus) - for monitoring of services, metrics, scaling and dashboards -* [OpenFaaS CE Gateway](https://github.com/openfaas/faas/tree/master/gateway) - the UI portal, CLI, and other OpenFaaS tooling can talk to this. -* [OpenFaaS CE queue-worker for NATS Streaming](https://github.com/openfaas/nats-queue-worker) - run your invocations in the background without adding any code. See also: [asynchronous invocations](https://docs.openfaas.com/reference/triggers/#async-nats-streaming) -* [NATS](https://nats.io) for asynchronous processing and queues - -## Licensing & EULA for OpenFaaS (faasd) +### Deployment tutorials -faasd (which is a distribution of OpenFaaS) is licensed under the [OpenFaaS Community Edition (CE) EULA](https://github.com/openfaas/faas/blob/master/EULA.md), [additional clauses apply](EULA.md) to enable faasd to be used for Personal Use and within Small Business Environments. - -A separate OpenFaaS Standard license is available for commercial use-cases, which is required for certain commercial use. - -### When should you use faasd over OpenFaaS on Kubernetes? - -faasd relies on industry-standard tools for running containers: - -* [CNI](https://github.com/containernetworking/plugins) -* [containerd](https://github.com/containerd/containerd) -* [runc](https://github.com/opencontainers/runc) - -You can use the standard [faas-cli](https://github.com/openfaas/faas-cli) along with pre-packaged functions from *the Function Store*, or build your own using any OpenFaaS template. +* [Use multipass on Windows, MacOS or Linux](/docs/MULTIPASS.md) +* [Deploy to DigitalOcean with Terraform and TLS](https://www.openfaas.com/blog/faasd-tls-terraform/) +* [Deploy to any IaaS with cloud-init](https://blog.alexellis.io/deploy-serverless-faasd-with-cloud-init/) +* [Deploy faasd to your Raspberry Pi](https://blog.alexellis.io/faasd-for-lightweight-serverless/) -* To deploy microservices and functions that you can update and monitor remotely -* When you don't have the bandwidth to learn or manage Kubernetes -* To deploy embedded apps in IoT and edge use-cases -* To distribute applications to a customer or client -* You have a cost sensitive project - run faasd on a 1GB VM for 5-10 USD / mo or on your Raspberry Pi -* When you just need a few functions or microservices, without the cost of a cluster +Terraform scripts: -faasd does not create the same maintenance burden you'll find with maintaining, upgrading, and securing a Kubernetes cluster. You can deploy it and walk away, in the worst case, just deploy a new VM and deploy your functions again. +* [Provision faasd on DigitalOcean with Terraform](docs/bootstrap/README.md) +* [Provision faasd with TLS on DigitalOcean with Terraform](docs/bootstrap/digitalocean-terraform/README.md) -You can learn more about supported OpenFaaS features in the [ROADMAP.md](/docs/ROADMAP.md) -## Learning faasd +### Training / Handbook You can find various resources to learn about faasd for free, however the official handbook is the most comprehensive guide to getting started with faasd and OpenFaaS. ["Serverless For Everyone Else"](https://openfaas.gumroad.com/l/serverless-for-everyone-else) is the official handbook and was written to contribute funds towards the upkeep and maintenance of the project. -### The official handbook and docs for faasd @@ -119,93 +102,4 @@ Topics include: View sample pages, reviews and testimonials on Gumroad: -["Serverless For Everyone Else"](https://openfaas.gumroad.com/l/serverless-for-everyone-else) - -### Deploy OpenFaaS Edge (commercial distribution of faasd) - -OpenFaaS Edge is a commercial distribution of faasd, with enhancements and additional features from OpenFaaS Pro. The [OpenFaaS Pro EULA applies](https://github.com/openfaas/faas/blob/master/pro/EULA.md). - -* Upgraded Pro components from OpenFaaS Standard: Gateway, Cron Connector, JetStream Queue Worker and Classic Scale to Zero -* Deploy up to 250 functions per installation -* Configure private DNS servers -* Airgap-friendly with installation bundled in an OCI image -* Detailed RAM/CPU metrics for stateful containers, and functions, including Out Of Memory (OOM) events -* Multiple namespace support - -This version is intended for resale as part of a wider solution, and to be deployed both into industrial and on-premises environments. - -Individual [GitHub Sponsors of OpenFaaS](https://github.com/sponsors/openfaas) (25 USD / mo and higher) can use OpenFaaS Edge for personal use. - -You can install OpenFaaS Edge with the following script: - -```bash -curl -sLSf \ - https://raw.githubusercontent.com/openfaas/faasd/refs/heads/master/hack/install-edge.sh \ - -o install-edge.sh && \ -chmod +x install-edge.sh -sudo -E ./install-edge.sh -``` - -*For an offline installation* - -Copy the OCI bundle and the install-edge.sh script to the remote server. - -Then mirror the various images from docker-compose.yaml into your private registry, and update the references from i.e. `image: ghcr.io/openfaasltd/gateway` to the equivalents in your registry. - -If your system is unable to install apt, yum, or pacman packages, due to limited network access, then set the `SKIP_OS` environment to 1. The list of packages is available in the `install_required_packages` section of the script. - -### Deploy faasd CE - -faasd-ce supports 15 functions and needs a computer with a stable Internet connection to run. There are some restrictions on commercial use, but [individuals and certain small businesses can use it for free](EULA.md). - -The easiest way to deploy faasd is with cloud-init, we give several examples below, and post IaaS platforms will accept "user-data" pasted into their UI, or via their API. - -For trying it out on MacOS or Windows, we recommend using [multipass](https://multipass.run) to run faasd in a VM. - -If you don't use cloud-init, or have already created your Linux server you can use the installation script as per below: - -```bash -git clone https://github.com/openfaas/faasd --depth=1 -cd faasd - -./hack/install.sh -``` - -> This approach also works for Raspberry Pi when using the 64-bit OS or Ubuntu 22.04 or higher. - -It's recommended that you do not install Docker on the same host as faasd, since 1) they may both use different versions of containerd and 2) docker's networking rules can disrupt faasd's networking. When using faasd - make your faasd server a faasd server, and build container image on your laptop or in a CI pipeline. - -#### Deployment tutorials - -* [Use multipass on Windows, MacOS or Linux](/docs/MULTIPASS.md) -* [Deploy to DigitalOcean with Terraform and TLS](https://www.openfaas.com/blog/faasd-tls-terraform/) -* [Deploy to any IaaS with cloud-init](https://blog.alexellis.io/deploy-serverless-faasd-with-cloud-init/) -* [Deploy faasd to your Raspberry Pi](https://blog.alexellis.io/faasd-for-lightweight-serverless/) - -Terraform scripts: - -* [Provision faasd on DigitalOcean with Terraform](docs/bootstrap/README.md) -* [Provision faasd with TLS on DigitalOcean with Terraform](docs/bootstrap/digitalocean-terraform/README.md) - -### Function and template store - -For community functions see `faas-cli store --help` - -For templates built by the community see: `faas-cli template store list`, you can also use the `dockerfile` template if you just want to migrate an existing service without the benefits of using a template. - -### Community support - -Commercial users and solo business owners should become OpenFaaS GitHub Sponsors to receive regular email updates on changes, tutorials and new features. - -If you are learning faasd, or want to share your use-case, you can join the OpenFaaS Slack community. - -* [Become an OpenFaaS GitHub Sponsor](https://github.com/sponsors/openfaas/) -* [Join the weekly Office Hours call](https://docs.openfaas.com/community/) - -### Backlog, features, design limitations and any known issues - -For open backlog items, shipped features, design limitations and any known issues, see [ROADMAP.md](docs/ROADMAP.md) - -Want to build a patch without setting up a complete development environment? See [docs/PATCHES.md](docs/PATCHES.md) - -Are you looking to hack on faasd? Follow the [developer instructions](docs/DEV.md) for a manual installation, or use the `hack/install.sh` script and pick up from there. +["Serverless For Everyone Else"](https://openfaas.gumroad.com/l/serverless-for-everyone-else) \ No newline at end of file diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index 98a8ae73..fa2b27bd 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -1,12 +1,12 @@ # faasd backlog and features -It's important to understand the vision for faasd vs OpenFaaS CE/Pro. +It's important to understand the vision and tradeoffs between OpenFaaS Edge (faasd-pro) vs. OpenFaaS on Kubernetes. faasd is a single-node implementation of OpenFaaS. -It is supposed to be a lightweight, low-overhead, way to deploy OpenFaaS functions for functions which do not need planet-scale. +It is supposed to be a lightweight, low-overhead, way to deploy OpenFaaS functions for functions which do not need to scale out. -It is not supposed to have multiple replicas, clustering, HA, or auto-scaling. +It is not supposed to have multiple replicas, clustering, High Availability (HA), or auto-scaling. [Learn when to use faasd](https://docs.openfaas.com/deployment/) @@ -43,12 +43,6 @@ It can scale vertically, and this may be a suitable alternative for many use-cas Workaround: deploy multiple, dynamically named functions `scraper-1`, `scraper-2`, `scraper-3` and set up a reverse proxy rule to load balance i.e. `scraper.example.com => [/function/scraper-1, /function/scraper-2, /function/scraper-3]`. -### Scale from zero may give a non-200 - -faasd itself does not implement a health check to determine if a function is ready for traffic. Since faasd doesn't support auto-scaling, this is unlikely to affect you. - -Workaround: Have your client retry HTTP calls, or don't scale to zero. - ### Leaf-node only - no clustering faasd is operates on a leaf-node/single-node model. If this is an issue for you, but you have resource constraints, you will need to use [OpenFaaS CE or Pro on Kubernetes](https://docs.openfaas.com/deployment/). @@ -77,7 +71,7 @@ There is a very detailed chapter on troubleshooting in the eBook [Serverless For ### Your function timed-out at 60 seconds -This is no longer an issue, see the manual for how to configure a longer timeout, updated 3rd October 2022. +See the manual for how to configure a longer timeouts. ### Non 200 HTTP status from the gateway upon reboot @@ -149,3 +143,5 @@ Won't have: * [x] An installer for faasd and dependencies - runc, containerd * [x] Offer a recommendation or implement a strategy for faasd replication/HA * [x] [Remove / deprecate armhf / armv7 support](https://github.com/openfaas/faasd/issues/364) +* [x] Add support for CPU/RAM metrics in the UI, CLI and API +* [x] Network segmentation (functions cannot talk to each other or the host)