Edge Node Configuration

Configuration reference for Expanso Edge nodes.

Minimal Configuration

Only one field is required to run an edge node:

# Core data directory (required)
data_dir: ~/.expanso-edge

With just data_dir configured:

• The edge node runs in local mode (no orchestrator connection)
• Node name defaults to system hostname
• Subdirectories are created automatically
• API server is disabled by default
• Logging defaults to info level with json format

Common Configurations

Connect to Orchestrator

To connect to Expanso Cloud (most common):

data_dir: ~/.expanso-edge

orchestrator:
  address: nats://orchestrator.expanso.io:4222
  heartbeat_interval: 30s

Custom Node Name

Set a custom node name instead of using the hostname:

data_dir: ~/.expanso-edge
name: edge-production-01

Enable API Server

Enable the local management API:

data_dir: ~/.expanso-edge

api:
  listen_addr: localhost:9010

Warning: The API has no authentication by default. Only enable on trusted networks or add authentication.

Debug Logging

Enable debug logging for troubleshooting:

data_dir: ~/.expanso-edge

log:
  level: debug
  format: text  # Human-readable format

Complete Configuration Reference

All available configuration options:

# Node name - defaults to system hostname
name: edge-node-01

# Name provider for automatic name generation
# Options: "cloud", "hostname", "uuid", "machine-id"
name_provider: hostname

# Core data directory (REQUIRED)
data_dir: /var/lib/expanso-edge

# Local mode - run without orchestrator connection
local_mode: false

# Orchestrator connection settings
orchestrator:
  address: nats://orchestrator.expanso.io:4222
  heartbeat_interval: 30s
  require_tls: true

# API server configuration
api:
  listen_addr: localhost:9010
  auth:
    token: your-api-token-here

# Logging configuration
log:
  level: info  # trace, debug, info, warn, error
  format: json # console, json, text

# Telemetry configuration (OpenTelemetry)
telemetry:
  endpoint: localhost:4317
  protocol: grpc  # grpc or http
  export_interval: 30s
  resource_attributes:
    environment: production
    region: us-west-2

# Graceful shutdown timeout
shutdown_timeout: 30s

# Node labels for selection and filtering
labels:
  region: us-west-2
  environment: production

Configuration Sections

Node Identity

# Node name (defaults to hostname)
name: edge-node-01

# Name generation method
name_provider: hostname  # cloud, hostname, uuid, machine-id

Name Providers:

• hostname: Uses system hostname (default)
• cloud: Fetches from cloud metadata (AWS, GCP, Azure)
• uuid: Generates random UUID
• machine-id: Uses system machine ID

Data Directory

# REQUIRED: Core data directory
data_dir: /var/lib/expanso-edge

Subdirectories (created automatically):

• state/ - Pipeline state and checkpoints
• metrics/ - Metrics data
• temp/ - Temporary files
• auth/ - Credentials from bootstrap
• config.d/ - Dynamic configuration

Orchestrator Connection

orchestrator:
  address: nats://orchestrator.expanso.io:4222
  heartbeat_interval: 30s
  require_tls: true

Key points:

• Address uses NATS protocol
• Credentials populated during bootstrap
• Automatic retry with exponential backoff

API Server

api:
  listen_addr: localhost:9010
  auth:
    token: your-api-token

Authentication options:

• Token: auth.token: "secret"
• Basic: auth.username + auth.password
• None: Omit auth section (not recommended)

Security:

• Default is localhost:9010 (local-only)
• Use reverse proxy for HTTPS and remote access

Logging

log:
  level: info
  format: json

Levels:

• error - Only errors
• warn - Warnings and errors
• info - Informational messages (default)
• debug - Detailed debugging
• trace - Very detailed tracing

Formats:

• json - Structured JSON (recommended for production)
• text - Human-readable text
• console - Colored console output

Telemetry

telemetry:
  endpoint: localhost:4317
  protocol: grpc
  export_interval: 30s
  resource_attributes:
    environment: production
    region: us-west-2

Protocols:

• grpc - OTLP over gRPC (default, port 4317)
• http - OTLP over HTTP (port 4318)

Labels

labels:
  region: us-west-2
  environment: production
  hardware: gpu

Labels are used for:

• Node selection in deployment targeting
• Filtering nodes in orchestrator UI
• Grouping metrics and logs

Environment Variables

All configuration can be overridden with environment variables:

# Core settings
export EXPANSO_EDGE_NAME=edge-node-01
export EXPANSO_EDGE_DATA_DIR=/var/lib/expanso-edge

# Orchestrator
export EXPANSO_EDGE_ORCHESTRATOR_ADDRESS=nats://orchestrator.expanso.io:4222

# API
export EXPANSO_EDGE_API_LISTEN_ADDR=localhost:9010

# Logging
export EXPANSO_EDGE_LOG_LEVEL=debug
export EXPANSO_EDGE_LOG_FORMAT=text

Environment variables take precedence over file configuration.

Configuration File Locations

The edge node looks for configuration in these locations (in order):

1. Path specified with --config flag
2. ./expanso-edge.yaml (current directory)
3. ~/.expanso-edge/config.yaml
4. /etc/expanso-edge/config.yaml

Example Configurations

Production Deployment

name: edge-prod-${HOSTNAME}
data_dir: /var/lib/expanso-edge

orchestrator:
  address: nats://orchestrator.expanso.io:4222
  heartbeat_interval: 60s
  require_tls: true

api:
  listen_addr: localhost:9010
  auth:
    token: ${API_TOKEN}

log:
  level: info
  format: json

telemetry:
  endpoint: collector.expanso.io:4317
  protocol: grpc
  resource_attributes:
    environment: production
    region: us-west-2

labels:
  environment: production
  region: us-west-2

Development/Testing

name: dev-edge
data_dir: ./dev-data

local_mode: true  # No orchestrator

api:
  listen_addr: localhost:9010

log:
  level: debug
  format: text

telemetry:
  do_not_track: true  # Disable telemetry

High-Security Environment

name: secure-edge-01
data_dir: /var/lib/expanso-edge

orchestrator:
  address: nats://orchestrator.internal:4222
  require_tls: true

api:
  listen_addr: localhost:9010  # Local-only
  auth:
    username: admin
    password: ${ADMIN_PASSWORD}

log:
  level: warn
  format: json

telemetry:
  endpoint: internal-collector:4317
  protocol: grpc

Validation

The edge node validates configuration on startup:

• data_dir is required
• orchestrator.heartbeat_interval must be positive
• log.level must be valid option
• log.format must be valid option
• telemetry.protocol must be "grpc" or "http"

Invalid configuration will cause startup failure with clear error messages.

Next Steps

• Installation Guide - Install Expanso Edge
• Quick Start - Build your first pipeline