Scheduling Event Broker Service Upgrades Using the REST API for Solace Cloud

Maintenance schedules allow you to schedule your event broker service upgrades at times that meet the needs of your organization. Event broker services added to maintenance windows on a maintenance schedule will be upgraded during that maintenance window without requiring human intervention. You can use the REST API for Solace Cloud to create and populate maintenance schedules with maintenance windows and then schedule your event broker service upgrades to those maintenance windows.

Scheduling event broker service upgrades using maintenance windows with the REST API requires the following steps:

  1. Creating a Maintenance Schedule Using the REST API

  2. Creating a Maintenance Window in a Maintenance Schedule Using the REST API

  3. Scheduling Event Broker Service Upgrades in a Maintenance Window Using the REST API

You can view information about your maintenance schedule, maintenance windows, and event broker service upgrades schedule in them using the REST API. For more information, see Scheduling Event Broker Service Upgrades Using the REST API for Solace Cloud.

You may decide at a later date that you no longer need a maintenance schedule, or you want to remove a specific maintenance window, or remove a scheduled event broker service upgrade from a maintenance window. You can delete maintenance windows you no longer need after removing any scheduled event broker service upgrades from the maintenance window. For more information see Scheduling Event Broker Service Upgrades Using the REST API for Solace Cloud.

For more information about event broker service upgrades in general, see Upgrading Event Broker Services in Solace Cloud.

Before scheduling your event broker service upgrades using the REST API, you should review the Considerations for Scheduling Event Broker Service Upgrades Using the REST API

Considerations for Scheduling Event Broker Service Upgrades Using the REST API

Here are some considerations when managing maintenance schedules for self-serve event broker service upgrades:

Creating a Maintenance Schedule Using the REST API

If your organization does not have a maintenance schedule, you can create one using the REST API. You can have only one maintenance schedule per organization. After creating a maintenance schedule, you can create maintenance windows in the schedule.

To create a maintenance schedule for event broker service upgrades, perform these step:

  • Create the maintenance schedule by using the Create a maintenance schedule REST API:

  • Define the Body Parameter fields with the information as described in the following table:

    Body Parameter Definition
    maintenanceType

    The maintenance type for the schedule. This can be either:

    • DATA_PLANE—Designates the schedule as responsible for upgrading data operations resources, such as an event broker service.

    • CONTROL_PLANE—Designates the schedule as responsible for is for upgrading environment operations resources, such as the Mission Control Agent.
    environmentId

    The identifier of the environment the maintenance window belongs to. You can get the ID for your organization's environments using the Get list of environments API.

    A successful POST returns code 204 Created. The response returns a JSON body containing an id as part of the payload. You can use the id with the Get a maintenance schedule REST API to retrieve the maintenance schedule at a later date.

Creating a Maintenance Window in a Maintenance Schedule Using the REST API

After creating a maintenance schedule, you can add maintenance windows to the schedule. When you create a maintenance window, you define dates and times the window is available, and the frequency of the window's occurrence. After creating the maintenance window, you can add upgrades to the window.

