Skip to content
On this page

tm_timecmp Function

tm_timecmp compares two timestamps and returns a number that represents the ordering of the instants those timestamps represent.

tm_timecmp(timestamp_a, timestamp_b)
ConditionReturn Value
timestamp_a is before timestamp_b-1
timestamp_a is the same instant as timestamp_b0
timestamp_a is after timestamp_b1

When comparing the timestamps, timecmp takes into account the UTC offsets given in each timestamp. For example, 06:00:00+0200 and 04:00:00Z are the same instant after taking into account the +0200 offset on the first timestamp.

In the Terraform language, timestamps are conventionally represented as strings using RFC 3339 "Date and Time format" syntax. timecmp requires the its two arguments to both be strings conforming to this syntax.


tm_timecmp("2017-11-22T00:00:00Z", "2017-11-22T00:00:00Z")
tm_timecmp("2017-11-22T00:00:00Z", "2017-11-22T01:00:00Z")
tm_timecmp("2017-11-22T01:00:00Z", "2017-11-22T00:00:00Z")
tm_timecmp("2017-11-22T01:00:00Z", "2017-11-22T00:00:00-01:00")

tm_timecmp can be particularly useful in defining custom condition checks that involve a specified timestamp being within a particular range. For example, the following resource postcondition would raise an error if a TLS certificate (or other expiring object) expires sooner than 30 days from the time of the "apply" step:

lifecycle {
    postcondition {
      condition     = timecmp(timestamp(), timeadd(self.expiration_timestamp, "-720h")) < 0
      error_message = "Certificate will expire in less than 30 days."
  • tm_timestamp returns the current timestamp when it is evaluated during the apply step.
  • tm_timeadd can perform arithmetic on timestamps by adding or removing a specified duration.