feat(promotion-windows): add promotion windows for auto-promotion

[LittaKake]

Promotion Windows

This PR partly adds the requested feature for allowing/disallowing promotions based on time windows as tracked here #1328.

PR introduces a new CRD, PromotionWindow, which can be referenced from ProjectConfig.spec.promotionPolicies[].promotionWindows to control when automatic promotions are allowed or denied.

I opted for a CRD for re-usability of common timewindows (such as weekends). Its also easier to re-use if its ever decided to put a reference field in either stage or warehouse aswell.

Note

The PR opts for putting promotionWindows directly below promotionPolicies for now, but it could be better to rework the spec with ...promotionPolicies[].autoPromotion.enabled and ...promotionPolicies[].autoPromotion.promotionWindows instead. But I want someones opinion on this before proceeding.

PromotionWindow CRD

A PromotionWindow defines, in spec, a time window using the following fields:

• kind: Either allow or deny, determining whether promotions are permitted or blocked while the window is active.
• schedule: A cron expression (parsed using robfig/cron) defining when the window starts.
• duration: How long the window remains active after each scheduled start.
• timeZone: An IANA time zone (e.g. UTC, Europe/Oslo) resolved via Go’s time package / tzdata.

Example

Define a PromotionWindow that allows promotions during weekdays:

apiVersion: kargo.akuity.io/v1alpha1
kind: PromotionWindow
metadata:
  name: allow-weekend
  namespace: my-project
spec:
  kind: "allow"
  schedule: "0 0 * * 1-5"
  duration: "24h"
  timeZone: "Europe/xxx"

Reference the window from a ProjectConfig:

apiVersion: kargo.akuity.io/v1alpha1
kind: ProjectConfig
metadata:
  name: my-project
  namespace: my-project
spec:
  promotionPolicies:
  - stageSelector:
      name: automation-window-test
    autoPromotionEnabled: true
    promotionWindows:
    - name: allow-weekend
      kind: PromotionWindow

Evaluation

The evaluation of promotionWindows are as follows

// CheckPromotionWindows checks all defined promotion windows to determine if
// promotion is allowed at the current time. It follows these rules:
//
//  1. If no promotion windows are defined, promotions are allowed by default.
//  2. If a allow window is defined, the current time must fall within the allow windows for
//     promotion to be allowed.
//  3. If a deny window is defined, the current time must not fall within any deny windows for
//     promotion to be allowed.
//  4. If both a allow and deny window is active, the deny window takes precedence and
//     promotions are denied.
// 5. If both a allow and deny window are defined, but none are active, promotions are denied.

Considerations

1. In the future, create ClusterPromotionWindow to enable re-use of typical windows (such as christmas, weekends, etc)

[netlify]

✅ Deploy Preview for docs-kargo-io ready!

Name	Link
🔨 Latest commit	1dddda1
🔍 Latest deploy log	https://app.netlify.com/projects/docs-kargo-io/deploys/6952e7b25585b30008f02efc
😎 Deploy Preview	https://deploy-preview-5544.docs.kargo.io
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Default to UTC when timeZone is omitted

checkPromotionWindow always calls time.LoadLocation(promotionWindowSpec.TimeZone) and treats a missing timeZone as an error, even though the CRD/docs describe the field as optional with a UTC default. Any PromotionWindow created without a timeZone now returns an error from CheckPromotionWindows, which bubbles up through autoPromotionAllowed and blocks Stage reconciliation/auto-promotion. Please default to UTC when the field is empty instead of erroring.

Useful? React with 👍 / 👎.

[LittaKake]

if the returned timeZone is "" it should already default to UTC.

If the name is "" or "UTC", LoadLocation returns UTC. If the name is "Local", LoadLocation returns Local.

[sstarcher]

Conceptually if you had auto promotion on and had a promotion window. If something was wrong with the release to prevent it from being promoted to the next env you would need to modify this CR and disable the window. Is that the correct structure you imagine?

[LittaKake]

Conceptually if you had auto promotion on and had a promotion window. If something was wrong with the release to prevent it from being promoted to the next env you would need to modify this CR and disable the window. Is that the correct structure you imagine?

My intent isn't to have this CR used for adhoc disabling of autopromotion. If thats what you mean.