Skip to content

Commit c3a445e

Browse files
alexellisalexellis
committed
Add OpenFaaS Edge section to docs
Signed-off-by: Alex Ellis (OpenFaaS Ltd) <[email protected]>
1 parent c7a6841 commit c3a445e

File tree

8 files changed

+518
-0
lines changed

8 files changed

+518
-0
lines changed

‎docs/edge/custom-dns.md

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
# Custom DNS for OpenFaaS Edge
2+
3+
By default, OpenFaaS Edge will use Google's public DNS servers to look up IP addresses from core-services and from functions. This is done to ensure that the functions can reach the Internet.
4+
5+
If you deploy OpenFaaS Edge within a private VPC, or enterprise network, you may need to configure custom DNS servers for functions for them to reach the Internet.
6+
7+
## During installation
8+
9+
You can specify custom DNS servers during the installation phase with:
10+
11+
```bash
12+
faasd install --dns-server 1.1.1.1 --dns-server 8.8.4.4
13+
```
14+
15+
## Update an existing installation
16+
17+
Sometimes, it's easier to update the system after the installation.
18+
19+
Update the systemd services for `faasd` and `faasd-provider` to include the `--dns-server` flag.
20+
21+
Edit the following:
22+
23+
* `/var/lib/faasd/faasd.service`
24+
* `/var/lib/faasd-provider/faasd-provider.service`
25+
26+
In each, find the `ExecStart` line and add the `--dns-server` flag once per DNS server.

