Manage private apps in Splunk Cloud Platform

The Admin Config Service (ACS) API supports programmatic self-service management of private apps and add-ons on Splunk Cloud Platform. You can use the ACS API to install, upgrade, and uninstall apps directly on your Splunk Cloud Platform deployment without assistance from Splunk Support.

The ACS API works in conjunction with the Splunk AppInspect app validation tool to ensure that your private apps meet Splunk Cloud Platform requirements. Your app must be approved by AppInspect before you can install it using the ACS API.

The ACS API also facilitates orchestration of app deployment for CI/CD pipelines. You can integrate ACS requests into automated workflows for upgrade, validation, and installation of private apps that you develop and maintain for your Splunk Cloud Platform deployment.

Requirements

To manage private apps using the ACS API, you must:

Have the sc_admin (Splunk Cloud Platform Administrator) role.
Have Splunk Cloud Platform version 8.2.2109 or higher.

The ACS API does not currently support AWS GovCloud or FedRAMP environments.

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 retrieve the ACS Open API 3.0 specification and create a JWT authentication token, see Set up the ACS API.

Determine the correct ACS API endpoints for your Splunk Cloud Platform Experience

The correct ACS API endpoints to use for private app management depend on your Splunk Cloud Platform Experience. To find out if your deployment is on Classic Experience or Victoria Experience: In Splunk Web, click Support & Services > About.

After you determine your deployment's Experience, follow the instructions that apply to your deployment:

For more information on the Splunk Cloud Platform Experience, see Determine your Splunk Cloud Platform Experience.

Manage private apps using the ACS API on Victoria Experience

This section shows you how to manage private apps on your Splunk Cloud Platform deployment using the ACS API on Victoria Experience. If your Splunk Cloud Platform deployment is on Classic Experience, see Manage private apps using the ACS API on Classic Experience. For more information, see Determine the correct ACS endpoints for your Splunk Cloud Platform Experience.

You can use the ACS API to manage private apps on premium search heads, such as those running Splunk Enterprise Security, on Victoria Experience only. ACS does not support private app management on premium search heads on Classic Experience.

Validate your private app

Before you can install your private using the ACS API, you must manually validate the app using Splunk AppInspect.

The following is a summary of the main steps involved in using the Splunk AppInspect API to validate your private app. For complete instructions, see Use the AppInspect API in the Splunk Developer Guide.

Authenticate with the Splunk API service using your Splunk.com credentials. The login request returns an authentication token, which you need to authenticate Splunk AppInspect API requests. You must provide this authentication token when you send an app for validation using the AppInspect API and when you install an app using the ACS API. For instructions on how to login to the Splunk API service, see Authenticate with the Splunk API service.

Submit your app package to AppInspect for validation. To do so, send an HTTP POST request to the app/validate endpoint, specifying your AppInspect authentication token in the Authorization: Bearer header and the app_package path. You must also specify 'included_tags=private_app'. For example:

curl -X POST 'https://appinspect.splunk.com/v1/app/validate' \
--header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9…' \
--form 'app_package=@"/Users/croth/Downloads/opsgenie-for-splunk_122.tgz"' \
--form 'included_tags=private_app'

The request returns a "request ID" that is required to check the app validation status and retrieve your app validation report. For example:

{
   "request_id": "2860f181-604f-4a91-88f3-f0d52a763e77",
   "message": "Validation request submitted.",
   "links": [
       {
           "href": "/v1/app/validate/status/2860f181-604f-4a91-88f3-f0d52a763e77",
           "rel": "status"
       },
       {
           "href": "/v1/app/report/2860f181-604f-4a91-88f3-f0d52a763e77",
           "rel": "report"
       }
   ]
}

Check the status of your app validation request. To do so, send a GET request to the /app/validate/status/{request_id} endpoint, specifying the request_id returned in the previous step. The status endpoint returns a SUCCESS result to indicate the AppInspect run was successful. However, to determine if the app passed validation, you must retrieve the app validation report as shown in the next step.
Retrieve the app validation report. To do so, send a GET request to the /app/report/{request_id} endpoint, specifying the request_id returned in the previous step. The report must show 0 Failures, 0 Errors, and 0 Manual Checks before you can install your app using the ACS API. If your report shows a value greater than zero for Manual Checks, you must contact Splunk Support to install your app.

