opsctl CLI - Autopilot by Xano

opsctl is the command-line interface for Autopilot. It provides interactive cluster analysis, rebalancing, resource prediction, and CRD status inspection without requiring the full controller to be running.

opsctl keeps its original command name — it is a runtime binary, not a brand name.

Installation

Build from source:

make opsctl

The binary is placed at bin/opsctl. Move it onto your PATH:

sudo mv bin/opsctl /usr/local/bin/

Prerequisites:

A valid kubeconfig file (defaults to ~/.kube/config)
For GKE mode: GCP credentials configured (gcloud auth application-default login)
For the predict command: a reachable Prometheus endpoint

Commands

rebalance (default)

Analyze cluster resource distribution and optionally rebalance pods across nodes. This is the default command when no subcommand is specified.

opsctl [flags]

Flag	Default	Description
`--kubeconfig`	`~/.kube/config`	Path to kubeconfig file
`--dry-run`	`true`	Analyze only, do not execute movements
`--min-imbalance`	`0.2`	Minimum imbalance score (0–1) to trigger rebalancing
`--max-movements`	`10`	Maximum pod movements per run
`--target-util`	`0.7`	Target resource utilization (0–1)
`--show-nodes`	`true`	Show node utilization table
`--show-candidates`	`false`	Show pod movement candidates

GKE provision-first mode flags — when --gke is set, opsctl provisions new nodes before migrating workloads, avoiding resource contention during rebalancing:

Flag	Default	Description
`--gke`	`false`	Enable GKE provision-first mode
`--gke-project`	(required)	GCP project ID
`--gke-location`	(required)	GKE cluster location or region
`--gke-cluster`	(required)	GKE cluster name
`--machine-type`	`e2-standard-4`	Machine type for new nodes
`--spot`	`false`	Use spot VMs for new nodes (60–91% cheaper)
`--auto-delete-old`	`false`	Automatically delete old nodes after migration

predict

Predict resource usage trends and detect anomalies using Prometheus historical data.

opsctl predict [flags]

Flag	Default	Description
`--kubeconfig`	`~/.kube/config`	Path to kubeconfig file
`--prometheus-url`	(required)	Prometheus endpoint URL
`--horizon`	`10m`	Prediction time horizon
`--namespace`	(all)	Namespace filter for predictions
`--pod`	(none)	Specific pod name to predict (requires `--namespace`)

When both --namespace and --pod are provided, opsctl runs a detailed single-pod prediction including trend analysis, pattern classification, forecasting, peak estimation, and anomaly detection. When only --namespace is given (or neither), it runs a cluster-wide analysis with node utilization and fragmentation scoring.

status

Show the current state of all Autopilot CRD resources in the cluster.

opsctl status [flags]

Flag	Default	Description
`--kubeconfig`	`~/.kube/config`	Path to kubeconfig file
`--namespace`	(all)	Namespace to query

Displays tables for RebalancePolicy (schedule, dry-run mode, last run), NodeScalingPolicy (min/max nodes, current/desired counts, last action), and PodResizePolicy (resize mode, recommendation count, total resizes).

help

opsctl help

Common usage examples

Dry-run cluster analysis (default)

opsctl

Gathers cluster state, prints a node utilization table, computes the imbalance score, and lists proposed pod movements without executing anything. Since --dry-run defaults to true, this is always safe.

Execute rebalancing

opsctl --dry-run=false

Only movements that improve the imbalance score are executed. Pods are evicted through the Kubernetes eviction API, which respects PodDisruptionBudgets.

Adjust thresholds

opsctl --min-imbalance=0.1 --max-movements=20 --target-util=0.6

GKE provision-first rebalance (dry-run)

opsctl --gke \
  --gke-project=my-project \
  --gke-location=us-central1 \
  --gke-cluster=production \
  --machine-type=e2-standard-8 \
  --spot

GKE provision-first rebalance (execute)

opsctl --gke \
  --gke-project=my-project \
  --gke-location=us-central1 \
  --gke-cluster=production \
  --machine-type=e2-standard-8 \
  --spot \
  --auto-delete-old \
  --dry-run=false

Predict resource usage for a specific pod

opsctl predict \
  --prometheus-url=http://prometheus.monitoring:9090 \
  --namespace=default \
  --pod=my-app-7b9d4c6f8-x2k9l \
  --horizon=30m

Check CRD status

opsctl status                        # all namespaces
opsctl status --namespace=production # one namespace

Exit codes

Code	Meaning
0	Success
1	Error — kubeconfig failure, cluster state gathering failure, analysis failure, execution failure, or missing required flags

All errors are printed to stderr with a descriptive message. Diagnostic output (node tables, analysis results) goes to stdout.

Tips

Always start with a dry run. The default --dry-run=true ensures no cluster changes are made until you explicitly opt in.
In GKE mode, --spot can reduce costs by 60–91% for new nodes, but spot VMs can be preempted — use it for fault-tolerant workloads.
The predict command requires at least 5 historical data points from Prometheus. If your retention is too short, predictions won’t be available.
The status command works even if the controller is not running — it reads CRD resources directly from the API server.

​Installation

​Commands

​rebalance (default)

​predict

​status

​help

​Common usage examples

​Dry-run cluster analysis (default)

​Execute rebalancing

​Adjust thresholds

​GKE provision-first rebalance (dry-run)

​GKE provision-first rebalance (execute)

​Predict resource usage for a specific pod

​Check CRD status

​Exit codes

​Tips

Installation

Commands

rebalance (default)

predict

status

help

Common usage examples

Dry-run cluster analysis (default)

Execute rebalancing

Adjust thresholds

GKE provision-first rebalance (dry-run)

GKE provision-first rebalance (execute)

Predict resource usage for a specific pod

Check CRD status

Exit codes

Tips