cdillc.splunk.splunk_rest_conf module – Manage adhoc configurations via the Splunk REST API

Note

This module is part of the cdillc.splunk collection (version 0.26.1).

It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install cdillc.splunk. You need further requirements to be able to use this module, see Requirements for details.

To use it in a playbook, specify: cdillc.splunk.splunk_rest_conf.

New in cdillc.splunk 0.10.0

Synopsis

  • Manage the content of Splunk .conf files via Ansible.

  • This module uses the Python Splunk SDK to fetch and modify configuration settings via the Splunk REST endpoint of a running splunkd service.

  • Authentication can be handled via either username and password or via token.

Requirements

The below requirements are needed on the host that executes this module.

  • splunk-sdk

Parameters

Parameter

Comments

app

string

The Splunk “app” (namespace) where the stanza lives or will be created.

The special value of system can be used to indicate no app association.

conf

string / required

The configuration type to manage or view.

The list of choices provided here are for reference only and are not enforced by the module.

Any value supported by the underling Splunk SDK / REST API should work.

Choices:

  • "server"

  • "props"

  • "transforms"

  • "macros"

defaults

string

The dictionary of key/values to push into a newly created stanza.

Use this to set stanza defaults that you do not want to override on subsequent runs.

The defaults option is only used when state=present and a new stanza is created.

If a new stanza is created, the result output will contain the value created.

Default: {}

del_unknown

boolean

Not implemented yet!

Remove any keys in the servers configuration that are not present within the settings dictionary.

This feature does not yet exist in the code.

Currently only adding or updated keys or removing the entire stanza is supported.

Choices:

  • false ← (default)

  • true

owner

string

The Splunk owner (namespace) of the stanza.

Use the special value of nobody if no owner is desired.

The value of sharing may also impact the owner.

password

string

The password for username/password authentication.

Must be provided if username is provided.

restart_on_change

boolean

Enable an immediate splunkd restart on configuration change.

Choices:

  • false ← (default)

  • true

restart_timeout

string

Amount of time to wait for the restart to complete.

If restart_timeout is 0 then the restart wait is disabled.

settings

string

The dictionary of key/values to push into the given stanza.

The settings option must be provided when state=present.

The final value of the stanza is returned via the content output.

Default: {}

sharing

string

The Splunk sharing mode to use for stanza creation or modification.

See the note on “Splunk namespaces” below.

The default global will create entries that are placed in etc/system/local/

Choices:

  • "user"

  • "app"

  • "global" ← (default)

  • "system"

splunkd_uri

aliases: uri

string

The Splunkd endpoint of the Splunk server to configure.

Defaults to the local server and default splunkd port.

Default: "https://localhost:8089"

stanza

string / required

The stanza to edit within the given conf configuration file.

state

string

Ensure the configuration settings are either present or absent, or to list existing settings.

The content output contains the final setting.

If the state is absent, the content output will be missing if the stanza was previously removed.

Choices:

  • "present" ← (default)

  • "absent"

  • "list"

token

string

Token to use when authentication has already taken place.

The token can be specified instead of username and password.

This module returns an output named token that can be used for subsequent splunkd calls to the same splunkd endpoint.

username

string

Splunk username for username/password authentication.

When provided, password must also be specified.

Notes

Note

  • The owner, app, and sharing options determine the Splunk namespace. See http://dev.splunk.com/python#namespaces for more details.

  • Not all changes take effect immediately. Even though changes are persisted to the config quickly, like editing .conf file by hand, a splunkd restart or endpoint reload may be necessary for some changes to take effect. (The exact behavior is unknown.)

Examples

Change the minimum free disk space:

    - cdi.splunk.splunk_rest_conf:
        state: present
        username: admin
        password: "{{ secret_password }}"
        conf: server
        stanza: diskUsage
        settings:
          minFreeSpace: 3000

For comparison, here's the same (offline) change using ini_file:

    - community.general.ini_file:
        dest: "{{splunk_home}}/etc/system/local/server.conf"
        section: diskUsage
        option: minFreeSpace
        value: 3000


Here is an example of updating a Splunk license pool.  Note that the
description and quota are only set the first time the pool is created.  After
that Ansible will only update the "slaves" key.

    - splunk_rest_conf:
        splunkd_uri: "{{splunk_license_master_uri}}"
        username: "{{splunk_admin_user}}"
        password: "{{splunk_admin_pass}}"
        state: present
        conf: "server"
        stanza: lmpool:MyLicesePool
        settings:
          slaves: "{{guids}}"
          stack_id: enterprise
        defaults:
          description: NOTICE - The list of slaves is automatically updated by Ansible
          quota: 1073741824

Authors

  • Lowell C. Alleman (@lowell80)