Edge Connector
Edge connector mode polls ilert for events and delivers them to local on-premise targets via HTTP, Kafka, MQTT, script execution, or stdout.
Edge connector mode turns ilagent into a local delivery agent for ilert edge connections. Instead of pushing events from your infrastructure to ilert, the edge connector pulls events from the ilert API and delivers them to a target inside your network.
This is useful when:
Your on-premise systems cannot be reached from the internet
You need to fan-out ilert alert lifecycle events to internal tools (ticketing, automation, dashboards)
You want reliable local delivery with cursor-based at-least-once semantics
Quick start
export ILERT_EDGE_CONNECTOR_KEY='iec1...'
ilagent daemon -v -v -p 8977 \
--edge_mode http \
--edge_http_url http://localhost:9090/webhookThe agent will poll ilert for new events and POST them to your local webhook endpoint. The -p 8977 flag enables the health/readiness endpoints for container orchestration.
Authentication
Edge connector mode requires the ILERT_EDGE_CONNECTOR_KEY environment variable. This key is obtained from an edge connection (alert action) configuration in ilert and is separate from the standard ILERT_API_KEY.
Alert action events are queued server-side for up to 7 days. If they are not polled within that timeframe, they are lost. Make sure your edge connector is running continuously or restarts promptly after downtime.
Delivery modes
HTTP
Delivers events as JSON to a local HTTP endpoint.
--edge_http_url
Target URL (required)
—
--edge_http_method
HTTP method
POST
--edge_http_auth_header
Header name for authentication (e.g. Authorization, X-API-Key)
—
--edge_http_auth_value
Auth header value (falls back to ILERT_EDGE_HTTP_AUTH_VALUE env var)
—
Authentication
If your target endpoint requires authentication, you can attach a custom auth header to every delivery request:
The value can also be passed directly via --edge_http_auth_value, but using the environment variable is recommended to avoid exposing secrets in process listings. Both the header name and value must be set — specifying --edge_http_auth_header without a value will cause ilagent to exit with an error.
Each request includes metadata headers:
X-ilert-Event-Type
Event type (e.g. alert-created, alert-resolved)
X-ilert-Alert-Id
Alert ID
X-ilert-Edge-Item-Id
Unique edge item ID for deduplication
Error handling: 2xx responses are treated as success. 4xx responses (except 429) are considered non-retryable — the item is skipped and the cursor advances. 429 and 5xx responses stop the batch and retry on the next poll cycle.
Kafka
Produces events to a Kafka topic.
--kafka_brokers
Comma-separated broker list (required)
—
--edge_topic
Target topic (required)
—
Messages are keyed by the alert ID from the event payload. The producer uses the default partitioner, which deterministically assigns all messages with the same key to the same partition — this ensures that webhook events for a given alert are delivered in order.
MQTT
Publishes events to an MQTT topic.
-m
MQTT broker host (required)
—
-q
MQTT broker port
1883
--edge_topic
Target topic (required)
—
--mqtt_qos
QoS level (0, 1, 2)
0
--mqtt_username
Username
—
--mqtt_password
Password
—
--mqtt_tls
Enable TLS
—
--mqtt_ca
CA certificate path
—
QoS 0 does not provide broker acknowledgements. The cursor advances after the message is queued locally, not after broker confirmation. Use QoS 1 or 2 for stronger delivery assurance.
Script
Executes a script for each event, piping the JSON payload to stdin.
--edge_script
Path to executable script (required)
—
The script receives environment variables:
ILERT_EVENT_TYPE
Event type
ILERT_ALERT_ID
Alert ID
ILERT_EDGE_ITEM_ID
Unique edge item ID
ILERT_TIMESTAMP
Event timestamp
The full JSON payload is written to stdin. Scripts have a 30-second execution timeout — if exceeded, the process is killed and the delivery is retried.
Example script:
Stdout
Prints each event's JSON payload to stdout — useful for testing, debugging, or piping into other tools.
No additional flags are required. Each polled item is printed as a single JSON line:
Payload format
The JSON payload delivered via all modes (HTTP request body, Kafka/MQTT message value, script stdin) follows the same structure as the ilert custom webhook payload. See Webhook payload for the full schema and field reference.
Health and readiness
Pass -p <port> to enable the HTTP server with health/readiness endpoints:
GET /health
Returns 204 while running, 503 during shutdown
GET /ready
Returns 204 when polling successfully, 503 with diagnostics on error
The /ready endpoint returns structured JSON on failure:
Heartbeat
Use -b to send regular heartbeat pings alongside the edge connector:
This lets you monitor the ilagent process itself via ilert heartbeat monitoring.
High availability
Edge connector supports server-managed HA with leader election:
--edge_cluster_id
Cluster identifier (enables HA)
(disabled)
--edge_instance_id
Unique instance ID
auto-generated UUID
--edge_standby_interval
Standby poll interval
10s
The ilert API manages leader election. Only the leader receives events — standby instances poll at the standby interval waiting to be promoted. If the leader stops reporting, a standby is promoted automatically.
In HA mode, the cursor is managed server-side (not persisted locally in SQLite).
Polling configuration
--edge_poll_interval
Seconds between polls
10
5–120
--edge_standby_interval
Seconds between standby polls (HA)
10
5–120
When a poll returns a full batch (100 items), the edge connector immediately re-polls without waiting — up to 10 consecutive times to drain backlogs. After that, it pauses for one poll interval to prevent starvation.
On consecutive poll failures, the agent applies exponential backoff (starting at 5s, capped at 300s) and resets on the first successful poll.
Delivery semantics
At-least-once — the cursor only advances after successful delivery. On failure, the same item is retried on the next poll cycle.
Ordered — items within a batch are delivered sequentially. A retryable failure stops the batch; remaining items are retried in order.
Non-retryable skip — if the delivery target returns a non-retryable error (HTTP 4xx except 429), the item is logged and skipped to prevent permanent queue blocking.
Cursor persistence — in non-HA mode, the cursor is persisted to SQLite after each successful delivery, surviving process restarts.
Exclusive mode
Edge connector is an exclusive daemon mode. The following flags from other daemon modes cannot be combined with --edge_mode:
Consumer topics:
--event_topic,--heartbeat_topic,--policy_topicConsumer mappings:
--event_key,--map_key_*,--map_val_*,--filter_key,--filter_valConsumer flags:
--forward_message_payload,--mqtt_buffer,--mqtt_shared_groupOther:
--max_retries,--shift_offset
Full example
This runs the edge connector in HA mode with script delivery, health endpoints on port 8977, heartbeat monitoring, and 15-second poll intervals.
Last updated
Was this helpful?