NanoFaaS

A minimal, modular Function-as-a-Service control plane.

Quick start · Architecture · Documentation · Write a function

NanoFaaS registers, deploys and invokes containerized functions on Kubernetes or on a single host. The control plane is one reactive Java service. Everything beyond invocation (queueing, autoscaling, concurrency control, hot reconfiguration, offloading, and each deployment backend) is a module you choose at build time. A build contains only the modules it needs.

Build composition is provided by the standalone NanoFaaS Gradle plugin. See plugin versions and local development.

Highlights

• Build-time modularity. Twelve optional modules with declared defaults, requirements and conflicts, validated before a single task runs.
• One API, three execution modes. Managed deployments, passthrough to external endpoints, and in-process execution share the same invocation endpoints.
• Interchangeable backends. Kubernetes, a local Docker-compatible runtime, or rootless containerd.
• Concurrency control with SLOs. Per-function limits that are static, adapt to latency, or share a platform-wide budget with weighted max-min fairness.
• Native builds. The control plane, CLI and Java example functions compile to GraalVM native executables; services ship on Distroless images.
• Any language. Functions are HTTP services behind a small contract. There are SDKs for Java, Python, Go, JavaScript and Rust, and examples in each of them plus Bash.
• Reproducible distributions. One versioned YAML recipe builds a control plane and its functions, images included.

[!NOTE] NanoFaaS is a research platform that favours latency and simplicity over availability. It runs as a single control-plane pod, keeps executions and queues in memory (the function catalog is persisted to a file), and has no authentication.

Quick start

You need Java 25. If it is missing, Gradle downloads a JDK. Start the control plane:

./gradlew :control-plane:bootRun

In a second terminal, start an example function on port 9090:

./gradlew :functions:java:word-stats:bootRun --args='--server.port=9090'

In a third, build the CLI, register the function and invoke it:

./gradlew :nanofaas-cli:installDist
alias nanofaas="$PWD/clients/cli/build/install/nanofaas-cli/bin/nanofaas-cli"

cat > word-stats.yaml <<'EOF'
name: word-stats
image: nanofaas/java-word-stats
executionMode: EXTERNAL
endpointUrl: http://localhost:9090/invoke
EOF

nanofaas fn apply -f word-stats.yaml
nanofaas invoke word-stats -d '{"text": "to be or not to be", "topN": 2}'

{"executionId":"cf9360a6-…","status":"success","output":{"averageWordLength":2.17,"wordCount":6,"topWords":[{"count":2,"word":"be"},{"count":2,"word":"to"}],"uniqueWords":4},…}

Asynchronous invocation returns an execution ID straight away:

nanofaas enqueue word-stats -d '{"text": "hello world"}'
nanofaas exec get <executionId>

The CLI wraps the HTTP API, which you can also call directly:

curl -X POST http://localhost:8080/v1/functions/word-stats:invoke \
  -H 'Content-Type: application/json' -d '{"input": {"text": "hello"}}'

To have NanoFaaS run the function itself, register it in DEPLOYMENT mode with a deployment backend. The quickstart guide covers Kubernetes, and the tutorial covers writing your own function.

Architecture

flowchart LR
    client(["Client · SDK · CLI"])

    subgraph cp["Control plane"]
        direction TB
        core["<b>Core</b><br/>registry · invocation<br/>dispatch · execution store"]
        mods["<b>Optional modules</b><br/>queues · autoscaler<br/>concurrency control<br/>runtime config · offload"]
        prov["<b>Deployment provider</b><br/>k8s · container-local<br/>containerd"]
        mods --- core --- prov
    end

    client -- "HTTP :8080" --> core
    prov --> managed["Managed<br/>instances"]
    core --> external["External<br/>endpoint"]

A synchronous call (POST /v1/functions/{name}:invoke) is validated, rate-limited and checked for idempotency, then recorded in the execution store. It goes through sync-queue if that module is present, otherwise through async-queue, otherwise straight to the function. Asynchronous calls (:enqueue) require async-queue; without it the API answers 501 Not Implemented. Metrics and health are served on port 8081.

