Splunk Cloud Platform

Admin Config Service Manual

Acrobat logo Download manual as PDF


Acrobat logo Download topic as PDF

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 your change freeze requests made in the past 1 year.

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 your change freeze requests made in the past 1 year. For example:

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

Error response (400, 404, 500):

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

All times are UTC.

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

Update maintenance window change freeze requests

You can use the ACS API to update maintenance window change freeze requests. ACS supports update of customer-initiated change freezes 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:

Parameter Description
id ID of the change freeze
startDate Start date of the change freeze, format: YYYY/MM/DD (UTC). Change freezes start at 00:00 UTC on the start date.
endDate End date of the change freeze, format: YYYY/MM/DD (UTC). Change freezes end at 23:59 UTC on the end date.
appliesTo Supported change freeze types:
  • Splunk Initiated Changes Only
  • Customer and Splunk Initiated Changes
reason Reason for this change freeze request.
recordVersion Version of the record used to handle write conflicts. To obtain this value, send a GET request to the maintenance-windows/preferences endpoint prior to sending a PUT request. The recordVersion value that you specify in the PUT request must match the value in the latest GET request. See View maintenance window change freeze requests.

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. Omitting an existing change freeze from the PUT request deletes that change freeze request.

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.

Last modified on 17 April, 2024
PREVIOUS
Manage users, roles, and capabilities in Splunk Cloud Platform
  NEXT
Admin Config Service (ACS) API endpoint reference

This documentation applies to the following versions of Splunk Cloud Platform: 8.2.2112, 8.2.2201, 8.2.2202, 8.2.2203, 9.0.2205, 9.0.2208, 9.0.2209, 9.0.2303, 9.0.2305, 9.1.2308 (latest FedRAMP release), 9.1.2312


Was this documentation topic helpful?


You must be logged into splunk.com in order to post comments. Log in now.

Please try to keep this discussion focused on the content covered in this documentation topic. If you have a more general question about Splunk functionality or are experiencing a difficulty with Splunk, consider posting a question to Splunkbase Answers.

0 out of 1000 Characters