Description
Customers configuring planned maintenance windows using a weekly schedule with intervalWeeks often assume that interval counting starts immediately from the configured startDate. In practice, the scheduling behavior is different and can lead to confusion when the first maintenance window occurs later than expected.
The current documentation does not clearly explain how the startDate, dayOfWeek, and intervalWeeks are evaluated together, which has resulted in repeated customer questions and misunderstandings.
Actual Behavior
Planned maintenance windows are evaluated based on a fixed weekly cadence.
If the configured startDate falls after the selected dayOfWeek within the same calendar week, that week is considered skipped.
Interval counting begins from the next occurrence of the configured day of the week, and the intervalWeeks value is applied from that point forward.
As a result, the first maintenance window may open later than customers expect.
Example:
As per the above screenshot, assumption is that planned maintenance window is configured to run every 2 weeks on Sunday with the effective maintenance start date as 14th of April 2026. So, as per document assumption is that the next update window should start on 19th of April 2026. But from a recent issue, we identified that as the frequency is 2 weeks, this is starting from 26th of April 2026. As per frequency it is taking 2nd sunday from maintenance start date.
If the startDate occurs after Sunday in the same calendar week, the immediate Sunday is skipped. The interval calculation starts from the next Sunday, and the first maintenance window opens only after completing the full 2-week interval, not on the nearest Sunday after the start date. This is just an example, please clarify accordingly for 3 and 4 as well.
Expected Documentation Improvement
The documentation should explicitly clarify:
That intervalWeeks is anchored to the next eligible occurrence of the configured day of the week after the start date.
That maintenance windows are not applied retroactively to a week where the target day has already passed.
That this behavior applies to planned maintenance in general, regardless of time zone configuration.
Adding this clarification would help set correct expectations and reduce customer confusion when configuring planned maintenance schedules.
Document to update:
https://learn.microsoft.com/en-us/azure/aks/planned-maintenance?tabs=azure-cli
Description
Customers configuring planned maintenance windows using a weekly schedule with intervalWeeks often assume that interval counting starts immediately from the configured startDate. In practice, the scheduling behavior is different and can lead to confusion when the first maintenance window occurs later than expected.
The current documentation does not clearly explain how the startDate, dayOfWeek, and intervalWeeks are evaluated together, which has resulted in repeated customer questions and misunderstandings.
Actual Behavior
Planned maintenance windows are evaluated based on a fixed weekly cadence.
If the configured startDate falls after the selected dayOfWeek within the same calendar week, that week is considered skipped.
Interval counting begins from the next occurrence of the configured day of the week, and the intervalWeeks value is applied from that point forward.
As a result, the first maintenance window may open later than customers expect.
Example:
As per the above screenshot, assumption is that planned maintenance window is configured to run every 2 weeks on Sunday with the effective maintenance start date as 14th of April 2026. So, as per document assumption is that the next update window should start on 19th of April 2026. But from a recent issue, we identified that as the frequency is 2 weeks, this is starting from 26th of April 2026. As per frequency it is taking 2nd sunday from maintenance start date.
If the startDate occurs after Sunday in the same calendar week, the immediate Sunday is skipped. The interval calculation starts from the next Sunday, and the first maintenance window opens only after completing the full 2-week interval, not on the nearest Sunday after the start date. This is just an example, please clarify accordingly for 3 and 4 as well.
Expected Documentation Improvement
The documentation should explicitly clarify:
That intervalWeeks is anchored to the next eligible occurrence of the configured day of the week after the start date.
That maintenance windows are not applied retroactively to a week where the target day has already passed.
That this behavior applies to planned maintenance in general, regardless of time zone configuration.
Adding this clarification would help set correct expectations and reduce customer confusion when configuring planned maintenance schedules.
Document to update:
https://learn.microsoft.com/en-us/azure/aks/planned-maintenance?tabs=azure-cli