A tour of zshell

The operator's interface to a Samoza cluster — system status, mesh, topologies, cluster, spaces.

zshell is the day-to-day interface for operating a Samoza cluster. It speaks to all the services — zbase, zmesh, zrms, zrun — through a single command surface, with friendly tabular output.

Start it

./bin/zshell
zshell[0] >>

Each prompt has a counter so you can refer back to earlier commands. By default it talks to the local services on their default ports; override with environment variables (see below).

The first command: status

status gives you the whole stack at a glance:

zshell[0] >> status
zshell:
  zbase=connected assistant=enabled uptime=5m32s
zmesh:
  status=connected zhost=zhost-alpha mode=super connections=3
zrms:
  status=connected zhost=zhost-alpha mode=super topologies=2/5
zrun:
  status=connected spaces=4

Status values: connected, unreachable, error.

Mesh — the network

The mesh is the overlay network connecting zhosts.

zshell[0] >> mesh
zmesh: http://127.0.0.1:9200 (connected)
  zhost_id:    zhost-alpha
  cluster_id:  production
  mode:        super
  connections: 3
  cluster_peers: zhost-beta, zhost-gamma

zshell[1] >> mesh ping
MESH PING broadcast (hops=2, timeout=10s)

ZHOST_ID                             HOPS  RTT(ms)  PATH
--------------------------------------------------------------------
+ zhost-beta                            1     2.34  (direct)
+ zhost-gamma                           1     3.12  (direct)
+ zhost-delta                           2     8.45  zhost-beta -> zhost-delta

mesh ping <target> pings a specific zhost. mesh peers lists cluster members. mesh spaces lists every registered space across the cluster (so you know where workloads are running).

Topologies — the apps

zshell[0] >> topo
Topologies: 2

ID                                   NAME             STATE      SPACES
------------------------------------------------------------------------------
a1b2c3d4-e5f6-7890-abcd-ef1234567890 web-application  running    3
f0e1d2c3-b4a5-6789-0fed-cba987654321 data-pipeline    running    2

Common operations:

> topo submit ./my-app.yaml          # deploy a topology YAML
> topo status <id>                   # detailed view with placements
> topo stop <id>                     # gracefully stop

A topology’s status view shows where each of its spaces is running — useful for tracking placement decisions.

Cluster — the zhosts

zshell[0] >> cluster
zrms: http://127.0.0.1:7331 (connected)
  zhost_id: zhost-alpha
  mode:     super
  uptime:   2h15m30s

Topologies:
  total:   5  running: 3  failed:  1

Cluster:
  zhosts:   4  healthy:  3  degraded: 1

zshell[1] >> cluster zhosts
ID            HOSTNAME             MODE     STATUS
---------------------------------------------------------
zhost-alpha   server1.example.com  super    healthy
zhost-beta    server2.example.com  local    healthy
zhost-gamma   server3.example.com  local    healthy
zhost-delta   server4.example.com  local    degraded

degraded means a node missed recent heartbeats. If it stays degraded long enough, zrms declares it failed and re-places its workloads.

Spaces — what’s running locally

zshell[0] >> spaces
Running spaces: 3

SPACE_NAME           STATE      TOPOLOGY              STARTED
------------------------------------------------------------------
web-frontend         running    a1b2c3d4-…            10:30
api-gateway          running    a1b2c3d4-…            10:30
worker-1             running    f0e1d2c3-…            09:15

zshell[1] >> spaces status web-frontend
Space: web-frontend
  instance_id: inst-abc123
  topology_id: a1b2c3d4-…
  state:       running
  started_at:  10:30:00Z

Config:
  type:         UI
  wasm_path:    /var/lib/samoza/wimages/web-frontend.wasm
  capabilities: sys.log, net.emit_to, net.recv_next

Runtime:
  uptime:             4h30m15s
  messages_processed: 12847
  agents_invoked:     3521

Configuration

zshell reads these environment variables:

So pointing zshell at a remote control plane is just:

export SAMOZA_ZMESH_URL=http://mesh-node.internal:9200
export SAMOZA_ZRMS_URL=http://scheduler.internal:7331
zshell

Command reference (short)

Next

You can now stand up clusters and run things on them. For the model behind it all, head to concepts. For deeper operational concerns — topology lifecycle, troubleshooting, recovery — head to operate.