Maintenance Window

This page explains how to configure maintenance windows for your Google Kubernetes Engine clusters.

Overview

A maintenance window is a four-hour timeframe that you choose in which automatic upgrades should occur. Creating a maintenance window instructs GKE to automatically trigger automated master upgrades, IP rotations, and node pool upgrades, during the chosen timeframe. For example, if you create a maintenance window starting at 4:00 PM, the window lasts until 8:00 PM.

Upgrades can occur on any day of the week, and at any time within the timeframe. Maintenance windows give you more control over when upgrades to the Kubernetes software on your cluster or nodes occur.

GKE automatically upgrades your cluster master and, if node auto-upgrades are enabled, your nodes with the latest Kubernetes version. If tasks run beyond the maintenance window, GKE attempts to stop the operation. A stopped operation starts again during the next maintenance window.

These automatic upgrades occur periodically without user intervention, though it may cause short downtimes of the master and/or individual nodes. However, in some scenarios, you might want to have more control over when these upgrades occur. For example:

  • Off-peak hours: You want to minimize the chance of downtime by scheduling automatic upgrades during off-peak hours when traffic is reduced.
  • On-call: You want to ensure that upgrades happen during working hours so that someone can monitor the upgrades and manage any unanticipated issues.
  • Multi-cluster upgrades: You want to roll out upgrades across multiple clusters in different regions one at a time at specified intervals.

GKE might also choose not to perform any upgrades during the window you specify. Planned or upcoming upgrades are typically announced on the release notes page.

GKE reserves the right to roll out unplanned, emergency upgrades outside of maintenance windows. Additionally, mandatory upgrades to upgrade from deprecated or outdated software might automatically occur outside of maintenance windows.

Caveats

When you make changes to your nodes that require the nodes be recreated, such as when you enable network policies, your nodes might not be recreated until the next maintenance window, causing a perceived delay. If you prefer not to wait, you can manually upgrade your cluster at any time.

Before you begin

To prepare for this task, perform the following steps:

  • Ensure that you have enabled the Google Kubernetes Engine API.
  • Enable Google Kubernetes Engine API
  • Ensure that you have installed the Cloud SDK.
  • Set your default project ID:
    gcloud config set project [PROJECT_ID]
  • If you are working with zonal clusters, set your default compute zone:
    gcloud config set compute/zone [COMPUTE_ZONE]
  • If you are working with regional clusters, set your default compute region:
    gcloud config set compute/region [COMPUTE_REGION]
  • Update gcloud to the latest version:
    gcloud components update

Configuring a maintenance window in your cluster

The following sections explain how to configure maintenance windows.

To create a maintenance window, you need to specify a time to initiate the automatic upgrades on the master and, if node auto-upgrades is enabled, your nodes.

Creating a cluster with a maintenance window

gcloud

To create a new cluster with a maintenance window, use the gcloud container clusters create command and include the --maintenance-window flag:

gcloud container clusters create [CLUSTER_NAME] --maintenance-window [HH:MM]

For example, the following command creates a cluster named my-cluster with a maintenance window for 2:00 AM:

gcloud container clusters create my-cluster --maintenance-window 2:00

Console

To create a new cluster with a maintenance window, perform the following steps:

  1. Visit the Google Kubernetes Engine menu in GCP Console.

    Visit the Google Kubernetes Engine menu

  2. Click Create cluster.

  3. Choose the Standard cluster template or choose an appropriate template for your workload. If you choose the Highly Available template, a regional cluster is created with a default maintenance window.
  4. Configure your cluster as desired.
  5. To customize the maintenance window, or if you used a cluster-creation template that does not include a maintenance window by default, click Advanced options. Then, from the Maintenance window drop-down menu, select the desired time.
  6. Click Create.

Configuring a maintenance window for an existing cluster

gcloud

To create or modify a maintenance window for an existing cluster, use the gcloud container clusters update command and include the --maintenance-window flag:

gcloud container clusters update [CLUSTER_NAME] --maintenance-window [HH:MM]

For example, the following command changes the maintenance window in my-cluster to 4:00 PM:

gcloud container clusters update my-cluster --maintenance-window 16:00

Console

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

  1. Visit the Google Kubernetes Engine menu in GCP Console.

    Visit the Google Kubernetes Engine menu

  2. Click the cluster's Edit button, which looks like a pencil.

  3. From the Maintenance window drop-down menu, select the desired time.
  4. Click Save.

Removing a maintenance window

gcloud

To remove a maintenance window, set the value of the --maintenance-window flag to None:

gcloud container clusters update [CLUSTER_NAME] --maintenance-window None

Console

To remove a maintenance window:

  1. Visit the Google Kubernetes Engine menu in GCP Console.

    Visit the Google Kubernetes Engine menu

  2. Click the cluster's Edit button, which looks like a pencil.

  3. From the Maintenance window drop-down menu, select Any time.
  4. Click Save.

Cancelling an upgrade

In rare cases where upgrades take longer than four hours to complete, GKE attempts to stop ongoing upgrades and resume them during the next maintenance window. If an automatic upgrade is cancelled, and you have node auto-upgrades enabled, your nodes might be in a mixed-version state but your cluster should operate normally.

If you want to manually cancel, rollback, or manually upgrade your cluster, refer to Upgrading a Container Cluster.

What's next

Was this page helpful? Let us know how we did:

Send feedback about...

Kubernetes Engine