Manage AlloyDB for PostgreSQL cluster maintenance windows

This page shows you how to perform the following actions related to AlloyDB for PostgreSQL cluster maintenance:

  • Set, view, and clear a maintenance window.
  • View upcoming maintenance events scheduled.
  • Configure and remove a deny maintenance period.

All of the listed actions apply to both primary and secondary clusters.

For an overview of how maintenance works with AlloyDB clusters, see Maintenance overview.

Set a maintenance window on a cluster

Console

  1. Go to the Clusters page.

    Go to Clusters

  2. Click a cluster in the Resource Name column.

  3. In the Overview page, in Maintenance, click Edit.

  4. In Maintenance window, select the day of the week for this maintenance window.

    The default option is Any window. When you create a cluster, the cluster is assigned this default maintenance window.

  5. Select the hour of the day for this maintenance window.

  6. Click Update to save the changes.

gcloud

To use the gcloud CLI, you can install and initialize the Google Cloud CLI, or you can use Cloud Shell.

To set a maintenance window on a cluster, run the gcloud clusters update command with the --maintenance-window-day and --maintenance-window-hour flags:

gcloud alloydb clusters update CLUSTER_ID \
  --region LOCATION_ID \
  --maintenance-window-day DAY_OF_WEEK \
  --maintenance-window-hour HOUR_OF_DAY

Replace the following:

  • CLUSTER_ID: the cluster to set the maintenance window on.

  • LOCATION_ID: the Google Cloud region that this cluster is located in—for example, us-central1.

  • DAY_OF_WEEK: the day of the week, in the Coordinated Universal Time (UTC) time zone, for this maintenance window. Valid values are MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, and SUNDAY.

    The default value is Any window. When you create a cluster, the cluster is assigned this default maintenance window.

  • HOUR_OF_DAY: an integer between 0 and 23 representing the hour of the day, in the UTC time zone, for this maintenance window.

If you make changes to your maintenance window setting while the cluster is already undergoing maintenance or is scheduled for maintenance, then the changes don't take effect until after the current or scheduled maintenance is complete.

Clear a maintenance window

Console

  1. Go to the Clusters page.

    Go to Clusters

  2. Click a cluster in the Resource Name column.

  3. In the Overview page, in Maintenance, click Edit.

  4. In Maintenance window, select Any window.

  5. Click Update to save the changes.

gcloud

To use the gcloud CLI, you can install and initialize the Google Cloud CLI, or you can use Cloud Shell.

To clear the maintenance window from a cluster, run the gcloud clusters update command with the --maintenance-window-any flag:

gcloud alloydb clusters update CLUSTER_ID \
  --region LOCATION_ID \
  --maintenance-window-any

Replace the following:

  • CLUSTER_ID: the cluster to set the maintenance window on.

  • LOCATION_ID: the Google Cloud region that this cluster is located in—for example, us-central1.

View the maintenance window of a cluster

Console

  1. Go to the Clusters page.

    Go to Clusters

  2. Click a cluster in the Resource Name column.

  3. In the Overview page, in Maintenance, view the maintenance window details for your cluster.

gcloud

To use the gcloud CLI, you can install and initialize the Google Cloud CLI, or you can use Cloud Shell.

To review the current maintenance window on a cluster, run the gcloud alloydb clusters describe command:

gcloud alloydb clusters describe CLUSTER_ID \
  --region LOCATION_ID

Replace the following:

  • CLUSTER_ID: the cluster to set the maintenance window on.

  • LOCATION_ID: the Google Cloud region that this cluster is located in—for example, us-central1.

If the cluster has a maintenance window set, then the output of the command includes lines that resemble the following:

maintenanceUpdatePolicy:
  maintenanceWindows:
  - day: TUESDAY
    startTime:
      hours: 23

If the output doesn't include a maintenanceUpdatePolicy section, then the cluster has no maintenance window set.

View upcoming maintenance on a cluster

