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 your workspace Keys tab, under Bootstrap Tokens)
  • An edge node installed and connected to your workspace — 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 an API key.

Find your endpoint: Your CLI endpoint follows this pattern:

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

To find your workspace ID:

  • Option A: Open the workspace in cloud.expanso.io. The ID is the ID badge at the top of the page.
  • 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://<workspace-id>.<region>.cloud.expanso.io:4222
# Use the same workspace-id but with port 9010 for the CLI

Save a profile:

Create an API key from your workspace Keys tab (API Keys → Create API Key). The API Access dialog on the workspace Overview also shows your endpoint and generates this command for you.

expanso-cli profile save my-cloud \
  --endpoint https://YOUR_WORKSPACE_ID.us2.cloud.expanso.io:9010 \
  --api-key exp_ak_YOUR_KEY \
  --select
note

The bootstrap token (exp_bk_...) only registers edge nodes; it cannot authenticate the CLI. Use an API key (exp_ak_...) instead.

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 workspace. 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 pass pipeline config format (with input/pipeline/output at the root level) to expanso-cli job deploy. That format is the pipeline itself: it is what expanso-edge validate checks and what gets nested under config: here. Nothing runs it directly — in particular expanso-edge run --config loads agent settings and will ignore it. 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 deploy even if the spec hasn't changed. To restart a job with the spec it already has, use expanso-cli job rerun hello-world instead.

Converting Pipeline Config to Job Format​

If you have an existing pipeline config file — input/pipeline/output at the root level — 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​