Manage restarts in Splunk Cloud Platform

The Admin Config Service (ACS) API lets you manage restarts for your Splunk Cloud Platform deployment in a self-service manner. You can use the ACS API to initiate restarts for single search heads or search head clusters programmatically, without assistance from Splunk Support.

ACS restart functionality does not support searchable rolling restarts.

Requirements

To manage restarts using the ACS API:

• Your role must have the capabilities required to access the ACS API endpoint. The sc_admin role has all required capabilities by default. For a list of required capabilities, see Manage ACS API access with capabilities.
• Splunk Cloud Platform deployments on Classic Experience require version 9.1.2308 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 AWS GovCloud or 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, codes, and other data you need to work with the ACS API. You must also create a JWT authentication token in Splunk Cloud Platform for use with ACS endpoint requests. For details on how to set up the ACS API to manage restarts, see Set up the ACS API.

Check if a restart is required

To check if your search head tier currently requires a restart, send an HTTP GET request to the ACS /status endpoint. For example:

curl https://admin.splunk.com/{stack}/adminconfig/v2/status \
--header 'Authorization: Bearer eyJraWQiOiJzcGx1bmsuc2...'

If the request returns "restartRequired": true, then your search head tier requires a restart. For example:

{
    "infrastructure": {
        "status": "Failed"
    },
    "messages": {
        "restartRequired": true
    }
}

Initiate a restart using the ACS API

You can use the ACS API restart-now endpoint to initiate a restart for a single search head, or a rolling restart for a search head cluster. ACS lets you target a specific search head (including standalone and premiums search heads) or search head cluster, by adding the search head prefix to the stack URL when you send a restart request. For more information on search head targeting, see Target a specific search head for ACS operations.

You do not need to specify if your deployment is a single search head or search head cluster. ACS checks this in the background and calls the appropriate splunkd endpoint.

Restart a single search head

To initiate a restart of a single search head, send an HTTP POST request to the restart-now endpoint. For example:

curl -X POST 'https://admin.splunk.com/{stack}/adminconfig/v2/restart-now' \
--header 'Authorization: Bearer eyJraWQiOiJzcGx1bmsuc2VjcmV0IiwiYW...'

A successful request returns a 202 response code and a message indicating that the restart is in progress, but might take some time to complete. For example:

{
    "message": "Successfully initiated a server restart. It might take some time for completion"
}

To check the restart status of a single search head, send an HTTP GET request to the ACS /status endpoint. For example:

curl https://admin.splunk.com/{stack}/adminconfig/v2/status \
--header 'Authorization: Bearer eyJraWQiOiJzcGx1bmsuc2VjcmV0IiwiYW...

If the restart has completed successfully, the request returns status: Ready and restartRequired: false. If the restart is still in progress, the request returns a 500 status code and an error message indicating the search head is inaccessible. For example:

{
   "code": "500-internal-server-error",
   "message": "An error occurred while processing this request. Trying this request again may succeed if the bug is transient, otherwise please report this issue this response. (requestID=62e993069b8e447c34240569). Please refer to https://docs.splunk.com/Documentation/SplunkCloud/latest/Config/ACSerrormessages for general troubleshooting tips."
}

Restart a search head cluster

To initiate a rolling restart of a search head cluster, send an HTTP POST request to the to the restart-now endpoint. For example:

curl -X POST 'https://admin.splunk.com/{stack}/adminconfig/v2/restart-now' \
--header 'Authorization: Bearer eyJraWQiOiJzcGx1bmsuc2VjcmV0IiwiYW...'

A successful request returns a 202 response code and a message indicating that a rolling restart of search head cluster members is in progress, but might take some time to complete. For example:

{
    "message": "Rolling Restart of all the search head cluster members has been kicked off. It might take some time for completion"
}

To check the status of the search head cluster rolling restart, send an HTTP GET request to the /restart/status endpoint. For example:

curl https://admin.splunk.com/{stack}/adminconfig/v2/restart/status \
--header 'Authorization: Bearer eyJraWQiOiJzcGx1bmsuc2VjcmV0IiwiYW...

If all cluster members have successfully restarted, the request returns a 202 status code with "serviceReady": true and "rollingRestartInitiated": false. If the rolling restart is still in progress, the request returns a 500 error code, and shows "serviceReady": false and "rollingRestartInitiated": true. For example:

{
    "shcStatus":  [
     {
	   
        "captain": "sh-i-..",
        
        "rollingRestartInitiated": true,
        "serviceReady": false
     }
   ]
}

The /restart/status endpoint applies to search head cluster rolling restarts only. To check the status of a single search head restart, use the ACS /status endpoint.

If the rolling restart fails and your deployment remains inaccessible, contact Splunk Support.

For endpoint details, see restart-now and restart/status in the ACS API endpoint reference.

For more information on search head cluster rolling restarts, see Restart the search head cluster in the Splunk Enterprise Distributed Search manual.