Console

  1. Go to the Clusters page.

    Go to Clusters

  2. Locate your cluster, and view the Maintenance column for information about the upcoming maintenance window.

gcloud

To use the gcloud CLI, you can install and initialize the Google Cloud CLI, or you can use Cloud Shell.

To see upcoming maintenance planned for a cluster that has a maintenance window set, run the gcloud clusters describe command:

gcloud alloydb clusters describe CLUSTER_ID \
  --region LOCATION_ID

Replace the following:

  • CLUSTER_ID: the cluster to set the maintenance window on.

  • LOCATION_ID: the Google Cloud region that this cluster is located in—for example, us-central1.

If the cluster has a planned maintenance event in its future, then the output of the command includes lines that resemble the following:

maintenanceSchedule:
  startTime: 2024-07-03T09:46:40Z

The UTC-formatted timestamp specifies the moment at which AlloyDB plans to start updating the system software of all of the nodes in this cluster.

Opt in to maintenance notifications

Maintenance notifications are disabled by default. When you choose to opt in to receive email notifications about upcoming AlloyDB maintenance events, keep the following in mind:

  • You receive an automated notification about the event as soon as it is scheduled. Maintenance events are scheduled at least one week ahead of time.
  • Maintenance notifications are enabled at the Google Cloud project level. You can't choose to be notified about a subset of clusters in a project.
  • You can only enable notifications for yourself. Each user must opt in separately to receive maintenance notifications.

For more information, see Maintenance overview.

To receive an automated email notification whenever a maintenance event is scheduled or canceled for a cluster that has a maintenance window set, follow these steps using the Google Cloud console:

  1. Go to the Clusters page.

    Go to Clusters

  2. Click a cluster in the Resource Name column.

  3. In the Overview page, in Maintenance, click Edit in the Notifications: row.

  4. Click Communication.

  5. In the row for AlloyDB, Maintenance window, select the toggle in the Email column.

Configure a deny maintenance period

To prevent maintenance operations during a specific time period, you can configure a deny maintenance period. You can set deny maintenance on a cluster running the latest version of AlloyDB. A deny maintenance period can span from one to 30 days.

Set deny maintenance periods

To configure a deny maintenance period, you set its start date, end date, and the time of day the interval begins and ends.

The start and end dates must be in the following format:

  • YYYY-MM-DD: indicates a specific date

The start date, end date, and time are in the UTC time zone.

gcloud

To use the gcloud CLI, you can install and initialize the Google Cloud CLI, or you can use Cloud Shell.

To add a deny maintenance period to an AlloyDB cluster, run the gcloud alloydb clusters update command with the deny-maintenance-period-start-date, deny-maintenance-period-end-date, and deny-maintenance-period-time flags:

gcloud alloydb clusters update CLUSTER_ID \
   --region LOCATION_ID \
   --deny-maintenance-period-start-date START_DATE \
   --deny-maintenance-period-end-date END_DATE \
   --deny-maintenance-period-time TIME

Replace the following:

  • CLUSTER_ID: the cluster to configure for the maintenance-free period.
  • LOCATION_ID: the Google Cloud region that this cluster is located in—for example, us-central1.
  • START_DATE: the maintenance-free period start date in YYYY-MM-DD UTC format.
  • END_DATE: the end of the maintenance-free period in YYYY-MM-DD UTC format.
  • TIME: the time of the maintenance-free period in HH:MM UTC format. The hours are represented in the 24-hour format where values range from 00:00 to 23:59—for example, 16:45.

REST v1

This example adds a deny maintenance period to an existing cluster. For a complete list of parameters for this call, see Method: projects.locations.clusters.instances.patch.

