Maintenance Window

This page explains how to configure maintenance windows for your 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 Kubernetes Engine 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.

Kubernetes Engine 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, Kubernetes Engine 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.

Kubernetes Engine 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.

Kubernetes Engine 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.

Before you begin

To prepare for this task, perform the following steps:

  • Ensure that you have installed the Cloud SDK.
  • Set your default project ID:
    gcloud config set project [PROJECT_ID]
  • Set your default compute zone:
    gcloud config set compute/zone [COMPUTE_ZONE]
  • Update all gcloud commands 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

Console

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

  1. Visit the Kubernetes Engine menu in GCP Console.

    Visit the Kubernetes Engine menu

  2. Click Create cluster.

  3. Configure your cluster as desired. Then, from the Maintenance window drop-down menu, select the desired time.
  4. Click Create.

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

Configuring a maintenance window for an existing cluster

Console

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

  1. Visit the Kubernetes Engine menu in GCP Console.

    Visit the Kubernetes Engine menu

  2. Click your cluster, then click Edit.

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

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

Removing a maintenance window

Console

To remove a maintenance window:

  1. Visit the Kubernetes Engine menu in GCP Console.

    Visit the Kubernetes Engine menu

  2. Click your cluster, then click Edit.

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

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

Cancelling an upgrade

In rare cases where upgrades take longer than four hours to complete, Kubernetes Engine 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