Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
This is a complement to "timestamp" and "timeadd" which allows establishing the ordering of two different timestamps while taking into account their timezone offsets, which isn't otherwise possible using the existing primitives in the Terraform language.
- Loading branch information
1 parent
036db86
commit 29ba8c8
Showing
7 changed files
with
296 additions
and
1 deletion.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,67 @@ | ||
--- | ||
page_title: timecmp - Functions - Configuration Language | ||
description: |- | ||
The timecmp function adds a duration to a timestamp, returning a new | ||
timestamp. | ||
--- | ||
|
||
# `timecmp` Function | ||
|
||
`timecmp` compares two timestamps and returns a number that represents the | ||
ordering of the instants those timestamps represent. | ||
|
||
```hcl | ||
timecmp(timestamp_a, timestamp_b) | ||
``` | ||
|
||
| Condition | Return Value | | ||
|----------------------------------------------------|--------------| | ||
| `timestamp_a` is before `timestamp_b` | `-1` | | ||
| `timestamp_a` is the same instant as `timestamp_b` | `0` | | ||
| `timestamp_a` is after `timestamp_b` | `1` | | ||
|
||
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](https://tools.ietf.org/html/rfc3339) | ||
"Date and Time format" syntax. `timecmp` requires the its two arguments to | ||
both be strings conforming to this syntax. | ||
|
||
## Examples | ||
|
||
``` | ||
> timecmp("2017-11-22T00:00:00Z", "2017-11-22T00:00:00Z") | ||
0 | ||
> timecmp("2017-11-22T00:00:00Z", "2017-11-22T01:00:00Z") | ||
-1 | ||
> timecmp("2017-11-22T01:00:00Z", "2017-11-22T00:00:00Z") | ||
1 | ||
> timecmp("2017-11-22T01:00:00Z", "2017-11-22T00:00:00-01:00") | ||
0 | ||
``` | ||
|
||
`timecmp` can be particularly useful in defining | ||
[custom condition checks](/language/expressions/custom-conditions) 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: | ||
|
||
```hcl | ||
lifecycle { | ||
postcondition { | ||
condition = timecmp(timestamp(), timeadd(self.expiration_timestamp, "-720h")) < 0 | ||
error_message = "Certificate will expire in less than 30 days." | ||
} | ||
} | ||
``` | ||
|
||
## Related Functions | ||
|
||
* [`timestamp`](./timestamp) returns the current timestamp when it is evaluated | ||
during the apply step. | ||
* [`timeadd`](./timeadd) can perform arithmetic on timestamps by adding or | ||
removing a specified duration. |