<commit_before># Hiera Backend for Trocla

[![Build Status](https://travis-ci.org/ZeroPointEnergy/hiera-backend-trocla.svg)](https://travis-ci.org/ZeroPointEnergy/hiera-backend-trocla)

This is a simple hiera backend to retrieve passwords from trocla.

The idea of this backend is to enable you to use secrets from trocla
directly from your hiera data via interpolation tokens.

## Installation

Simply install the gem and hiera will find it automatically

    $ gem install hiera-backend-trocla

## Usage

Add the backend to your hiera.yaml to use it.

    :backends:
        - 'trocla'
        - 'yaml'
    :hierarchy:
        - 'defaults'
    :yaml:
        :datadir: '/path/to/your/hieradata'
    :trocla:
        :config: '/path/to/your/troclarc.yaml'

There are two different methods to lookup a password in trocla. trocla_lookup and trocla_hierarchy

### trocla_lookup

trocla_lookup will simply lookup the password for a specified key and completely ignore
the hierarchy defined in the hiera configuration. If the password does not exist it will
create one.

The trocla hiera backend will resolve all the variables which start with "trocla_lookup::"

The second part of the variable is used to describe the format, the last part is the variable
to lookup in trocla.

    torcla_lookup::<format>::<myvar>

You can use the backend via interpolation tokens like this:

    myapp::database::password: "%{hiera('trocla_lookup::plain::myapp_mysql_password')}"

    mysql::server::users:
      'someuser@localhost':
          ensure: 'present'
          password_hash: "%{hiera('trocla_lookup::mysql::myapp_mysql_password')}"

### trocla_hierarchy

trocla_hierarchy will lookup the key in the hierarchy defined in your hiera configuration.
It will simply prefix all the variables with 'hiera/<source>/<key>' where source is one of
the strings defined in the hierarchy section.

It will try to find a password on every level in your hierarchy first. After that it will
create a password on the first hierarchy level by default. You can overwrite the level it
should create the password with the key 'order_override' in the trocla_options hash.

This is useful if you require different key for different nodes or on any other hierarchy level
you desire.

If you have a hierarchy defined like this:

    :hierarchy:
      - "nodes/%{::clientcert}"
      - "roles/%{::role}"
      - defaults

And you want to create a different password on the roles level, so that nodes within the
same role will get the same password you can set the 'order_override' like this:

    trocla_options::my_special_key:
      order_override: "roles/%{::role}"

### options hash

Trocla takes a hash of options which provides information for the password creation. This
options can be set directly in hiera globally for every format of for every key.

    trocla_options:
      length: 16<commit_msg>add an example for trocla_hierarchy in the readme<commit_after># Hiera Backend for Trocla

[![Build Status](https://travis-ci.org/ZeroPointEnergy/hiera-backend-trocla.svg)](https://travis-ci.org/ZeroPointEnergy/hiera-backend-trocla)

This is a simple hiera backend to retrieve passwords from trocla.

The idea of this backend is to enable you to use secrets from trocla
directly from your hiera data via interpolation tokens.

## Installation

Simply install the gem and hiera will find it automatically

    $ gem install hiera-backend-trocla

## Usage

Add the backend to your hiera.yaml to use it.

    :backends:
        - 'trocla'
        - 'yaml'
    :hierarchy:
        - 'defaults'
    :yaml:
        :datadir: '/path/to/your/hieradata'
    :trocla:
        :config: '/path/to/your/troclarc.yaml'

There are two different methods to lookup a password in trocla. trocla_lookup and trocla_hierarchy

### trocla_lookup

trocla_lookup will simply lookup the password for a specified key and completely ignore
the hierarchy defined in the hiera configuration. If the password does not exist it will
create one.

The trocla hiera backend will resolve all the variables which start with "trocla_lookup::"

The second part of the variable is used to describe the format, the last part is the variable
to lookup in trocla.

    torcla_lookup::format::myvar

You can use the backend via interpolation tokens like this:

    myapp::database::password: "%{hiera('trocla_lookup::plain::myapp_mysql_password')}"

    mysql::server::users:
      'someuser@localhost':
          ensure: 'present'
          password_hash: "%{hiera('trocla_lookup::mysql::myapp_mysql_password')}"

### trocla_hierarchy

trocla_hierarchy will lookup the key in the hierarchy defined in your hiera configuration.
It will simply prefix all the variables with 'hiera/source/key' where source is one of
the interpolated strings defined in the hierarchy section.

It will try to find a password on every level in your hierarchy first. After that it will
create a password on the first hierarchy level by default. You can overwrite the level it
should create the password with the key 'order_override' in the trocla_options hash.

This is useful if you require different key for different nodes or on any other hierarchy level
you desire.

If you have a hierarchy defined like this:

    :hierarchy:
      - "nodes/%{::clientcert}"
      - "roles/%{::role}"
      - defaults

And you want to create a different password on the roles level, so that nodes within the
same role will get the same password you can set the 'order_override' like this:

    trocla_options::my_special_key:
      order_override: "roles/%{::role}"

The format to lookup a password this way is the same as with 'trocla_lookup':

    trocla_hierarchy::format::myvar

Here is how you would use that in hiera:

    mysql::server::root_password: "%{hiera('trocla_hierarchy::plain::mysql_root')}"

### options hash

Trocla takes a hash of options which provides information for the password creation. This
options can be set directly in hiera globally or for every key. You can also specify options
specifically for a password format. However, keep in mind that it will only use the options
of the format which is used first to retrieve a password for a key, because thats when the
password is generated.

    trocla_options:
      length: 16
{'fraction_non_alphanumeric': 0.06939558682443236, 'fraction_numerical': 0.0006395906619763352, 'mean_word_length': 3.940758293838863, 'pattern_counts': {'":': 0, '<': 7, '<?xml version=': 0, '>': 7, 'https://': 4, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '549730', 'n_tokens_mistral': 1816, 'n_tokens_neox': 1759, 'n_words': 780}