plexsphere

Appearance

Operate reachability ​

A Domain's ReachabilityPolicy decides when a Node moves Healthy → Stale → Unreachable. There is no plexctl reachability command yet — plexctl wraps no reachability subcommand — so this guide drives /v1/nodes/{id}/reachability with curl.

Prerequisites ​

  • An authenticated session — see Log in with plexctl.
  • kubectl to scale plexd for the transition test.

Bind the three placeholders the steps reference. PLEXSPHERE_URL is the control-plane URL; TOKEN reuses the bearer token plexctl login persisted to the default profile (or set PLEXSPHERE_TOKEN directly for a service token); NODE_ID is the Node UUID — list Nodes with GET /v1/nodes, or take it from Register a Node:

shell
export PLEXSPHERE_URL="${PLEXSPHERE_URL:-https://localhost:8080}"
TOKEN="$(jq -r '.profiles[.default].token' ~/.config/plexctl/config.json)"
NODE_ID=<node-uuid>

Steps ​

Read the reachability projection ​

shell
curl --silent --show-error --fail-with-body \
  -H "Authorization: Bearer ${TOKEN}" \
  "${PLEXSPHERE_URL}/v1/nodes/${NODE_ID}/reachability"
# {"state":"healthy","last_heartbeat_at":"2026-04-27T10:15:30Z","changed_at":"2026-04-27T10:15:30Z"}

A Healthy Node reports a last_heartbeat_at that advances by heartbeat_interval (30 s by default; stale_after = 90s, unreachable_after = 300s).

Drive a transition ​

shell
kubectl scale deploy/plexd --replicas=0      # stop heartbeats
# wait > stale_after  → state: stale
# wait > unreachable_after → state: unreachable
kubectl scale deploy/plexd --replicas=1      # resume → state: healthy

Verification ​

shell
curl -s -H "Authorization: Bearer ${TOKEN}" \
  "${PLEXSPHERE_URL}/v1/nodes/${NODE_ID}/reachability" | jq '.state'
# "healthy"

See also ​