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 currently use the ACS API to view both historic and upcoming maintenance window schedule information.

Note: 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.
Note: 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 manage 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.

Note: Maintenance window schedule data is updated 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:

JSON 
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:

JSON 
{
   "nextLink": "2024-08-21T04:00:00Z",
   "schedules": [
       {
           "duration": "2h",
           "lastModifiedTimestamp": "2024-06-20T04:00:00Z",
           "mwType": "Service Update Maintenance",
           "operations": [
               {
                   "SFDCTickets": ["SFDC-1234"],
                   "endTime": "2024-08-21T06:00:00Z",
                   "notes": ["Updating the stack to the latest version."],
                   "operationDescription": "KitKat Tock Upgrade 9.1.2308",
                   "operationStatus": "Tentative",
                   "startTime": "2024-08-21T04:00:00Z",
                   "targetVersion": "9.1.2308.207",
                   "zeroDowntime": true
               }
           ],
           "requestedEntity": "splunk",
           "scheduleEndTimestamp": "2024-08-21T06:00:00Z",
           "scheduleId": "1e4729b4-11d0-4165-a886-a21cce7139f2",
           "scheduleStartTimestamp": "2024-08-21T04:00:00Z",
           "status": "Tentative",
           "zeroDowntime": true
       }
   ]
}

Note: 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:

JSON 
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:

JSON 
{
    "duration": "2h",
    "lastModifiedTimestamp": "2024-06-20T04:00:00Z",
    "mwType": "Service Update Maintenance",
    "operations": [
        {
            "SFDCTickets": ["SFDC-1234"],
            "endTime": "2024-08-21T06:00:00Z",
            "notes": ["Updating the stack to the latest version."],
            "operationDescription": "KitKat Tock Upgrade 9.1.2308",
            "operationStatus": "Tentative",
            "startTime": "2024-08-21T04:00:00Z",
            "targetVersion": "9.1.2308.207",
            "zeroDowntime": true
        }
    ],
    "requestedEntity": "splunk",
    "scheduleEndTimestamp": "2024-08-21T06:00:00Z",
    "scheduleId": "1e4729b4-11d0-4165-a886-a21cce7139f2",
    "scheduleStartTimestamp": "2024-08-21T04:00:00Z",
    "status": "Tentative",
    "zeroDowntime": true
}

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:

JSON 
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:

JSON 
{
    "audits": [
        {
            "duration": "2h",
            "lastModifiedTimestamp": "2024-06-20T04:00:00Z",
            "mwType": "Service Update Maintenance",
            "operations": [
                {
                    "SFDCTickets": ["SFDC-1234"],
                    "endTime": "2024-08-21T06:00:00Z",
                    "notes": ["Updating the stack to the latest version."],
                    "operationDescription": "KitKat Tock Upgrade 9.1.2308",
                    "operationStatus": "Tentative",
                    "startTime": "2024-08-21T04:00:00Z",
                    "targetVersion": "9.1.2308.207",
                    "zeroDowntime": true
                }
            ],
            "requestedEntity": "splunk",
            "scheduleId": "1e4729b4-11d0-4165-a886-a21cce7139f2",
            "scheduleStartTimestamp": "2024-08-21T04:00:00Z",
            "status": "Tentative",
            "zeroDowntime": true
        },
        {
            "duration": "2h",
            "lastModifiedTimestamp": "2024-06-22T08:00:00Z",
            "mwType": "Service Update Maintenance",
            "operations": [
                {
                    "SFDCTickets": ["SFDC-1234"],
                    "endTime": "2024-08-21T06:00:00Z",
                    "notes": ["Updating the stack to the latest version."],
                    "operationDescription": "KitKat Tock Upgrade 9.1.2308",
                    "operationStatus": "Scheduled",
                    "startTime": "2024-08-21T04:00:00Z",
                    "targetVersion": "9.1.2308.207",
                    "zeroDowntime": true
                }
            ],
            "requestedEntity": "splunk",
            "scheduleEndTimestamp": "2024-08-21T06:00:00Z",
            "scheduleId": "1e4729b4-11d0-4165-a886-a21cce7139f2",
            "scheduleStartTimestamp": "2024-08-21T04:00:00Z",
            "status": "Tentative",
            "zeroDowntime": true
        }
    ]
}

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

Manage maintenance window preferences

