Skip to main content

Workspaces & Nodes

Workspaces and nodes are how you organize and run pipelines across your infrastructure.

Workspaces​

A workspace is a logical grouping of nodes that work together.

Purpose​

Workspaces help you:

  • Organize nodes by environment, region, or project
  • Isolate workloads between teams or applications
  • Manage permissions with role-based access
  • Deploy pipelines to groups of nodes

Common Patterns​

By Environment:

├── dev-workspace        → 5 development nodes
├── staging-workspace    → 3 staging nodes
└── production-workspace → 20 production nodes

By Geography:

├── us-east-workspace    → Nodes in US East region
├── eu-west-workspace    → Nodes in EU West region
└── ap-south-workspace   → Nodes in Asia Pacific

By Team/Project:

├── team-data-workspace   → Data engineering nodes
├── team-ml-workspace     → ML inference nodes
└── iot-project-workspace → IoT sensor nodes

Workspace Isolation​

What's isolated:

  • Nodes can only see other nodes in same workspace
  • Pipelines deploy only to nodes in same workspace
  • Metrics and logs scoped to workspace

What's shared:

  • User accounts span workspaces
  • Billing is account-level

Creating Workspaces​

Every organization starts with a Default workspace, created automatically at signup. Organizations can have up to 3 workspaces in total (the Default counts toward this limit); contact support if you need more.

Via Cloud UI:

  1. Open the workspace dropdown in the top navigation
  2. Click "Create Workspace"
  3. Enter a name (letters, numbers, and dashes)
  4. Click "Create Workspace"

Nodes​

An edge node is the lightweight runtime that executes data pipelines on your infrastructure.

What is a Node?​

A node is:

  • A lightweight daemon (a single binary)
  • Runs on your infrastructure (bare metal, VMs, containers, edge devices)
  • Executes one or more pipelines
  • Reports metrics to Expanso Cloud

Resource Requirements​

A node runs comfortably on modest hardware. Actual CPU, memory, and disk usage depend on the number of pipelines, data volume, buffering, and transformation complexity.

Node Lifecycle​

1. Bootstrap — Register with Expanso Cloud using a bootstrap token:

expanso-edge bootstrap --token YOUR_TOKEN

The node receives credentials and workspace assignment.

2. Connect — Establish secure TLS connection to control plane. The node registers with its assigned workspace, receives initial configuration, and begins health reporting.

3. Execute — Run assigned pipelines: download configs, process data, report metrics and status.

4. Update — Receive configuration updates as pipelines are deployed, updated, or removed.

Deployment Options​

Bare metal / VMs:

curl -sL https://get.expanso.io/edge/install.sh | bash
expanso-edge bootstrap --token TOKEN

Docker:

docker run ghcr.io/expanso-io/expanso-edge:latest run \
  --bootstrap-token <TOKEN>

Kubernetes:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: expanso-edge
spec:
  template:
    spec:
      containers:
      - name: expanso-edge
        image: ghcr.io/expanso-io/expanso-edge:latest
        env:
        - name: EXPANSO_EDGE_BOOTSTRAP_TOKEN
          value: YOUR_TOKEN

Edge devices: Raspberry Pi, IoT gateways, industrial PLCs.

Health & Monitoring​

Nodes send heartbeats every 15 seconds by default, reporting:

  • Connection status: Connected/disconnected
  • Pipeline status: Running/stopped/failed
  • Resource usage: CPU, memory, disk
  • Error conditions: Recent errors and warnings

The heartbeat interval is configurable per workspace through connectivity profiles (Stable network, Balanced, and Unreliable network).

Labels and Selectors​

Use labels on nodes to target specific groups within a workspace:

# Node labels (set during bootstrap or via configuration)
labels:
  env: production
  region: us-east-1
  datacenter: dc-1
  role: log-processor

Deploy pipelines using selectors:

# Deploy only to production log processors in us-east-1
selector:
  env: production
  region: us-east-1
  role: log-processor

Labels enable gradual rollouts, environment-specific deployments, role-based targeting, and monitoring filters.

What's Next?​

👉 Pipelines - Learn about data flow definitions

👉 Deploy a Node - Get hands-on