...
The simp/simpkv module provides a library that allows Puppet to access one or more key/value stores (aka backends), each of which, can be used to store global keys and keys specific to a Puppet environmentenvironments. This section will present an overview of simpkv. Please refer to the module design documentation, README, and library documentation for more details.
...
Function Name | Description |
|---|---|
| Deletes a key from a backend. |
| Deletes an entire folder from a backend. |
| Returns whether a key or key folder exists in a backend. |
| Retrieves the value and any metadata stored at for a key from a backend. |
| Returns a listing of all keys and sub-folders in a folder in a backend The list operation does not recurse through any sub-folders. Only information about the specified key folder is returned. |
| Sets the data value and optional, user-provided metadata for a key to a value in a backend.Optionally sets metadata along with the value. |
Backend logical structure
Logically, keys for a specific backend are organized within global and environment directory trees below that backend's root directory. You can visualize this tree as a filesystem in which a leaf node is a file named for the key and whose contents contains the value of for that key. For example,
...
To facilitate implementations of this tree, key and folder names are restricted to sequences of alphanumeric, ‘.', ‘_', and ‘-’ characters, with '/' used as the path separator. Furthermore, when specifying the path to a key in an access operation, the path cannot contain relative path subsequences (e.g., '/./' or '/../').
Backend selection
simpkv allows the user to select and configure one or more backends to be used when simpkv::* functions are called in Puppet manifests during catalog compilation. The configuration is largely made via hieradata.
...
There must be one LDAP backend DIT for all SIMP application data.
This is distinct from the DIT containing user accounts data.
Data to be stored must include simpkv data.
Data to be stored may in the future include other application data, (e.g., IP firewall data).
The simpkv data must be a subtree of the DIT.
The simpkv subtree must support partitioning the data into LDAP backend instances.
The simpkv subtree must allow storage of per-LDAP-backend-instance global and environment-specific key/value entries.
Entries may be stored in subtrees within the LDAP instance subtree.
Each key/value entry must be a leaf node in the LDAP instance subtree.
The DistinguishedName (DN) to each key/value entry throughout the entire DIT must be unique.
The JSON value of the key/value entry must be stored in some form in the key/value entry.
The key/value entry may have an attribute containing the JSON-encoded value.
The key/value entry may have attributes that map to the value’s JSON attributes.
The tree must support efficient
simpkv::get,simpkv::exists, andsimpkv::listoperations.Folder and/or key objects may store data in attributes to leverage LDAP search capabilities.
The simpkv LDAP plugin should nothave to retrieve the entire tree or subtree in order to fulfill any of these operations.
Any custom schema
attributeTypeorobjectClasswill be specified with an Object Identifier (OID) below the official SIMP Object Identifier (OID).
...
At first blush, the mapping of the logical simpkv tree structure into a LDAP DIT appears to be straight forward, because LDAP is fundamentally a tree whose leaf nodes could hold a key/value pairsdata. For example, we could design a tree as follows:
...
The simplest design option enforces DN case invariance by requiring all the values of all attributes used in a DN for a key/value pair to be lowercase. In other words, change the experimental simpkv API to only allow lowercase letters, numerals, and ‘.', ‘_’, and ‘-’ characters for all key names, folder names, and plugin instance identifiers. Then, because each key’s DN is unique and case invariant, the simple mapping scheme described in 'Design Considerations’ can be used.
With this simple mapping, The the proposed simpkv LDAP subtree will look nearly like that of the logical key/value tree. It just inserts a few extra “folders” into the tree in order to clarify the roles of the nodes beneath it. The new “folders” are
...
The second design option enforces DN case invariance without impacting the existing simpkv API. In this design, the LDAP plugin transforms any problematic attributes that are to be used in a DN for a key/value pair to a hexadecimal representation. Soan encoded representation (e.g., hexadecimal, Base 64). For example, with a hexadecimal transformation, all backend instance identifiers, key names, and folder names would be represented in hex, minus the ‘0x’ or ‘0X’ preface**. This means key paths production/app1/key1 and production/App1/Key1 are mapped to simpkvHexId=fixme61707031,simpkvHexId=fixme6b657931,ou=production,ou=environments,...
andsimpkvHexId=41707031,simpkvHexId=4b657931,ou=production,ou=environments,...
which although not human-friendly are definitely unique.(Puppet environment is required to use lowercase letters, and does not need to be transformed)
As with Option 1, the proposed simpkv LDAP subtree
Then, in order to support standard searches of the LDAP tree using the raw backend instance identifiers, key names, and folder names outside of Puppet manifests, each node in the tree would have to contain an attribute with the raw identifiers.
In addition, to facilitate searching of the LDAP by their original
**Puppet environment names are not allowed to include uppercase letters
Recommendation
Schema and OID Subtree Design
...