Skip to content

Commit 37d3bda

Browse files
hardillbhardillb
authored
Merge pull request #6762 from FlowFuse/device-agent-kube
Add Device Agent on Kubernetes documentation
2 parents 28bdb44 + 3494625 commit 37d3bda

5 files changed

Lines changed: 197 additions & 4 deletions

File tree

‎docs/device-agent/install/README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ navTitle: Installation
44
redirect:
55
to: /docs/device-agent/install/overview
66
layout: redirect
7-
navOrder: 1
7+
navOrder: 3
88
tags:
99
- noDropdown
1010
---

‎docs/device-agent/install/docker.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
navGroup: DeviceAgentInstallation
33
navTitle: Docker Install
4-
navOrder: 4
4+
navOrder: 3
55
meta:
66
description: Run the FlowFuse Device Agent with Docker or Docker Compose, including configuration binding, ports, time zone, and verification steps.
77
tags:

‎docs/device-agent/install/kubernetes.md‎

Lines changed: 191 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,191 @@
1+
---
2+
navGroup: DeviceAgentInstallation
3+
navTitle: Kubernetes Install
4+
navOrder: 4
5+
meta:
6+
description: Run the FlowFuse Device Agent in a Kubernetes cluster
7+
tags:
8+
- device agent
9+
- kubernetes
10+
- installation
11+
---
12+
13+
# Kubernetes Install
14+
15+
## When to Use Each Option
16+
17+
Running the Device Agent in Kubernetes is appropriate when devices are containerized or managed as part of a Kubernetes-based edge or infrastructure platform.
18+
19+
Choose your deployment pattern based on how you manage device identity:
20+
21+
- **Fixed Configuration**
22+
Use when the device already exists in FlowFuse and you have a `device.yml` with its credentials. One deployment maps to one device identity.
23+
24+
- **Automatic Provisioning**
25+
Use when devices should register themselves at startup using a Provisioning Token. Each instance requires writable persistent storage.
26+
27+
Any deployment on Kubernetes is going to be specific to the environment and requirements of the solution. The following examples show two common patterns for running the FlowFuse Device Agent on Kubernetes:
28+
29+
- Fixed configuration using a static `device.yml`
30+
- Automatic provisioning using a FlowFuse Provisioning Token
31+
32+
Choose the approach that matches how you manage device lifecycle and credentials.
33+
34+
## Fixed Configuration
35+
36+
If you have an existing `device.yml` file containing a set of Device Agent credentials.
37+
38+
```bash
39+
kubectl create secret generic device-one-secret --from-file=device.yml=./device.yml
40+
```
41+
42+
The following manifest will create a Deployment and Service for a device using the supplied Secret as its credentials
43+
44+
```yaml
45+
apiVersion: apps/v1
46+
kind: Deployment
47+
metadata:
48+
name: device-one
49+
labels:
50+
app: device-one
51+
spec:
52+
replicas: 1 # there can only be one replica as there is one configuration
53+
revisionHistoryLimit: 10
54+
selector:
55+
matchLabels:
56+
app: device-one
57+
template:
58+
metadata:
59+
labels:
60+
app: device-one
61+
spec:
62+
containers:
63+
- name: device-one
64+
image: flowfuse/device-agent:latest
65+
ports:
66+
- containerPort: 1880
67+
volumeMounts:
68+
- name: config
69+
mountPath: "/opt/flowfuse-device/device.yml"
70+
subPath: "device.yml"
71+
readOnly: true
72+
resources:
73+
limits:
74+
cpu: 1000m
75+
memory: 256Mi
76+
requests:
77+
cpu: 500m
78+
memory: 128Mi
79+
volumes:
80+
- name: config
81+
secret:
82+
secretName: device-one-secret
83+
---
84+
apiVersion: v1
85+
kind: Service
86+
metadata:
87+
name: device-one-service
88+
spec:
89+
selector:
90+
app: device-one
91+
ports:
92+
- protocol: TCP
93+
port: 1880
94+
targetPort: 1880
95+
```
96+
97+
## Automatic Provisioning
98+
99+
Using a FlowFuse Provisioning Token to automatically configure a new Device Agent on deployment.
100+
101+
Because the Device Agent will need to re-write the `device.yml` file it can no longer be stored in a Secret and a PersistentVolume must be used for each instance of the Device Agent.
102+
103+
A Secret is used to hold the initial `device.yml` which contains the provisioning token.
104+
105+
```bash
106+
kubectl create secret generic device-provisioning-secret --from-file=device.yml=./device.yml
107+
```
108+
109+
The following manifest will create a Deployment, Service and PVC for a device using the supplied Secret as the source of the Provisioning token.
110+
111+
The PVC will be used to store the updated `device.yml` and the Node-RED nodes installed by the Remote Instance.
112+
113+
```yaml
114+
apiVersion: apps/v1
115+
kind: Deployment
116+
metadata:
117+
name: device-one
118+
labels:
119+
app: device-one
120+
spec:
121+
replicas: 1 # to scale to more than one instance you should modify this to use a StatefulSet
122+
revisionHistoryLimit: 10
123+
selector:
124+
matchLabels:
125+
app: device-one
126+
template:
127+
metadata:
128+
labels:
129+
app: device-one
130+
spec:
131+
initContainers: # on first run copies the device.yml from Secret to PVC volume
132+
- name: config-copy
133+
image: busybox:latest
134+
command:
135+
- "/bin/sh"
136+
- "-c"
137+
- "if [ ! -f /opt/flowfuse-device/device.yml ]; then cp /tmp/device.yml /opt/flowfuse-device/device.yml; fi"
138+
volumeMounts:
139+
- name: config
140+
mountPath: "/opt/flowfuse-device"
141+
- name: initial-config
142+
mountPath: "/tmp/device.yml"
143+
subPath: "device.yml"
144+
readOnly: true
145+
containers:
146+
- name: device-one
147+
image: flowfuse/device-agent:latest
148+
ports:
149+
- containerPort: 1880
150+
volumeMounts:
151+
- name: config
152+
mountPath: "/opt/flowfuse-device"
153+
resources:
154+
limits:
155+
cpu: 1000m
156+
memory: 256Mi
157+
requests:
158+
cpu: 500m
159+
memory: 128Mi
160+
volumes:
161+
- name: initial-config
162+
secret:
163+
secretName: device-provisioning-secret
164+
- name: config
165+
persistentVolumeClaim:
166+
claimName: device-one-pvc
167+
168+
---
169+
apiVersion: v1
170+
kind: Service
171+
metadata:
172+
name: device-one-service
173+
spec:
174+
selector:
175+
app: device-one
176+
ports:
177+
- protocol: TCP
178+
port: 1880
179+
targetPort: 1880
180+
---
181+
apiVersion: v1
182+
kind: PersistentVolumeClaim
183+
metadata:
184+
name: device-one-pvc
185+
spec:
186+
accessModes:
187+
- ReadWriteOnce
188+
resources:
189+
requests:
190+
storage: 1Gi
191+
```

