---
title: Guides
description: Deploy models, run them on OMENative, set up networking, roll out changes, scale and schedule workloads, try alpha multi-cluster routing, and operate and troubleshoot OME.
---
New to OME? Start by [installing it](../getting-started/install.md) and [serving your first model](../getting-started/serve-your-first-model.md). If an InferenceService isn't ready, go to [Troubleshoot an InferenceService](troubleshoot/troubleshoot-an-inferenceservice.md).
## Deploy models
Start with the smallest InferenceService, then add what you need: a runtime you name, weights that are already in the cluster, or an accelerator class.
- **[Deploy an InferenceService](deploy-models/deploy-an-inferenceservice.md)**
Write the smallest InferenceService that serves a model, with only a model, a model and a runtime, or only a runtime, then wait for it, send it a request and see what OME created.
- **[Reference a runtime explicitly](deploy-models/reference-a-runtime-explicitly.md)**
Name the ServingRuntime or ClusterServingRuntime that an InferenceService uses instead of letting OME choose one, then check that OME used it.
- **[Troubleshoot runtime selection](deploy-models/troubleshoot-runtime-selection.md)**
Find out why OME can't auto-select a runtime for your model, from kubectl's error or the RuntimeReady condition, then fix the runtime or name one.
- **[Serve models from a PVC](deploy-models/serve-models-from-pvc.md)**
Serve model weights that already live on a PersistentVolumeClaim by pointing a BaseModel at a pvc:// URI, with no download to nodes.
- **[Serve models from node-local storage](deploy-models/serve-models-from-local-storage.md)**
Serve model weights already on your nodes' disks with a local:// storage URI, which OME validates in place and mounts read-only.
- **[Select accelerators](deploy-models/select-accelerators.md)**
Pick the AcceleratorClass for the engine and decoder by naming a class, or let OME choose one with the BestFit, Cheapest, MostCapable or FirstAvailable policy.
- **[Configure pod disruption budgets](deploy-models/configure-pod-disruption-budgets.md)**
Control how many of a component's pods a node drain can take down, with a budget on each component or defaults for each deployment mode.
- **[Run benchmarks](deploy-models/run-benchmarks.md)**
Run a BenchmarkJob against an InferenceService with realistic traffic scenarios, and collect its throughput and latency results from storage.
## OMENative
[OMENative](../concepts/omenative/overview.md) runs each replica as an Instance, one pod or a leader and its workers, that OME creates, updates, repairs, moves and removes as one unit.
- **[Serve a model on OMENative](omenative/serve-a-model-on-omenative.md)**
Opt a single-pod InferenceService into OMENative with spec.deploymentMode, then check the InferenceReplica, the Instance and the pod that OME creates.
- **[Serve a multi-node model](omenative/serve-a-multi-node-model.md)**
Run one copy of a model across several nodes by giving its engine a leader and workers, which OMENative creates, updates and repairs together as one Instance.
- **[Serve a prefill-decode model](omenative/serve-a-prefill-decode-model.md)**
Serve a model with prefill on the engine and decode on the decoder, each with its own InferenceReplica on OMENative, and scale prefill on its own.
- **[Run a standalone InferenceReplica](omenative/run-a-standalone-inferencereplica.md)**
Create an InferenceReplica directly, with no parent InferenceService: give it a model, a runtime or rendered pod templates, then scale, update and pause the pod set yourself.
- **[Provision TPU slices on demand](omenative/provision-tpu-slices.md)**
Serve an OMENative component on GKE TPU node pools that provision slices on demand: OME creates a Slice for each Instance's pods, holds the pods until it's ready, and releases it when no pod needs it.
- **[Move from LeaderWorkerSet to OMENative](omenative/move-from-leaderworkerset.md)**
Move a multi-node InferenceService off the deprecated MultiNode mode, which runs on LeaderWorkerSet, onto OMENative, and delete the LeaderWorkerSet that OME leaves behind.
- **[Spread Instances across fault domains](omenative/spread-instances-across-fault-domains.md)**
Spread an OMENative engine's or decoder's Instances across racks, fabric slices or zones with topologySpread and topologySpreadKey, as a preference or a requirement.
- **[Set Instance readiness deadlines](omenative/set-instance-readiness-deadlines.md)**
Bound how long OMENative waits for a new Instance to become Ready with instanceReadyTimeout and the stuck-pod and unschedulable grace periods, and see what OME does when one runs out.
- **[Reset failed Instances](omenative/reset-failed-instances.md)**
Rebuild the OMENative Instances that OME marked Failed, once you've fixed the cause, with the ome.io/reset-instances annotation.
- **[Recover stuck deletions](omenative/recover-stuck-deletions.md)**
Recover OMENative pods stuck Terminating on dead nodes with the opt-in forceDelete escalation, and bound how long a deleting InferenceReplica holds its teardown finalizer.
- **[Change the Instance status encoding](omenative/change-the-status-encoding.md)**
Choose how OME stores per-Instance status on InferenceReplicas, as compact ColumnarV2 columns or a DenseV1 list, and switch a cluster between them.
## Networking
- **[Configure ingress](networking/configure-ingress.md)**
Configure how OME exposes InferenceServices through Kubernetes Ingress or Gateway API with the ingress block of the inferenceservice-config ConfigMap.
- **[Expose a service without ingress](networking/expose-without-ingress.md)**
Put an InferenceService behind a LoadBalancer or NodePort Service with the ome.io/service-type annotation, without an Ingress controller or a Gateway.
- **[Choose a Gateway API host scheme](networking/gateway-host-schemes.md)**
Choose between one shared hostname with per-service path prefixes and a subdomain per InferenceService for the HTTPRoutes OME generates.
- **[Use multiple gateways](networking/multiple-gateways.md)**
Attach OME's HTTPRoutes to more than one Gateway, such as an internal and an external one, and read the gateways' addresses in status.
- **[Use per-namespace gateways](networking/namespace-gateways.md)**
Route each namespace's InferenceServices through that namespace's own Gateway, and override the gateway for a single service with annotations.
- **[Configure route timeouts](networking/configure-route-timeouts.md)**
Set the request timeout on OME's HTTPRoutes for one InferenceService or the whole cluster, or turn it off so long generations can finish.
- **[Set appProtocol on services](networking/set-service-app-protocols.md)**
Set Kubernetes appProtocol values on the Service ports OME generates, so gateways and service meshes use the right protocol for your model server.
## Roll out changes
These guides are for components on [OMENative](../concepts/omenative/overview.md). To set up a canary, blue-green or rolling update, see [Rollout groups](../concepts/rollouts-and-traffic/rollout-groups.md#choose-a-progression).
- **[Pause and resume a rollout](roll-out-changes/pause-and-resume-a-rollout.md)**
Pause in-flight rollout work on an OMENative InferenceService with the alpha kubectl ome rollout pause action, and continue it with resume.
- **[Promote or roll back a canary](roll-out-changes/promote-or-roll-back-a-canary.md)**
Advance a gated canary step with kubectl ome rollout promote, or abort the canary back to the stable revisions with rollback; both are alpha.
- **[Release a held revision](roll-out-changes/release-a-held-revision.md)**
Get OME to retry a revision it stopped retrying, once you've fixed what made it fail, with the alpha kubectl ome instance release-held command.
- **[Repin a drifted rollout plan](roll-out-changes/repin-a-drifted-rollout-plan.md)**
Apply an edit to spec.rollout or a RolloutPolicy to the active rollout run, keeping its progress, with the alpha kubectl ome rollout repin action.
- **[Pace rollouts with minReadySeconds](roll-out-changes/pace-rollouts-with-min-ready-seconds.md)**
Make a new OMENative pod stay Ready for a warm-up window before it counts as Available, so a rollout waits before draining the old pods.
## Scale and migrate
To autoscale a component with HPA or KEDA, see [Component autoscaling](../concepts/serving/component-autoscaling.md).
- **[Request a transient scale](scale-and-migrate/request-a-transient-scale.md)**
Change how many Instances one OMENative component runs with the alpha kubectl ome scale command, until its autoscaler or OME sets the count again.
- **[Request an Instance migration](scale-and-migrate/request-an-instance-migration.md)**
Move one OMENative Instance to another node, with its replacement serving before the old one drains, using the alpha kubectl ome migration start command.
- **[Scale to zero with KEDA](scale-and-migrate/scale-to-zero-with-keda.md)**
Scale an idle RawDeployment component to zero replicas with a KEDA autoscaler, and back up when a trigger becomes active.
- **[Bring your own autoscaler](scale-and-migrate/bring-your-own-autoscaler.md)**
Turn off OME's autoscaler for a component with the External class, and scale it with your own autoscaler through the scaleTargetRef that OME publishes.
## Scheduling and capacity
The OME scheduler and Alfred are alpha. Their configuration and behavior can change between releases.
- **[Use the OME scheduler](operate-ome/ome-scheduler.md)**
Install the alpha ome-scheduler as a second scheduler and opt workloads into topology-packed gang placement; it requires Kubernetes 1.35.
- **[Run Alfred in recommend-only mode](scheduling/run-alfred.md)**
Install Alfred and read the Instance moves it recommends when free GPUs fragment or a node turns unhealthy, then tune its policies.
- **[Set up scheduler simulation for Alfred](scheduling/set-up-scheduler-simulation.md)**
Load your schedulers' configurations into Alfred, so that it predicts where the replacement pods of each move would land.
- **[Let Alfred migrate Instances](scheduling/let-alfred-migrate-instances.md)**
Turn on Alfred's execute mode, so that it asks OMENative to migrate Instances off fragmented or unhealthy nodes within the limits you set.
- **[Set accelerator quotas](operate-ome/accelerator-quota.md)**
Install the ome-quota-manager, split a cluster's GPUs among teams with an AcceleratorQuota tree, and charge workloads to each team's Kueue budget.
## Multi-cluster
Multi-cluster placement and routing are alpha, still in development, and off by default. Fields and behavior can change between releases. [Turn on routing](../concepts/rollouts-and-traffic/traffic-map.md#turn-on-routing) before you follow these guides.
- **[Publish a global endpoint](multi-cluster/publish-a-global-endpoint.md)**
Give an alpha multi-cluster InferenceService one global hostname that splits its traffic across workload clusters by its TrafficMap's weights.
- **[Configure routing health probes](multi-cluster/routing-health-probes.md)**
Configure the alpha end-to-end probe that sets a workload cluster's TrafficMap weight to zero after repeated failures, for every InferenceService or for one.
- **[Drain a workload cluster](multi-cluster/drain-a-workload-cluster.md)**
Use the alpha kubectl ome traffic drain to take a workload cluster out of an InferenceService's traffic for maintenance, and undrain to give it back.
- **[Weight traffic for heterogeneous clusters](multi-cluster/weight-traffic-for-heterogeneous-clusters.md)**
Give a workload cluster whose replicas serve more requests a larger share of an alpha multi-cluster InferenceService's traffic, with capacity factors in spec.routing.capacityFactors.
- **[Tune routing capacity polling](multi-cluster/tune-routing-capacity-polling.md)**
Cap a workload cluster's TrafficMap weight at the replicas that its endpoint reports it can serve, with an alpha poll set in the chart or for one InferenceService.
## Operate OME
- **[Configure the controller](operate-ome/configure-the-controller.md)**
Tune the OME controller manager's command-line flags, including reconcile concurrency, leader election and runtime-revision garbage collection.
- **[Set replica defaults](operate-ome/set-replica-defaults.md)**
Choose the minReplicas and maxReplicas that components get when the InferenceService and its runtime leave them unset, with the ome-resources chart's ome.controller.replicas values.
- **[Run the model agent](operate-ome/model-agent.md)**
Turn on the optional model agent for models stored on the nodes, and configure how it prepares them.
- **[Keep downloaded model files](operate-ome/configure-model-artifact-retention.md)**
Keep a model's downloaded files on the nodes after you delete the model, with the models.ome/reserve-model-artifact label.
- **[Share Hugging Face artifacts](operate-ome/shared-hf-artifacts.md)**
Keep one downloaded copy of a Hugging Face snapshot per node and share it across BaseModels and ClusterBaseModels with downloadPolicy ReuseIfExists.
- **[Replicate model weights](operate-ome/replicate-model-weights.md)**
Copy model weights between Hugging Face, OCI Object Storage and PVCs with the ome-agent replica command, run as a one-shot Kubernetes Job.
- **[Collect metrics](operate-ome/metrics.md)**
Tune or turn off the short-retention Prometheus that the ome-resources chart deploys for KEDA autoscaling and canary analysis, or scrape OME with your own.
- **[Set up alerting](operate-ome/alerting.md)**
Enable the ome-resources chart's five P0 PrometheusRule alerts, which are off by default, and tune their thresholds and selectors.
- **[Move a manifest install to the Helm charts](operate-ome/move-to-the-helm-charts.md)**
Move an OME install from make install or kubectl apply -k to the ome-crd and ome-resources Helm charts, and keep your InferenceServices, models and runtimes in place.
## Troubleshoot
- **[Troubleshoot an InferenceService](troubleshoot/troubleshoot-an-inferenceservice.md)**
Find out why an InferenceService isn't ready or serving by checking its status, model, runtime and logs, then look up the fix for what you see.