> ## Documentation Index
> Fetch the complete documentation index at: https://sambanova-systems.mintlify.site/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Migrating bundle configuration
> Migrate custom bundles from the previous BundleTemplate and Bundle format to the resource model introduced in SambaStack v2.0.2, including the field mapping and the deprecation timeline.
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](/docs/en/v2.0.2/sambastack/service-administration/model-deployment/deploying-model-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.
A `ModelDeployment` can declare a single model and profile inline, so a `ModelBundle` is not required in order to serve a model.
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.
A `ModelBundle` remains available for validation, iteration, sharing, and modularity, but it is no longer a prerequisite for deployment.
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](/docs/en/v2.0.2/sambastack/service-administration/model-deployment/deploying-model-bundles#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](/docs/en/v2.0.2/sambastack/service-administration/model-deployment/deploying-model-bundles#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](/docs/en/v2.0.2/sambastack/service-administration/model-deployment/deploying-model-bundles#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 `:` reference, or through `modelSettings.checkpointOverrides`. For the field reference, see [Model structure](/docs/en/v2.0.2/sambastack/service-administration/model-deployment/deploy-custom-checkpoints#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](/docs/en/v2.0.2/sambastack/service-administration/model-deployment/deploying-model-bundles#deploy-a-custom-checkpoint).
## Field mapping
### Resource mapping
| Previous resource | New resource | Notes |
| -------------------------------------------------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `BundleTemplate` | `ModelProfile` | Scoped to a single model architecture rather than to a set of models. Profiles for supported architectures are provided with the SambaStack installation. |
| `Bundle` | `ModelBundle` | Optional. Required only for multi-model deployments, speculative decoding, legalizer validation, or sharing a named configuration. |
| `BundleDeployment` | `ModelDeployment` | Can reference a `ModelBundle` through `spec.bundle`, or declare a model and profile inline through `spec.models`. |
| Checkpoints declared inline in `Bundle.spec.checkpoints` | `Model` | Checkpoints move to a first-class resource, referenced by name from a `ModelBundle` or `ModelDeployment`. Compatibility with a profile is determined by `model_arch`, but is not verified by the operator. |
| `Pef` | `Pef` | Unchanged. PEF referencing behavior is the same as before; only the location of the reference changes, from the bundle template to `ModelProfile.spec.pefs`. |
### Field mapping
| Previous field | New field |
| -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| `BundleTemplate.spec.models..experts` and `configs[]` | `ModelProfile.spec.defaultBatchingConfig`, keyed by tier |
| `spec.models`, a map of models | `spec.modelConfigs[]`, a list of model configurations |
| Model referenced by name | Model referenced as `[:][:]` |
| Inline `pefs` map and `usePefCRs` | `ModelProfile.spec.pefs`. The `[:]` reference format is unchanged. |
| `expertSet` | Tier keys present in `batchingConfig` |
| `default_expert_values.swappable` and per-expert-configuration `swappable` | `modelConfigs[].modelSettings.swappable`, defined once per model |
| `private` | `modelSettings.routable`, which is the inverse flag |
| `Bundle.spec.checkpoints..source` | `Model.spec.checkpoints..versions..source` |
| `Bundle.spec.checkpoints..toolSupport` | `Model.spec.checkpoints..versions..tool_support` |
| `Bundle.spec.models..template` | `modelConfigs[].profile` |
| Per-configuration `spec_decoding.draft_model` | `spec.specDecodingPairs[]`, declared at the bundle level |
| `resubmit`, `resubmit_to`, and `enableResubmit` | Removed. |
| `continuous_batching` declared in the bundle | `Pef.spec.metadata.continuous_batching`, surfaced in `ModelProfile.spec.features` |
| `constrained_decoding` declared in the bundle | `Pef.spec.metadata.constrained_decoding`, surfaced in `ModelProfile.spec.features` |
| `output_processor`, `enable_reasoning_effort`, and `postprocess_parser` | `Model.spec.expertFields` |
**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
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.
```bash theme={}
kubectl -n get modelprofiles
kubectl -n get models
```
For details, see [Identify available models and profiles](/docs/en/v2.0.2/sambastack/service-administration/model-deployment/deploying-model-bundles#identify-available-models-and-profiles).
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](/docs/en/v2.0.2/sambastack/service-administration/model-deployment/deploying-model-bundles#batching-configuration).
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](/docs/en/v2.0.2/sambastack/service-administration/model-deployment/deploying-model-bundles#deploy-a-custom-checkpoint).
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](/docs/en/v2.0.2/sambastack/service-administration/model-deployment/deploying-model-bundles#create-a-modelbundle).
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](/docs/en/v2.0.2/sambastack/service-administration/model-deployment/deploying-model-bundles#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.
## Related resources
* [Deploying models and bundles](/docs/en/v2.0.2/sambastack/service-administration/model-deployment/deploying-model-bundles): the complete resource reference and authoring procedures.
* [Supported models and bundles](/docs/en/v2.0.2/sambastack/service-administration/model-deployment/supported-models-and-bundles): available models and recommended bundles.
* [Speculative decoding deployment guidelines](/docs/en/v2.0.2/sambastack/service-administration/performance/deploy-with-speculative-decoding): configuring draft and target models.