Skip to main content
SambaStack v2.0.2 replaces the BundleTemplate, Bundle, and BundleDeployment resources with four new ones.
  • Model and ModelProfile describe what to serve and how to run it.
  • ModelDeployment serves it, and can reference a model and a profile directly.
  • ModelBundle groups several models into one unit, when you need that.
Because a ModelDeployment references a model and a profile directly, a bundle is no longer required – serving one model takes one resource instead of three. This page is a migration guide. It covers what the new resource model changes, the field mapping from the previous format, and the deprecation timeline.
Previous resource model deprecation. The previous resource model format is deprecated; however, it remains functional until September 30, 2026. Until then, both configurations can coexist in the same cluster. Use the new format for new configurations and migrate existing bundles before that date.
For the resource reference and the procedures for authoring each resource, see Deploying models and bundles. That page documents every field, provides YAML examples, and covers deployment, custom checkpoints, and troubleshooting. This page covers only what changes relative to the previous format.

​
How the new format differs

You author fewer resources and compose the ones the SambaStack installation already provides.
  • Direct model deployment.
    • Previously: serving one model required a BundleTemplate, a Bundle, and a BundleDeployment.
    • Now: a ModelDeployment declares the model and profile inline under spec.models – one resource instead of three.
    See Deploy a single model.
  • Reusable model profiles. A ModelProfile defines how a model architecture runs – feature flags, PEFs, and per-tier batching – keyed to an architecture, not a checkpoint.
    • Previously: the equivalent configuration was declared inline in every BundleTemplate and maintained by you.
    • Now: profiles for supported architectures ship with SambaStack, so you reference one by name.
    See ModelProfile structure.
  • Optional bundles.
    • Previously: a bundle was mandatory for every deployment.
    • Now: you author a ModelBundle only when you need what it offers – serving several models as one unit, legalizer validation with DDR and host memory reporting, batching overrides, or sharing a named configuration.
    See ModelBundle structure.
  • Checkpoints in Model resources.
    • Previously: bundles declared checkpoint sources in a spec.checkpoints block.
    • Now: checkpoints live in Model resources. Pair a model with a profile by name in a ModelBundle or ModelDeployment, and select a checkpoint with <model-name>:<checkpoint-version> or modelSettings.checkpointOverrides.
    See Model structure.
    Compatibility between a checkpoint and a profile is determined by model_arch, but the operator does not verify it for you. Select a checkpoint whose architecture is compatible with the profile you intend to use.
  • Custom checkpoints need no new bundle or profile. Reference your checkpoint and reuse a profile whose model_arch matches. See Deploy a custom checkpoint.

​
Mapping from the previous format

​
Resources

​
Fields

Removed and relocated fields.
  • The resubmit mechanism, comprising resubmit_to, resubmit_tool, and enableResubmit, is removed with no replacement.
  • Feature settings such as continuous_batching and constrained_decoding are properties of the compiled PEF. Declare them under Pef.spec.metadata, not in a bundle.

​
Migrate a bundle

1

Identify the profile that replaces your BundleTemplate

For each model in your existing BundleTemplate, find the ModelProfile whose model_arch value matches the model’s checkpoint architecture. In most cases a profile already exists in the cluster, and the expert and config structure from the template does not need to be recreated.
For details, see Identify available models and profiles.
2

Convert expert configurations to a batching configuration

Replace the nested experts and configs[] structure with a flat batchingConfig that maps each sequence length tier to its batch sizes. If the profile’s defaultBatchingConfig already matches what the existing bundle served, omit the override entirely.For details, see Batching configuration.
3

Move checkpoints to Model resources

Remove the spec.checkpoints block. Confirm that a Model resource exists for each checkpoint, or author one for a custom checkpoint. Checkpoint paths are resolved by the operator and are no longer declared in the bundle.For details, see Deploy a custom checkpoint.
4

Author the ModelBundle or deploy directly

If the existing bundle contained a single model with no speculative decoding, you can skip the bundle and deploy the model directly. Otherwise, author a ModelBundle with one modelConfigs entry per model, and move any spec_decoding.draft_model settings to spec.specDecodingPairs.For details, see Create a ModelBundle.
5

Validate and deploy

Apply the bundle and confirm the legalizer reports ValidationSucceeded, then deploy it with a ModelDeployment. The deployment-level settings from the previous BundleDeployment, including groups, owner, secretNames, and engineConfig, carry over unchanged.For details, see Deploy a bundle.

​
Deprecation timeline

The previous resource model format is deprecated; however, it remains functional until September 30, 2026. Migrate existing bundles to the new format before that date. Until then, existing bundles remain functional in SambaStack v2.0.2, and both configurations can coexist in the same cluster. Internally, the operator converts a ModelBundle back to an in-memory BundleTemplate and Bundle and reuses the earlier legalizer and rendering pipeline, so a new-format configuration and its previous-format equivalent produce the same deployment. SambaNova-provided bundles in the new format are generated from the previous definitions, which allows the new format to be adopted incrementally.
If a bundle is defined in both formats under the same name, installation fails on the duplicate. Ensure that a given bundle is defined in only one format.