The ACS API gives Splunk Cloud Platform administrators a self-service toolkit for maintenance planning. Use change freeze to identify critical periods when planned changes should be avoided. Use preferred maintenance windows to define the times that work best for changes that require downtime.

To learn more, see the Splunk Cloud Platform maintenance policy and the Maintenance section in the Splunk Cloud Platform Service Details.

List available preferred maintenance windows

Use this endpoint to view a pre-selected list of time windows that eligible stacks can select as a preferred window, sorted by capacity from highest to lowest capacity.

Send an HTTP GET request to the maintenance-windows/preferences/available-windows endpoint. You can filter the response with start and end times. Supply both parameters or neither parameter. When you supply the parameters, their values must exactly match a predefined regional off-hours time slot.

JSON 
curl -X GET "https://admin.splunk.com/{stack}/adminconfig/v2/maintenance-windows/preferences/available-windows?start=21:00&end=05:00" \
  --header "Authorization: Bearer <token>"

The request returns HTTP 200 and a response similar to the following example:

JSON 
{
  "availableWindows": [
    {
      "timeSlot": {
        "start": "21:00",
        "end": "05:00"
      },
      "daysOfWeek": [
        "Wednesday",
        "Friday",
        "Monday",
        "Thursday",
        "Tuesday",
        "Sunday",
        "Saturday"
      ]
    }
  ]
}

Use the ACS CLI to list available windows:

CODE 
acs maintenance-windows preferences list-available-windows --start 21:00 --end 05:00

If the stack is not eligible for preferred maintenance windows, the endpoint returns HTTP 403:

JSON 
{
  "code": "403-forbidden",
  "message": "stack not yet eligible for preferred windows feature"
}

View maintenance window preferences

Use the ACS API to view the current preferred schedule and all customer- and Splunk-initiated change freeze requests for your deployment. The response includes past, current, and upcoming change freeze requests.

Send an HTTP GET request to the maintenance-windows/preferences endpoint:

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

The request returns HTTP 200 and a response similar to the following example:

JSON 
{
  "preferredSchedule": {
    "preferredWindow": {
      "timeSlot": {
        "start": "21:00",
        "end": "05:00"
      },
      "preferredDay": "Wednesday",
      "alternateDays": [
        "Monday",
        "Tuesday",
        "Thursday",
        "Friday",
        "Saturday",
        "Sunday"
      ]
    },
    "additionalPreferences": [
      {
        "timeSlot": {
          "start": "14:00",
          "end": "17:00"
        },
        "daysOfWeek": [
          "Monday"
        ]
      }
    ]
  },
  "changeFreezes": {
    "customerInitiatedFreezes": [],
    "splunkInitiatedFreezes": []
  },
  "recordVersion": 3
}

Use the ACS CLI to view the preferences:

CODE 
acs maintenance-windows preferences describe

Error response (400, 404, 500):

PYTHON 
{
  "code": "400-bad-request",
  "message": "<error message from server>"
}
Note: All times are UTC.

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

Update a preferred maintenance schedule

Update the preferred schedule for an eligible stack by sending an HTTP PUT request to the maintenance-windows/preferences endpoint.

Before you update the schedule, retrieve the current preferences. Include the recordVersion value from that response in your request. The value in your request must match the latest recordVersion. ACS uses this value to prevent write conflicts.

CAUTION: The request replaces the existing customer-initiated change freezes and preferred schedule. Include every existing customer-initiated change freeze with its associated ID value. Omitting an existing change freeze deletes it. You cannot update or include changes to the splunkInitiatedFreezes list.

Save the request body in preferences.json:

JSON 
{
  "preferredSchedule": {
    "preferredWindow": {
      "timeSlot": {
        "start": "21:00",
        "end": "05:00"
      },
      "preferredDay": "Wednesday",
      "alternateDays": [
        "Monday",
        "Tuesday",
        "Thursday",
        "Friday"
      ]
    },
    "additionalPreferences": [
      {
        "timeSlot": {
          "start": "14:00",
          "end": "17:00"
        },
        "daysOfWeek": [
          "Monday",
          "Tuesday"
        ]
      }
    ]
  },
  "changeFreezes": {
    "customerInitiatedFreezes": []
  },
  "recordVersion": 3
}

Send the request:

JSON 
curl -X PUT "https://admin.splunk.com/{stack}/adminconfig/v2/maintenance-windows/preferences" \
  --header "Authorization: Bearer <token>" \
  --header "Content-Type: application/json" \
  --data @preferences.json

