Rancher自定义模板栈升级时版本识别异常咨询

Understanding the Root Cause #

This is a common pain point when working with mixed version formats in Rancher catalog templates. The core issues are:

1. Lexicographical Sorting: Rancher defaults to dictionary-style ordering for version strings, not your directory's physical order. Non-semantic labels like custom_branch and stable get grouped separately from semantic versions like 0.3/0.4.
2. Upgrade Filtering Logic: When upgrading from a non-semantic version, Rancher sometimes filters out versions that don't match the same "format"—so it only shows other string-based labels instead of your numbered versions.

Step-by-Step Solutions #

1. Standardize Version Naming

Rancher handles consistent version strings far more reliably. Unify your version labels to keep all entries in the same category:

• Rename your directories to: v-custom_branch, v-stable, v0.3, v0.4
• Update each version's rancher-compose.yml to match, e.g.:

  version: "v-custom_branch"
  # rest of your template config
  

  This ensures Rancher treats all versions as a single group, eliminating the filtering during upgrades.

If you want custom branches to fit into semantic ordering, name them like 0.0-custom_branch—this places them before 0.3/0.4 while remaining compatible with semantic version parsing.

2. Explicitly Define Version Order

For full control over display order (ignoring automatic sorting), add a catalog.yml file at the root of your template repo to list versions manually:

name: "Your Custom Template"
description: "Brief description of your template"
versions:
  - name: "0.4"
    path: "0.4"
  - name: "0.3"
    path: "0.3"
  - name: "stable"
    path: "stable"
  - name: "custom_branch"
    path: "custom_branch"

Rancher will follow this exact sequence in both new stack creation and upgrade dropdowns.

3. Refresh Catalog Cache

Outdated cache often causes partial version recognition:

1. In Rancher UI, go to Catalogs and locate your custom template repository
2. Click the Refresh button (circular arrow icon) to force a re-sync
3. Wait for the catalog to update, then test the upgrade flow again

4. Upgrade Rancher (If Needed)

Older Rancher versions (pre-v2.6) had known bugs with mixed semantic/non-semantic version handling. If you're running an outdated release, upgrading to a recent stable version (v2.7+) typically resolves these quirks.

Quick Verification Checks #

• After making changes, create a new stack first to confirm all versions appear correctly
• Test upgrading from every version to ensure the full dropdown list loads
• Double-check that every version directory has a valid rancher-compose.yml with a consistent version field declared

内容的提问来源于stack exchange，提问作者Meir Tseitlin