Fleet Management
Overview
Fleet Management is the central control plane for all distributed edge gateways. Instead of SSH-ing into each device individually, Fleet Management provides a single dashboard to register, monitor, and manage all devices remotely.
Every device registered here also receives its own certificate-based identity through the platform's PKI module, which it uses to authenticate itself afterwards. See Additional Services / PKI for details on how a device obtains, renews, and eventually loses that identity.
Key Features
Device Dashboard
The dashboard provides a real-time overview of all registered edge devices:
- KPI Cards — Total devices, online, warnings, offline, updating (auto-refreshing)
- Device Table — Sortable, filterable, paginated list of all devices with status, site, health score, and last heartbeat
- Device Detail Drawer — Click any device to view CPU/RAM/disk usage, running connectors, and event history
- Configurable Auto-Refresh — Choose update interval (5s, 10s, 30s, 60s, or off)
Device Registration
- Click Register Device in the dashboard
- Enter a Device Name and Site (select existing or create a new one)
- Registration automatically requests a device-specific enrollment token from the PKI module (short-lived, single-use) and returns it together with a ready-to-use install command
Run the install command on the target device to set up the agent automatically:
curl -sSL http://<management-host>/api/fleet/agent/install.sh | \
ENROLLMENT_TOKEN=<token> \
DEVICE_ID=<uuid> \
MANAGEMENT_URL=http://<management-host> bash
The device appears in the dashboard within seconds. Behind the scenes, the agent uses the enrollment token exactly once to obtain its own certificate from the PKI module before it starts sending heartbeats — see Additional Services / PKI for the full onboarding sequence.
Monitoring
Each device sends a heartbeat at a regular interval (default: every 30 seconds) containing:
- System Metrics — CPU, RAM, and disk usage
- Device Information — OS, kernel, architecture, uptime
- Connector Status — List of all running ALP-CONNEX connectors with name, type, and status
Health Score
Each device receives a Health Score (0–100) calculated from its system metrics:
| Factor | Healthy | Warning | Critical |
|---|---|---|---|
| CPU Usage | < 70% | 70–90% (−15) | > 90% (−30) |
| RAM Usage | < 75% | 75–90% (−10) | > 90% (−25) |
| Disk Usage | < 80% | 80–90% (−10) | > 90% (−25) |
| Connector Status | All running | — | Proportional penalty up to −20 |
The health score determines the device status:
| Status | Meaning |
|---|---|
| Online | Health score ≥ 80 |
| Warning | Health score < 80 |
| Offline | No heartbeat for 2× the heartbeat interval (default: ~60 seconds) |
| Updating | Update command in progress |
Remote Commands
Commands can be sent to devices from the dashboard and are executed on the next heartbeat:
| Command | Description |
|---|---|
| Restart Connectors | Restarts all connector containers on the device |
| Update | Pulls a specified image and restarts the target container |
| Configure | Pushes a configuration payload to the device |
Command status is tracked in the device's event log.
Site Management
Devices can be assigned to sites. Sites are created during device registration and allow filtering and grouping in the dashboard.
Device Groups
Devices can also be organized into device groups — a more flexible grouping than sites, used for filtering and bulk assignment. A device group can optionally be pinned to a specific certificate authority (CA): every device placed in that group then receives its certificates from that CA instead of the platform's default one. This is useful for separating trust between sites, customers, or environments. See Additional Services / PKI for how certificate authorities work.
Connector Templates
Reusable connector configurations that can be applied to device profiles for consistent, fleet-wide deployment instead of configuring each device by hand.
Agent Installation
Prerequisites
- Docker must be installed on the target device
- Root access for installation
- Network connectivity to the management server
Automated Installation
The easiest way: copy the install command from the UI and run it on the device. The script will:
- Check prerequisites (Docker, architecture)
- Download the agent Docker image from the management server (~8 MB)
- Create the configuration under
/opt/connex-agent/ - Start the agent as a Docker container
Agent Configuration
| Setting | Required | Default | Description |
|---|---|---|---|
MANAGEMENT_URL | Yes | — | Management server URL |
ENROLLMENT_TOKEN | First start only | — | One-time PKI enrollment token from the UI, used to obtain the device's first certificate |
HEARTBEAT_INTERVAL | No | 30 | Seconds between heartbeats (10–300) |
CERT_RENEW_BEFORE | No | 7d | How long before certificate expiry the agent renews it automatically |
STACK_VERSION | No | dev | Reported software version |
Persistent Data
The agent stores its data locally, including:
| File | Purpose |
|---|---|
device-id | Unique device identifier |
device-key.pem | The device's private key (generated locally, never leaves the device) |
device-cert.pem | The device's current certificate, issued by the platform's PKI |
device-chain.pem | The certificate chain needed to validate the device certificate |
device-config.json | Configuration pushed from the server |
The enrollment token itself is not stored — it is used once during onboarding and discarded. See Additional Services / PKI for how these files are obtained and kept up to date.
Troubleshooting
Device not appearing in dashboard
- Check agent logs:
docker logs connex-agent - Management URL reachable?
curl http://<host>/api/fleet/devices/stats - Enrollment token expired? These tokens are short-lived by design — register the device again (or reissue a token from Certificate Management) to get a fresh one
Device shows "Offline"
A device is marked offline if no heartbeat has been received for over 2 minutes:
- Is the agent container running?
docker ps -f name=connex-agent - Check network connectivity to the management server
No connectors reported
The agent discovers connectors by inspecting running Docker containers. Requirements:
- Docker socket must be mounted
- Connector containers must use the ALP-CONNEX naming scheme