How-To: Packaging

Table of Contents

Overview

Splunk Modules, Add-ons, and Apps are designed to be distributed to other Splunk instances in as simple and platform-agnostic a way as possible.

Reading this How-To can help you to correctly package your app or add-on.

'Splunk App Components' shows the technologies and component parts that make up an app or add-on, including the required directory structure.

Modules

In general, modules should not be distributed as stand-alone packages. Modules should be encapsulated in apps or add-ons to facilitate distribution using Splunkbase.

That said, it is helpful to understand exactly how to package a module for distribution. For more information on modules, review 'what is a module?'.

Structure

This describes the module/ directory structure. In general, including files in a module that are not specified here is not recommended.

/<app_or_add-on_name>/appserver/modules/<module_name>
  • The module root - <module_name> should be descriptive and unique.
  • Example: /webintelligence/appserver/modules/HiddenSearchSwapper/
/<app_or_add-on_name>/appserver/modules/<module_name>/<module_name>.conf
  • The module configuration file (REQUIRED).
  • Failure to include a module configuration file results in the module failing to load.
  • See the module .conf spec for details.
  • Example: /webintelligence/appserver/modules/HiddenSearchSwapper/HiddenSearchSwapper.conf
/<app_or_add-on_name>/appserver/modules/<module_name>/<module_name>.css
  • The module CSS file (OPTIONAL).
  • Include a module CSS file for styles that should be scoped to the module.
  • Example: /webintelligence/appserver/modules/HiddenSearchSwapper/HiddenSearchSwapper.css
/<app_or_add-on_name>/appserver/modules/<module_name>/<module_name>.html
  • The module Mako Template file (OPTIONAL).
  • Include a template file if the module should render some HTML content by default.
  • Example: /webintelligence/appserver/modules/HiddenSearchSwapper/HiddenSearchSwapper.html
/<app_or_add-on_name>/appserver/modules/<module_name>/<module_name>.js
  • The module JavaScript file (REQUIRED).
  • Failure to include a module JavaScript file results in a JavaScript loading error.
  • Example: /webintelligence/appserver/modules/HiddenSearchSwapper/HiddenSearchSwapper.js
/<app_or_add-on_name>/appserver/modules/<module_name>/<module_name>.py
  • The module controller file (OPTIONAL).
  • Include a module controller file if the module must perform some custom rendering function.
  • Example: /webintelligence/appserver/modules/HiddenSearchSwapper/HiddenSearchSwapper.py
 

Module .conf

The module configuration file format is defined as follows:

[module]
className=Splunk.Module.<module_name> (REQUIRED)
superClass=<module that was super classed> (OPTIONAL)
description=<some descriptive text> (OPTIONAL)
    
[param:<param_name>]
required = {Boolean} If True, param must be specified for module in view XML (REQUIRED)
default = {String} The default value for this param (OPTIONAL)
label = {String} Some descriptive text about the param (OPTIONAL)
values = {String} Comma separated list of allowed values for the param (OPTIONAL)

Example module configuration file:

[module]
className = Splunk.Module.HiddenSearchSwapper
superClass = Splunk.Module
description = Given the time range selected by time range picker, adjusts the context's search

[param:rangeMap]
required = True
label = Use this to specify a list of searches and time ranges associated with them

### EXAMPLE CONFIG
#
# <module name="HiddenSearchSwapper">
#   <param name="rangeMap">
#     <param name="default">
#       <param name="search">index=main fiz=baz</param>
#     </param>
#     <param name="rt">
#       <param name="search">index=main foo=bar</param>
#     </param>
#     <param name="1d">
#       <param name="search">index=summary marker=search1</param>
#     </param>
#     <param name="1w">
#       <param name="savedsearch">my cool saved search that actually exists</param>
#     </param>
#     <param name="1m">
#       <param name="search">index=summary marker=search3</param>
#     </param>
#   </param>
# </module>

Apps & Add-ons

Packaging apps and add-ons should be a straightforward experience. For more information about add-ons, review 'what is an addon?' and 'what is an app?'. Additionally, consider reading through the core Splunk app and add-on packaging information documentation.

Structure

NB: Apps and add-ons must NEVER be packaged inside other apps and add-ons. Apps can have dependencies on add-ons, but never to the extent that they are packaged inside another app or add-on.

To handle dependencies, use one of the following methods :

  • Merge dependencies from add-ons into the app package.
    • For example, if your app requires the props.conf and transforms.conf from a supporting add-on, consider merging the contents of those files into your app props.conf and transforms.conf files.
  • Document the dependencies to inform administrators of them when they install and configure your app.

In general, it is recommended that you do not include custom directories or files.

One exception is to use an <app_or_add-on_name>.conf custom configuration file. By following this convention, inter-app configuration namespace collisions are easier to avoid.

The app or add-on directory structure is defined as follows:

/<app_or_add-on_name>
  • The app or add-on root:
    • <app_or_add-on_name> should be short and unique.
    • Example: /webintelligence
/<app_or_add-on_name>/appserver
  • The app or add-on appserver directory:
    • Only required if the app or add-on includes UI components.
    • Example: /webintelligence/appserver
/<app_or_add-on_name>/appserver/controllers
  • The app or add-on custom controllers directory:
    • Only required if the app or add-on includes custom controllers.
    • Example: /webintelligence/appserver/controllers
/<app_or_add-on_name>/appserver/modules
  • The app or add-on custom modules directory:
    • Only required if the app or add-on includes custom modules.
    • Example: /webintelligence/appserver/modules
/<app_or_add-on_name>/appserver/static
  • The app or add-on static content directory:
    • Only required if the app or add-on includes custom static content.
    • Example: /webintelligence/appserver/static
/<app_or_add-on_name>/appserver/templates
  • The app or add-on custom templates directory:
    • Only required if the app or add-on includes custom templates.
    • Example: /webintelligence/appserver/templates
/<app_or_add-on_name>/bin
  • The app or add-on custom scripts directory:
    • Only required if the app or add-on includes scripted inputs or search commands.
    • Example: /webintelligence/bin
/<app_or_add-on_name>/default
  • The app or add-on configuration file directory:
    • All apps and add-ons require /default and /default/app.conf.
    • Example: /webintelligence/default
/<app_or_add-on_name>/default/data/ui/nav
  • The app or add-on navigation XML directory:
    • Only required if the app or add-on exposes views.
    • The NavBar module consumes the app or add-on navigation file to render the navigation menu.
    • An app can only have one navigation file, and it must be named default.xml.
    • Example: /webintelligence/default/data/ui/nav
/<app_or_add-on_name>/default/data/ui/views
  • The app or add-on view XML directory:
    • Only required if the app or add-on exposes views.
    • Each view exposed by the app or add-on is described by the XML in <view_name>.xml.
    • Example: /webintelligence/default/data/ui/views
/<app_or_add-on_name>/lookups
  • The app or add-on lookups directory:
    • Only required if the app or add-on includes default lookup files.
    • The lookup directory should only include non-mutable lookups.
    • Example: /webintelligence/lookups
/<app_or_add-on_name>/metadata
  • The app or add-on metadata directory:
    • Should only include default.meta.
    • Example: /webintelligence/metadata
 

app.conf

All apps and add-ons must include /default/app.conf. Moreover, there are a number of required and optional values within app.conf to consider.

The core Splunk documentation for app.conf provides the defacto reference document for required and optional stanzas, keys, and values.

If using SplunkBase as the primary repository for apps, the following app.conf requirements must be met for each app iteration:

  • Each app must contain a universally unique "id" key under the "package" stanza
  • Each subsequent iteration of an app must contain:
    • an incremented "version" key under the "launcher" stanza
    • an incremented "build" key under the "install" stanza

For example, the first iteration of an app might have the following in default/app.conf:

    [ui]
    is_visible = 1
    label = my_app

    [install]
    author=araitz
    description=This is a cool app
    build = 1

    [launcher]
    version = 1.0

Subsequent iterations of this app that are uploaded to Splunkbase must have an incremented "build" number greater than 1 as well as a different version number (e.g 1.0.1, 1.1, 2.0, etc).

On that note, it is a good practice to decide on a version standard prior to the initial release of an app. In most cases, a major-minor system will suffice:

  • Major release (e.g. 1.0, 2.0, 3.0, etc)
    • Major releases are reserved for major milestones of or changes to the app
  • Minor release (e.g 1.1, 1.2, 1.3, etc)
    • Minor releases are reserved for bug fixes or cosmetic changes to the app

It cannot be emphasized enough how important the "id" of an app is, and subsequently how important it is to pick the right "id" initially. In the world of Splunk and Splunkbase, changing an app's "id" is tantamount to creating an entirely new app, and comes with several unpleasant headaches when trying to inform or migrate users of the previous app "id". Changing an "id" is thus not recommended.

Finally, keep in mind that any changes made to an app's default configuration file values will not be effective if the values are present in the app's local configuration files.

For example, the following setting exists in default/inputs.conf:

    [monitor:///my_app/my_file]
    sourcetype=my_special_sourcetype

During the course of normal operations, a Splunk administrator sets the following in local/inputs.conf:

    [monitor:///my_app/my_file]
    sourcetype=my_special_sourcetype
    host=special_host

If the sourcetype definition in default/inputs.conf changes in a subsequent iteration of the app, the change will not be respected due to Splunk's order of precedence.

 

Distribution

To upload your app or add-on to Splunkbase, a few more steps are needed to create a complete package that passes the upload validation process to be fully ready for distribution.

Screenshot & Icon

Apps and add-ons can be packaged with a screenshot and an icon. Although not strictly required, including a screenshot and an icon are highly recommended.

The screenshot gives Splunkbase users a preview of the app or add-on's look and feel before they download. During the upload process, Splunkbase will extract the screenshot file from the app and use it on the app or add-on's download page.

To include a screenshot, place a 623px x 350px PNG image in the following location:


/<app_or_add-on_name>/appserver/static/screenshot.png

Upon upload, Splunkbase will attempt to re-size the provided image if it does not precisely match the above dimensions. For best results, make sure the image size is in the 98:55 ratio and do not include browser chrome in your image.

The app icon can be used to represent a particular author, technology, or brand. The icon will appear in Splunk's built-in launcher app next to the app or add-on name and description as well as next to the app or add-on name on Splunkbase.

To include an icon, place a 35 x 35 PNG image in the following location:


/<app_or_add-on_name>/appserver/static/appicon.png

The app icon for Web Intelligence as viewed from the launcher app:

Package Format

Splunkbase requires that all submitted packages are compressed tarballs with the file suffix '.spl'.

> tar -zcv /my_app > my_app.tgz > mv my_app.tgz my_app.spl

See 'package your app or add on' in the core Splunk documentation for additional details.

 

At this point, your app or add-on should be good to go! Upload your app to Splunkbase, have a beer, and bask in your own glory.