cdillc.splunk.ksconf_app_sideload module – Unpacks a Splunk app archive after copying it from the controller machine

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.ksconf_app_sideload.

New in cdillc.splunk 0.10.0

Synopsis 

By default, it will copy the source file from the local system to the target before unpacking.
For Windows targets, switch to Linux.

Note

This module has a corresponding action plugin.

Requirements 

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

ksconf>=0.11

Parameters 

Parameter	Comments
attributes aliases: attr string	The attributes the resulting filesystem object should have. To get supported flags look at the man page for chattr on the target system. This string should contain the attributes in the same order as the one displayed by lsattr. The `=` operator is assumed as default, otherwise `+` or `-` operators need to be included in the string.
decrypt boolean	This option controls the autodecryption of source files using vault. Choices: `false` `true` ← (default)
dest path / required	Remote absolute path where the archive should be unpacked. Typically this will be `/opt/splunk/etc/apps` or a management folder like `deployment-apps`, `manager-apps` (or `master-apps` pre Splunk 9.0), or `shcluster/apps`.
group string	Name of the group that should own the filesystem object, as would be fed to chown. When left unspecified, it uses the current group of the current user unless you are root, in which case it can preserve the previous ownership.
io_buffer_size bytes	Size of the volatile memory buffer that is used for extracting files from the archive in bytes. Default: `65536`
list_files boolean added in cdillc.splunk 2.0	If set to True, return the list of files that are contained in the tarball. Choices: `false` ← (default) `true`
mode any	The permissions the resulting filesystem object should have. For those used to /usr/bin/chmod remember that modes are actually octal numbers. You must give Ansible enough information to parse them correctly. For consistent results, quote octal numbers (for example, `'644'` or `'1777'`) so Ansible receives a string and can do its own conversion from string into number. Adding a leading zero (for example, `0755`) works sometimes, but can fail in loops and some other circumstances. Giving Ansible a number without following either of these rules will end up with a decimal number which will have unexpected results. As of Ansible 1.8, the mode may be specified as a symbolic mode (for example, `u+rwx` or `u=rw,g=r,o=r`). If `mode` is not specified and the destination filesystem object does not exist, the default `umask` on the system will be used when setting the mode for the newly created filesystem object. If `mode` is not specified and the destination filesystem object does exist, the mode of the existing filesystem object will be used. Specifying `mode` is the best way to ensure filesystem objects are created with the correct permissions. See CVE-2020-1736 for further details.
owner string	Name of the user that should own the filesystem object, as would be fed to chown. When left unspecified, it uses the current user unless you are root, in which case it can preserve the previous ownership. Specifying a numeric username will be assumed to be a user ID and not a username. Avoid numeric usernames to avoid this confusion.
recreate_manifest boolean	Allow remote rebuilding of corrupted or missing manifest state data. This can be beneficial when upgrading between versions of the collection. But this may not be desirable in all situations. For example, any files not in new app will be removed, which can be problematic if you’ve intensionally created content within an app (e.g., you’ve deployed to the ‘apps’ folder of a running search head and allowed users to create/edit knowledge objects) When disabled, any app update from earlier versions will simply overwrite the current content, leaving any unknown files as-is. This means that previously deleted content will remain also means that previously delete content will not be removed, as file deletions were not supported prior to manifest support. Choices: `false` `true` ← (default)
selevel string	The level part of the SELinux filesystem object context. This is the MLS/MCS attribute, sometimes known as the `range`. When set to `_default`, it will use the `level` portion of the policy if available.
serole string	The role part of the SELinux filesystem object context. When set to `_default`, it will use the `role` portion of the policy if available.
setype string	The type part of the SELinux filesystem object context. When set to `_default`, it will use the `type` portion of the policy if available.
seuser string	The user part of the SELinux filesystem object context. By default it uses the `system` policy, where applicable. When set to `_default`, it will use the `user` portion of the policy if available.
src path / required	Local path to Splunk archive file to copy to the target server; can be absolute or relative.
state_file path	Override the default state file location. The default state file location is nested immediately under the app folder, called `.ksconf_sideload.json`. Sometimes this may not be ideal when populating `deployment-apps` where a single change could trigger a burst of traffic, or `shcluster/apps` where looking at the manifest on the SHC members is always off (because local is merged to default behavior). Be sure you understand the implications of changing this path. There must be one exactly state file per app per target, otherwise you can anticipate “flapping” between states as app deployment executes.
unsafe_writes boolean	Influence when to use atomic operation to prevent data corruption or inconsistent reads from the target filesystem object. By default this module uses atomic operations to prevent data corruption or inconsistent reads from the target filesystem objects, but sometimes systems are configured or just broken in ways that prevent this. One example is docker mounted filesystem objects, which cannot be updated atomically from inside the container and can only be written in an unsafe manner. This option allows Ansible to fall back to unsafe methods of updating filesystem objects when atomic operations fail (however, it doesn’t force Ansible to perform unsafe writes). IMPORTANT! Unsafe writes are subject to race conditions and can lead to data corruption. Choices: `false` ← (default) `true`

