Customer-defined maintenance windows

Gen 2

Set the days and start time for maintenance on your deployment. Cloud Databases controls the duration of the maintenance window, and all maintenance work is completed or stopped within 4 hours of your scheduled start time.

Availability

Customer-defined maintenance windows are available for:

Databases for PostgreSQL in eu-de.
Databases for MongoDB Enterprise Edition in eu-de.

Support for more databases and regions will be added over time.

Configure a daily maintenance window unless your organization requires maintenance to run on specific days only. A daily window allows pending or incomplete maintenance, including security and reliability updates, to resume the next day rather than waiting until the next week.

What maintenance includes

Maintenance includes any change that directly affects your deployment, such as:

Database software and image updates.
Updates to the worker nodes that your deployment runs on.
Security, reliability, and supportability updates.

These changes run during your maintenance window, even when they don't cause a visible service impact. Changes that you request yourself, such as scaling your deployment, run when you request them.

During maintenance, your deployment might fail over to a new primary. Make sure that your applications can reconnect automatically. For more information, see High availability.

Default maintenance window

You don't have to set a maintenance window. If you don't, Cloud Databases uses the regional default: a start time between 23:00 UTC and 10:00 UTC, Monday to Friday. The exact start time isn't shown.

To go back to the regional default after you set your own window, set system_assigned to true.

Maintenance window requirements

You can set only a start time. You can't set a duration or end time. Cloud Databases controls the length of the maintenance window.
Specify the start time in UTC by using the hh:mmZ format.
Select at least one maintenance day per week. A daily maintenance window is recommended. For more information, see If maintenance doesn't finish in time.
Set your start time at least 60 minutes before the maintenance window that you want it to apply to.
You can update your maintenance window at any time. Changes take effect for the next eligible maintenance window. If maintenance has already completed for the day, the updated schedule takes effect the next time maintenance is eligible to run.
If you update the maintenance window while maintenance is in progress, the current maintenance operation isn't restarted. The updated schedule applies to the next eligible maintenance window.
Maintenance notifications are based on the schedule in effect when the notification is generated. Changes made shortly before a maintenance window might not apply to notifications that were already generated or sent.

How maintenance windows work

The maintenance window lasts 4 hours from the scheduled start time, and all maintenance work is completed or stopped within that period.

For example, if your maintenance start time is 02:00 UTC:

Example maintenance window with a start time of 02:00 UTC
Time (UTC)	What happens
02:00 - 6:00	Maintenance begins, and maintenance activities are initiated. Your deployment might switch over to a new primary, and your applications might need to reconnect.
By 06:00	All maintenance work is completed or stopped.

When you choose a start time, plan for the full 4-hour window, not just the start time. Choose a time when your application has the least traffic and your operations team is available.

Your backups never overlap with your maintenance window. Cloud Databases adjusts the backup schedule automatically.

Set a maintenance window

You can set your maintenance days and start time by using the console, CLI, API, or Terraform.

Set a maintenance window in the console

You can configure a maintenance window when you create a deployment or after provisioning.

In the IBM Cloud console, create a deployment or open an existing deployment.
Go to Maintenance window and click Edit.
Select the days of the week when maintenance can start. A daily maintenance schedule is recommended.
Select a maintenance start time. You can display the time in UTC or your local time zone.
Review the maintenance schedule and click Save.

To return to the regional default maintenance window, click Reset to default.

Set a maintenance window by using the CLI

You can set a specific maintenance window by using the following command:

ibmcloud resource service-instance-create \
  <INSTANCE_NAME> \
  <SERVICE_NAME> \
  <SERVICE_PLAN_NAME> \
  <LOCATION> \
  -g <RESOURCE_GROUP> \
  -p '{
    "dataservices": {
      "maintenance": {
        "window": {
          "start_time": "05:00Z",
          "days": "Wednesday,Thursday"
        }
      }
    }
  }'

You can set system_assigned maintenance window by using the following commands:

ibmcloud resource service-instance-create \
  <INSTANCE_NAME> \
  <SERVICE_NAME> \
  <SERVICE_PLAN_NAME> \
  <LOCATION> \
  -g <RESOURCE_GROUP> \
  -p '{
    "dataservices": {
      "maintenance": {
        "window": {
          "system_assigned": true
        }
      }
    }
  }'

Set a maintenance window by using the API

You can set a specific maintenance window by using the following request:

curl -X POST \
  "https://resource-controller.cloud.ibm.com/v2/resource_instances" \
  -H "Authorization: Bearer <IAM_ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "<DATABASE_INSTANCE_NAME>",
    "target": "<REGION>",
    "resource_group": "<RESOURCE_GROUP_ID>",
    "resource_plan_id": "<DATABASE_SERVICE_PLAN_ID>",
    "parameters": {
      "dataservices": {
        "maintenance": {
          "window": {
            "start_time": "05:00Z",
            "days": "Wednesday,Thursday"
          }
        }
      }
    }
  }'

You can set system_assigned maintenance window by using the following request:

curl -X POST \
  "https://resource-controller.cloud.ibm.com/v2/resource_instances" \
  -H "Authorization: Bearer <IAM_ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "<DATABASE_INSTANCE_NAME>",
    "target": "<REGION>",
    "resource_group": "<RESOURCE_GROUP_ID>",
    "resource_plan_id": "<DATABASE_SERVICE_PLAN_ID>",
    "parameters": {
      "dataservices": {
        "maintenance": {
          "window": {
            "system_assigned": true
          }
        }
      }
    }
  }'

Set a maintenance window by using Terraform

You can set a specific maintenance window by using the following Terraform request:

maintenance_days = ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"]

data "ibm_resource_group" "rg" {
  name = var.resource_group_name
}

resource "ibm_database" "cmw_test" {
  name              = "<DATABASE_INSTANCE_NAME>"
  resource_group_id = data.ibm_resource_group.rg.id
  service = "<DATABASE_SERVICE_NAME>"
  plan    = "<DATABASE_SERVICE_PLAN_ID>"
  location          = "<GEN2-REGION>"
  service_endpoints = "private"
  maintenance {
    window {
      start_time = "05:00Z"
      days       = var.maintenance_days
    }
  }
}

You can set system_assigned maintenance window by using the following Terraform request:

data "ibm_resource_group" "rg" {
  name = var.resource_group_name
}

resource "ibm_database" "cmw_test" {
  name              = "<DATABASE_INSTANCE_NAME>"
  resource_group_id = data.ibm_resource_group.rg.id
  service = "<DATABASE_SERVICE_NAME>"
  plan    = "<DATABASE_SERVICE_PLAN_ID>"
  location          = "<GEN2-REGION>"
  service_endpoints = "private"
  maintenance {
    window {
      system_assigned = true
    }
  }
}

Tracking maintenance

When maintenance is pending for your deployment, you receive an IBM Cloud Activity Tracker event at least 2 hours before your maintenance activity starts.

IBM Cloud Activity Tracker events are also triggeered as a result of any service instance update due to a successful maintenance window. Check out the full list of Database Activity Tracker events.

Incomplete maintenance

Maintenance never runs past the end of your maintenance window. If maintenance is still running 4 hours after your start time, Cloud Databases stops it. The remaining work runs in your next maintenance window. Your deployment stays available in the meantime.

Set a daily maintenance window. If you select only one day each week, maintenance that wasn't completed, including security fixes, waits up to a week for your next window. With a daily window, maintenance resumes the next day, and your deployment stays up to date and secure.

Emergency maintenance

In exceptional circumstances, emergency maintenance might occur outside the scheduled maintenance window without advance notice. In these cases, scheduled maintenance events aren't created.