Managing Maintenance Activities With 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. You can schedule an event broker service to a maintenance window on a maintenance schedule so the service is upgraded without requiring human intervention. You can manage maintenance schedules, their maintenance windows, and the maintenance activities in the windows using the v2 REST APIs for Solace Cloud.

Managing maintenance schedules, windows, and activities includes getting details about them, and deleting them using the v2 REST APIs.

You can also manage maintenance schedules, windows, and activities from the Cloud Console. For more information, see Creating and Managing Maintenance Windows for Self-Serve Upgrades in the Cloud Console.

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

For information about creating and populating maintenance schedules with maintenance windows and maintenance activities, see Scheduling Event Broker Service Upgrades Using the REST API for Solace Cloud.

For more information about managing maintenance schedules, windows, and activities, see the following sections:

Before creating and managing maintenance schedules for event broker service upgrades using the REST API, you should review the Considerations for Managing Maintenance Schedules Using the REST API.

Considerations for Managing Maintenance Schedules Using the REST API

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

Getting Information About Maintenance Schedules Using the REST API

You can get information about maintenance schedules, including information about an entire schedule, the maintenance windows for a maintenance schedule, and event broker service upgrades scheduled in maintenance windows using the REST API. For example, you may want to get information about the maintenance windows in your organization's maintenance schedule so you can schedule an event broker service to best minimize any potential service interruptions. You can get a variety of information about your maintenance schedules, maintenance windows, and scheduled event broker service upgrades using the REST API, including the details of:

Getting the Details of All Maintenance Schedules for an Environment Using the REST API

You can query maintenance schedules for event broker service upgrades in your environment using the REST API by performing this step:

  • Get a list of maintenance schedules by using the Get a list of maintenance schedules REST API.

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

    Variable Definition
    environmentId The identifier of the environment to filter the response by. You can get the ID for your organizations environments using the Get list of environments API.

    A successful GET returns a code 200 OK. The response returns a JSON body containing data describing all of the current maintenance schedules for the queried environment.

Getting the Details of a Specific Maintenance Schedule Using the REST API

You can query the details of a specific maintenance schedule for event broker service upgrades in your environment using the REST API by performing this step:

  • Get the details of a specific maintenance schedule by using the Get a maintenance schedule REST API.

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

    Variable Definition
    maintenanceScheduleId The identifier of the maintenance schedule you want to get information about. You can get a list of maintenance schedules for an environment using the REST API. For more information see Getting the Details of All Maintenance Schedules for an Environment Using the REST API.

    • A successful GET returns a code 200 OK. The response returns a JSON body containing data describing the queried maintenance schedule.

Get the Details of All Maintenance Windows in a Maintenance Schedule

You can query the details of all maintenance windows for a maintenance schedule in an environment using the REST API by performing this step:

  • Get a list of all maintenance windows in a maintenance schedule by using the Get maintenance windows REST API.

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

    Variable Definition
    environmentId The identifier of the environment to filter the response by. You can get the ID for your organizations environments using the Get list of environments API.
    maintenanceScheduleId The identifier of the maintenance schedule to filter the response by. You can get the ID of your maintenance schedules using the Get All Maintenance Schedules API.

    • A successful GET returns a code 200 OK. The response returns a JSON body containing data describing the available maintenance widows in the queried maintenance schedule and environment.

Get the Details of a Specific Maintenance Window in a Maintenance Schedule

You can query the details of a specific maintenance window for a maintenance schedule in an environment using the REST API by performing this step:

  • Get the details of a specific maintenance window in a maintenance schedule by using the Get a maintenance window REST API.

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

    Variable Definition
    maintenanceWindowId The identifier of the maintenance window you want to get information about. You can get a list of maintenance windows for a maintenance schedule using the REST API. For more information see Get the Details of All Maintenance Windows in a Maintenance Schedule.

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

    Variable Definition
    environmentId The identifier of the environment to filter the response by. You can get the ID for your organizations environments using the Get list of environments API.
    maintenanceScheduleId The identifier of the maintenance schedule to filter the response by. You can get the ID of your maintenance schedules using the Get All Maintenance Schedules API.

    A successful GET returns a code 200 OK. The response returns a JSON body containing data describing the queried maintenance window.

Get the Details of All Scheduled Upgrades in a Maintenance Window

You can query the details all scheduled event broker service upgrades in a maintenance window using the REST API by performing this step:

  • Get a list of all upgrades scheduled in a maintenance window use the Get a list of maintenance activities REST API.

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

    Variable Definition
    maintenanceWindowId The identifier of the maintenance window you want to get information about. You can get a list of maintenance windows for a maintenance schedule using the REST API. For more information see Get the Details of All Maintenance Windows in a Maintenance Schedule.
    environmentId The identifier of the environment to filter the response by. You can get the ID for your organizations environments using the Get list of environments API.
    maintenanceScheduleId The identifier of the maintenance schedule to filter the response by. You can get the ID of your maintenance schedules using the Get All Maintenance Schedules API.
    operationStatus

    The status of the upgrade process. The possible responses are:

    PENDING, INITIATED, IN_PROGRESS, COMPLETED, FAILED, CANCELED, SKIPPED, REGISTERED, PAUSED
    resourceId The identifier of the resource to filter the response by.
    resourceType The resource type to filter by.
    scheduledStartTimeAfter Filter the returned query results by maintenance activities with start times scheduled after the entered timestamp (epoch milliseconds).
    scheduledStartTimeBefore Filter the returned query results by maintenance activities with start times scheduled before the entered timestamp (epoch milliseconds).

    • A successful GET returns a code 200 OK. The response returns a JSON body containing data describing the scheduled upgrades in the queried maintenance window.

