Skip to main content
Version: v4.11 Stable

Versioning Templates

Enterprise
Available in these plansFreeDevProdScale
Template Versioning

Free, Dev, Prod, and Scale are vCluster Platform license plans. Open source does not need a license or a Platform connection. See Compare open source and free tiers.

Versioning a template allows you to make changes over time to a template while retaining the current version/iteration. Resources (for example tenant clusters, namespaces) that are deployed with templates that have updated versions show up with a warning indicating that a newer template version is available.

Template version strings​

When creating a tenant cluster from a template, you can specify a template version string. If omitted, the latest available version is selected by default.

You can use the X wildcard in the major, minor, or patch components of the version string to enable automatic upgrades. This allows tenant clusters to automatically update to newer compatible versions of the template.

For example given a template version 1.0.0:

  • If you set the version string to 1.X.X, and a new template version 1.1.0 is added, the tenant cluster will automatically upgrade to 1.1.0.
  • If a version 2.0.0 is added instead, the tenant cluster is not upgraded, because the major version does not match.

To always upgrade to the latest available version, you can X.X.X as the version string.

note

Avoid using X.X.X unless necessary. Use the X placeholder only in the minor or patch position—for example, 1.X.X or 1.2.X—to maintain greater control over version updates.

How template changes propagate to existing resources​

Whether a template change reaches an already-created tenant cluster or namespace depends on whether the template is versioned.

For a versioned template, every reconcile re-evaluates the resource's version string against the versions available on the template, and applies whichever version matches. This is what makes wildcard version strings such as 1.X.X self-updating. As soon as a new matching version is added, it's applied automatically. If a resource pins an exact version, edits to that specific version's configuration still propagate automatically, but adding a newer version alongside it does not, since the exact pin never matches anything else.

For a template with no versions (a single, unversioned spec.template), an edit to the template only reaches resources that reference it in three cases. The resource is being created for the first time, its templateRef.syncOnce field is set to true, or its version string is exactly x.x.x. Otherwise, the resource keeps running its last-applied configuration, and the platform UI surfaces the pending change as a Template Changes Available notice without applying it.

To force a one-time sync after editing an unversioned template, set syncOnce on the affected resource:

Modify the following with your specific values to generate a copyable command:
spec:
  templateRef:
    name: my-template
    syncOnce: true

syncOnce resets to false automatically once the resource's template resolves, so it needs to be set again for any subsequent edit. A TemplateResolved failure, for example ErrorRenderingTemplate, leaves syncOnce set, since the sync never got that far. Once resolution succeeds, syncOnce clears even if applying the change afterward still fails. To have a resource pick up template edits automatically without setting syncOnce each time, use x.x.x as the version string instead, which behaves like a versioned template's wildcard match even though the referenced template itself has no versions.

Unlike the X/x wildcards on a versioned template, which match regardless of case, this x.x.x sentinel is checked as an exact, case-sensitive string. X.X.X doesn't trigger it. The version gets cleared instead, and the resource falls back to needing syncOnce for each edit.

If a template change doesn't reach a resource the way you expect, see Troubleshoot template and app sync failures.

Create a template version​

You can add new versions to your templates using the UI. The steps are the same for all resources.

note

Alternatively, you can use a GitOps workflow by applying an updated VirtualClusterInstance resource to the vCluster Platform cluster using tools such as kubectl or Argo CD.

Semantic versioning

While not strictly mandatory, you should follow standard semantic versioning practices for your template versioning. vCluster Platform refers to the version numbers provided when determining whether to indicate if a template has a newer version available.

  1. Go to Tenant Management and select the template type you want to version.

  2. Find the template you want to add a new version to in the list. Click the actions menu next to its name and click Add New Version.

  3. In the pop-up window, enter the new version string for your App. Then, click .

  4. In the menus displayed in the right, make any modifications desired for your new template version.

  5. Click .

Update a template​

You can change the template and/or template version in the UI.

  1. Select the project containing the resource using the project selector dropdown.

  2. Click the resource type on the project page.

  3. Click the actions menu next to the resource you want to modify and select Change Template.

  4. In the pop-up window, select the name of the template from the list. The applied template is already selected, so if you are changing the template version, you don't need to do anything for this step.

  5. If the template has multiple versions, a version selector appears next to the template selector. Select your desired template version.

  6. Click .