# Hiera

Please refer to `here <https://docs.puppet.com/hiera/>`_ for a general Hiera
introduction.

Our current hierarchy has seven levels (first will be considered first
during value lookup):

- nodes (FQDN)
- subgroup (optional, ``puppet_subgroup`` attribute in sysdb)
- group (``puppet_group`` attribute in sysdb)
- sysdb environments
- Puppet server specific
- global
- common
    
The first four layers can be edited by the admin in the respective hiera git repository. The common layer (default values) and the server specific layer (differences between test and prod) are part of the Puppet code repository. Finally the global layer contains a few configurations which are managed by the Core Linux Group outside of the normal Puppet release process, eg. for license management.

The values can be stored as classical YAML values or with [encrypted yaml](https://github.com/TomPoulton/hiera-eyaml) for secrets.

The filesystem structure is as follows (the last 3 cannot be controlled by a common admin):

1. ``%{::sysdb_env}/%{::group}/%{::fqdn}.yaml`` or ``%{::sysdb_env}/%{::group}/%{::subgroup}/%{::fqdn}.yaml``
2. ``%{::sysdb_env}/%{::group}/%{::subgroup}.yaml``
3. ``%{::sysdb_env}/%{::group}.yaml``
4. ``%{::sysdb_env}/%{::sysdb_env}.yaml``

5. ``%{::environment}/data/server_%{server_facts.servername}.yaml``
6. ``/srv/puppet/data/global/global.yaml``
7. ``%{::environment}/data/common.yaml``

Depending if a subgroup is defined, the node specific YAML is at a different level in the filesysystem hierarchy.

The ``%{variable}`` notation is hiera specific.

## Repositories

Hiera data are organized in different repositories. These repositories are located at: https://git.psi.ch/linux-infra/hiera


Each __sysdb environment__ has a dedicated hiera repository, called ``data-<sydbenv>``, eg. [data-hpc]( https://git.psi.ch/linux-infra/hiera/data-hpc).
The first 4 levels of the filesystem structure shown before are actually the files inside this kind of repositories.

Any change to the repo will automatically trigger a redeployment of the new version of its content on the puppet master within a few seconds from the push.

## Configuration

### Secrets
Secrets and clear-text values can be mixed inside the same yaml file, eg.::
```yaml
ntp_client::servers:
  - pstime1.psi.ch
  - pstime2.psi.ch
  - pstime3.psi.ch

secret_key: ENC[PKCS7,MIIBiQYJKoZIhvcNAQcDoIIBejCCAXYCAQAxggEhMIIBHQIBADAFMAACAQEwDQYJKoZIhvcNAQEBBQAEggEAY/9V1S0VAMrRX1B4V06AgsbHPHdONFCQ4RiWfTrhV02rL5gSL4LAdqOuvGPY8YZZv8Mp06/FARlvP1aOfEx7avqSBy11IoUGkeajKZFzJV3OJsfhso4wroQ4JmfBaVKICnQZwCdpke+PHPRkwTgHcjmY2FeBnhvOlrGiQMQU3JzCjLePOa7UvlIIin3xOU/TdetzhfvoNGRhsz7+XRPD+mTT8efJ+OslJmqU7hEqMbs9CmhPJWqsjsQUp8jsM10Dk2Rv4v+zYeJd1ZLRGK3Z56G4NrlLyYua+/yyPbUP4+1bEuisDg9bfQHp3R491/kN0W558oQ+85rsRVXCp1Hb6TBMBgkqhkiG9w0BBwEwHQYJYIZIAWUDBAEqBBB2x9awGQnxAJsxIHA9OiM2gCBFvgxIR4SJZPrrQ/UlhKU39yYSkEmuKE/ou+yeIe5AMA==]
```

The encrypted values can be decrypted transparently from Hiera (on a host having the proper hiera key):
```bash
[root]# hiera secret_key
this is a secret value
```

You can edit secure data inside any yaml file with the command `/opt/puppetlabs/puppet/bin/eyaml edit common.yaml`. In this case secure data will appear in clear-text inside the editor.


### Encrypt Data
To encrypting data you have to use following public key:
```
-----BEGIN CERTIFICATE-----
MIIC2TCCAcGgAwIBAgIBATANBgkqhkiG9w0BAQUFADAAMCAXDTE2MTAyNDE0NTY1
N1oYDzIwNjYxMDEyMTQ1NjU3WjAAMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIB
CgKCAQEA2eykSgS7VJEXrWYkQMV48ZkUVcHMbCEo2gZXD4vIJsOdJu77F7tA53Ay
NxdKnJTftsj+R7yFP9Z2XllA9Our0Ypphj40rNstRg5O4IoSkAqitJchlfGL9jZ3
CB4dJqFitzOkxxCWZjQpjBd3dMJc6U3us6IDWohCjYqyjMZIVwU5EflzJKV4haEy
Y9qHkVt938RM9UohEvia5/1lZxuZQmDpYqCw9gmBK/dVKZ7abZGkujTKAg5cjD/X
vuexLMCGrjnPdrsblwBh+yfu6cEo9nfvfj6EA0FxPHIvQ3fv1yJZ+90OA9eUJnqQ
ED66OGPATAJIqhWlgb8a760xPQFQQQIDAQABo1wwWjAPBgNVHRMBAf8EBTADAQH/
MB0GA1UdDgQWBBSF05r9TYDiAmkdguCVcDzmYR8Q6TAoBgNVHSMEITAfgBSF05r9
TYDiAmkdguCVcDzmYR8Q6aEEpAIwAIIBATANBgkqhkiG9w0BAQUFAAOCAQEAWAER
CTGsOFUkCfvqke75PmIkxKBp/2eJbavWzPkbA/mwAGS4lQc5oyS8FMkUFxATo1k/
WIb2B3WJIMHfCzMNxTlQLjJiSyvWAlEBHDW4H2XekzKSbj96l+/nirmOq3QkEKTK
omexF5zYSPkBVA/S2m2wae3g2kubH1p42+REKQUvt1+xaecHBYD6eXzBWChnMMnq
FbXoayTibn0p9Roo8HClGGJpjPZUTMf+VGUqKWPfvaKl48Y0yrc/4BzZT6Sbzeou
ZSiHwa62rTV7ia7m2SILZU5b65JUVkFH/2r6qkxCr0Ep+oaxSNXtAXLCbnXmdOeK
B40J8ePbbmmGE24+zQ==
-----END CERTIFICATE-----
```

On the puppet server this key can be found at `/etc/puppetlabs/keys/eyaml/public_key.pkcs7.pem`.

Beside this key you also need to have `hiera-eyaml` tool installed on your system.

Assuming the public key is saved in a file (e.g. ``~/eyaml_key.pub``), that the file path has been put into the environment varialbe ``EYAML_PUB_KEY``, then a string can be encripted with::

```bash
eyaml encrypt --pkcs7-public-key=$EYAML_PUB_KEY -s secret_string
```

While a complete file can be encrypted with:
```bash
eyaml encrypt --pkcs7-public-key=$EYAML_PUB_KEY -f secret_file
```

#### Example

To encrypting password for a system you can go about like this:

```bash
# openssl passwd -6 | eyaml encrypt --pkcs7-public-key=$EYAML_PUB_KEY --stdin
Password: 
Verifying - Password: 
string: ENC[PKCS7,MIIBxxxxxxxx...xxxxxxxx]

OR

block: >
  ENC[PKCS7,MIIBxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
  xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
  ...
  xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
  xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx]
#
```

and place either the string or the block at the required place in your Hiera YAML.