Configure maintenance windows and exclusions

Autopilot Standard

Use maintenance windows and maintenance exclusions to control when automatic cluster maintenance, such as auto-upgrades, can and can't occur on your Google Kubernetes Engine (GKE) clusters. Before configuring these maintenance policies, ensure that you review what changes do and don't respect GKE maintenance policies.

Before you begin

Before you start, make sure you have performed the following tasks:

Enable the Google Kubernetes Engine API.

Enable Google Kubernetes Engine API

If you want to use the Google Cloud CLI for this task, install and then initialize the gcloud CLI. If you previously installed the gcloud CLI, get the latest version by running gcloud components update.
Note: For existing gcloud CLI installations, make sure to set the compute/region and compute/zone properties. By setting default locations, you can avoid errors in gcloud CLI like the following: One of [--zone, --region] must be supplied: Please specify location.

Configure a maintenance window

To configure a maintenance window, specify when it starts, how long it lasts, and how often it repeats. For example, you can configure a maintenance window that recurs weekly on Monday through Friday for four hours each day.

You can configure a maintenance window by using the Google Cloud console or the Google Cloud CLI.

Considerations when configuring a maintenance window

When configuring a maintenance window, follow this guidance:

Understand which types of maintenance events do and don't respect GKE maintenance windows. To learn more, see Automatic maintenance that respects GKE maintenance policies and Automatic maintenance that doesn't respect GKE maintenance policies.
You can only configure one maintenance window for a cluster, and configuring a new window overwrites the previous one.
You must allow at least 48 hours of maintenance availability in a 32-day rolling window. Only contiguous availability windows of at least four hours are considered.
When using the Google Cloud console, times are always displayed using the local time zone.
Day of the week recurrences are always based on UTC. As a result, we recommend setting maintenance windows involving such recurrences entirely in UTC, through the gcloud CLI. While local time can be used when setting flags, the time zone won't be stored. For example, if your time zone is UTC+6 and you want a maintenance window to start at 02:00 on Wednesdays in your time zone, then specify a UTC value of 20:00 on Tuesdays. To learn more, see Time zones for maintenance windows.

Maintenance window preventing node update completion

If your cluster can't finish node updates, such as node version upgrades, within the scheduled maintenance window, this can slow down the rate of upgrades, or delay changes to the nodes from completing. You might need to experiment with your configuration to find the optimal balance between speed and disruption for your environment. Factors that can affect the upgrade rate include:

Low maintenance availability (for example, short maintenance windows).
Large Standard node pools.
Node upgrade strategy configuration prioritizing minimal disruption versus speed.
Some Pod configuration choices. See Considerations for node upgrade duration for more information.

Create a Standard cluster with a simple maintenance window

You can create a simple maintenance window in the gcloud CLI by specifying the --maintenance-window flag. This flag allows you to specify a daily 4-hour maintenance window using a simplified format. To create an Autopilot cluster with a maintenance window, use the Google Cloud console.

Create a new Standard cluster with a simple maintenance window:

gcloud container clusters create CLUSTER_NAME \
    --maintenance-window START_TIME

Replace the following:

CLUSTER_NAME: The name of your new cluster.
START_TIME: A 24-hour timestamp in UTC time, like 16:00.

The maintenance window runs each day at the specified START_TIME and runs for four hours.

Create a custom maintenance window

You can create a maintenance window that occurs certain times of the week or month using additional parameters explained in this section.

For example, the following command creates a cluster named my-cluster with a maintenance window enabled at 2:00 AM UTC on Friday, August 23, 2024. This maintenance window recurs weekly every Monday and Friday, and ends 30 hours later. The first occurrence of the maintenance window starts on Friday, August 23 at 2:00 AM and ends on Saturday, August 24, at 8:00 AM. You can learn more about formatting dates and times.

gcloud container clusters create my-cluster \
    --maintenance-window-start 2024-08-23T02:00:00Z \
    --maintenance-window-end 2024-08-24T08:00:00Z \
    --maintenance-window-recurrence 'FREQ=WEEKLY;BYDAY=MO,FR'

For more scenarios, see the example maintenance windows.

Create a cluster with a maintenance window

You can create a new Standard cluster with a maintenance window by using the gcloud CLI or the Google Cloud console. To create a new Autopilot cluster with a maintenance window, use the Google Cloud console.

gcloud

Create a new Standard cluster with a maintenance window:

gcloud container clusters create CLUSTER_NAME \
    --maintenance-window-start START_TIME \
    --maintenance-window-end END_TIME \
    --maintenance-window-recurrence RRULE