‎docs/edge/gpus.md

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
# GPU support for OpenFaaS Edge
2+
3+
At the time of speaking, OpenFaaS Pro on Kubernetes supports GPUs for functions via Profiles.
4+
5+
OpenFaaS Edge supports Nvidia GPUs for core services only.
6+
7+
Example:
8+
9+
```yaml
10+
services:
11+
ollama:
12+
image: docker.io/ollama/ollama:latest
13+
command:
14+
- "ollama"
15+
- "serve"
16+
volumes:
17+
- type: bind
18+
source: ./ollama
19+
target: /root/.ollama
20+
ports:
21+
- "127.0.0.1:11434:11434"
22+
gpus: all
23+
deploy:
24+
restart: always
25+
```
26+
27+
Learn more: [How to Protect Your Data with Self-Hosted LLMs and OpenFaaS Edge](https://www.openfaas.com/blog/local-llm-openfaas-edge/)
28+

‎docs/edge/kafka-deployment.md

Lines changed: 218 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,218 @@
1+
# Deploy the Kafka Connector for OpenFaaS Edge
2+
3+
The Kafka Connector for OpenFaaS Edge is used to trigger functions from Kafka topics.
4+
5+
This page covers deployment options for the connector with OpenFaaS Edge
6+
7+
For instructions on usage, once deployed: [see the page for OpenFaaS on Kubernetes](/openfaas-pro/kafka-events)
8+
9+
## Deployment modes
10+
11+
There are three main modes of deployment for the Kafka Connector, although some options can also be mixed such as using SASL authentication with a custom TLS bundle.
12+
13+
* No authentication - usually used in development, or within some enterprise networks
14+
* SASL username and password authentication - often used with cloud-hosted Kafka brokers such as Aiven, Confluent Cloud or Amazon Managed Streaming for Apache Kafka (MSK).
15+
* Custom TLS CA bundle - used when the Kafka broker uses a self-signed certificate or a certificate signed by a private CA.
16+
17+
## Environment variables
18+
19+
There are a number of environment variables that can be set to configure the Kafka Connector, however these are the most important:
20+
21+
* `topics` - the Kafka topic to listen to. This can be a comma-separated list of topics.
22+
* `broker_hosts` - the Kafka brokers to connect to. This can be a comma-separated list of brokers.
23+
* `upstream_timeout` - the maximum time to wait for a function to respond. This is set to 2 minutes by default.
24+
* `rebuild_interval` - the interval to check for new functions to invoke. This is set to 30 seconds by default.
25+
* `content_type` - the content type to use when invoking functions. This is set to `text/plain` by default.
26+
* `group` - the Kafka consumer group to use. This is set to `faas-group-1` by default.
27+
* `log_sessions` - whether to log sessions. This is set to `true` by default.
28+
* `max_bytes` - the maximum number of bytes to read from the Kafka topic. This is set to 1MB by default.
29+
* `initial_offset` - the initial offset to use when consuming messages. This is set to `oldest` by default.
30+
31+
## Multiple connectors
32+
33+
To deploy multiple connectors, give varying names to the service in the `docker-compose.yaml` file:
34+
35+
```yaml
36+
kafka-connector-private:
37+
topics: user.signup
38+
broker_hosts: kafka-1:9092,kafka-2:9092,kafka-3:9092
39+
...
40+
kafka-connector-cloud:
41+
topics: user.signup
42+
broker_hosts: pkc-5r697.europe-west1.gcp.confluent.cloud:9092
43+
```
44+
45+
## No authentication
46+
47+
This option uses no authentication, and turns TLS off.
48+
49+
It connects to three different Kafka brokers via the `broker_hosts` environment variable, and subscribes to the `user.signup` topic.
50+
51+
```yaml
52+
kafka-connector:
53+
image: ghcr.io/openfaasltd/kafka-connector:latest
54+
environment:
55+
- gateway_url=http://gateway:8080
56+
- topics=user.signup
57+
- print_response=true
58+
- print_response_body=true
59+
- print_request_body=false
60+
- asynchronous_invocation=false
61+
- basic_auth=true
62+
- secret_mount_path=/run/secrets
63+
- broker_hosts=kafka-1:9092,kafka-2:9092,kafka-3:9092
64+
- upstream_timeout=2m
65+
- rebuild_interval=30s
66+
- content_type=text/plain
67+
- group=faas-group-1
68+
- log_sessions=true
69+
- max_bytes=1048576
70+
- initial_offset=oldest
71+
command:
72+
- "/usr/bin/kafka-connector"
73+
- "-license-file=/run/secrets/openfaas-license"
74+
volumes:
75+
# we assume cwd == /var/lib/faasd
76+
- type: bind
77+
source: ./secrets/basic-auth-password
78+
target: /run/secrets/basic-auth-password
79+
- type: bind
80+
source: ./secrets/basic-auth-user
81+
target: /run/secrets/basic-auth-user
82+
- type: bind
83+
source: "./secrets/openfaas-license"
84+
target: "/run/secrets/openfaas-license"
85+
depends_on:
86+
- gateway
87+
```
88+
89+
## SASL authentication
90+
91+
The following example is for Confluent Cloud, but the same principles apply to other Kafka brokers.
92+
93+
TLS is enabled, however no specific CA bundle is required since Confluent Cloud uses a trust bundle already available on most systems.
94+
95+
Create two files in the `secrets` directory:
96+
97+
```bash
98+
mkdir -p /var/lib/faasd/secrets
99+
echo "username" > /var/lib/faasd/secrets/broker-username
100+
echo "password" > /var/lib/faasd/secrets/broker-password
101+
```
102+
103+
Example:
104+
105+
```yaml
106+
kafka-connector:
107+
image: ghcr.io/openfaasltd/kafka-connector:latest
108+
environment:
109+
- gateway_url=http://gateway:8080
110+
- topics=user.signup
111+
- print_response=true
112+
- print_response_body=true
113+
- print_request_body=false
114+
- asynchronous_invocation=false
115+
- basic_auth=true
116+
- secret_mount_path=/run/secrets
117+
- broker_hosts=pkc-5r697.europe-west1.gcp.confluent.cloud:9092
118+
- upstream_timeout=2m
119+
- rebuild_interval=30s
120+
- content_type=text/plain
121+
- group=faas-group-1
122+
- log_sessions=true
123+
- max_bytes=1048576
124+
- initial_offset=oldest
125+
command:
126+
- "/usr/bin/kafka-connector"
127+
- "-license-file=/run/secrets/openfaas-license"
128+
- "-username-file=/run/secrets/broker-username"
129+
- "-password-file=/run/secrets/broker-password"
130+
- "-tls"
131+
volumes:
132+
# we assume cwd == /var/lib/faasd
133+
- type: bind
134+
source: ./secrets/basic-auth-password
135+
target: /run/secrets/basic-auth-password
136+
- type: bind
137+
source: ./secrets/basic-auth-user
138+
target: /run/secrets/basic-auth-user
139+
- type: bind
140+
source: "./secrets/openfaas-license"
141+
target: "/run/secrets/openfaas-license"
142+
- type: bind
143+
source: "./secrets/broker-username"
144+
target: "/run/secrets/broker-username"
145+
- type: bind
146+
source: "./secrets/broker-password"
147+
target: "/run/secrets/broker-password"
148+
depends_on:
149+
- gateway
150+
```
151+
152+
## Custom TLS CA bundle
153+
154+
When a custom CA bundle is required for self-signed or untrusted certificates, the CA bundle can be mounted into the container and used by the Kafka Connector.
155+
156+
Create a file in the `secrets` directory:
157+
158+
```bash
159+
mkdir -p /var/lib/faasd/secrets
160+
cp ./ca-bundle.crt /var/lib/faasd/secrets/kafka-ca-bundle.crt
161+
```
162+
163+
Then add the following mount:
164+
165+
```yaml
166+
volumes:
167+
- type: bind
168+
source: "./secrets/kafka-ca-bundle.crt"
169+
target: "/run/secrets/kafka-ca-bundle.crt"
170+
```
171+
172+
Then add the following flag to the command:
173+
174+
```yaml
175+
command:
176+
- "-tls"
177+
- "-ca-file=/run/secrets/kafka-ca-bundle.crt"
178+
```
179+
180+
## Self-signed certificate
181+
182+
If you want to use a self-signed certificate, which has not been signed by a CA bundle, or by a CA which is not in your trust bundle, do the following:
183+
184+
1. Create a self-signed certificate using OpenSSL:
185+
186+
```bash
187+
openssl req -x509 -newkey rsa:2048 -keyout kafka.key -out kafka.crt -days 365 -nodes
188+
```
189+
190+
2. Copy the certificate and key to the `secrets` directory:
191+
192+
```bash
193+
mkdir -p /var/lib/faasd/secrets
194+
cp kafka.crt /var/lib/faasd/secrets/kafka.crt
195+
cp kafka.key /var/lib/faasd/secrets/kafka.key
196+
```
197+
198+
Then add the following to the command:
199+
200+
```yaml
201+
command:
202+
- "-tls"
203+
- "-cert-file=/run/secrets/kafka.crt"
204+
- "-key-file=/run/secrets/kafka.key"
205+
```
206+
207+
And then mount the two files:
208+
209+
```yaml
210+
volumes:
211+
- type: bind
212+
source: "./secrets/kafka.crt"
213+
target: "/run/secrets/kafka.crt"
214+
- type: bind
215+
source: "./secrets/kafka.key"
216+
target: "/run/secrets/kafka.key"
217+
```
218+

‎docs/edge/overview.md

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# OpenFaaS Edge Overview
2+
3+
OpenFaaS Edge is a commercial distribution of both [OpenFaaS Standard](/docs/openfaas-pro/) and [faasd](https://github.com/openfaas/faasd) designed for redistribution of bespoke solutions to end customers.
4+
5+
The handbook and reference documentation for OpenFaaS Edge are available in the [Serverless for Everyone Else eBook](https://store.openfaas.com/l/serverless-for-everyone-else?layout=profile). As a customer, you will receive a 100% discount code for the eBook.
6+
7+
Most of the [OpenFaaS Pro documentation](/docs/openfaas-pro/) and [Helm charts](https://github.com/openfaas/faas-netes/tree/master/chart) can be used or adapted, however you'll find some specifics here:
8+
9+
* [OpenFaaS Edge Deployment](/deployment/edge)
10+
* [Services](/edge/services)
11+
* [TLS](/edge/tls)
12+
* [Scale to Zero for OpenFaaS Edge](/edge/scale-to-zero)
13+
* [Custom DNS servers](/edge/custom-dns)
14+
* [Kafka Connector for OpenFaaS Edge](/edge/kafka-deployment)
15+
* [GPU support for services](/edge/gpus)
16+
17+
## Looking for something else?
18+
19+
Reach out to us via [email protected] with comments, questions or suggestions for additional content.

‎docs/edge/scale-to-zero.md

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# Scale to Zero for OpenFaaS Edge
2+
3+
OpenFaaS Edge ships a simplified version of scale to zero, which supports a global idle value for all functions.
4+
5+
OpenFaaS on Kubernetes supports fine-grained idle times for each function.
6+
7+
To enable scale to zero for a function, add the following label:
8+
9+
* `com.openfaas.scale.zero=true`
10+
11+
This can be set via the CLI using flags, REST API, or via stack.yaml.
12+
13+
The global idle period can be adjusted by editing the `faas-idler` section of `/var/lib/faasd/docker-compose.yaml`
14+
15+
```yaml
16+
# If a function is inactive for x minutes, it may be scaled to zero
17+
- "inactivity_duration=10m"
18+
# The interval between each attempt to scale functions to zero
19+
- "reconcile_interval=5m"
20+
# Write additional debug information
21+
- "write_debug=false"
22+
```
23+

0 commit comments

Comments
 (0)