Welcome to Ansible hieradata documentation!

Ansible Hieradata

This collection provides plugins to manage your project configuration data in a hierarchical manner like puppet do.

Installation

The collection is available via Ansible Galaxy. So you can run

ansible-galaxy collection install codeaffen.hieradata

Alternatively you can build and install the collection from source.

make dist
ansible-galaxy collection install codeaffen-hieradata-<version>.tar.gz

Configuraton

vars plugin configuration

The plugin comes with useful defaults to start to use the hieradata vars plugin without any configuration.

But if you need to customize the configuration you can see in documentation you can configure the vars plugin eigther via ansible.cfg parameter in section hieradata or via environment variables.

You have to keep in mind that the paths for basedir and config are relative to your inventory or playbook directory, depending of the selected stage. Without any configuration you have to place the basedir and config as followed.

.
├── ansible.cfg
├── hieradata
├── hieradata.yml
└── hosts

If you want to use a different base then hieradata you can override it by exporting HIERADATA_BASE_DIR environment variable. This directory also has to belongs to inventory dirctory.

.
├── ansible.cfg
└── inventory
    ├── hieradata
    │   └── customer_a
    ├── hieradata.yml
    └── hosts

In this example you need to do export HIERADATA_BASE_DIR=hieradata/customer_a if you want to use hieradata/customer_a as hiera basedir.

Documentation

readthedocs.io

Current documentation can be found on readthedocs.io.

repository folder

A last option to read the docs is the docs folder in this repository.

Dependencies

The following dependencies have to be fulfiled by the Ansible controller.

• …

Need help?

If you’ve found any issues in this release please head over to github and open a bug so we can take a look.

codeaffen.hieradata Release Notes

v0.1.0

Minor Changes

• Add a wrapper function combine_vars to be compatible to default ansible.

• Add configuration parameters to manage hash and list behavior.

• Add method to parse configuration file (e.g. hieradata.yml).

• After loading, the vars will be combined with ansible functions.

• Change parameter names. Remove prefix to make documentation more clear.

• If last part is directory it can have no, one or multiple files in it.

• Last part of hierarchy can be file or directory.

• Load files from hierarchy.

• Parse entity name into hiera_vars dict.

• The hiera_vars dict can be used to generate a dynamic hierarchy.

• These function tages two extra parameters hash_behavior and list_behavior to configure this feature as needed.

v0.0.1

New Plugins

Vars

• codeaffen.hieradata.hieradata - Loads configuration from a hierarchical configuration structure structure

Codeaffen.Hieradata

Collection version 0.1.0

Plugin Index

These are the plugins in the codeaffen.hieradata collection

Lookup Plugins

• list – simply returns what it is given.

• lookup – prints debug text

Vars Plugins

• hieradata – Loads configuration from a hierarchical configuration structure

See also

List of collections with docs hosted here.

codeaffen.hieradata.list – simply returns what it is given.

Note

This plugin is part of the codeaffen.hieradata collection (version 0.1.0).

To install it use: ansible-galaxy collection install codeaffen.hieradata.

To use it in a playbook, specify: codeaffen.hieradata.list.

New in version 0.0.2: of codeaffen.hieradata

Synopsis

• this is mostly a noop, to be used as a with_list loop when you dont want the content transformed in any way.

Examples

- name: unlike with_items you will get 3 items from this loop, the 2nd one being a list
  debug: var=item
  with_list:
    - 1
    - [2,3]
    - 4

Return Values

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

Key	Returned	Description
_list list / elements=any	success	basically the same as you fed in

Authors

• Christian Meißner <cme+codeaffen@meissner.sh>

codeaffen.hieradata.lookup – prints debug text

Note

This plugin is part of the codeaffen.hieradata collection (version 0.1.0).

To install it use: ansible-galaxy collection install codeaffen.hieradata.

To use it in a playbook, specify: codeaffen.hieradata.lookup.

New in version 0.0.2: of codeaffen.hieradata

Synopsis

• This lookup returns nothing but a text to stderr

Authors

• Christian Meißner <cme+codeaffen@meissner.sh>

codeaffen.hieradata.hieradata – Loads configuration from a hierarchical configuration structure

Note

This plugin is part of the codeaffen.hieradata collection (version 0.1.0).

To install it use: ansible-galaxy collection install codeaffen.hieradata.

To use it in a playbook, specify: codeaffen.hieradata.hieradata.

New in version 0.0.1: of codeaffen.hieradata

