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.

You can also install and manage private apps using the Splunk Web UI. For more information, including details on app installation behavior and how lookups work in Splunk Cloud Platform, see Manage private apps on your Splunk Cloud Platform deployment in the Splunk Cloud Platform Admin Manual.

Requirements

To manage private apps 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.
• You must have Splunk Cloud Platform version 8.2.2109 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.

If you plan to integrate ACS app management into your CI/CD pipeline, make sure to store your Splunk credentials (username and password) securely. To do so, you can integrate a solution such as Vault, which uses token authentication to protect your confidential data. See See https://docs.gitlab.com/ee/ci/secrets in GitLab CI/CD documentation.

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 for app management, 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:

• Manage private apps using the ACS API on Victoria Experience
• Manage private apps using the ACS API on Classic Experience

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.

ACS supports app management operations (install, view, describe, uninstall) on premium search heads, such as those running Enterprise Security or ITSI, in Victoria Experience only. ACS does not support app management operations on premium search heads in Classic Experience.

When you install an app in Victoria Experience, by default the app is installed on all search heads across the Splunk Cloud Platform deployment. You cannot install apps on individual search heads in Victoria Experience using either the ACS API or Splunk Web UI. For more information, see How self-service app installation works in Victoria 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.

1. 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.
2. 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. 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"'
   

   As of version 9.0.2205, the 'included_tags=private_app' parameter is no longer required when sending POST requests to the app/validate endpoint.

   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"
          }
      ]
   }
   

3. Check the status of your app validation request. To do so, send a GET request to /app/validate/status/{request_id}?included_tags=private_victoria, 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.
4. Retrieve the app validation report. To do so, send a GET request to /app/report/{request_id}?included_tags=private_victoria, 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.

   When sending GET requests to the app/validate/status/{request_id} or app/report/{request_id} endpoints, if you do not specify the query parameter ?included_tags=private_victoria, the request will return extraneous results.

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. You must also specify your Splunk Cloud JWT token in the Authorization: Bearer header, and you must specify your app installation package in the request body.

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.

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": ""
       }
   ]
}

You can also view installed apps using the Splunk Web UI. For more information, see Install a private app on Classic 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. This is supported 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.

1. 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.
2. Submit your app package to AppInspect for validation. 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"'
   

   As of version 9.0.2205, the 'included_tags=private_app' parameter is no longer required when sending POST requests to the app/validate endpoint.

   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"
          }
      ]
   }
   

3. Check the status of your app validation request. To do so, send a GET request to /app/validate/status/{request_id}?included_tags=private_classic, 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
4. Retrieve your app validation report. To do so, send a GET request to the /app/report/{request_id}?included_tags=private_classic, 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.

   When sending GET requests to the app/validate/status/{request_id} or app/report/{request_id} endpoints, if you do not specify the query parameter ?included_tags=private_classic, the request will return extraneous results.

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, your AppInspect authentication token (which authenticates the app is approved), and your private app installation package.

When you install a private app, you must also specify the ACS-Legal-Ack: Y parameter to acknowledge your acceptance of any risks involved with the installation of unsupported apps on your system, as specified in the Splunk legal disclaimer for app installation, which is 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.

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…' 

The request returns a list of apps installed on your deployment.

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.