# salt.pillar.file_tree

The `file_tree` external pillar allows values from all files in a directory tree to be imported as Pillar data.

Note

This is an external pillar and is subject to the rules and constraints governing external pillars.

Added in version 2015.5.0.

In this pillar, data is organized by either Minion ID or Nodegroup name. To setup pillar data for a specific Minion, place it in `<root_dir>/hosts/<minion_id>`. To setup pillar data for an entire Nodegroup, place it in `<root_dir>/nodegroups/<node_group>` where `<node_group>` is the Nodegroup's name.

## Example `file_tree` Pillar

### Master Configuration

    ext_pillar:
      - file_tree:
          root_dir: /srv/ext_pillar
          follow_dir_links: False
          keep_newline: True

The `root_dir` parameter is required and points to the directory where files for each host are stored. The `follow_dir_links` parameter is optional and defaults to False. If `follow_dir_links` is set to True, this external pillar will follow symbolic links to other directories.

Warning

Be careful when using `follow_dir_links`, as a recursive symlink chain will result in unexpected results.

Changed in version 2018.3.0: If `root_dir` is a relative path, it will be treated as relative to the `pillar_roots` of the environment specified by `pillarenv`. If an environment specifies multiple roots, this module will search for files relative to all of them, in order, merging the results.

If `keep_newline` is set to `True`, then the pillar values for files ending in newlines will keep that newline. The default behavior is to remove the end-of-file newline. `keep_newline` should be turned on if the pillar data is intended to be used to deploy a file using `contents_pillar` with a `file.managed` state.

Changed in version 2015.8.4: The `raw_data` parameter has been renamed to `keep_newline`. In earlier releases, `raw_data` must be used. Also, this parameter can now be a list of globs, allowing for more granular control over which pillar values keep their end-of-file newline. The globs match paths relative to the directories named for minion IDs and nodegroups underneath the `root_dir` (see the layout examples in the below sections).

    ext_pillar:
      - file_tree:
          root_dir: /path/to/root/directory
          keep_newline:
            - files/testdir/*

Note

In earlier releases, this documentation incorrectly stated that binary files would not affected by the `keep_newline` configuration. However, this module does not actually distinguish between binary and text files.

Changed in version 2017.7.0: Templating/rendering has been added. You can now specify a default render pipeline and a black- and whitelist of (dis)allowed renderers.

`template` must be set to `True` for templating to happen.

    ext_pillar:
      - file_tree:
        root_dir: /path/to/root/directory
        render_default: jinja|yaml
        renderer_blacklist:
          - gpg
        renderer_whitelist:
          - jinja
          - yaml
        template: True

### Assigning Pillar Data to Individual Hosts

To configure pillar data for each host, this external pillar will recursively iterate over `root_dir`/hosts/`id` (where `id` is a minion ID), and compile pillar data with each subdirectory as a dictionary key and each file as a value.

For example, the following `root_dir` tree:

    ./hosts/
    ./hosts/test-host/
    ./hosts/test-host/files/
    ./hosts/test-host/files/testdir/
    ./hosts/test-host/files/testdir/file1.txt
    ./hosts/test-host/files/testdir/file2.txt
    ./hosts/test-host/files/another-testdir/
    ./hosts/test-host/files/another-testdir/symlink-to-file1.txt

will result in the following pillar tree for minion with ID `test-host`:

    test-host:
        ----------
        apache:
            ----------
            config.d:
                ----------
                00_important.conf:
                    <important_config important_setting="yes" />
                20_bob_extra.conf:
                    <bob_specific_cfg has_freeze_ray="yes" />
        corporate_app:
            ----------
            settings:
                ----------
                common_settings:
                    // This is the main settings file for the corporate
                    // internal web app
                    main_setting: probably
                bob_settings:
                    role: bob

Note

The leaf data in the example shown is the contents of the pillar files.

salt.pillar.file_tree.ext_pillar(minion_id, pillar, root_dir=None, follow_dir_links=False, debug=False, keep_newline=False, render_default=None, renderer_blacklist=None, renderer_whitelist=None, template=False)

  Compile pillar data from the given `root_dir` specific to Nodegroup names and Minion IDs.

  If a Minion's ID is not found at `<root_dir>/host/<minion_id>` or if it is not included in any Nodegroups named at `<root_dir>/nodegroups/<node_group>`, no pillar data provided by this pillar module will be available for that Minion.

  Changed in version 2017.7.0: Templating/rendering has been added. You can now specify a default render pipeline and a black- and whitelist of (dis)allowed renderers.

  `template` must be set to `True` for templating to happen.

      ext_pillar:
        - file_tree:
          root_dir: /path/to/root/directory
          render_default: jinja|yaml
          renderer_blacklist:
            - gpg
          renderer_whitelist:
            - jinja
            - yaml
          template: True

  Parameters:

    - minion_id -- The ID of the Minion whose pillar data is to be collected

    - pillar -- Unused by the `file_tree` pillar module

    - root_dir --

      Filesystem directory used as the root for pillar data (e.g. `/srv/ext_pillar`)

      Changed in version 2018.3.0: If `root_dir` is a relative path, it will be treated as relative to the `pillar_roots` of the environment specified by `pillarenv`. If an environment specifies multiple roots, this module will search for files relative to all of them, in order, merging the results.

    - follow_dir_links --

      Follow symbolic links to directories while collecting pillar files. Defaults to `False`.

      Warning

      Care should be exercised when enabling this option as it will follow links that point outside of `root_dir`.

      Warning

      Symbolic links that lead to infinite recursion are not filtered.

    - debug -- Enable debug information at log level `debug`. Defaults to `False`. This option may be useful to help debug errors when setting up the `file_tree` pillar module.

    - keep_newline --

      Preserve the end-of-file newline in files. Defaults to `False`. This option may either be a boolean or a list of file globs (as defined by the Python fnmatch package) for which end-of-file newlines are to be kept.

      `keep_newline` should be turned on if the pillar data is intended to be used to deploy a file using `contents_pillar` with a `file.managed` state.

      Changed in version 2015.8.4: The `raw_data` parameter has been renamed to `keep_newline`. In earlier releases, `raw_data` must be used. Also, this parameter can now be a list of globs, allowing for more granular control over which pillar values keep their end-of-file newline. The globs match paths relative to the directories named for Minion IDs and Nodegroup namess underneath the `root_dir`.

          ext_pillar:
            - file_tree:
                root_dir: /srv/ext_pillar
                keep_newline:
                  - apache/config.d/*
                  - corporate_app/settings/*

      Note

      In earlier releases, this documentation incorrectly stated that binary files would not affected by the `keep_newline`. However, this module does not actually distinguish between binary and text files.

    - render_default --

      Override Salt's `default global renderer` for the `file_tree` pillar.

          render_default: jinja

    - renderer_blacklist --

      Disallow renderers for pillar files.

          renderer_blacklist:
            - json

    - renderer_whitelist --

      Allow renderers for pillar files.

          renderer_whitelist:
            - yaml
            - jinja

    - template -- Enable templating of pillar files. Defaults to `False`.