For more detailed information on how to validate your app using the AppInspect API, see Use the AppInspect API in the Splunk Developer Guide.

Install an app

To install a private app on Victoria Experience using the ACS API:

Send an HTTP POST request to the apps/victoria endpoint, specifying your AppInspect authentication token in the X-Splunk-Authorization header, which allows for verification of app validation with AppInspect. For details on how to create an AppInspect authentication token, see Step 1 under Validate your private app.

You must also specify your Splunk Cloud Platform JWT token in the Authorization: Bearer header, and specify your app installation package in the request body. For details on how to create a JWT token in Splunk Cloud Platform, see Create an authentication token.

You must also specify Y in the ACS-Legal-Ack: header to acknowledge your acceptance of any risks involved installing unsupported apps, as specified in the Splunk legal disclaimer for app installation, provided in the ACS OpenAPI 3.0 specification. To review the disclaimer, see Set up the ACS API.

The header you use to specify your AppInspect authentication token (X-Splunk-Authorization) differs from the header you use to specify the token when you submit an app to the AppInspect API for validation (Authorization: Bearer).

For example:

curl -X POST 'https://admin.splunk.com/{stack}/adminconfig/v2/apps/victoria' \
--header 'X-Splunk-Authorization: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9…' \
--header 'Authorization: Bearer eyJraWQiOiJzcGx1bmsuc2VjcmV0IiwiYWxnI…' \
--header 'ACS-Legal-Ack: Y' \
--data-binary '@/Users/croth/Downloads/pa1v20.tar.gz'

The request output shows "status": "installed" when app installation successfully completes. If the request output shows "status": "uploaded", this means the app has been successfully uploaded, but app installation is still in-progress due to the asynchronous app installation process. For example:

{
   "label": "pa1",
   "name": "pa1",
   "status": "installed",
   "version": "1.2.2"
}

ACS app installation occurs in an eventually consistent manner, so you might experience a brief delay before the app becomes fully functional.

When you install an app using the ACS API on Victoria Experience, the app is automatically installed on all standalone search heads, search head cluster members, and premium search heads. For more information, see How self-service app installation works on Victoria Experience.

View installed apps

To view a list of apps currently installed on your deployment, send an HTTP GET request to the apps/victoria endpoint, specifying the Splunk Cloud Platform JWT token. For example:

curl 'https://admin.splunk.com/{stack}/adminconfig/v2/apps/victoria?count=50' \
--header 'Authorization: Bearer eyJraWQiOiJzcGx1bmsuc2VjcmV0IiwiYWxnI…'

The request returns a list of all apps installed on your deployment. For example:

{
   "apps": [
       {
           "label": "075-cloudworks",
           "name": "075-cloudworks",
           "status": "installed",
           "version": ""
       },
       {
           "label": "100-cloudworks-wlm",
           "name": "100-cloudworks-wlm",
           "status": "installed",
           "version": ""
       },
     
       
       {
           "label": "tos",
           "name": "tos",
           "status": "installed",
           "version": ""
       }
   ]
}

By default, the list apps request returns a maximum count of 30 apps. To change the count, you can specify a count value up to a maximum of 100. A count value of 0 lists all apps.

If you have more than 100 apps, you can specify an offset value to list additional apps. For example, to list apps 100-200, specify an offset value of 100. For example:

curl 'https://admin.splunk.com/{stack}/adminconfig/v2/apps/victoria?offset=100&count=100'

You can also view installed apps using the Splunk Web UI. For more information, see Install a private app on Victoria Experience in the Splunk Cloud Platform Admin Manual.

For endpoint details, see apps/victoria in the ACS endpoint reference.

Describe an app

To view details of an individual app, send an HTTP GET request to the apps/victoria/{app_name} endpoint, specifying the name of the app and the Splunk Cloud Platform JWT token. For example:

