Run the Driver in a container
Run a standalone Driver in Docker or Kubernetes with an API key from the environment and its state on a volume.
A standalone Driver can run in a Docker or Kubernetes container. There is no Driver
image. Copy the Linux binary into an image with glibc 2.39 or later, such as
ubuntu:24.04. See Requirements.
Start command
Run start --standalone in the foreground. Do not use install or the service.
synnax-driver start --standalone --disable-stdin-stop \
--state-file /var/lib/synnax-driver/persisted-state.jsonAlways give --disable-stdin-stop. A container without an interactive stdin closes it
at once, and the Driver then stops.
The Driver stops on SIGTERM, so docker stop and a Kubernetes pod shutdown stop it
cleanly. Run the Driver as the main process of the container: use the exec form of CMD
or ENTRYPOINT, or exec in a wrapper script. A shell does not pass SIGTERM to the
Driver.
Connection
Set the connection with
environment variables.
The Driver reads SYNNAX_DRIVER_ and the parameter name in upper case, such as
SYNNAX_DRIVER_HOST, SYNNAX_DRIVER_PORT, SYNNAX_DRIVER_SECURE, and
SYNNAX_DRIVER_API_KEY.
Create an API key for a rack in the Console and give it as SYNNAX_DRIVER_API_KEY. In
Kubernetes, keep the key in a Secret. The Driver logs in as the rack of the key, so the
rack stays the same when the container starts again, also with an empty state file.
Without an API key, the Driver logs in with a username and password, creates a new rack, and saves its key in the state file. If the state file is lost, the next start creates another rack. Use an API key in a container.
State on a volume
The Driver writes the state file at each start, so its directory must be writable. Put the directory on a volume:
- The Driver creates a missing directory with mode
0700and a missing state file with mode0600. It does not change the mode or owner of a directory or file that exists, such as a volume mount. Create the directory with the owner and mode you want before the Driver starts, and make sure the user of the Driver can write to it. - If the state file exists, the user of the Driver must own it, and other users must not
be able to read it, or the Driver does not start. Set the file to mode
0600. - The directory and the file cannot be symbolic links. Do not mount the state file from a Kubernetes Secret or ConfigMap.
- Driver 0.61.0 to 0.61.4 set the state file to mode
0600at each start. Without--state-file, they also change the mode of the directory. With these versions, always give the flag.
OPC UA certificates
The Driver keeps its OPC UA client certificates in opcua/pki/ in the directory of the
state file. Keep this directory on a persistent volume. If it is lost, the Driver makes
a new certificate, and an OPC UA server that uses signing or encryption rejects it until
you trust it on the server again.
Kubernetes example
apiVersion: v1
kind: Secret
metadata:
name: synnax-driver
stringData:
api-key: syk_...
---
apiVersion: apps/v1
kind: StatefulSet
metadata:
name: synnax-driver
spec:
serviceName: synnax-driver
replicas: 1
selector:
matchLabels:
app: synnax-driver
template:
metadata:
labels:
app: synnax-driver
spec:
containers:
- name: driver
image: registry.example.com/synnax-driver:0.61.5
command:
- synnax-driver
- start
- --standalone
- --disable-stdin-stop
- --state-file
- /var/lib/synnax-driver/persisted-state.json
env:
- name: SYNNAX_DRIVER_HOST
value: synnax.example.com
- name: SYNNAX_DRIVER_PORT
value: "9090"
- name: SYNNAX_DRIVER_API_KEY
valueFrom:
secretKeyRef:
name: synnax-driver
key: api-key
volumeMounts:
- name: state
mountPath: /var/lib/synnax-driver
volumeClaimTemplates:
- metadata:
name: state
spec:
accessModes: ["ReadWriteOnce"]
resources:
requests:
storage: 1GiRun one replica for each API key.