pilotctl command reference
Applies to: Kestowv 0.5.5 enterprise pilot package
Updated
pilotctl operates on one pilot manifest. Run it from the supplied Kestowv pilot package using the supported JRuby runtime.
Syntax#
jruby bin/pilotctl COMMAND MANIFEST [ARG]
MANIFEST is a JSON file. Use an absolute path in runbooks and scheduled operations. KESTOWV_PILOT_STATE_ROOT, when set, overrides the state directory used by operational commands; use the same setting consistently when reading status and metrics. The validate summary reports the manifest's configured directory.
Commands#
| Command | Result | Operational effect |
|---|---|---|
validate MANIFEST |
JSON with valid, pilot name, configured state directory, release and counts. |
Checks the manifest. Does not start services or deploy a release. |
doctor MANIFEST |
Readiness result and individual checks. | Checks the environment, required resources, release source and secret references. Use before deployment. |
workloads MANIFEST |
JSON list of declared workload names and kinds. | Reads configuration. Does not run a workload. |
deploy MANIFEST |
Release activation result. | Changes the active release when its checks succeed. Can restore the previous release after a failed activation check. |
run MANIFEST WORKLOAD |
Result for the named declared workload. | Executes the configured program or comparison and writes result records. |
status MANIFEST |
Latest saved status as JSON. | Reads saved state. It is not an on-demand poll of every service. |
metrics MANIFEST |
Latest saved metrics in Prometheus text format. | Reads the stored metrics snapshot. |
rollback MANIFEST |
Rollback result. | Restores the previous release. The running pilot must then be restarted or reprovisioned using its runbook. |
--help prints usage and succeeds. Supplying no command, an unknown command, or no manifest prints a usage error. The standalone utility does not replace the long-running service supervisor supplied with the pilot.
Exit codes#
| Code | Meaning | Next step |
|---|---|---|
0 |
The command succeeded. | Read the output for the scope of that success. |
1 |
Configuration, input, file or release-integrity error. | Correct the reported cause before retrying. |
2 |
Command usage error. | Check command spelling and required arguments. |
3 |
Deployment did not activate successfully. | Review health results and confirm the active release. |
4 |
The workload did not meet its success condition. | Review errors, timeouts, correctness and applicable thresholds. |
5 |
The readiness check is not ready. | Resolve the failed checks before deployment. |
Capture a status snapshot#
jruby bin/pilotctl status /path/to/pilot.json > pilot-status.json
jruby bin/pilotctl metrics /path/to/pilot.json > pilot-metrics.prom
These are host-shell commands; redirection is performed by that shell. Choose new output filenames when preserving an earlier snapshot. A missing status or metrics file produces an error rather than an invented empty healthy state. Check the manifest and state-directory override, then verify that the pilot has actually written state there.
For deployment and rollback sequencing, see Services, releases and recovery.