The core::semverconstraint function

The core::semverconstraint function compares the version given in the first argument with the version constraint given in the second argument. It returns true if the version matches the constraint, and false otherwise.

Note

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

Signature

core::semverconstraint(version, constraint)

Arguments

Argument	Required	Type	Description
`version`	Yes	String	The semantic version to validate (For example: `"1.2.3"`, `"2.0.0-beta"`).
`constraint`	Yes	String	The version constraint to check against. Uses the same syntax as Terraform version constraints.

Return value

Returns true if the version satisfies the constraint, false otherwise.

Version constraint syntax

The constraint argument uses the same version constraint syntax as Terraform. Refer to Version constraint syntax for detailed information.

Common constraint operators:

= 1.2.3 - Exactly version 1.2.3
!= 1.2.3 - Any version except 1.2.3
> 1.2.3 - Greater than 1.2.3
>= 1.2.3 - Greater than or equal to 1.2.3
< 1.2.3 - Less than 1.2.3
<= 1.2.3 - Less than or equal to 1.2.3
~> 1.2.3 - Pessimistic constraint (>= 1.2.3, < 1.3.0)
>= 1.0.0, < 2.0.0 - Multiple constraints

Examples

The following examples demonstrate the use of semver comaparison for specific use cases.

Enforce minimum provider version

In the following example, the core::semverconstraint function is used to enforce a provider version.

provider_policy "aws" "minimum_version" {
  locals {
    meets_minimum = core::semverconstraint(meta.version, ">= 5.0.0")
  }

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

Enforce version range

In the following example, the core::semverconstraint function is used to ensure module versions fall within the given range.

module_policy "app.terraform.io/my-org/vpc/aws" "version_range" {
  locals {
    in_range = core::semverconstraint(meta.version, ">= 2.0.0, < 3.0.0")
  }

  enforce {
    condition     = local.in_range
    error_message = "The VPC module must be version 2.x.x. Current version: ${meta.version}"
  }
}

Use pessimistic constraint

In the following example, the core::semverconstraint function is used to ensure that the provider is the specified minor release.

provider_policy "google" "compatible_version" {
  locals {
    is_compatible = core::semverconstraint(meta.version, "~> 4.50.0")
  }

  enforce {
    condition     = local.is_compatible
    error_message = "Google provider must be version ~> 4.50.0 (>= 4.50.0, < 4.51.0). Current: ${meta.version}"
  }
}

Exclude specific versions

In the following example, the core::semverconstraint function is used to exclude a specific version of a provider.

provider_policy "azurerm" "no_buggy_version" {
  locals {
    not_buggy = core::semverconstraint(meta.version, "!= 3.45.0")
  }

  enforce {
    condition     = local.not_buggy
    error_message = "Azure provider version 3.45.0 has known issues and must not be used."
  }
}

Use with input variables

In the following example, the core::semverconstraint function is used with an input to configure a minimum provider version.

input "min_provider_version" {
  type        = string
  description = "Minimum required provider version"
  default     = "5.0.0"
}

provider_policy "aws" "configurable_minimum" {
  locals {
    meets_requirement = core::semverconstraint(meta.version, ">= ${input.min_provider_version}")
  }

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

Complex version logic

In the following example, the core::semverconstraint function is used to ensure that the provider version matches one of two allowed major versions.

provider_policy "kubernetes" "version_policy" {
  locals {
    # Allow 2.x.x versions >= 2.10.0 OR any 3.x.x version
    version_2x = core::semverconstraint(meta.version, ">= 2.10.0, < 3.0.0")
    version_3x = core::semverconstraint(meta.version, ">= 3.0.0, < 4.0.0")
    is_approved = local.version_2x || local.version_3x
  }

  enforce {
    condition     = local.is_approved
    error_message = "Kubernetes provider must be version >= 2.10.0 and < 4.0.0. Current: ${meta.version}"
    info_message  = "Using Kubernetes provider version ${meta.version}"
  }
}