kubectl ome autoscale Unreleased: coming in v1.3

kubectl ome autoscale shows how each component of an InferenceService scales: its autoscaler, where the autoscaler's settings came from, the object it scales and its replica counts. Both subcommands only read. The component autoscaler settings and status fields they read are alpha. Component autoscaling describes the autoscalers, and kubectl ome scale changes a component's replica count for a while.

kubectl ome autoscale SUBCOMMAND INFERENCESERVICE [flags]

Each subcommand takes the name of one InferenceService and prints a table. -o json and -o yaml print the whole report, including warnings the table leaves out, as Output formats describes. Required RBAC lists the permissions each command needs, and Extra rules lists the one --live-scaler adds.

status¶

kubectl ome autoscale status INFERENCESERVICE [flags]

status shows what the InferenceService's status reports for each component: the autoscaler's class, what manages it, where its settings came from, the object it scales, its replica counts and conditions. Add --live-scale to check the replica count on the component's InferenceReplica, as after a transient scale. Add --live-scaler to check the HorizontalPodAutoscaler or ScaledObject itself. The live rows carry their own evidence, and don't change STATE.

For the autoscaler's metrics and condition messages, run kubectl describe hpa chat-engine -n prod, or kubectl describe scaledobject scaledobject-chat-engine -n prod for KEDA.

Flags¶

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

Output fields¶

The table has a row per field, and a column for the whole service, SERVICE, and for each component: ENGINE, DECODER and ROUTER. STATE always appears. Other rows appear only when a component has a value, and show - under SERVICE. ISSUES comes last.

The service's STATE is one of:

The first state in this list that applies wins. Any state other than Reported adds a PartialData warning, which only -o json and -o yaml show.

A component's state is one of:

The component rows are:

ISSUES names the cause of any other value. An autoscaler that OME doesn't manage has no counts or conditions in the status, so Unavailable is normal for it, and the component can still be Reported. For an OMENative component, the counts are Instances: one pod, or a leader and its workers.

Long cells are shortened with ..., and -o wide shows full values. The LIVE and SCALER rows that the live flags add follow REPLICA-EVIDENCE.

Each ISSUES cell holds a short alias. State is the state the issue leads to. -o wide shows the exact codes.

POLICY-STATE and POLICY appear when a component references an AutoscalerPolicy.

POLICY-STATE says how the policy relates to the autoscaler in effect. POLICY names the referenced policy, except for Held:

-o wide adds the reason on the component's AutoscalerResolved condition as POLICY-RESOLUTION, and Conditions and status lists the reasons. Fail-closed behavior explains holds, and Inline settings win explains the shadowed case. Right after you change the InferenceService, a component with a policy reference is Invalid, with the issue BadPolicy, until the controller catches up.

--live-scale compares the counts in the status with the live counts of an OMENative component's InferenceReplica, which it reads with its scale subresource. After a kubectl ome scale request, LIVE-SPEC shows the count you asked for. A RawDeployment component shows Unsupported. --live-scaler reads the autoscaler that OME manages: the HorizontalPodAutoscaler named after the scale target, or the ScaledObject scaledobject-<target>. For an InferenceReplica target, both flags first check that it's the one the InferenceService currently selects. They add these rows:

LIVE-EVIDENCE and SCALER-EVIDENCE are one of:

--live-scale also adds a PartialData warning when a component's result isn't Reported with Equal, and --live-scaler when an autoscaler that OME manages isn't Reported.

-o wide prints one row per component, with full values and exact issue codes. Policy evidence adds columns after SPEC-SOURCE, including the render's policy generation and digests, and the live flags add theirs at the end.

Examples¶

Show the autoscaling state of chat in prod:

kubectl ome autoscale status chat -n prod

