Support Week Numbers

[bloudraak]

Terraform CLI and Provider Versions

$ terraform version
Terraform v1.5.3
on darwin_amd64

Use Cases or Problem Statement

Problem

There is often a need to change the passwords, certificates and whatnot based on the week number. The primary reason for using the week number as appose to every seven days is due to the week number changing on specific days of the week (Monday according to ISO 8601), and thus offer predictability.

Use Case 1:

Change the password every time the week number changes, which would be the first time it's invoked, which is the first Monday if per ISO 8601.

Use Case 2:

In order to ensure system remain operational, there's a need to maintain several passwords concurrently. A common approach is to have two passwords namely odd and even. The passwords are updated under these circumstances:

1. When the week number is odd, the even password should be updated.
2. When the week number is even, the odd password should be updated.

Proposal

Resources

The proposal is to support ISO week numbers in every resource, except time_sleep.

time_offset

For time_offset provide an additional attribute, namely offset_weeks. In this example, the offset would be two weeks from now. So if the current week number is 26, that will be after midnight Monday, week 28.

resource "time_offset" "example" {
  offset_weeks = 2
}

time_rotating

For time_rotating provide an additional attribute, namely rotation_weeks. In this example it recreates the resource every Monday at midnight.

resource "time_rotating" "example" {
  rotation_weeks = 1
}

In this example, it recreates the resource every second Monday at midnight.

resource "time_rotating" "example" {
  rotation_weeks = 1
}

time_static

time_static exposes the week number for the given timestamp.

resource "time_static" "example" {}

output "current_week_number" {
  value = time_static.example.weeknumber
}

Additional Considerations

Optionally accept options, to allow for culture specific handling.

• a rule
  • first day ⏤ week 1 of a year starts on the first day of the year, so Jan 1 will always be week 1
  • first four day week ⏤ week 1 of a year starts on the first week that has four or more days in it. This is the default per ISO 8601
  • first full week ⏤ week 1 starts on the first full week
• day of the week ⏤ the first day of the week (for example, Sunday for USA, Canada and Japan, Saturday in some Islam countries). The default is Monday (per ISO 8601)

So time_rotating may look as follows, stating that it should be recreated every second Sunday (that's when the week starts), with week numbers starting on the first day of the year.

resource "time_rotating" "example" {
  rotation_weeks = 2
  week_number {
      year_offset = 4   //  the week 1 starts with the first week that has 4 days or more in it
      day = "sunday"
  }
}

Supporting odd/even

(This may be a separate feature request, since it doesn't only extend to week numbers)

One of the challenges is to trigger an recreate of a resource so that we can support the odd/even pattern when changing passwords of systems that doesn't allow more than one password. The proposal would be to introduce an "invalidate" block into each resource, allowing us to invalidate the resource based on modulus.

For example, the following time_rotating resources will be invalidated when the modulus of the week number is 1 or 0 respectively. This approach may be useful when dealing with rotating passwords on a daily basis.

resource "time_rotating" "odd" {
  rotation_weeks = 1
  invalidate {
      modulus = 2
      value = 1
  }
}

resource "time_rotating" "even" {
  rotation_weeks = 1
  invalidate {
      modulus = 2
      value = 0
  }
}

Another approach would be to add an offset to the timestamp only during creation. This example accomplishes the same effect as the previous example but may be more obvious.

resource "time_rotating" "odd" {
  rotation_weeks = 2
  offset {
      weeks = 1
  }
}

resource "time_rotating" "even" {
  rotation_weeks = 2
  offset {
      weeks = 2
  }
}

So if it's July 18, 2023, odd would be invalidated on Monday, July 24, and then August 7, while even will be invalidated on Monday, July 31, 2023 and then on August 14, 2023. This approach may be better than the modulus approach, and can be useful for hours, days and months.

How much impact is this issue causing?

High

Additional Information

Here's the Go code for getting the ISO 8601 week number for a given timestamp.

tn := time.Now().UTC()
year, week := tn.ISOWeek()

See the section Week Dates about how to format it.

The .NET library provides Calendar.GetWeekOfYear which accepts a timestamp, a rule, and culture specific day of the week. This may act as inspiration for the proposal to extend week number handling with additional options to support additional cultures. There's also ISOWeek

Code of Conduct

• I agree to follow this project's Code of Conduct