The core::semvercmp function

The core::semvercmp function compares two semantic version strings. It returns -1 if the first version is older than the second, 0 if they are the same, and 1 if the first version is newer than the second.

Note

This functionality is in beta. Do not use beta features in production environments.

Signature

core::semvercmp(version_a, version_b)

Arguments

Argument	Required	Type	Description
`version_a`	Yes	String	The first semantic version to compare (For example: `"1.2.3"`, `"2.0.0-beta"`).
`version_b`	Yes	String	The second semantic version to compare (For example: `"1.2.3"`, `"2.0.0-beta"`).

Return value

Returns a number indicating the comparison result:

-1 if version_a is older than version_b
0 if version_a is the same as version_b
1 if version_a is newer than version_b

Raises an error if either version string is not a valid semver.

Semantic version format

Version strings must follow semantic versioning format: MAJOR.MINOR.PATCH[-PRERELEASE][+BUILD]

Examples of valid versions:

Examples

The following examples demonstrate the use of semantic version comparison for specific use cases.

Compare provider versions

In the following example, the core::semvercmp function compares the current provider version against a minimum required version.

provider_policy "aws" "minimum_version_check" {
  locals {
    min_version        = "5.0.0"
    version_comparison = core::semvercmp(meta.version, local.min_version)
    meets_minimum      = local.version_comparison >= 0
  }

  enforce {
    condition     = local.meets_minimum
    error_message = "AWS provider version must be at least ${local.min_version}. Current version: ${meta.version}"
  }
}

Enforce version range

In the following example, the core::semvercmp function ensures a module version falls within an acceptable range.

module_policy "app.terraform.io/my-org/vpc/aws" "version_range" {
  locals {
    min_version = "2.0.0"
    max_version = "3.0.0"
    above_min   = core::semvercmp(meta.version, local.min_version) >= 0
    below_max   = core::semvercmp(meta.version, local.max_version) < 0
    in_range    = local.above_min && local.below_max
  }

  enforce {
    condition     = local.in_range
    error_message = "VPC module version must be >= ${local.min_version} and < ${local.max_version}. Current: ${meta.version}"
  }
}

Compare versions for conditional logic

In the following example, the core::semvercmp function determines which validation rules to apply based on version.

provider_policy "google" "version_specific_rules" {
  locals {
    min_version = "4.50.0"
    is_newer    = core::semvercmp(meta.version, local.min_version) >= 0
  }

  enforce {
    condition     = local.is_newer
    error_message = "Google provider must be version ${local.min_version} or newer for required features. Current: ${meta.version}"
  }
}

Handle pre-release versions

In the following example, the core::semvercmp function compares versions including pre-release identifiers.

provider_policy "azurerm" "stable_versions_only" {
  locals {
    # Check if version is a pre-release (contains -)
    is_prerelease = core::contains_substring(meta.version, "-")

    # If not comparing pre-release versions
    min_stable         = "3.0.0"
    is_stable_or_newer = core::semvercmp(meta.version, local.min_stable) >= 0
  }

  enforce {
    condition     = !local.is_prerelease && local.is_stable_or_newer
    error_message = "Azure provider must be a stable version >= ${local.min_stable}. Current: ${meta.version}"
  }
}

Exclude specific version ranges

In the following example, the core::semvercmp function excludes versions known to have issues.

provider_policy "aws" "exclude_buggy_versions" {
  locals {
    buggy_start = "4.45.0"
    buggy_end   = "4.47.0"

    is_in_buggy_range = (
      core::semvercmp(meta.version, local.buggy_start) >= 0 &&
      core::semvercmp(meta.version, local.buggy_end) <= 0
    )
  }

  enforce {
    condition     = !local.is_in_buggy_range
    error_message = "AWS provider versions ${local.buggy_start} through ${local.buggy_end} have known issues. Current: ${meta.version}"
  }
}