Skip to main content

Environment Variables

Expanso Edge follows 12-factor app principles for configuration. Environment variables separate configuration from code, letting you change settings across environments without modifying pipeline definitions.

How Environment Variables Work​

Expanso Edge reads environment variables at two key times:

  1. Agent startup - The edge agent reads EXPANSO_EDGE_* variables when the process starts
  2. Pipeline initialization - Pipeline configurations using ${VAR_NAME} syntax are resolved when a pipeline starts

Key Behavior​

  • Variables are read once at startup or pipeline initialization
  • Changes require a restart to take effect
  • The edge agent inherits variables from whatever process launched it (shell, systemd, Docker, Kubernetes)

Using Environment Variables in Pipelines​

Reference environment variables using the ${VAR_NAME} syntax:

pipeline.yaml
input:
  kafka:
    addresses:
      - ${KAFKA_BROKER}
    topics:
      - ${KAFKA_TOPIC}
    sasl:
      user: ${KAFKA_USERNAME}
      password: ${KAFKA_PASSWORD}

output:
  http_client:
    url: ${API_ENDPOINT}/events
    headers:
      Authorization: Bearer ${API_TOKEN}

Variables are resolved when the pipeline starts. If a variable isn't set, the literal string ${VAR_NAME} appears in the configuration (which usually causes an error).

For detailed interpolation patterns, see Local Secrets.

Providing Environment Variables​

How you provide environment variables depends on how you run Expanso Edge.

Direct Execution​

Set variables in your shell before running the agent:

export KAFKA_BROKER="kafka.example.com:9092"
export KAFKA_TOPIC="events"
export API_TOKEN="your-api-token"

expanso-edge run --config pipeline.yaml

Or inline for a single command:

KAFKA_BROKER="kafka.example.com:9092" KAFKA_TOPIC="events" \
  expanso-edge run --config pipeline.yaml

Environment Files​

Store variables in a file and load them before starting:

/etc/expanso/pipeline.env
KAFKA_BROKER=kafka.example.com:9092
KAFKA_TOPIC=events
KAFKA_USERNAME=[email protected]
KAFKA_PASSWORD=secure-password
API_TOKEN=your-api-token
# Load variables and start
source /etc/expanso/pipeline.env
expanso-edge run --config pipeline.yaml

Updating Environment Variables​

Environment variables are read once when the edge agent or pipeline starts. To apply changes:

  1. Update the environment variables in your source (file, secret store, etc.)
  2. Restart the edge agent to pick up the new values

Systemd​

# Edit the environment file
sudo nano /etc/expanso/pipeline.env

# Restart to apply changes
sudo systemctl restart expanso-edge

To reload the systemd service definition (if you changed the service file):

sudo systemctl daemon-reload
sudo systemctl restart expanso-edge

Docker​

# Stop and remove the container
docker stop expanso-edge
docker rm expanso-edge

# Start with new variables
docker run -d \
  --name expanso-edge \
  -e KAFKA_BROKER="new-broker.example.com:9092" \
  -v $(pwd)/pipeline.yaml:/etc/expanso/pipeline.yaml:ro \
  ghcr.io/expanso-io/expanso-edge:latest \
  run --config /etc/expanso/pipeline.yaml

Or with Docker Compose:

# Update .env file or docker-compose.yml
docker compose down
docker compose up -d

Kubernetes​

Update the Secret or ConfigMap, then restart the pods:

# Update the secret
kubectl create secret generic pipeline-credentials \
  --from-literal=API_TOKEN='new-token' \
  --namespace=expanso-system \
  --dry-run=client -o yaml | kubectl apply -f -

# Restart pods to pick up changes
kubectl rollout restart deployment/expanso-edge -n expanso-system

Edge Agent Configuration Variables​

The edge agent accepts configuration through EXPANSO_EDGE_* environment variables:

VariableDescriptionDefault
EXPANSO_EDGE_NAMENode nameSystem hostname
EXPANSO_EDGE_DATA_DIRData directory~/.expanso-edge
EXPANSO_EDGE_LOG_LEVELLog level (debug, info, warn, error)info
EXPANSO_EDGE_LOG_FORMATLog format (json, text, console)json
EXPANSO_EDGE_API_LISTEN_ADDRAPI server addresslocalhost:9010

These override values in the configuration file. For the complete list, see Edge Node Configuration.

Security Best Practices​

Restrict File Permissions​

Keep environment files readable only by the service user:

sudo chmod 600 /etc/expanso/pipeline.env
sudo chown expanso:expanso /etc/expanso/pipeline.env

Don't Commit Secrets​

Add environment files to .gitignore:

.env
*.env
pipeline.env
secrets/

Use a Template​

Provide a template showing required variables without actual values:

pipeline.env.template
# Copy to pipeline.env and fill in values
KAFKA_BROKER=
KAFKA_TOPIC=
KAFKA_USERNAME=
KAFKA_PASSWORD=
API_TOKEN=

Validate Before Starting​

Check that required variables are set:

#!/bin/bash
REQUIRED_VARS="KAFKA_BROKER KAFKA_TOPIC API_TOKEN"

for var in $REQUIRED_VARS; do
  if [ -z "${!var}" ]; then
    echo "Error: $var is not set"
    exit 1
  fi
done

expanso-edge run --config pipeline.yaml

Troubleshooting​

Variable Not Resolved​

Symptom: Literal ${VAR_NAME} appears in logs or errors

Cause: The environment variable wasn't set when the pipeline started

Solution:

# Check if the variable is set
echo $VAR_NAME

# Set it and restart
export VAR_NAME="value"
sudo systemctl restart expanso-edge

Changes Not Taking Effect​

Symptom: Updated environment variables aren't being used

Cause: The edge agent reads variables at startup, not dynamically

Solution: Restart the edge agent after changing variables:

sudo systemctl restart expanso-edge

Systemd Not Loading Environment File​

Symptom: Variables are set in the file but not available to the service

Solution: Verify the EnvironmentFile directive in the service file:

# Check the service configuration
sudo systemctl cat expanso-edge | grep EnvironmentFile

# Reload and restart
sudo systemctl daemon-reload
sudo systemctl restart expanso-edge

Next Steps​