> ## 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

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.

<Warning>
  **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.
</Warning>

<Note>
  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.
</Note>

## 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](/docs/en/v2.0.2/sambastack/service-administration/model-deployment/deploying-model-bundles#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](/docs/en/v2.0.2/sambastack/service-administration/model-deployment/deploying-model-bundles#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](/docs/en/v2.0.2/sambastack/service-administration/model-deployment/deploying-model-bundles#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](/docs/en/v2.0.2/sambastack/service-administration/model-deployment/deploy-custom-checkpoints#model-structure).

  <Warning>
    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.
  </Warning>

* **Custom checkpoints need no new bundle or profile.** Reference your checkpoint and reuse a profile whose `model_arch` matches. See [Deploy a custom checkpoint](/docs/en/v2.0.2/sambastack/service-administration/model-deployment/deploying-model-bundles#deploy-a-custom-checkpoint).

## Mapping from the previous format

### Resources

| 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`.                                               |

### Fields

| Previous field                                                             | New field                                                                             |
| -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| `BundleTemplate.spec.models.<model>.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 `<model-name>[:<arch>][:<version>]`                               |
| Inline `pefs` map and `usePefCRs`                                          | `ModelProfile.spec.pefs`. The `<pef-name>[:<version>]` 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.<alias>.source`                                   | `Model.spec.checkpoints.<arch>.versions.<version>.source`                             |
| `Bundle.spec.checkpoints.<alias>.toolSupport`                              | `Model.spec.checkpoints.<arch>.versions.<version>.tool_support`                       |
| `Bundle.spec.models.<model>.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`                                                             |

<Warning>
  **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.
</Warning>

## Migrate a bundle

<Steps>
  <Step title="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.

    ```bash theme={}
    kubectl -n <namespace> get modelprofiles
    kubectl -n <namespace> 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).
  </Step>

  <Step title="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](/docs/en/v2.0.2/sambastack/service-administration/model-deployment/deploying-model-bundles#batching-configuration).
  </Step>

  <Step title="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](/docs/en/v2.0.2/sambastack/service-administration/model-deployment/deploying-model-bundles#deploy-a-custom-checkpoint).
  </Step>

  <Step title="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](/docs/en/v2.0.2/sambastack/service-administration/model-deployment/deploying-model-bundles#create-a-modelbundle).
  </Step>

  <Step title="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](/docs/en/v2.0.2/sambastack/service-administration/model-deployment/deploying-model-bundles#deploy-a-bundle).
  </Step>
</Steps>

## 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.

<Note>
  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.
</Note>

## 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.