Manage maintenance windows for Splunk Cloud Platform

The Admin Config Service (ACS) API lets you perform certain maintenance window management tasks for your Splunk Cloud platform deployment on a self-service basis. You can use the ACS API to view maintenance window schedule information. You can also use the ACS API to view and update maintenance window preferences. ACS currently supports view and update of change freeze preferences only.

ACS supports viewing of maintenance window schedule information only. It does not support scheduling of maintenance windows.

For more information on Splunk Cloud Platform maintenance windows, see Splunk Cloud Platform Service Details.

Requirements

To view maintenance window information using the ACS API:

• You must have the sc_admin role.
• You must have Splunk Cloud Platform version 8.0.2007 or higher.
• Your deployment must have one or more separate search heads or a search head cluster. ACS is not supported on single instance deployments.

The ACS API does not support maintenance window operations on FedRAMP deployments.

Set up the ACS API

Before using the ACS API, you must download the ACS Open API 3.0 specification, which includes the parameters, response codes, and other data you need to work with the ACS API. You must also create an authentication token in Splunk Cloud Platform for use with ACS endpoint requests. For details on how to set up the ACS API to view maintenance windows, see Set up the ACS API.

View maintenance window schedules

You can use the ACS API to view both historic and upcoming maintenance window schedule information for your Splunk Cloud Platform deployment.

Maintenance window schedule data is updated daily, not in real time.

List maintenance windows

To list scheduled maintenance windows for your deployment, send an HTTP GET request to the /maintenance-windows/schedules endpoint. By default, the request returns a list of maintenance windows scheduled within +/-30 days from now.

You can optionally specify the following query parameters to customize the time frame and the number of listed maintenance windows:

Parameter	Description
fromTime	The earliest time the maintenance window schedule starts. Acceptable format is YYYY-MM-DD or in RFC3339 (YYYY-MM--DDTHH:mm:SSZHH:mm).
toTime	The latest time the maintenance window schedule starts. Acceptable format is YYYY-MM-DD or in RFC3339 (YYYY-MM--DDTHH:mm:SSZHH:mm).
count	Number of maintenance window schedules. Default value is 30.
nextLink	The start time of the next scheduled maintenance window relative to the current maintenance window count. For example, if there are 3 total scheduled maintenance windows and the count is set to 2, the request returns a nextLink value stating the start time of the 3rd maintenance window. This is used for pagination purposes. A value of null indicates there are no more pages.

If fromTime and toTime are not set, the request returns +30 days from now. If only fromTime is set, it returns +30 days from fromTime. If only toTime is set, it returns -30 days until toTime. If both are set it returns from fromTime to toTime.

For example:

curl -X GET 'https://admin.splunk.com/{stack}/adminconfig/v2/maintenance-windows/schedules?fromTime=2022-08-09&toTime=2022-08-14&nextLink=2022-08-21T04:00:00Z&count=1' \
--header 'Authorization: Bearer eyJraWQiOiJzcGx1bmsu …'

The request returns information about the scheduled maintenance windows within the specified time frame. For example:

{
   "nextLink": "2022-08-21T04:00:00Z",
   "schedules": [
       {
           "duration": "2h",
           "lastModifiedTimestamp": "2022-11-16T19:09:53Z",
           "lastSummary": "Customer requested upgrade",
           "mwType": "Service Update",
           "operations": [
               {
                   "SFDCTickets": [
                       "string"
                   ],
                   "endTime": "2022-04-20T05:00:00Z",
                   "notes": [
                       "string"
                   ],
                   "operationDescription": "string",
                   "operationStatus": "Tentative",
                   "operationType": "Splunk Upgrade",
                   "startTime": "2022-09-20T04:00:00Z",
                   "targetVersion": "string"
               }
           ],
           "requestedEntity": "splunk",
           "scheduleId": "1e4729b4-11d0-4165-a886-a21cce7139f2",
           "scheduleStartTimestamp": "2022-08-21T04:00:00Z",
           "status": "Tentative"
       }
   ]
}

The maintenance-windows/schedules endpoint only lists historical maintenance windows that have completed. The endpoint does not list previously scheduled maintenance windows that have been canceled.

For endpoint details, see maintenance-windows/schedules in the ACS endpoint reference.

