Skip to main content

Deploy to Cloud

This guide walks you through deploying a pipeline to Expanso Cloud. You'll configure the CLI, write a job file, and deploy it to your connected edge nodes.

Prerequisites
  • An Expanso Cloud account (cloud.expanso.io)
  • A bootstrap token (from Cloud → Settings → Tokens)
  • An edge node installed and connected to your cloud network — see Installation for setup instructions
  • expanso-cli installed (curl -fsSL https://get.expanso.io/cli/install.sh | bash)

Step 1: Configure the CLI​

The CLI needs your cloud endpoint and auth token.

Find your endpoint: Your CLI endpoint follows this pattern:

https://<network-id>.<region>.cloud.expanso.io:9010

To find your network ID:

  • Option A: Log into cloud.expanso.io → Settings → Network ID
  • Option B: Read it from a running edge node's config:
cat /var/lib/expanso/edge/config.d/50-connection.yaml
# Look for: address: nats://<network-id>.<region>.cloud.expanso.io:4222
# Use the same network-id but with port 9010 for the CLI

Save a profile:

expanso-cli profile save my-cloud \
  --endpoint https://YOUR_NETWORK_ID.us1.cloud.expanso.io:9010 \
  --auth-token your-token-here \
  --select
Same Token

The same bootstrap token (EXPANSO_EDGE_BOOTSTRAP_TOKEN) works as the --auth-token for expanso-cli. You don't need a separate API key.

Step 2: Verify the Node Connected​

expanso-cli node list

You should see your node with state connected:

 ID       │ NAME      │ STATE     │ VERSION
 abc12345 │ my-edge   │ connected │ v2.1.7

If your node doesn't appear, check that it started successfully and can reach your cloud network. See Installation for troubleshooting.

Step 3: Create a Job File​

Pipelines deployed via expanso-cli use the job wrapper format — the pipeline config is nested under a config: key with name and type at the top level.

hello-world-job.yaml
name: hello-world
type: pipeline
config:
  input:
    generate:
      mapping: |
        root.message = "hello from the edge"
        root.timestamp = now()
      interval: 5s
  pipeline:
    processors: []
  output:
    stdout: {}
Pipeline Config vs Job Format

Do not use pipeline config format (with input/pipeline/output at the root level) for expanso-cli job deploy. That format is only for expanso-edge run --config. See Build Your First Pipeline for the pipeline config format.

Validate before deploying:

expanso-cli job validate hello-world-job.yaml --offline

Step 4: Deploy​

expanso-cli job deploy hello-world-job.yaml

Output:

Job 'hello-world' created successfully in namespace ''

Step 5: Verify​

# Check job status
expanso-cli job describe hello-world

# List executions on nodes
expanso-cli execution list --job-id $(expanso-cli job describe hello-world 2>&1 | grep '^ID' | awk '{print $NF}')

Updating a Pipeline​

To update a running pipeline, edit the job file and redeploy:

expanso-cli job deploy hello-world-job.yaml --force

The --force flag applies the update even if the config hasn't changed (useful for restarting).

Converting Pipeline Config to Job Format​

If you have an existing pipeline config file (used with expanso-edge run --config), convert it to job format by:

  1. Adding name and type: pipeline at the top level
  2. Indenting the entire pipeline config under a config: key

Before (pipeline config):

input:
  file:
    paths: ["./data.json"]
pipeline:
  processors:
    - mapping: "root = this"
output:
  stdout: {}

After (job wrapper):

name: my-file-processor
type: pipeline
config:
  input:
    file:
      paths: ["./data.json"]
  pipeline:
    processors:
      - mapping: "root = this"
  output:
    stdout: {}

Next Steps​