Skip to main content

CLI Reference

Kymaros uses standard Kubernetes custom resources. All management is done through kubectl. This page collects the most useful commands organized by task.

The examples assume Kymaros is installed in kymaros-system. Substitute your namespace if different.

RestoreTest commands​

List all tests​

kubectl get rt -n kymaros-system

Print columns: Name, Phase, Score, Result, Last Run, Age.

List with wider output​

kubectl get rt -n kymaros-system -o wide

Describe a test (full spec and status)​

kubectl describe rt my-app-nightly -n kymaros-system

Watch status in real time​

kubectl get rt -n kymaros-system -w

Show only the current phase​

kubectl get rt my-app-nightly -n kymaros-system \
  -o jsonpath='{.status.phase}{"\n"}'

Show next scheduled run​

kubectl get rt my-app-nightly -n kymaros-system \
  -o jsonpath='{.status.nextRunAt}{"\n"}'

Edit a test​

kubectl edit rt my-app-nightly -n kymaros-system

Delete a test​

kubectl delete rt my-app-nightly -n kymaros-system

Associated RestoreReport objects are garbage-collected automatically via owner references.

Triggering tests manually​

Kymaros exposes an annotation that the controller watches to trigger an immediate out-of-schedule run. Set the annotation, and the controller will begin a run within one reconciliation cycle.

kubectl annotate rt my-app-nightly \
  -n kymaros-system \
  restore.kymaros.io/trigger="$(date -u +%Y%m%dT%H%M%SZ)" \
  --overwrite

Alternatively, use the REST API trigger endpoint:

kubectl port-forward -n kymaros-system svc/kymaros-api 8080:8080 &
curl -X POST http://localhost:8080/api/v1/tests/my-app-nightly/trigger

Watch a triggered run to completion​

kubectl get rt my-app-nightly -n kymaros-system -w

Wait until Phase transitions from Running back to Completed or Failed.

RestoreReport commands​

List all reports​

kubectl get rr -n kymaros-system

Print columns: Name, Score, Result, Test, Age.

List reports for a specific test​

kubectl get rr -n kymaros-system -l kymaros.io/test=my-app-nightly

Show the most recent report for a test​

kubectl get rr -n kymaros-system \
  -l kymaros.io/test=my-app-nightly \
  --sort-by=.metadata.creationTimestamp \
  | tail -n 1

Describe a report (full status with all check results)​

kubectl describe rr my-app-nightly-20240315-030012 -n kymaros-system

Get the score from a specific report​

kubectl get rr my-app-nightly-20240315-030012 -n kymaros-system \
  -o jsonpath='{.status.score}{"\n"}'

List all check results from a report​

kubectl get rr my-app-nightly-20240315-030012 -n kymaros-system \
  -o jsonpath='{range .status.checks[*]}{.name}{"\t"}{.status}{"\t"}{.message}{"\n"}{end}'

List all failed reports across all tests​

kubectl get rr -n kymaros-system \
  -o jsonpath='{range .items[?(@.status.result=="fail")]}{.metadata.name}{"\n"}{end}'

Show RTO measurement for a report​

kubectl get rr my-app-nightly-20240315-030012 -n kymaros-system \
  -o jsonpath='measured={.status.rto.measured} target={.status.rto.target} withinSLA={.status.rto.withinSLA}{"\n"}'

Get completeness counts​

kubectl get rr my-app-nightly-20240315-030012 -n kymaros-system \
  -o jsonpath='{.status.completeness}' | python3 -m json.tool

HealthCheckPolicy commands​

List all policies​

kubectl get hcp -n kymaros-system

Describe a policy (shows all check definitions)​

kubectl describe hcp web-api-health-policy -n kymaros-system

List check names and types for a policy​

kubectl get hcp web-api-health-policy -n kymaros-system \
  -o jsonpath='{range .spec.checks[*]}{.name}{"\t"}{.type}{"\n"}{end}'

Log inspection​

Controller logs (follow)​

kubectl logs -n kymaros-system deploy/kymaros-controller -f

Controller logs filtered to a specific test​

kubectl logs -n kymaros-system deploy/kymaros-controller \
  | grep my-app-nightly

API server logs​

kubectl logs -n kymaros-system deploy/kymaros-api -f

Previous container logs (after a crash)​

kubectl logs -n kymaros-system deploy/kymaros-controller --previous

Port-forwarding​

Access the API server locally​

kubectl port-forward -n kymaros-system svc/kymaros-api 8080:8080

The API is then available at http://localhost:8080.

Access the dashboard locally​

kubectl port-forward -n kymaros-system svc/kymaros-frontend 3000:80

The dashboard is then available at http://localhost:3000.

Sandbox namespace inspection​

The controller creates sandbox namespaces during test runs. These are visible as standard Kubernetes namespaces and are automatically deleted after the TTL expires.

List active sandbox namespaces​

kubectl get ns | grep rp-test

Inspect pods in a sandbox​

kubectl get pods -n rp-test-my-app

Get events in a sandbox (useful when pods fail to start)​

kubectl get events -n rp-test-my-app --sort-by=.lastTimestamp

Describe a failing pod in a sandbox​

kubectl describe pod <pod-name> -n rp-test-my-app

View pod logs in a sandbox​

kubectl logs <pod-name> -n rp-test-my-app

Force-delete a stuck sandbox namespace​

If a sandbox namespace is stuck in Terminating (typically due to a finalizer on a PVC or network policy), identify and remove the blocking finalizer:

# Check what is blocking termination
kubectl get ns rp-test-my-app -o jsonpath='{.spec.finalizers}'

# Remove finalizers from the namespace (use with caution)
kubectl patch ns rp-test-my-app \
  -p '{"spec":{"finalizers":[]}}' \
  --type=merge

Debugging​

Check CRD registration​

kubectl get crd | grep kymaros

Expected output:

healthcheckpolicies.restore.kymaros.io    <timestamp>
restorereports.restore.kymaros.io         <timestamp>
restoretests.restore.kymaros.io           <timestamp>

Check controller leader election​

kubectl get lease -n kymaros-system

Verify RBAC permissions​

kubectl auth can-i create namespaces --as=system:serviceaccount:kymaros-system:kymaros
kubectl auth can-i create restores.velero.io --as=system:serviceaccount:kymaros-system:kymaros -n velero

Dump full controller state for a test (useful for filing bug reports)​

kubectl get rt my-app-nightly -n kymaros-system -o yaml
kubectl get rr -n kymaros-system -l kymaros.io/test=my-app-nightly -o yaml
kubectl logs -n kymaros-system deploy/kymaros-controller --tail=200