FIELD              SERVICE    ENGINE         DECODER   ROUTER
STATE              Reported   Reported       -         -
CLASS              -          HPA            -         -
MANAGED-BY         -          ome            -         -
SPEC-SOURCE        -          default        -         -
TARGET-KIND        -          IR             -         -
TARGET-NAME        -          chat-engine    -         -
TARGET-EVIDENCE    -          Reported       -         -
CURRENT            -          2              -         -
DESIRED            -          3              -         -
REPLICA-EVIDENCE   -          Reported       -         -
LAST-SCALE         -          Aug31 18:20Z   -         -
COND-EVIDENCE      -          Reported       -         -
ABLE-TO-SCALE      -          True           -         -
SCALING-ACTIVE     -          True           -         -

The engine has the default HPA, which OME manages and which scales the InferenceReplica chat-engine. The HPA reports 2 current replicas and wants 3, and it last scaled at 18:20 UTC on August 31. The status reports no decoder or router.

Show the same report with exact values:

kubectl ome autoscale status chat -n prod -o wide

STATE      COMPONENT   COMPONENT-STATE   CLASS   MANAGED-BY   SPEC-SOURCE   TARGET                              TARGET-EVIDENCE   CURRENT   DESIRED   REPLICA-EVIDENCE   LAST-SCALE             CONDITION-EVIDENCE   CONDITIONS                            ISSUES
Reported   engine      Reported          HPA     ome          default       InferenceReplica/prod/chat-engine   Reported          2         3         Reported           2026-08-31T18:20:00Z   Reported             AbleToScale=True,ScalingActive=True   -

Check the engine's counts against its InferenceReplica. In this report, the status records no last scale time, so the LAST-SCALE row is left out:

kubectl ome autoscale status chat -n prod --live-scale

FIELD              SERVICE    ENGINE        DECODER   ROUTER
STATE              Reported   Reported      -         -
CLASS              -          HPA           -         -
MANAGED-BY         -          ome           -         -
SPEC-SOURCE        -          default       -         -
TARGET-KIND        -          IR            -         -
TARGET-NAME        -          chat-engine   -         -
TARGET-EVIDENCE    -          Reported      -         -
CURRENT            -          2             -         -
DESIRED            -          3             -         -
REPLICA-EVIDENCE   -          Reported      -         -
LIVE-EVIDENCE      -          Reported      -         -
LIVE-SPEC          -          3             -         -
LIVE-CURRENT       -          2             -         -
LIVE-COUNT         -          Equal         -         -
COND-EVIDENCE      -          Reported      -         -
ABLE-TO-SCALE      -          True          -         -
SCALING-ACTIVE     -          True          -         -

LIVE-SPEC is the 3 Instances the InferenceReplica asks for, and LIVE-CURRENT the 2 it has. They match DESIRED and CURRENT in the status, so LIVE-COUNT is Equal.

Check the engine's HPA, with the same status:

kubectl ome autoscale status chat -n prod --live-scaler

FIELD              SERVICE    ENGINE        DECODER   ROUTER
STATE              Reported   Reported      -         -
CLASS              -          HPA           -         -
MANAGED-BY         -          ome           -         -
SPEC-SOURCE        -          default       -         -
TARGET-KIND        -          IR            -         -
TARGET-NAME        -          chat-engine   -         -
TARGET-EVIDENCE    -          Reported      -         -
CURRENT            -          2             -         -
DESIRED            -          3             -         -
REPLICA-EVIDENCE   -          Reported      -         -
SCALER-KIND        -          HPA           -         -
SCALER-EVIDENCE    -          Reported      -         -
SCALER-GEN         -          Matched       -         -
SCALER-CURRENT     -          2             -         -
SCALER-DESIRED     -          3             -         -
SCALER-SCALING     -          True          -         -
COND-EVIDENCE      -          Reported      -         -
ABLE-TO-SCALE      -          True          -         -
SCALING-ACTIVE     -          True          -         -

The HPA's counts agree with the status, and it has processed its latest spec, so SCALER-GEN is Matched. The SCALER rows show the conditions the HPA reports itself, here only ScalingActive.

Print the first report as JSON:

kubectl ome autoscale status chat -n prod -o json