Synopsis

• Loads YAML vars into corresponding hierarchy directories/files.

• Loads only files with extension to one of .yaml, .json, .yml or no extension.

• Starting in 0.0.1, this plugin requires explicit whitelisting via vars_plugins_enabled.

Requirements

The below requirements are needed on the local controller node that executes this vars.

• whitelist in configuration

Parameters

Parameter	Choices/Defaults	Configuration	Comments
_valid_extensions list / elements=string	Default: [".yml", ".yaml", ".json"]	ini entries: [yaml_valid_extensions] defaults = ['.yml', '.yaml', '.json'] env:ANSIBLE_YAML_FILENAME_EXT	Check all of these extensions when looking for 'variable' files which should be YAML or JSON or vaulted versions of these. This affects vars_files, include_vars, inventory and vars plugins among others.
basedir string	Default: "hieradata"	ini entries: [hieradata] basedir = hieradata env:HIERADATA_BASE_DIR	The base directory where the hierarchy has to be placed in. The base directory has to be placed within the inventory directory or playbook directory.
config string	Default: "hieradata.yml"	ini entries: [hieradata] config = hieradata.yml env:HIERADATA_CONFIG_FILE	Name of hieradata configuration file. The hieradata configuration file has to be placed within the inventory dirctory or playbook directory.
hash_behavior string	Choices: merge ← replace	ini entries: [hieradata] hash_behavior = merge env:HIERADATA_HASH_BEHAVIOR	This setting defines how hashes will be merged. By default hieradata will merge hashes, so data only exists in higher precedence will be added to the data with lower precedence. Higher precedence value will override lower precedence values. You can define replace if you want to override data with lower precedence.
list_behavior string	Choices: append append_rp keep prepend prepend_rp replace ←	ini entries: [hieradata] list_behavior = replace env:HIERADATA_HASH_BEHAVIOR	This setting defines how lists will be handled. By default data with higher precedence will `replace` data with lower precedence. You can also append or prepend data with higher precedence. With replace you can override data with lower precedece by data with higher one.
stage string added in 2.10 of ansible.builtin	Choices: all task inventory	ini entries: [hieradata] stage = None env:HIERADATA_VARS_PLUGIN_STAGE	Control when this vars plugin may be executed. Setting this option to all will run the vars plugin after importing inventory and whenever it is demanded by a task. Setting this option to task will only run the vars plugin whenever it is demanded by a task. Setting this option to inventory will only run the vars plugin after parsing inventory. If this option is omitted, the global RUN_VARS_PLUGINS configuration is used to determine when to execute the vars plugin.

Examples

# hieradata.yml.
# Each level in hierarchy can be a file or a directory.
hiera_vars:
  role: "{{ entity.name.split('-').0 }}"
  env: "{{ entity.name.split('-').2 }}"
hierarchy:
  - common
  - "{{ env }}"
  - "{{ role }}"
  - "{{ role }}-{{ env }}"

# hieradata organized with sub directories.
# Last part of path of each level can be a file or a directory.
hiera_vars:
  role: "{{ entity.name.split('-').0 }}"
  env: "{{ entity.name.split('-').2 }}"
hieradata:
  hierarchy:
    - common
    - "environments/{{ env }}"
    - "roles/{{ role }}"
    - "roles/{{ role }}-{{ env }}"

Filters

Filters are used to manipulate data if needed.

<filter_name>

<!– Filter description –>

since version: <SemVer_string>

<!-- example code -->

How to contribute to ansible-hiera-data

Did you found a bug

• Make sure the bug is not already opened by another user.

• If you can’t find an open issue which reflects your observed problem go ahead an open a new bug.

• Provide as much information as mentioned in the bug report template.

Did you wrote a patch for an open bug

• Open new pull request containing the patch.

• Provide a clear description which describes the problem and the solution. Link the existing bug to the PR.

Do you want to add a new feature

• Make sure there isn’t already a feature request.

• If you can’t find an open feature request which describe your feature idea or parts of it feel free to open a new feature request.

• Suggest your feature idea within the created feature request.

• Provide as much discribtion as possible to enable others to have a good understanding of what you are doing.

• Point out that you want to start to work on the new feature

Do you wnat to contribute to documentation

• Write you documentation change.

• Open a PR with your change.

• Discuss with the team about your changes.

Thank you for any contribution

We will thank you for heed the contribution guidelines and we encourage you to contribute and join the team.

Indices and tables

• Index

• Search Page