curl 'https://admin.splunk.com/{stack}/adminconfig/v2/apps/victoria/tos' \
--header 'Authorization: Bearer eyJraWQiOiJzcGx1bmsuc2VjcmV0IiwiYWxnI…'

The request returns information about the specific app, including the app installation status. When app installation successfully completes, the request output shows "status": "installed". For example:

{
   "label": "tos",
   "name": "tos",
   "status": "installed",
   "version": ""
}

If the request returns "code": "404-app-not-found", app installation is still in progress due to the asynchronous app installation process.

Uninstall an app

To uninstall an app, send an HTTP DELETE request to the apps/victoria/{app_name}/ endpoint, specifying the name of the app and the Splunk Cloud Platform JWT token. For example:

curl -X DELETE 'https://admin.splunk.com/{stack}/adminconfig/v2/apps/victoria/{app_name} \
--header 'Authorization: Bearer eyJraWQiOiJzcGx1bmsuc2VjcmV0IiwiYWxnI…'

For endpoint details, see apps/victoria/{app_name} in the ACS endpoint reference.

Manage private apps using the ACS API on Classic Experience

This section shows you how to validate, install, and manage private apps on your Splunk Cloud Platform deployment using the ACS API on Classic Experience. If your Splunk Cloud Platform deployment is on Victoria Experience, see Manage private apps using the ACS API on Victoria Experience. For more information, see Determine the correct ACS endpoints for your Splunk Cloud Platform Experience.

You cannot use the ACS API to manage private apps on premium search heads, such as those running Splunk Enterprise Security, on Classic Experience. ACS supports private app management on premium search heads on Victoria Experience only.

Validate your private app

Before you can install your private using the ACS API, you must manually validate your app using Splunk AppInspect.

The following is a summary of the main steps involved in using the AppInspect API to validate your private app. For complete instructions, see Use the AppInspect API in the Splunk Developer Guide.

Authenticate with the Splunk API service using your Splunk.com credentials. The login request returns an authentication token, which you need for Splunk AppInspect requests. See Authenticate with the Splunk API service.

Submit your app package to AppInspect for validation. You must specify 'included_tags=private_app'. For example:

curl -X POST 'https://appinspect.splunk.com/v1/app/validate' \
--header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9…' \
--form 'app_package=@"/Users/croth/Downloads/opsgenie-for-splunk_122.tgz"' \
--form 'included_tags=private_app'

The request returns a "request ID", that is required to check the app validation status and retrieve your app validation report. For example:

{
   "request_id": "2860f181-604f-4a91-88f3-f0d52a763e77",
   "message": "Validation request submitted.",
   "links": [
       {
           "href": "/v1/app/validate/status/2860f181-604f-4a91-88f3-f0d52a763e77",
           "rel": "status"
       },
       {
           "href": "/v1/app/report/2860f181-604f-4a91-88f3-f0d52a763e77",
           "rel": "report"
       }
   ]
}

Check the status of your app validation request. To do so, send a GET request to the /app/validate/status/{request_id} endpoint, specifying the request_id returned in the previous step. The status endpoint returns a SUCCESS result to indicate the AppInspect run was successful. However, to determine if the app passed validation, you must retrieve the app validation report as shown in the next step
Retrieve your app validation report. To do so, send a GET request to the /app/report/{request_id} endpoint, specifying the request_id returned in the previous step. The report must show 0 Failures, 0 Errors, and 0 Manual Checks before you can install your app using the ACS API. If your report shows a value greater than zero for Manual Checks, you must contact Splunk Support to install your app.

For more information on how to validate your app using the AppInspect API, see Use the AppInspect API in the Splunk Developer Guide.

Install an app on Classic Experience

To install a private app on Classic Experience using the ACS API:

Send an HTTP POST request to the apps endpoint, specifying your Splunk Cloud JWT token. For details on how to create a Splunk Cloud Platform JWT token, see Create an authentication token.