Getting the Details of a Specific Scheduled Upgrade in a Maintenance Window

You can query the details of a specific scheduled event broker service upgrade in a maintenance window using the REST API by performing this step:

  • Get the details of a specific scheduled upgrade in a maintenance window using the Get a specific maintenance activity REST API.

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

    Variable Definition
    maintenanceActivityId The unique identifier of the maintenance activity. You can get a list of maintenance acitivty ID's using the Get the Details of All Scheduled Upgrades in a Maintenance Window REST API.

    A successful GET returns a code 200 OK. The response returns a JSON body containing data describing the specific queried upgrade in the maintenance window.

Get the Details of an Event Broker Service Upgrade

You can query the details of a specific event broker service upgrade, past or present, using the REST API by performing this step:

  • Get the details of a specific event broker service upgrade by using the Get an event broker service upgrade REST API.

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

    Variable Definition
    serviceId

    The unique identifier of the event broker service the you want to schedule an upgrade for. You can find the ID either:
    maintenanceActivityId The unique identifier of the maintenance activity. You can get a list of maintenance acitivty ID's using the Get the Details of All Scheduled Upgrades in a Maintenance Window REST API.

    A successful GET returns a code 200 OK. The response returns a JSON body containing data describing the queried event broker service upgrade.

Get the Details of All Event Broker Service Upgrades

You can query the details of all upgrades, past and present, for a specific event broker service using the REST API by performing this step:

  • Get the list of all upgrades for an event broker service using the Get a list of event broker service upgrades REST API.

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

    Variable Definition
    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 Query Parameter fields with the information as described in the following table:

    Variable Definition
    environmentId The identifier of the environment to filter the response by. You can get the ID for your organizations environments using the Get list of environments API.
    maintenanceWindowId The identifier for the maintenance window the maintenance activity belongs to.
    operationStatus

    The status of the upgrade process. The possible responses are:

    PENDING, INITIATED, IN_PROGRESS, COMPLETED, FAILED, CANCELED, SKIPPED, REGISTERED, PAUSED
    preMaintenanceValidationStatus The current status of the pre-maintenance operation (for example, SCHEDULED, IN_PROGRESS, COMPLETED, FAILED).
    postMaintenanceValidationResults The post-maintenance validation results associated with the activity.
    maintenanceActivityStatus

    The combined status of preMaintenanceValidationStatus, operationStatus and postMaintenanceValidationStatus, (for example SCHEDULED, IN_PROGRESS, COMPLETED, FAILED, CANCELED, SKIPPED, PAUSED, WARNING).
    scheduledStartTimeAfter Filter the returned query results by maintenance activities with start times scheduled after the entered timestamp (epoch milliseconds).
    scheduledStartTimeBefore Filter the returned query results by maintenance activities with start times scheduled before the entered timestamp (epoch milliseconds).

    A successful GET returns a code 200 OK. The response returns a JSON body containing data describing the maintenance all upgrades for the event broker service.

Deleting Maintenance Schedules, Maintenance Windows, and Scheduled Upgrades Using the REST API

You may want to cancel an event broker service upgrade that is scheduled in a maintenance window, or may want to move the scheduled upgrade to another time. In these situations, you can delete the scheduled event broker service upgrade from the maintenance window. You can also delete maintenance windows entirely, for example, you decide to move all event broker service upgrades from Fridays to Sundays, leaving the Sunday maintenance window empty. You can also delete a maintenance schedule if you no longer need the schedule.

You must remove all:

  • scheduled upgrades in a maintenance window before you can delete the window.

  • maintenance windows from a maintenance schedule before you can delete the schedule.

For more information see:

Deleting a Maintenance Schedule

If you no longer need a maintenance schedule, you can use the REST API to delete the schedule. You must delete all maintenance windows on the maintenance schedule before you can delete the schedule.

To delete a maintenance schedule, perform this step:

Deleting a Maintenance Window on a Maintenance Schedule

If you no longer need a maintenance window on a maintenance schedule, you can use the REST API to delete the window. You must delete all scheduled maintenance activities in a maintenance window before you can delete the maintenance window.

To delete a maintenance window, perform this step:

  • Delete a maintenance window in a maintenance schedule using the Delete a maintenance window REST API.

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

    Variable Definition
    maintenanceWindowId

    The identifier of the maintenance window you want to delete. You can get a list of maintenance windows for a maintenance schedule using the REST API. For more information see Get the Details of All Maintenance Windows in a Maintenance Schedule.

    A successful DELETE returns code 204 No Content.

Canceling a Scheduled Upgrade in a Maintenance Window

If you no longer need a scheduled upgrade for an event broker service on a maintenance window, you can cancel the maintenance activity.

To delete an event broker service upgrade in a maintenance window, perform this step: