Splunk Cloud Platform

Admin Config Service Manual

Acrobat logo Download manual as PDF


This documentation does not apply to the most recent version of SplunkCloud. Click here for the latest version.
Acrobat logo Download topic as PDF

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 and higher

If your Splunk Cloud Platform account is in an AWS region, it must be enabled with the proper certificate. To have your account enabled, contact Splunk Support. If your account is in a Google Cloud region, it does not need to be enabled.

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 set up the ACS API for HEC token 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:

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.

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 send requests to AppInspect. See Authenticate with the Splunk API service.
  2. Submit your app package to AppInspect for validation. You must specify 'included_tags=cloud,self-service' (no space between the tags). 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=cloud,self-service'
    

    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. Use the "request ID" to check the status of the validation process. If your app is approved, you can proceed with app installation using ACS. If the app fails AppInspect validation, check the app validation report to determine the cause of the failure.
  4. Use the "request ID" to retrieve your app validation report. You can also retrieve your report using the Splunk Web UI. For information on how to manage private apps using Splunk Web, see Manage private apps on your Splunk Cloud Platform deployment.

    If your report shows a value greater than zero for Manual Checks, you cannot use ACS to install your app. You must instead open a support ticket to have your app installed by Splunk Support.

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

Install an app

To install an app, send an HTTP POST request to the apps/victoria endpoint, specifying your AppInspect authentication token in the X-Splunk-Authorization header (which authenticates that the app is approved), your Splunk Cloud JWT token in the Authorization header, 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 in 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/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 confirm that your app is installed using the Splunk Web UI. For information on managing private apps in Splunk Web, 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.

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. 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"
           }
       ]
    }
    
  3. Use the "request ID" to check the status of the validation process. If your app is approved, you can proceed with app installation using ACS. If the app fails AppInspect validation, check the app validation report to determine the cause of the failure.
  4. Use the "request ID" to retrieve your app validation report. You can also retrieve your report using the Splunk Web UI. For more information, see Manage private apps on your Splunk Cloud Platform Deployment.

    If your report shows a value greater than zero for Manual Checks, you cannot use ACS to install your app. You must instead open a support ticket to have your app installed by Splunk Support.

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

Install an app

To install an app, 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.

Last modified on 19 August, 2022
PREVIOUS
Manage indexes 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.2109, 8.2.2111


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