Terraform fot d timeadd()

This is part of an ongoing series of posts documenting the built-in interpolation functions in Terraform. For more information, check out the beginning post. In this post I am going to cover the timeadd() function. The example file is on GitHub here.

What is it?

Function name: timeadd(time, duration)

Returns: Takes a date time value and a duration value. Returns the date value plus the duration value. All values should conform to the RFC 3339 format.

Example:

# Returns 2018-09-10T21:00:00Z
output "timeadd_output" {
  value = "${timeadd("2018-09-10T20:00:00Z","1h")}"
}

Example file:

##############################################
# Function: timeadd
##############################################
##############################################
# Variables
##############################################

variable "date" {
  default = "1970-01-01T00:00:00Z"
}

variable "add" {
  default = "1h"
}


##############################################
# Resources
##############################################

##############################################
# Outputs
##############################################
output "1_timeadd_basic" {
  value = "${timeadd(var.date, var.add)}"
}

Run the following from the timeadd folder to get example output for a number of different cases:

# For your reference
# ns = nanosecond
# ms = millisecond
# s = second
# m = minute
# h = hour
# There is nothing bigger than an hour

#Defaults
terraform apply

#Negative duration
terraform apply -var="add=-1h"

#Zero duration
terraform apply -var="add=0h"

#Multiple durations
terraform apply -var="add=1h10m"

#My favorite day, adding a year
terraform apply -var="add=8760h" -var="date=2018-03-14T01:59:27Z"

Why use it?

I imagine using this to schedule a task in the future or retrieve a log from an hour ago. I’ve never had an occasion to use this function personally, so I don’t know what the most common use cases are. Basic date and time manipulation does seem like a fairly common task though.

Lessons Learned

One thing that bothered me is that the documentation references RFC 3339 for its formatting and provides a link to the format, but it doesn’t provide a link or reference what values are accepted for the duration argument. Through a bit of trial and error I found the accepted values in the example above: ns, ms, s, m, h. I assumed that there would be something to alter the day, month, and year, but there is not. Why? Well, the actual function in Terraform makes use of the Golang time package, specifically the Add function for time type variables. Digging into the Golang docs, I found that the Add function uses a Duration value, which is a type with a constructor that takes the following values: nano-second, micro-second, millisecond, second, minute, and hour. And that is because the Add function is only dealing with Time, not Dates. There is a separate function called AddDate that handles manipulating Dates. There should probably be a corresponding dateadd function in Terraform to support that.

Coming up next is the title() function.