Execution mode	Behaviour
DEPLOYMENT	The control plane owns the function's instances through a deployment backend.
EXTERNAL	The function runs elsewhere; invocations are forwarded to its endpointUrl.
LOCAL	In-process execution, for testing.

Modules

Module	Purpose	Default
async-queue	Per-function queues and scheduler for asynchronous calls	✓
sync-queue	Admission control and backpressure for synchronous calls	✓
autoscaler	Replica scaling driven by workload metrics	✓
concurrency-control	Per-function concurrency governor	✓
runtime-config	Hot reconfiguration through an admin API	✓
offload	Transparent proxying of synchronous calls to a remote NanoFaaS	✓
build-metadata	Build diagnostics endpoint	✓
k8s-deployment-provider	Kubernetes backend	✓
container-deployment-provider	Docker-compatible local backend
containerd-deployment-provider	Rootless containerd backend
forecasting	Per-function arrival-rate forecasts (EWMA or an uploaded trace)
p2p-discovery	Peer discovery, latency measurement and messaging between nodes

Select a set with -PcontrolPlaneModules=<list|all|none>; the three providers are mutually exclusive. See control-plane modules.

Building

The full build includes the rootless containerd provider. Its libraries resolve from Maven Central without credentials:

./gradlew build

For reproducible builds from the recorded source revisions, the same guide documents the local Maven bootstrap and -PcontainerdMavenLocal=true override.

Docker-backed tests need a Docker-compatible runtime. End-to-end scenarios on containers and Kubernetes run from NanoLab; see the testing guide and the E2E tutorial.

Before pushing, check unused private code and public reachability candidates:

./gradlew deadCode deadCodePublic -PcontrolPlaneModules=all -PdeadCodeStrict=true --continue

PMD findings fail this command; the public-code report remains advisory. See the testing guide for reports and framework keep rules.

./gradlew :control-plane:bootJar -PcontrolPlaneModules=none
./gradlew :control-plane:bootJar -PcontrolPlaneModules=async-queue,autoscaler
./gradlew :control-plane:bootJar -PcontrolPlaneModules=all

Each module declares its defaults, requirements and conflicts in platform/modules/<id>/module.properties. An invalid selection fails before any task runs.

With GraalVM Native Image available:

./gradlew :nanofaas-cli:nativeCompile          # standalone CLI
scripts/native-build.sh                        # every native Java target, smoke-tested
scripts/native-java-image.sh control-plane     # native Distroless image

JVM images use each module's Dockerfile on Distroless Java 25.

./gradlew validateRecipe -Precipe=recipes/local-demo.yaml
./gradlew assembleRecipe -Precipe=recipes/local-demo.yaml

A recipe fixes the control-plane modules and configuration, the JVM or native build mode, and the functions to package with their images. See distribution recipes.

Repository layout

Path	Contents
platform/	Shared contracts, control plane and modules
clients/cli/	nanofaas command-line client
sdks/	Function SDKs for Java, Python, Go, JavaScript and Rust
functions/	Example functions in Java, Python, Go, JavaScript, Rust and Bash
runtimes/watchdog/	Rust process supervisor for function containers
recipes/	Distribution recipes
deploy/helm/nanofaas/	Helm chart
docs/	Guides, architecture notes and reference
monograph/	Monograph on the design and its evaluation (Italian)

Provisioning and end-to-end orchestration live in the companion NanoLab repository.

Documentation

Quickstart	Local builds, the CLI, and provisioning a Kubernetes VM
Writing a function	Scaffold, handler, tests, deployment and invocation
Function lifecycle	Minimal HTTP function, three backend paths, invocation and catalog restart checks
Function images and registries	Registry setup and pull diagnostics for Docker, k3s and standalone containerd
CLI guide	Commands, payloads and deploy
Control plane	Modules, retries, admission, persistence
Observability	Metrics, health, logging and tracing
Release performance	Per-release load-test results
All documentation	The complete index

License

Released under the MIT License.