Describe individual maintenance windows

To describe a specific maintenance window, send an HTTP GET request to the /maintenance-windows/schedules/{scheduleId} endpoint, specifying the maintenance window schedule ID. For example:

curl -X GET 'https://admin.splunk.com/{stack}/adminconfig/v2/maintenance-windows/schedules/{scheduleId}' \
--header 'Authorization: Bearer eyJraWQiOiJzcGx1bmsu …'

The request returns information about the specific maintenance window. For example:

{
   "duration": "2h",
   "lastModifiedTimestamp": "2022-11-16T19:09:53Z",
   "lastSummary": "Customer requested upgrade",
   "mwType": "Service Update",
   "operations": [
       {
           "SFDCTickets": [
               "string"
           ],
           "endTime": "2022-04-20T05:00:00Z",
           "notes": [
               "string"
           ],
           "operationDescription": "string",
           "operationStatus": "Tentative",
           "operationType": "Splunk Upgrade",
           "startTime": "2022-04-20T04:00:00Z",
           "targetVersion": "string"
       }
   ],
   "requestedEntity": "splunk",
   "scheduleId": "14479cd5-8ada-41f0-92c4-d234e9124569",
   "scheduleStartTimestamp": "2022-08-13T04:00:00Z",
   "status": "Tentative"
}

For endpoint details, see maintenance-windows/schedules/{scheduleId} in the ACS endpoint reference.

Audit maintenance windows

To view an audit trail of status changes for a specific maintenance window, send an HTTP request to the maintenance-windows/schedules/{scheduleID}/audits endpoint, specifying the maintenance window schedule ID.

By default, the request returns a list of all audit events for the specified maintenance window. You can optionally specify the following fromTime and toTime query parameters to view a subset of audit events within a specified time frame:

Parameter	Description
fromTime	The earliest time the maintenance window schedule starts. Acceptable format is YYYY-MM-DD or in RFC3339 (YYYY-MM--DDTHH:mm:SSZHH:mm).
toTime	The latest time the maintenance window schedule starts. Acceptable format is YYYY-MM-DD or in RFC3339 (YYYY-MM--DDTHH:mm:SSZHH:mm).

For example:

curl -X GET 'https://admin.splunk.com/{stack}/adminconfig/v2/maintenance-windows/schedules/{scheduleId}/audits?fromTime=2022-08-09&toTime=2022-08-14' \
--header 'Authorization: Bearer eyJraWQiOiJzcGx1bmsu …'

The request returns a list of all audit events within the specified time frame. For example:

{
   "audits": [
       {
           "duration": "2h0m0s",
           "lastModifiedTimestamp": "2022-11-01T18:09:25Z",
           "lastSummary": "",
           "mwType": "Service Update",
           "operations": [
               {
                   "operationDescription": "Splunk version upgrade to latest/stable release",
                   "operationStatus": "Completed",
                   "operationType": "SplunkUpgrade",
                   "targetVersion": "9.0.2209.1"
               }
           ],
           "requestedEntity": "Splunk",
           "scheduleId": "66e20f3f-aea2-4096-982f-7f93a6979872",
           "scheduleStartTimestamp": "2022-10-14T04:00:00Z",
           "status": "Completed"
       },
       {
           "duration": "2h0m0s",
           "lastModifiedTimestamp": "2022-10-11T18:09:25Z",
           "lastSummary": "",
           "mwType": "Service Update",
           "operations": [
               {
                   "operationDescription": "Splunk version upgrade to latest/stable release",
                   "operationStatus": "Completed",
                   "operationType": "SplunkUpgrade",
                   "targetVersion": "9.0.2209.1"
               }
           ],
           "requestedEntity": "Splunk",
           "scheduleId": "66e20f3f-aea2-4096-982f-7f93a6979872",
           "scheduleStartTimestamp": "2022-10-14T04:00:00Z",
           "status": "Completed"
       }
   ]
}

For endpoint details, see maintenance-windows/schedules/{scheduleID}/audits in the ACS endpoint reference.

View and update maintenance window preferences

The ACS API lets you view and update certain maintenance window preferences for your Splunk Cloud Platform deployment.

ACS currently supports view and update of maintenance window change freeze preferences only.

View maintenance window change freeze requests