Replace the following:

CLUSTER_NAME: The name of the new cluster.
START_TIME: The date and time that the recurring maintenance window is enabled, expressed as an RFC-5545 DTSTART value. After this time, the maintenance window repeats according to the RRULE. The START_TIME also provides at what time of day the maintenance window starts.
END_TIME: The end time for calculating the duration of the maintenance window, as expressed by the amount of time after the START_TIME, in the same format. The value for END_TIME must be in the future, relative to START_TIME. This only calculates the duration of the window, and doesn't set when the maintenance window stops recurring. Maintenance windows only stop recurring when they're removed.
RRULE: The recurrence of the maintenance window, as expressed by an RFC-5545 RRULE. This is a flexible format with multiple ways to specify recurrence rules, determining what day the maintenance window starts. For example, you can specify a recurrence of certain times a week or month. If the END_TIME date is greater than the START_TIME date, the maintenance window spans multiple days. For example, a maintenance window starting on Sunday would continue to Monday.

Console

Go to the Google Kubernetes Engine page in the Google Cloud console.

Go to Google Kubernetes Engine
Click Create.
Configure your cluster.
From the navigation pane, under Clusters, click Automation.
Select the Enable Maintenance Window checkbox.
Select the start time and length, then select the days of the week on which the maintenance window occurs. To edit the recurrence rule specification (RRule) directly, select Custom editor.
Click Create.

Configure a maintenance window for an existing cluster

gcloud

Create or update a maintenance window for an existing cluster:

gcloud container clusters update CLUSTER_NAME \
    --maintenance-window-start START_TIME \
    --maintenance-window-end END_TIME \
    --maintenance-window-recurrence RRULE

Replace the following:

CLUSTER_NAME: The name of the new cluster.
START_TIME: The date and time that the recurring maintenance window is enabled, expressed as an RFC-5545 DTSTART value. After this time, the maintenance window repeats according to the RRULE. The START_TIME also provides at what time of day the maintenance window starts.
END_TIME: The end time for calculating the duration of the maintenance window, as expressed by the amount of time after the START_TIME, in the same format. The value for END_TIME must be in the future, relative to START_TIME. This only calculates the duration of the window, and doesn't set when the maintenance window stops recurring. Maintenance windows only stop recurring when they're removed.
RRULE: The recurrence of the maintenance window, as expressed by an RFC-5545 RRULE. This is a flexible format with multiple ways to specify recurrence rules, determining what day the maintenance window starts. For example, you can specify a recurrence of certain times a week or month. If the END_TIME date is greater than the START_TIME date, the maintenance window spans multiple days. For example, a maintenance window starting on Sunday would continue to Monday.

Console

To create or modify a maintenance window for an existing cluster:

Go to the Google Kubernetes Engine page in the Google Cloud console.

Go to Google Kubernetes Engine
In the cluster list, click the name of the cluster you want to modify.
Under Automation, click Edit maintenance policy next to the Maintenance window field.
Select the Enable Maintenance Window checkbox.
Select the start time and length, then select the days of the week on which the maintenance window occurs. To edit the RRule directly, select Custom editor.
Click Save Changes.

Manually finish incomplete maintenance

If an upgrade or other automatic maintenance takes longer than the maintenance window to complete, GKE attempts to stop ongoing maintenance tasks and resumes them during the next occurrence of the maintenance window. If an automatic upgrade is canceled, and you have node auto-upgrades enabled, your nodes might be in a mixed-version state but your cluster should operate normally.

To manually upgrade your cluster, or cancel or roll back a partial upgrade, visit Manually upgrading a cluster.

Remove a maintenance window

gcloud

Remove a maintenance window from a cluster:

gcloud container clusters update CLUSTER_NAME --clear-maintenance-window

Replace CLUSTER_NAME with the name of the existing cluster.

Console

To remove a maintenance window:

Go to the Google Kubernetes Engine page in the Google Cloud console.

Go to Google Kubernetes Engine
In the cluster list, click the name of the cluster you want to modify.
Under Automation, click Edit maintenance policy next to the Maintenance window field.
Clear the Enable Maintenance Window checkbox.
Click Save Changes.

Example maintenance windows

The following examples illustrate some of the different ways you can configure a maintenance window. Only the relevant flags are shown, because the flags use the same syntax for creating a new cluster or updating an existing one.

Weekends, starting August 22, 2026