You must also specify your AppInspect authentication token and your private app installation package in the request body. For details on how to get your AppInspect authentication token, see Step 1 under Validate your private app.

You must also specify Y in the ACS-Legal-Ack: header to acknowledge your acceptance of any risks involved installing unsupported apps, as specified in the Splunk legal disclaimer for app installation, provided in the ACS OpenAPI 3.0 specification. To review the disclaimer, see Set up the ACS API.

For example:

curl -X POST 'https://admin.splunk.com/{stack}/adminconfig/v2/apps' \
--header 'Authorization: Bearer eyJraWQiOiJzcGx1bmsuc2VjcmV0IiwiYWxnI…' \
--header 'ACS-Legal-Ack: Y' \
--form 'token=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9…' \
--form 'package=@"/Users/{name}/app_inspect/testapp.tar.gz"'

The request output shows "status": "installed" when app installation successfully completes. If the request output shows "status": "uploaded", this means the app has been successfully uploaded, but app installation is still in-progress due to the asynchronous app installation process. For example:

{
   "label": "pa1",
   "name": "pa1",
   "package": "pa1-1.0.31.tar.gz",
   "status": "installed",
   "version": "1.0.31"
}

ACS app installation occurs in an eventually consistent manner, so you might experience a brief delay before an app becomes fully functional.

When you install an app using the ACS API on Classic Experience, the app is installed on the default regular search head (sh1) or search head cluster only. ACS does not support private app installation on premium search heads.

View installed apps

To view a list of installed apps on your deployment, send an HTTP GET request to the apps endpoint. For example:

curl 'https://admin.splunk.com/{stack}/adminconfig/v2/apps?count=100' \
--header 'Authorization: Bearer eyJraWQiOiJzcGx1bmsuc2VjcmV0IiwiYWxnI…'

By default, the list apps request returns a maximum count of 30 apps. To change the count, you can specify a count value up to a maximum of 100. A count value of 0 lists all apps.

If you have more than 100 apps, you can specify an offset value to list additional apps. For example, to list apps 100-200, specify an offset value of 100. For example:

curl 'https://admin.splunk.com/{stack}/adminconfig/v2/apps?offset=100&count=100'

For endpoint details, see apps in the ACS endpoint reference.

Describe an app

To view details of an individual app, send an HTTP GET request to the apps/{app_name} endpoint, specifying the name of the app and the Splunk Cloud Platform JWT token. For example:

curl 'https://admin.splunk.com/{stack}/adminconfig/v2/apps/{app_name}' \
--header 'Authorization: Bearer eyJraWQiOiJzcGx1bmsuc2VjcmV0IiwiYWxnI…'

The request returns information about the specific app, including the app installation status. When app installation successfully completes, the request output shows "status": "installed". For example:

{
   "label": "",
   "name": "",
   "package": "pa1-1.0.31.tar.gz",
   "status": "installed",
   "version": "1.0.31"
}

If the request returns "code": "404-app-not-found", app installation is still in progress due to the asynchronous app installation process.

Uninstall an app

To uninstall an app, send an HTTP DELETE request to the apps{app_name} endpoint, specifying the name of the app and the Splunk Cloud Platform JWT token. For example, to delete the app "testapp":

curl -X DELETE 'https://admin.splunk.com/{stack}/adminconfig/v2/apps/testapp' \
--header 'Authorization: Bearer eyJraWQiOiJzcGx1bmsuc2VjcmV0IiwiYWxnI…'

For endpoint details, see apps/{app_name} in the ACS endpoint reference.

Related answers from Splunk Community

Manage private apps in Splunk Cloud Platform

Requirements

Set up the ACS API

Determine the correct ACS API endpoints for your Splunk Cloud Platform Experience

Manage private apps using the ACS API on Victoria Experience

Validate your private app

Install an app

View installed apps

Describe an app

Uninstall an app

Manage private apps using the ACS API on Classic Experience

Validate your private app

Install an app on Classic Experience

View installed apps

Describe an app

Uninstall an app

Comments

Manage private apps in Splunk Cloud Platform

Was this topic useful?