You can use the ACS API to list both customer-initiated and Spunk-initiated change freezes.

To list all maintenance window change freezes, send an HTTP GET request to the maintenance-windows/preferences endpoint. For example:

curl -X GET "https://admin.splunk.com/{stack}/adminconfig/v2/maintenance-windows/preferences" \
--header "Authorization: Bearer eyJraWQiOiJzcGx1bmsuc2VjcmV0IiwiYWxnI..."

The request returns details of all customer-initiated and Splunk-initiated maintenance window change freezes. For example:

{
	"changeFreezes":{
		"customerInitiatedFreezes":[
			{
				"appliesTo":"Customer and Splunk Initiated Changes",
				"createdTimestamp":"2024-01-08T22:00:57Z",
				"endDate":"2023/02/01",
				"id":"b84a41c4-0344-48e5-8008-33ed44c2d393",
				"lastModifiedTimestamp":"2024-01-08T22:00:57Z",
				"reason":"Professional Services Engagement",
				"startDate":"2023/01/01",
				"tickets":["SFDC-001"]
			}
		],
		"splunkInitiatedFreezes":[
			{
				"appliesTo":"Customer and Splunk Initiated Changes",
				"category":"Professional Services",
				"createdTimestamp":"2024-01-08T22:00:57Z",
				"endDate":"2023/02/01",
				"id":"c5c122ee-78fc-4b4e-be6d-737396913abb",
				"lastModifiedTimestamp":"2024-01-08T22:00:57Z",
				"reason":"Professional Services Engagement",
				"startDate":"2023/01/01",
				"tickets":["SFDC-003"]
			}
		]
	},
	"recordVersion":19
}

Error response (400, 404, 500):

{
	"code": "400-bad-request",
	"message": "<error message from server>"
}

The tickets field shows SFDC tickets only. All times are UTC.

For endpoint details, see maintenance-windows/preferences in the ACS endpoint reference.

Update maintenance window change freeze requests

The ACS API lets you update maintenance window change freeze requests. You can use this functionality to adjust the time frame during which Splunk suspends all non-critical changes to your deployment. ACS supports update of customer-initiated change freezes only.

Change freeze updates are limited to the 2 latest versions of Splunk Cloud Platform only.

To update a maintenance window change freeze, send an HTTP PUT request to the maintenance-windows/preferences endpoint, specifying the following parameters in the request body:

• id: ID of the change freeze (optional)
• startDate: Start date of the change freeze (UTC)
• endDate: End date of the change freeze (UTC)
• appliesTo: Either Splunk Initiated Changes Only or Customer and Splunk Initiated Changes
• reason: Reason for the change freeze request

For example:

curl -X PUT https://admin.splunk.com/{stack}/adminconfig/v2/maintenance-windows/preferences' \
--header 'Authorization: Bearer <token>' \
--data '{"changeFreezes":{"customerInitiatedFreezes":[{"appliesTo":"Customer and Splunk Initiated Changes","endDate":"2023/02/01","id":"b84a41c4-0344-48e5-8008-33ed44c2d393","reason":"Professional Services Engagement","startDate":"2023/01/01",}],},"recordVersion":19}'

A successful request returns a 204 (no content) code.

You must include all existing change freezes with an ID in the PUT request body. Any existing change freezes that you omit from the request body will be deleted.

For endpoint details, see maintenance-windows/preferences in the ACS endpoint reference.

When updating change freeze requests using the ACS API, note the following:

• You can only update changes freezes in the customerInitiatedFreezes list. Updates to change freezes in the splunkInitiatedFreezes list are ignored.
• Change freeze IDs uniquely identify a change freeze in the customerInitiatedFreezes list.
• You cannot create a change freeze ID. Splunk Cloud Platform automatically generates change freeze IDs.
• Adding a change freeze without an ID creates a new change freeze with a unique ID.
• Making a change to an existing change freeze with an ID updates that change freeze request.
• Omitting an existing change freeze with an ID from the PUT request body deletes that change freeze.

The following limitations apply when deleting or making changes to expired change freezes and ongoing change freezes:

• You cannot delete or modify completed change freezes.
• Deleting an ongoing change freeze cancels the change freeze (resets the endTime value to the current time).

For more information on change freeze limitations, see Splunk Cloud Platform maintenance policy.