In this example, the difference between the start and end timestamps is two full days, so the maintenance window runs for the entire weekend, throughout Saturdays and Sundays. If you want the window to be a different length than exactly 48 hours, modify the -start to change when the window starts, or the -end to change the total length of the window.

  --maintenance-window-start 2026-08-22T00:00:00Z \
  --maintenance-window-end 2026-08-24T00:00:00Z \
  --maintenance-window-recurrence 'FREQ=WEEKLY;BYDAY=SA'

Daily on weekdays from 9:00-17:00 UTC-4

This example shows how to have a daily maintenance window, but skip weekends. This example specifies a non-UTC time zone.

   --maintenance-window-start 2026-09-02T09:00:00-04:00 \
   --maintenance-window-end 2026-09-02T17:00:00-04:00 \
   --maintenance-window-recurrence 'FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR'

Weekly at 4PM for 8 hours, UTC-7

If you don't specify a time zone for --maintenance-window-start, local time is used, as configured in your Google Cloud account. The ** Google Cloud console always uses local time.**

   --maintenance-window-start 2026-08-13T16:00:00-7:00 \
   --maintenance-window-end 2026-08-14T00:00:00-7:00 \
   --maintenance-window-recurrence 'FREQ=WEEKLY'

Weekdays at night

This example shows a daily maintenance window that runs overnight between workdays in the UTC-7 time zone. In this example, the window runs from 20:00 in the evening until 4:00 the next morning.

   --maintenance-window-start 2026-08-15T20:00:00-7:00 \
   --maintenance-window-end 2026-08-16T04:00:00-7:00 \
   --maintenance-window-recurrence 'FREQ=WEEKLY;BYDAY=MO,TU,WE,TH'

Configure a maintenance exclusion

To set up a maintenance exclusion for your cluster, you need to specify the following:

Name: The name of the exclusion (optional).
Start time: The date and time for when the exclusion period should start. The start time must be now or in the future.
End time: The date and time for when the exclusion period should end. Refer to the following table for restrictions on the length of an exclusion period for each of the available scopes.
Scope: The scope of automatic upgrades to restrict. Refer to the following table that lists the available exclusion scopes.

Scope	Description	Maximum exclusion length
No upgrades (default)	Excludes all patch and minor upgrades. Avoids VM disruptions to the cluster's control plane and nodes from upgrades.	Cannot exceed 30 days.
No minor upgrades	Excludes all minor upgrades. VM disruptions can occur to the cluster's control plane and nodes due to patch upgrades.	For clusters enrolled in the Rapid, Regular, or Stable channels, can't extend past the end of standard support. For clusters enrolled in the Extended channel, can't extend past the end of extended support of the minor version.
No minor or node upgrades	Excludes all minor upgrades and node upgrades. Avoids VM disruptions to the cluster's nodes from upgrades. However, disruptions can occur to the control plane.	For clusters enrolled in the Rapid, Regular, or Stable channels, can't extend past the end of standard support. For clusters enrolled in the Extended channel, can't extend past the end of extended support of the minor version.

Create a cluster with a maintenance exclusion

You can configure a maintenance exclusion when creating a new cluster by using the Google Cloud console. This task cannot be performed in the gcloud CLI.

To create a new cluster with a maintenance exclusion:

Go to the Google Kubernetes Engine page in the Google Cloud console.

Go to Google Kubernetes Engine
Click Create.
Configure your cluster.
From the navigation pane, under Cluster, click Automation.
Under Maintenance exclusions, click Add Maintenance Exclusion.
Select the Scope, a Start time, and an End time.
Click Create.

You can see an example maintenance exclusion for Black Friday.

Configure a maintenance exclusion for an existing cluster

You can configure a maintenance exclusion on an existing cluster by using the Google Cloud console or the gcloud CLI.

gcloud

Configure a maintenance exclusion for an existing cluster:

gcloud container clusters update CLUSTER_NAME \
    --add-maintenance-exclusion-name EXCLUSION_NAME \
    --add-maintenance-exclusion-start START_DATE_TIME \
    --add-maintenance-exclusion-end END_DATE_TIME \
    --add-maintenance-exclusion-scope SCOPE

Replace the following:

CLUSTER_NAME: the name of your cluster.
EXCLUSION_NAME: the name of the maintenance exclusion.
START_DATE_TIME: the start date and time for the exclusion.
END_DATE_TIME: the end date and time for the exclusion.
SCOPE: the scope of upgrade to exclude, which can be one of the following values: no_upgrades, no_minor_upgrades, or no_minor_or_node_upgrades.

To view supported date and time formats, run gcloud topic datetimes.

Console

