shardpostctl-server(1) – ShardPost docs

SHARDPOSTCTL-SERVER(1)

ShardPost Manual

SHARDPOSTCTL-SERVER(1)

NAME

shardpostctl-server - version, state and registrations of ShardPost servers

SYNOPSIS

shardpostctl version
shardpostctl server status [--json]
shardpostctl server list [--json]

DESCRIPTION

The commands ask the server about itself and about the processes registered in the store. None touches an account.

version

Prints the version of the server the client is talking to and the Go version it was built with. Use it to check which build answers on this socket or endpoint, for example after a rollout.

Role: diagnose.

server status

Prints the state of this one server process:

version: Server version.
instance: Name of the process, in the cluster the pod name. Two pods serve the same accounts, so the same command can answer from either one.
started: When the process started.
config fingerprint: Hash over the effective configuration, with secrets left out. Two servers that answer with different fingerprints run different configurations, which is almost always a rollout that did not finish.
store: Result of a ping against the RADOS store, plus the pools in use.
placement: Where the store's own namespaces (admin store, account directory, queues) live, as the server's last placement check found it: none (the index pool), native or migrated (the system pool of ceph.system_pool, initialized there or migrated there, with its name and pool id), or unknown (the last check could not read; the server goes on). A server checks it every minute and ends when it reads a placement that contradicts its configuration.

Requires the role diagnose.

server list

Lists the registrations of the processes that use the store, one line per instance: every server, every job runner, the JMAP push workers, scrubs, sweeps and backfills register at startup and every minute (servers/<instance> in the admin store) and record their orderly end. Columns:

INSTANCE: The pod name for a server; host-push for the JMAP push worker and host-runner for a job runner (both stable across restarts of their container); host-role-random for the other processes, which may run in a server's pod.
ROLE: serve, runner (a job runner pod, shardpost runner), push, scrub, backfill or sweep; serve (before 0.47) for a registration without a role.
VERSION: The version of the process.
SYSTEM POOL: The system pool the process works with, by name and id; - when the store's own namespaces live in the index pool.
RUNNING: true while the registration was renewed within three minutes and the process has not ended in order. A process that crashed stays true for up to three minutes after its last heartbeat.
SEEN, STARTED, STOPPED: The last heartbeat, the start of the process and its orderly end (- while it runs or after a crash).
WORKERS: For a server: whether it runs the background workers (the job runner, the expiry workers, the delayed submission worker, the learning worker), that is workers.run (WORKERS_RUN). false is a front-end in a deployment with job runners; - for the other roles and for servers before 0.52.0.
PARTITIONS, WATCHED: For the JMAP push worker: the push partitions it holds (of 64) and the accounts with push subscriptions it watches, as of its last heartbeat; - for the other roles. The partitions of all fresh push workers together should reach 64; see docs/jmap.md.

A registration not renewed for 24 hours is deleted. With admin.kv_index other than read the command lists the admin namespace. Requires the role diagnose.

OPTIONS

--json: Print the answer as JSON instead of a table.

EXAMPLES

What runs against the store right now, with which role and system pool?

shardpostctl server list
shardpostctl server list --json | jq -r '.servers[] | select(.fresh) | .instance'

Do the push workers hold every partition between them?

shardpostctl server list --json \


    | jq '[.servers[] | select(.fresh and .role == "push") | .partitions] | add'

Which build is live, and do both pods agree on their configuration?

for p in $(kubectl -n shardpost get pod \


        -l app.kubernetes.io/name=shardpost-server -o name); do


    kubectl -n shardpost exec $p -c import -- \


        shardpostctl server status
done

Version only, for a deployment check:

shardpostctl version

Feed the state into a monitoring script:

shardpostctl server status --json | jq -r '.store.ok, .config_fingerprint'

EXIT STATUS

0: The server answered.
75: The server is not reachable, or server list asked a server without an admin store (the registrations are not available there). A server that answers but cannot reach its store is not a failure of the command: it prints store unavailable with the reason and exits 0 — that is the answer you asked for.
77: The caller lacks the role diagnose.