To create a maintenance window in a maintenance schedule, perform this step:

  • Create the maintenance window using the Create a maintenance window REST API.

    Define the Body Parameter fields with the information as described in the following table:

    Variable Definition
    maintenanceScheduleId The identifier for the maintenance schedule you want to add maintenance windows to. To get the maintenance schedule ID, see Getting the Details of All Maintenance Schedules for an Environment Using the REST API.
    recurrenceFrequency

    The frequency of the maintenance type for the schedule. The valid values are:

    • WEEKLY—The maintenance window repeats at a weekly frequency, as defined by the recurrenceDayWeekly variable, on the day defined by the recurrenceDayOfWeek variable.

    • MONTHLY—The maintenance window repeats at once per month, on a specific day every as defined by the recurrenceDayOfWeek variable, during a specific week of the month, as defined by the recurrenceDayOfWeekMonthly variable.

    Your selection for this variable determines the recurrenceInterval you must select. See recurrenceInterval in this table below.
    recurrenceDayOfWeek

    The day of the week that the recurrence occurs on. The valid values are:

    MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY

    recurrenceInterval

    Replace the recurrenceInterval with the variable that meets the recurrenceFrequency you selected.

    		 recurrenceDayWeekly

    Only required if recurrenceFrequency is set to WEEKLY.

    The frequency that the window repeats itself. If you choose weekly for the recurrenceFrequency, the maintenance window repeats:

    • EVERY—Every week on the selected day.

    • EVERY_OTHER—Every second week, on the selected day.

    • EVERY_THREE—Every third week on the selected day.

    • EVERY_FOUR—Every four weeks on the selected day.
    recurrenceDayOfWeekMonthly

    Only required if recurrenceFrequency is set to MONTHLY.

    The day of the month the window repeats on. If you choose monthly for the recurrenceFrequency, the maintenance window repeats:

    • FIRST—First occurrence of the selected day within a month, for example, the first Monday of December, and January.

    • SECOND—The second occurrence of a selected day within a month, for example, the second Tuesday of December, and January.

    • THIRD—The third occurrence of a selected day within a month, for example, the third Wednesday of December, and January.

    • LAST—The last occurrence of a day within a month, for example, the last Thursday of December, and January.
    startTime The date and time the maintenance window starts its recurrence at, in ISO 8601 format, for example: 2025-05-07T01:30:00.000Z.
    durationInHours The duration of the maintenance window in hours. Valid values are any whole number between 1 and 12.

    A successful POST returns code 201 Created. The response returns a JSON body containing information about the maintenance window in the response body.

Scheduling Event Broker Service Upgrades in a Maintenance Window Using the REST API

After creating a maintenance window, or if maintenance windows already exist, you can schedule event broker service upgrades to the maintenance window using the REST API.

To schedule an event broker service upgrade in a maintenance window, you must know:

To perform a scheduled self-serve upgrade, perform the these steps:

  1. Determine the unique identifier for the event broker service you want to upgrade using one of the following methods:

    • In Cluster Manager, select the event broker service and get its unique identifier from the last segment in the URL. For example, 9c5vurtex4b is the identifier from https://console.solace.cloud/services/9c5vurtex4b.

    • Use the Get list of services REST endpoint to find the unique identifier (id) of the event broker service.

    For example, on the Get list of services page, paste your API token into the Bearer field and then click Try It!. To find your event broker service named MyFirstService, you can find that string in the name object, and its corresponding id object is the unique identifier for the service.

  2. Upgrade the event broker service using the Create an event broker service upgrade REST API.

    Define the Path Parameter fields with the information as described in the following table:

    VariableDefinition
    serviceId

    The unique identifier of the event broker service the you want to schedule an upgrade for. You can find the ID either:

    Define the Body Parameter fields with the information as described in the following table:

    VariableDefinition
    targetVersion

    One of the available versions for upgrading the event broker service to. You can get a list of recommended and available upgrade versions using the REST API, as explained in Determining Available Upgrade Versions for an Event Broker Service Using the REST API.

    maintenanceWindowIdThe identifier for the maintenance window you want to schedule the event broker service upgrade in. To get the maintenance schedule ID, see Get the Details of All Maintenance Windows in a Maintenance Schedule.
    maintenanceOrdinal

    The position of an available time slot in a series of a maintenance window. For example, the third slot for a maintenance window sequence.

    The possible maintenanceOrdinal values are: 0, 1, or 2.

    You can find the ordinal number by looking at the upcomingMaintenanceTimes value in the response body of a GET all maintenance windows, or a GET for a specific maintenance window. For more information, see:

    A successful POST returns code 201 Created. The response returns a JSON body containing information about the scheduled upgrade in the response body.

Once the self-serve upgrades for your event broker service begins, you can view the progress of the upgrade using the REST API. For more information, see Viewing Self-Serve Event Broker Service Upgrade Progress Using the REST API.