Skip to main content
SambaStack v2.0.2 introduces a new resource model for configuring and deploying models. Four composable custom resources – Model, ModelProfile, ModelDeployment, and ModelBundle – replace the BundleTemplate, Bundle, and BundleDeployment resources. Because a ModelDeployment can reference a model and a profile directly, a bundle is no longer required in order to serve a model. 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 format remains fully supported in SambaStack v2.0.2, and both configurations can coexist in the same cluster. However, the previous resource model format will be deprecated on September 30, 2026. 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.

​
What changes

The new format allows you to author fewer custom resources and instead compose the out-of-the-box custom resources provided with the SambaStack installation to achieve a desired deployment configuration.

Direct model deployment

A ModelDeployment can declare a single model and profile inline, so a ModelBundle is not required in order to serve a model.

Reusable model profiles

Each ModelProfile provides a set of features and batching support for a model architecture. ModelProfiles are provided with the SambaStack installation and are referenced by name rather than defined by the user.

Optional bundles

A ModelBundle remains available for validation, iteration, sharing, and modularity, but it is no longer a prerequisite for deployment.

Checkpoints in Model resources

Checkpoint paths are not declared in a bundle. You select a checkpoint by referencing a Model and version, and the operator resolves the path from it.
  1. Direct model deployment. Previously, a bundle was a prerequisite for deployment: serving a single model required a BundleTemplate, a Bundle, and a BundleDeployment. Now, a ModelDeployment can declare a model and a profile inline under spec.models, so a single-model deployment requires only one authored custom resource. For the procedure, see Deploy a single model.
  2. Reusable model profiles. A ModelProfile describes how a model architecture runs, including its feature flags, its PEFs, and its per-tier batching support. It is keyed to an architecture rather than to a specific checkpoint. Previously, the equivalent configuration was declared inline in each BundleTemplate and had to be defined and maintained by the user. Now, the profiles for supported architectures are included with the SambaStack installation and are already present in the cluster, so you reference an existing profile by name instead of defining one. For the field reference, see ModelProfile structure.
  3. Optional bundles for validation, iteration, sharing, and modularity. Previously, a bundle was mandatory for every deployment. Now, a ModelBundle is authored only when its capabilities are required: serving multiple models as a single unit, validating a configuration against the legalizer, which reports DDR and host memory utilization, iterating on batching overrides, or distributing a named and validated configuration to other users. For the field reference, see ModelBundle structure.
  4. Checkpoints defined in Model custom resources. Bundles previously declared explicit checkpoint sources in a spec.checkpoints block. Now, checkpoints are defined in Model custom resources, and a model is paired with a profile by referencing both by name in a ModelBundle or a ModelDeployment. You select the checkpoint through a <model-name>:<checkpoint-version> reference, or through modelSettings.checkpointOverrides. For the field reference, 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.
  5. Additive support for custom checkpoints. Serving a custom checkpoint of a supported architecture does not require a new bundle or a new profile. Reference your checkpoint and reuse an existing profile whose model_arch is compatible with it. For the procedure, see Deploy a custom checkpoint.

​
Field mapping

​
Resource mapping

​
Field mapping

Removed fields. The resubmit mechanism, comprising resubmit_to, resubmit_tool, and enableResubmit, is removed. It is not enabled for bundles in the new format and has no replacement. Feature settings such as continuous_batching and constrained_decoding are properties of the compiled PEF and are declared under Pef.spec.metadata rather than 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 will be deprecated on September 30, 2026. Migrate existing bundles to the new format before that date. Until then, existing bundles remain supported 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.