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​

The pipeline runs inside the edge agent, so the variables have to be in the agent's environment. Set them in your shell before starting the agent, then deploy the pipeline as a job with expanso-cli job deploy:

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

expanso-edge run --config /etc/expanso/edge-config.yaml

Or inline for a single command:

KAFKA_BROKER="kafka.example.com:9092" KAFKA_TOPIC="events" \
  expanso-edge run --config /etc/expanso/edge-config.yaml
--config takes agent settings, not pipeline YAML

expanso-edge run --config loads the agent configuration. Passing pipeline.yaml to it reports the input, pipeline and output keys as unknown fields and ignores them: the agent starts and your pipeline never runs. Pipelines execute as jobs — see Deploy to Cloud.

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 the agent
source /etc/expanso/pipeline.env
expanso-edge run --config /etc/expanso/edge-config.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)/edge-config.yaml:/etc/expanso/edge-config.yaml:ro \
  ghcr.io/expanso-io/expanso-edge:latest \
  run --config /etc/expanso/edge-config.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/var/lib/expanso/edge or ~/.expanso/edge
EXPANSO_EDGE_LOG_LEVELLog level (debug, info, warn, error)info
EXPANSO_EDGE_LOG_FORMATLog format (json, text, console)console
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 /etc/expanso/edge-config.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​