A successful request returns HTTP 204 with no response body.

Use the ACS CLI to update the preferences:

CODE 
acs maintenance-windows preferences update --file preferences.json
Note: If the stack is not eligible for preferred maintenance windows, an update that includes preferredSchedule returns HTTP 403.

When you update a preferred maintenance schedule, note the following requirements:

  • Use HH:MM UTC values for all times. A time slot can span midnight.
  • Set preferredWindow.timeSlot to one of these values: 14:00-22:00, 21:00-05:00, 01:00-09:00, or 04:00-12:00 UTC.
  • Set preferredDay and each alternateDays value to a day from Monday through Sunday. ACS uses alternate days when the preferred day is unavailable.
  • Use additionalPreferences for smaller-impact changes. Each entry can use a different time range, must span from 2 through 24 hours, and can include one or more days of the week.
  • Include no more than three additionalPreferences entries.
  • If alternateDays is empty, include at least one additionalPreferences entry.

Update maintenance window change freeze requests

Use the ACS API to update customer-initiated change freeze requests. ACS does not support updates to Splunk-initiated change freezes.

Send an HTTP PUT request to the maintenance-windows/preferences endpoint. Include the following parameters in the request body:

Parameter Description
id Identifies an existing customer-initiated change freeze.
startDate Start date in YYYY/MM/DD UTC format. The change freeze starts at 00:00 UTC on this date.
endDate End date in YYYY/MM/DD UTC format. The change freeze ends at 23:59 UTC on this date.
appliesTo The types of maintenance window changes that the change freeze applies to:
  • Splunk Initiated Changes Only
  • Customer and Splunk Initiated Changes
reason Reason for the change freeze request.
recordVersion The version used to handle write conflicts. Retrieve this value by sending a GET request before you send a PUT request.

For example, the following request updates two customer-initiated change freezes:

JSON 
curl -X PUT "https://admin.splunk.com/{stack}/adminconfig/v2/maintenance-windows/preferences" \
  --header "Authorization: Bearer <token>" \
  --header "Content-Type: application/json" \
  --data @preferences.json
JSON 
{
  "changeFreezes": {
    "customerInitiatedFreezes": [
      {
        "startDate": "2024/06/28",
        "endDate": "2024/07/02",
        "id": "b84a41c4-0344-48e5-8008-33ed44c2d393",
        "appliesTo": "Splunk Initiated Changes Only",
        "reason": "End of Quarter Freeze"
      },
      {
        "startDate": "2024/09/01",
        "endDate": "2024/09/14",
        "id": "3200242e-afc8-41dd-acd4-13ef41b5f3fd",
        "appliesTo": "Customer and Splunk Initiated Changes",
        "reason": "Business Needs"
      }
    ]
  },
  "recordVersion": 2
}

A successful request returns HTTP 204 with no response body.

CAUTION: Include all existing change freeze requests with their associated ID value in the PUT request body. Omitting an existing change freeze from the PUT request deletes that change freeze request.

You can update only the customerInitiatedFreezes list. A change freeze ID uniquely identifies a change freeze in that list. Do not specify an ID when you create a new change freeze. Splunk Cloud Platform generates the ID.

Create a change freeze request

Before you create a change freeze request, retrieve the current preferences and note the recordVersion value. To create the request, send a PUT request that includes the current recordVersion and a customer-initiated change freeze without an id value.

JSON 
{
  "changeFreezes": {
    "customerInitiatedFreezes": [
      {
        "startDate": "2024/06/28",
        "endDate": "2024/07/02",
        "appliesTo": "Splunk Initiated Changes Only",
        "reason": "End of Quarter Freeze"
      }
    ]
  },
  "recordVersion": 1
}

The request creates the change freeze with a unique ID. Send a GET request to confirm that ACS created the request. You cannot create an in-progress change freeze with a startDate in the past and an endDate in the future.

Delete a change freeze request

Before you delete a change freeze request, retrieve the current preferences and note the recordVersion value. To delete a customer-initiated change freeze, send a PUT request that omits that change freeze object from the customerInitiatedFreezes list.

JSON 
{
  "changeFreezes": {
    "customerInitiatedFreezes": []
  },
  "recordVersion": 2
}
Note: You cannot delete a change freeze that has ended.
Note: Deleting an ongoing change freeze ends it at the current time.

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

For detailed information on maintenance window change freeze policies, see Splunk Cloud Platform maintenance policy.