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

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
  require_tls: true
  # Network identifier (optional)
  # Set automatically during bootstrap, or manually for local development
  network_id: ""

# 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
  require_tls: true
  network_id: ""  # Set automatically during bootstrap

Key points:

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

Network ID:

The network_id field identifies which network the node belongs to. This is set automatically during bootstrap based on the network you're registering the node with. For local development without an orchestrator, you can set this manually (e.g., network_id: "local-dev").

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
  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
• 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