Attributes 

Attribute	Support	Description
action	Support: full	Indicates this has a corresponding action plugin so some parts of the options can be executed on the controller
async	Support: none	Supports being used with the `async` keyword
bypass_host_loop	Support: none	Forces a ‘global’ task that does not execute per host, this bypasses per host templating and serial, throttle and other loop considerations Conditionals will work as if `run_once` is being used, variables used will be from the first available host This action will not work normally outside of lockstep strategies
check_mode	Support: none	Can run in check_mode and return changed status prediction without modifying target
diff_mode	Support: str	Will return details on what has changed (or possibly needs changing in check_mode), when in diff mode
platform	Platform: posix	Target OS/families that can be operated against
safe_file_operations	Support: none	Uses Ansible’s strict file operation functions to ensure proper permissions and avoid data corruption
vault	Support: full	Can automatically decrypt Ansible vaulted files

Notes 

Note

Requires ksconf package on controller and target host.
Can handle .tgz, .tar.gz, .spl, and .zip files.
Existing files/directories in the destination which are not in the archive are removed. This requires that the prior app installation include a manifest. This feature was added in v0.18 of this collection; and all hash calculations have changed.
Note that only files are extracted. This means empty directories will not be created. If this cause an issue for you, open a bug report and describe your use case.
Too speed up subsequent calls to ksconf_app_sideload, manifest files are created and cached on the controller node in the same directory as src. This reduces the controller’s processing overhead. For this speedup to work, the controller must have write access to the parent directory of src. Also, any tarball created with ksconf_package will already have this manifest file.

Examples 

- name: Extract ta-nix.tgz into /opt/splunk/etc/apps
  cdillc.splunk.ksconf_app_sideload:
    src: ta-nix.tgz
    dest: /opt/splunk/etc/apps

- name: Install rendered apps from version control & existing tarballs
    cdillc.splunk.ksconf_app_sideload:
      # Add prefix for archived apps
      src: "{{ apps_folder }}/{{ item }}"
      dest: "{{ splunk_home }}/etc/deployment-apps"
      owner: "{{ splunk_nix_user }}"
      group: "{{ splunk_nix_group }}"
    # Loop over present + managed apps created from (1) ksconf_package and (2) existing tarballs
    loop: >
      {{ app_render_output.results
        | selectattr("archive")
        | selectattr("item.state", "eq", "present")
        | selectattr("item.managed")
        | map(attribute="archive")
        + apps_inventory
        | selectattr("tarball")
        | selectattr("state", "eq", "present")
        | selectattr("managed")
        | map(attribute="tarball")
      }}
    become: true
    become_user: "{{ splunk_nix_user }}"
    notify: "reload deployment-server"
    tags: install'

Return Values 

Common return values are documented here, the following are the fields unique to this module:

Key	Description
dest string	Path to the destination directory. Returned: always Sample: `"/opt/software"`
files list / elements=string	List of all the files in the archive. Returned: When list_files is True Sample: `["[\"file1\"", " \"file2\"]"]`
gid integer	Numerical ID of the group that owns the destination directory. Returned: always Sample: `1000`
group string	Name of the group that owns the destination directory. Returned: always Sample: `"librarians"`
mode string	String that represents the octal permissions of the destination directory. Returned: always Sample: `"0755"`
owner string	Name of the user that owns the destination directory. Returned: always Sample: `"paul"`
src string	The source archive’s path. The location is local to the ansible controller. Returned: always Sample: `"/home/paul/test.tar.gz"`
state string	State of the destination. Effectively always “directory”. Returned: always Sample: `"directory"`
state_file string	Path to the json state tracking file where installation state, source hash, and application manifest is stored. By default, this is relative to the app install path. Returned: always Sample: `"fire_brigade/.ksconf_sideload.json"`
uid integer	Numerical ID of the user that owns the destination directory. Returned: always Sample: `1000`

Authors

Lowell C. Alleman (@lowell80)

cdillc.splunk.ksconf_app_sideload module – Unpacks a Splunk app archive after copying it from the controller machine

Synopsis

Requirements

Parameters

Attributes

Notes

Examples

Return Values

Authors

Collection links

Synopsis 

Requirements 

Parameters 

Attributes 

Notes 

Examples 

Return Values 