Skip to main content
logoTetrate Istio SubscriptionVersion: Next

Versioning System Update

Overview​

This document describes the changes in the versioning system for Tetrate Istio Distro (TID) and Tetrate Istio Subscription (TIS) Helm charts. These updates aim to streamline version numbering, enhance clarity, and address issues with Helm's version sorting. Below is a detailed overview of the previous schema, the new schema, and the motivations behind these changes.

Previous Schema - Prior to December 2023​

  • Chart Version: 1.20.0
  • App Version: 1.20.0-tetrate-v0

In the previous schema:

  1. Chart Version mirrored the upstream Istio version directly, without indicating TID-specific modifications.
  2. App Version appended a hyphen (-) followed by tetrate-vN (e.g., 1.20.0-tetrate-v0), where N denoted specific build or release iterations.
  3. Sorting Behavior: The use of a hyphen (-) was treated as a "pre-release" indicator per Semantic Versioning. This behavior was handled properly by Helm, as pre-release versions are part of the sorting mechanism. However, the introduction of the + symbol to align with Semantic Versioning as "build metadata" led to sorting issues, as metadata is ignored during version comparison.

This schema provided basic functionality but introduced limitations when distinguishing between upstream Istio releases and TID-specific changes, and when aligning with Semantic Versioning standards.

New Schema - December 2023 and Later​

  • Chart Version: 1.20.0+tetrate0
  • App Version: 1.20.0-tetrate0

In the new schema:

  1. Chart Version now uses the format: MAJOR.MINOR.PATCH+DISTRO
    • MAJOR: Matches the upstream Istio major version.
    • MINOR: Matches the upstream Istio minor version.
    • PATCH: Matches the upstream Istio patch version.
    • DISTRO: Tracks TID-specific changes, starting at tetrate0 for the initial release.
  2. A plus sign (+) is used in the Chart Version to align with Semantic Versioning, which defines + as build metadata. This allows TID to distinguish its specific changes without affecting the core version comparison rules.
  3. A canonical version (e.g., 1.20.30000) is introduced to ensure Helm displays the latest versions correctly. This is necessary because Helm ignores the + build metadata during version sorting. Canonical versions act as aliases and follow a structured format for sorting purposes while pointing to the actual + version.
  4. App Version continues to use a hyphen (-) (e.g., 1.20.0-tetrate0) to comply with Kubernetes naming conventions.

This schema improves clarity by clearly separating TID-specific changes and ensures compatibility with both Helm and Semantic Versioning standards.

Key Changes in the New Schema​

  1. Sorting Adjustment with Canonical Versions: Helm's inability to sort versions containing + properly is mitigated by introducing a canonical version. This version format is for display purposes and ensures correct sorting while retaining Semantic Versioning compliance.
  2. Clarification of Sorting Behavior:
    • Versions using + are considered build metadata in Semantic Versioning and ignored during sorting. As such, Helm displays the canonical version instead.
    • Versions with - (used in App Version) remain sortable as pre-release versions.

Example Helm Outputs​

Search Without a Version Specifier​

$ helm search repo tetratelabs/base
NAME                    CHART VERSION   APP VERSION     DESCRIPTION
tetratelabs/base        1.20.30000      1.20.0-tetrate0 Helm chart for deploying Istio cluster resources

Search With a Specific Version​

$ helm search repo tetratelabs/base --version "1.20.0+tetrate0"
NAME                    CHART VERSION   APP VERSION     DESCRIPTION
tetratelabs/base        1.20.0+tetrate0 1.20.0-tetrate0 Helm chart for deploying Istio cluster resources

Installation Example​

You can use either the canonical version or the actual version during installation:

$ helm install base tetratelabs/base --version "1.20.30000"
# or
$ helm install base tetratelabs/base --version "1.20.0+tetrate0"

Transition Strategy​

To minimize disruptions, TID is maintaining two Helm repositories during the transition period:

  • Legacy Repository (valid until TID 1.24.0):

  • New Repository (new versioning system):

Users are encouraged to migrate scripts and configurations to the new repository before the legacy repository is deprecated post-TID 1.24.0.

FAQ​

  • Why the Change in Versioning? The new schema improves clarity, aligns with Semantic Versioning, and resolves sorting issues in Helm.

  • Is + Still Supported? Yes, the actual version format with + is fully supported for installations and aligns with Semantic Versioning.

  • What About FIPS Deployments? Helm charts support both FIPS and non-FIPS deployments. To install a FIPS-compliant version, configure the image registry accordingly.