To configure a maintenance exclusion for an existing cluster:

Go to the Google Kubernetes Engine page in the Google Cloud console.

Go to Google Kubernetes Engine
In the cluster list, click the name of the cluster you want to modify.
Under Automation, next to the Maintenance exclusions field, click Edit maintenance exclusions.
Under Maintenance exclusions, click Add Maintenance Exclusion.
Select the Scope, a Start time, and an End time.
Click Save Changes.

Remove a maintenance exclusion

You can remove maintenance exclusions by using the Google Cloud console or the gcloud CLI.

gcloud

Remove an existing maintenance exclusion:

gcloud container clusters update CLUSTER_NAME \
    --remove-maintenance-exclusion EXCLUSION_NAME

Replace the following:

CLUSTER_NAME: the name of the existing cluster.
EXCLUSION_NAME: the name of the maintenance exclusion to remove.

Console

To remove a maintenance exclusion from an existing cluster:

Go to the Google Kubernetes Engine page in the Google Cloud console.

Go to Google Kubernetes Engine
In the cluster list, click the name of the cluster you want to modify.
Under Automation, next to the Maintenance exclusions field, click Edit maintenance exclusions.
Under Maintenance exclusions, click Delete item next to the End time field for the exclusion you want to remove.
Click Save Changes.

To see all maintenance exclusions on a cluster, you can view the cluster's maintenance policy.

Example maintenance exclusion

The following example prevents maintenance over the four days encompassing Black Friday through Cyber Monday, the highest-volume sales period of the year for many retail businesses. This example shows how to prevent a maintenance window from occurring from Black Friday 2021 (November 26, 2021) to Cyber Monday 2021 (November 29, 2021), from midnight Eastern (UTC-5) to 23:59:59 Pacific (UTC-8).

gcloud container clusters update sample-cluster \
    --add-maintenance-exclusion-name black-friday \
    --add-maintenance-exclusion-start 2021-11-26T00:00:00-05:00 \
    --add-maintenance-exclusion-end 2021-11-29T23:59:59-08:00 \
    --add-maintenance-exclusion-scope no_upgrades

View a cluster's maintenance policy

To view a cluster's maintenance policy, including whether it has a maintenance window and all of its maintenance exclusions, use the following command:

gcloud container clusters describe CLUSTER_NAME

Identify clusters without a configured maintenance window

GKE identifies clusters for which you haven't configured a maintenance window so that you can choose a recurring window in which GKE can perform cluster maintenance. We recommend that you configure a maintenance window to ensure that GKE performs automatic upgrades and other cluster maintenance that respects maintenance policies when it's most convenient for your cluster environment.

GKE delivers this guidance with an insight and recommendation through the Recommender service. To learn more about how to manage insights and recommendations from Recommender, see Optimize your usage of GKE with insights and recommendations.

To find clusters without a configured maintenance window, you can use one of the following ways:

Use the Google Cloud console.
Use the gcloud CLI or Recommender API, by specifying the CLUSTER_MAINTENANCE_WINDOW_AND_EXCLUSIONS recommender subtype.

For instructions, see how to view insights and recommendations.

To implement this recommendation, configure a maintenance window.

Troubleshooting

Restricting the scope of maintenance exclusions can only apply to release channels

When you restrict the scope of automatic upgrades in a maintenance exclusion, the cluster must be enrolled in a release channel, otherwise you might encounter the following errors:

ERROR: (gcloud.container.clusters.update) INVALID_ARGUMENT: Cannot update to
STATIC channel since following maintenancePolicy.maintenanceExclusions can only
apply to release channels. Please remove those maintenance exclusions.

ERROR: (gcloud.container.clusters.update) ResponseError: code=400,
message=MaintenancePolicy.maintenanceExclusions["no"] could not apply to cluster
in STATIC channel, only no_upgrades exclusions are allowed in STATIC channel.

Maintenance exclusions exceeds limit

You can only specify a maximum of 3 maintenance exclusions that exclude all upgrades (that is, a scope of "no upgrades"), otherwise you receive the following error:

ERROR: (gcloud.container.clusters.update) ResponseError: code=400,
message=Number of active maintenance exclusions exceeds limit (3).

You can only specify a maximum of 20 maintenance exclusions in total, otherwise you receive the following error:

ERROR: (gcloud.container.clusters.update) ResponseError: code=400,
message=Number of total maintenance exclusions exceeds limit (20).

What's next

Learn more about cluster and node upgrades.
Learn how to Enable node auto-upgrade.
Learn how to Receive cluster notifications.