‎docs/device-agent/install/manual.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
navGroup: DeviceAgentInstallation
33
navTitle: Manual Install with NPM
4-
navOrder: 3
4+
navOrder: 5
55
meta:
66
description: Install the FlowFuse Device Agent using NPM, configure its working directory and service, and verify the setup.
77
tags:

‎docs/device-agent/install/overview.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ meta:
1414

1515
## Choose your install path
1616

17-
Most users should use the Device Agent Installer. Power users can choose Manual ( using `npm`) or Docker deployments.
17+
**Recommended for most users:** Use the Device Agent Installer (Quick Start), the fastest way to deploy with minimal configuration. Power users can choose Manual (using `npm`), Docker, or Kubernetes deployments.
1818

1919
- Recommended: Use the Device Agent Installer
2020
- Fastest way to get started with a one-line command in the [Quick Start guide](../quickstart.md)
@@ -23,6 +23,8 @@ Most users should use the Device Agent Installer. Power users can choose Manual
2323
- Install the npm package, set working directory, configure, and run as a service. See [Manual install](./manual.md)
2424
- Alternative: Docker / Docker Compose
2525
- Run the agent in a container; bind-mount the configuration. See [Docker install](./docker.md)
26+
- Alternative: Kubernetes
27+
- Deploy the agent in a Kubernetes cluster. See [Kubernetes install](./kubernetes.md)
2628

2729
## Prerequisites
2830

0 commit comments

Comments
 (0)