kubectl ome cluster Preview Unreleased: coming in v1.3

kubectl ome cluster shows whether OME reports each of your workload clusters as connected. It reads the WorkloadClusters in the cluster of your current kubeconfig context, usually the control-plane cluster. A WorkloadCluster registers a cluster that OME can place the replicas of an InferenceService onto, for multi-cluster serving.

The status subcommand, the WorkloadCluster API and multi-cluster serving are alpha and still in development, and multi-cluster is off by default. To run the WorkloadCluster controller, set ome.multicluster.enabled: true in the ome-resources chart, as Controller manager flags shows. Without the controller, nothing reports a WorkloadCluster's status.

kubectl ome cluster SUBCOMMAND [WORKLOADCLUSTER] [flags]

status¶

kubectl ome cluster status [WORKLOADCLUSTER] [flags]

status shows how each WorkloadCluster declares its connection, and the Ready condition that the controller last wrote in its status. Name a WorkloadCluster to see only that one. Without a name, status lists up to 64, sorted by name. You need get on workloadclusters in the ome.io API group to read one by name, and list to list them. The reader ClusterRole in Required RBAC grants both.

kubectl get wlc shows the same Ready status in its REACHABLE column. kubectl ome get workloadclusters -o wide adds the Ready condition's reason, and kubectl describe workloadcluster with the WorkloadCluster's name shows its message.

Routing health probes check that each workload cluster answers for a service, and take a failing one out of the service's traffic. Drain a workload cluster takes one out for maintenance, and kubectl ome placement shows where an InferenceService is placed.

Flags¶

Plus the standard kubeconfig flags, such as -n and --context.

WorkloadClusters are cluster-scoped, so status ignores -n. To read the WorkloadClusters of another cluster, use --context.

Output fields¶

The default table fits in 80 columns, and cuts long values with .... -o wide prints every field in full, one per row, in FIELD and EVIDENCE columns. -o json and -o yaml print a ClusterStatusReport, as Output formats describes.

Each WorkloadCluster gets a row, after four rows marked @ that describe the read. Fields marked (wide) appear only in -o wide, JSON and YAML:

DECLARED is one of:

FRESHNESS is one of:

CONDITIONS is one of:

A * after a DECLARED or CONDITIONS value means that the CLI left some detail out. The table then ends with a row, @ * = truncated.

-o wide, JSON and YAML then show the conditions (conditions), Ready first:

The Ready condition's reason says why a WorkloadCluster is Ready or not. status shows ConnectionFailed as written, but every other reason as Other, Reachable included. Read the reason from the REASON column of kubectl ome get workloadclusters -o wide instead. This is a known bug. The controller writes these reasons:

The four @ rows are:

-o wide starts with the @ rows spelled out, then Condition scan/output limits, always 128/32, and Collected at (collectedAt), when the CLI built the report, in UTC.

@ observation is one of:

@ availability is one of:

A failed read still prints the report, and status exits with 0. In a script, check observation in the -o json output, not the exit code.

Examples¶

The examples run on the control-plane cluster, through its context hub. It holds two WorkloadClusters, worker-a and worker-b.

List the WorkloadClusters:

kubectl ome cluster status

CLUSTER          DECLARED           READY     FRESHNESS   CONDITIONS
@ observation    Complete           -         -           -
@ availability   -                  -         -           -
@ sources        returned=2         kept=2    max=64      cut=false
@ pages          seen=1/2           calls=1   cap=4       size=32
worker-a         KubeConfigSecret   True      Current     Reported
worker-b         KubeConfigSecret   False     Stale       Reported

The controller reports worker-a Ready for its current spec. worker-b is at generation 3, but its Ready condition is for generation 2, so FRESHNESS is Stale and READY False describes the old spec. A report that stays Stale suggests that the controller isn't running.

Print the report for worker-a as JSON:

kubectl ome cluster status worker-a -o json

{
  "apiVersion": "cli.ome.io/v1alpha1",
  "kind": "ClusterStatusReport",
  "collectedAt": "2026-01-01T00:00:00Z",
  "observation": "Complete",
  "requestedPages": 1,
  "observedPages": 1,
  "returnedSources": 1,
  "admittedSources": 1,
  "sourceLimit": 1,
  "pageLimit": 1,
  "requestLimit": 1,
  "pageSize": 1,
  "conditionScanLimit": 128,
  "conditionOutputLimit": 32,
  "sourcesTruncated": false,
  "clusters": [
    {
      "name": "worker-a",
      "generation": 1,
      "declaredConnectionKind": "KubeConfigSecret",
      "sourceState": "Reported",
      "profileResolution": "NotAttempted",
      "evidence": "Reported",
      "reportedReady": "True",
      "conditionState": "Reported",
      "freshness": "Current",
      "connectionState": "ReportedReady",
      "totalConditions": 1,
      "scannedConditions": 1,
      "retainedConditions": 1,
      "conditionsTruncated": false,
      "conditions": [
        {
          "type": "Ready",
          "status": "True",
          "observedGeneration": 1,
          "freshness": "Current",
          "reason": "Other",
          "transitionTime": "2025-12-31T23:00:00Z",
          "transitionState": "Reported"
        }
      ]
    }
  ]
}

The controller wrote the reason Reachable, which status shows as Other.

Name a WorkloadCluster that doesn't exist:

kubectl ome cluster status worker-c

CLUSTER          DECLARED      READY     FRESHNESS    CONDITIONS
@ observation    Unavailable   -         -            -
@ availability   NotFound      -         -            -
@ sources        returned=0    kept=0    max=1        cut=false
@ pages          seen=0/1      calls=1   cap=1        size=1
-                -             Unknown   Unobserved   Unavail...

The report holds no WorkloadClusters, so the last row shows the observation, cut to fit its column.

Exit codes¶

Errors print to stderr as error: <message>.

Related guides¶

• Troubleshoot an InferenceService