{
  "apiVersion": "cli.ome.io/v1alpha1",
  "kind": "AutoscaleStatusReport",
  "metadata": {
    "namespace": "prod",
    "name": "chat"
  },
  "collectedAt": "2026-08-31T18:30:00Z",
  "sources": [
    {
      "kind": "InferenceService",
      "namespace": "prod",
      "name": "chat",
      "uid": "uid-chat",
      "generation": 7,
      "evidence": "Reported",
      "collectedAt": "2026-08-31T18:30:00Z"
    }
  ],
  "content": {
    "summary": {
      "state": "Reported"
    },
    "components": [
      {
        "type": "engine",
        "state": "Reported",
        "class": "HPA",
        "managedBy": "ome",
        "specSource": "default",
        "target": {
          "state": "Reported",
          "apiVersion": "ome.io/v1beta1",
          "kind": "InferenceReplica",
          "namespace": "prod",
          "name": "chat-engine"
        },
        "replicas": {
          "state": "Reported",
          "currentReplicas": 2,
          "desiredReplicas": 3,
          "lastScaleTime": "2026-08-31T18:20:00Z"
        },
        "conditions": {
          "state": "Reported",
          "items": [
            {
              "type": "AbleToScale",
              "status": "True",
              "lastTransitionTime": "2026-08-31T18:15:00Z"
            },
            {
              "type": "ScalingActive",
              "status": "True",
              "lastTransitionTime": "2026-08-31T18:15:00Z"
            }
          ]
        }
      }
    ],
    "issues": []
  },
  "warnings": []
}

Scripts can read content.summary.state, and each component's state, class, target and replicas. With a live flag, each component also has liveScale or liveScaler. sources then also lists each object the flag read, with the evidence Observed, or Unavailable when the read or its checks failed.

explain¶

kubectl ome autoscale explain INFERENCESERVICE [flags]

explain works out which autoscaler each component should have, from the InferenceService and its runtime, and compares it with the autoscaler the status reports. It reads specs and status, not the autoscalers: to check the HPA or ScaledObject itself, use status --live-scaler.

It reads the serving runtime the controller selected, the runtimes it inherits from and, for a named runtime, a pinned revision in the OME namespace, which --ome-namespace sets.

A component's autoscaler comes from the first layer that supplies one, as Which setting wins describes:

explain doesn't read AutoscalerPolicies. When the policy layer supplies the autoscaler, DESIRED shows ?/policy, WHY shows policy-unavailable, and STATE is Partial or worse. status shows the policy evidence the controller reports.

Flags¶

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

Output fields¶

The table has a FIELD column and a column for each of the InferenceService's components, such as ENGINE. A SERVICE column follows for issues that no component column shows, such as decoder:unexpected-component.

STATE is one of:

The first state in this list that applies wins.

ZERO is one of:

An OMENative component never runs fewer than one Instance, even when ZERO is yes, as OMENative components can't scale to zero explains.

WHY shows these reasons, most severe first:

explain exits with code 1 when it can't read a consistent set of objects. The errors include:

Examples¶

Explain the autoscaling of chat in prod. Unlike the status examples, this chat runs its engine as a RawDeployment:

kubectl ome autoscale explain chat -n prod

FIELD                ENGINE
STATE                OK
MODE                 Raw
POLICY               Independent
DESIRED              HPA/default
RANGE                1..4
ZERO                 -
EXPECTED-TARGET      Deployment/chat-engine
REPORTED             HPA/default/ome
REPORTED-TARGET      Deployment/chat-engine
CUR/DES              2/2
LAST-SCALE           -
CONDITION-EVIDENCE   reported
CONDITIONS           AbleToScale=True
CHECK                match
WHY                  -

Neither the InferenceService nor its runtime sets an autoscaler, so the default applies: an HPA that scales the Deployment chat-engine between the engine's minReplicas: 1 and maxReplicas: 4. The status is current and reports the same class, layer and target, so CHECK is match and STATE is OK.

Exit codes¶

Errors print to stderr as error: <message>.

Related guides¶

• Request a transient scale
• Bring your own autoscaler
• Scale to zero with KEDA
• Troubleshoot an InferenceService