Before you use any of the request data, make the following replacements:

  • CLUSTER_ID: the cluster to configure for the maintenance-free period.
  • PROJECT_ID: the ID of the project where the cluster is placed.
  • LOCATION_ID: the Google Cloud region that this cluster is located in—for example, us-central1.
  • START_YEAR: the year when the maintenance-free period starts in the YYYY format.
  • START_MONTH: the month when the maintenance-free period starts in the MM format. A leading zero for single-digit months is optional—for example, both 2 and 02 are valid for February.
  • START_DAY: the day when the maintenance-free period starts in the DD format. A leading zero for single-digit days is optional—for example, both 1 and 01 are valid for the first day of the month.
  • END_YEAR: the year when the maintenance-free period ends in the YYYY format.
  • END_MONTH: the month when the maintenance-free period ends in the MM format.
  • END_DAY: the day when the maintenance-free period ends in the DD format.
  • HOUR(S): the maintenance-free period hour in 24-hour format—for example, 16. A leading zero for single-digit hours is optional—for example, both 2 and 02 are valid.
  • MINUTE(S): the minute of the maintenance-free period that accepts values from 0 to 59—for example, 45. A leading zero for single-digit minutes is optional— 7 and 07 are valid.

To add a deny maintenance period, use the following PATCH request:

PATCH https://alloydb.googleapis.com/v1/{cluster.name=projects/PROJECT_ID/locations/LOCATION_ID/clusters/CLUSTER_ID?update_mask=maintenance_update_policy.deny_maintenance_periods}

The maintenance_update_policy.deny_maintenance_periods query parameter tells the API to update the denyMaintenancePeriods field within the maintenanceUpdatePolicy block.

The request JSON body looks as follows:

"maintenanceUpdatePolicy": {
 "denyMaintenancePeriods": [
   {
     "startDate": {
       "year": START_YEAR,
       "month": START_MONTH,
       "day": START_DAY
     },
     "endDate": {
       "year": END_YEAR,
       "month": END_MONTH,
       "day": END_DAY
     },
     "time": {
       "hours": TIME
       "minutes": TIME
     }
   }
 ]
},

Deny upcoming maintenance

Deny maintenance periods take precedence over scheduled maintenance. If a timing conflict occurs, the deny maintenance period overrides the scheduled maintenance window.

Setting a deny period that conflicts with a scheduled maintenance event doesn't immediately cancel the maintenance and clear the schedule. AlloyDB shows the existing scheduled maintenance as upcoming, but it cancels the scheduled maintenance window when the scheduled time starts.

To help apply critical updates, the system does not typically allow setting a deny period to skip more than one maintenance event and may in rare cases apply emergency maintenance outside of configured maintenance preferences.

Remove a deny maintenance period from a cluster

You can remove a deny maintenance period at any time.

gcloud

To use the gcloud CLI, you can install and initialize the Google Cloud CLI, or you can use Cloud Shell.

To remove a deny maintenance period from an AlloyDB cluster, run the gcloud alloydb clusters update command with the remove-deny-maintenance-period flag:

gcloud alloydb clusters update CLUSTER_ID --region LOCATION_ID  --remove-deny-maintenance-period

Replace the following:

  • CLUSTER_ID: the cluster to remove the deny maintenance period from.
  • LOCATION_ID: the Google Cloud region that this cluster is located in—for example, us-central1.

REST v1

This example removes a deny maintenance period from an AlloyDB cluster. For a complete list of parameters for this call, see Method: projects.locations.clusters.patch.

Before you use any of the request data, make the following replacements:

  • CLUSTER_ID: the ID of the cluster that you add a deny maintenance period to.
  • PROJECT_ID: the ID of the project where the cluster is placed.
  • LOCATION_ID: the Google Cloud region that this cluster is located in—for example, us-central1.

To remove a deny maintenance period, use the following PATCH request:

PATCH https://alloydb.googleapis.com/v1/{cluster.name=projects/PROJECT_ID/locations/LOCATION_ID/clusters/CLUSTER_ID?update_mask=maintenance_update_policy.deny_maintenance_periods}

The maintenance_update_policy.deny_maintenance_periods query parameter tells the API to update the denyMaintenancePeriods field within the maintenanceUpdatePolicy block.

The request JSON body looks as follows:

{}