salt.runners.batch¶

Runner module for managing and inspecting async batch jobs.

Provides commands for checking batch status, listing active batches, and stopping running batch jobs.

# Check status of an async batch job
salt-run batch.status 20240610120000000000

# List all active async batch jobs
salt-run batch.list_active

# Stop a running async batch job (graceful drain)
salt-run batch.stop 20240610120000000000

# Stop and kill in-flight minions too
salt-run batch.stop 20240610120000000000 kill=True

salt.runners.batch.list_active()¶

Return a list of all active (non-halted) async batch jobs.

Reads <cachedir>/batch_active.p and returns one summary dict per batch. Entries whose .batch.p is missing or unreadable are silently dropped — Maintenance converges the index on its next pass.

Returns:

List of batch summary dicts.

Return type:

list

CLI Example:

salt-run batch.list_active

salt.runners.batch.status(jid)¶

Return the current status of an async batch job.

Reads .batch.p from the job cache for the given JID and returns a summary dict. Returns None if the JID does not exist or has no .batch.p (e.g. it was never an async batch, or the cache was cleaned).

Parameters:

jid (str) -- The batch JID to query.

Returns:

Summary dict or None.

Return type:

dict or None

CLI Example:

salt-run batch.status 20240610120000000000

salt.runners.batch.stop(jid, kill=False)¶

Stop a running async batch job.

Default (kill=False) is a graceful drain: halts further sub-batch publishes but leaves in-flight minion jobs running. Their returns are still recorded in the job cache via the normal salt/job/*/ret/* path.

With kill=True, also publishes saltutil.kill_job targeted at the batch's currently-active minions before firing the halt event. Safe on minions that have already finished (no-op there).

Returns False if the JID is unknown or already halted.

Parameters:

• jid (str) -- The batch JID to stop.

• kill (bool) -- When True, also terminate in-flight minion jobs via saltutil.kill_job.

Return type:

bool

CLI Example:

salt-run batch.stop 20240610120000000000
salt-run batch.stop 20240610120000000000 kill=True