libkv

partner
LibKV providers

SIMP

simp

30,726 downloads

30,628 latest version

2.4 quality score

Version information

  • 0.6.1 (latest)
  • 0.6.0
released Jan 31st 2018
This version is compatible with:
  • Puppet Enterprise 2017.2.x, 2017.1.x, 2016.5.x, 2016.4.x
  • Puppet 4.x
  • CentOS
    ,
    RedHat

Start using this module

Tags: simp, libkv

Documentation

simp/libkv — version 0.6.1 Jan 31st 2018

License Build Status SIMP compatibility

Table of Contents

  1. Description

  2. Usage - Configuration options and additional functionality

  3. Testing

  4. Function Reference

  5. Development - Guide for contributing to the module

Description

libkv is an abstract library that allows puppet to access a distributed key value store, like consul or etcd. This library implements all the basic key/value primitives, get, put, list, delete. It also exposes any 'check and set' functionality the underlying store supports. This allows building of safe atomic operations, to build complex distributed systems. This library supports loading 'provider' modules that exist in other modules, and provides a first class api.

libkv uses lookup to store authentication information. This information can range from ssl client certificates, access tokens, or usernames and passwords. It is exposed as a hash named libkv::auth, and will be merged by default. The keys in the auth token are passed as is to the provider, and can vary between providers. Please read the documentation on configuring 'libkv::auth' for each provider

libkv currently supports the following providers:

  • mock - Useful for testing, as it provides a kv store that is destroyed after each catalog compilation
  • consul - Allows connectivity to an existing consul service

With the intention to support the following:

  • etcd - Allows connectivity to an existing etcd service
  • simp6-legacy - Implements the SIMP 6 legacy file storage api.
  • file - Implements a non-ha flat file storage api.

This module is a component of the System Integrity Management Platform, a compliance-management framework built on Puppet.

If you find any issues, they may be submitted to our bug tracker.

Usage

As an example, you can use the following to store hostnames, and then read all the known hostnames from consul and generate a hosts file:

libkv::put("/hosts/${::clientcert}", $::ipaddress)

$hosts = libkv::list("/hosts")
$hosts.each |$host, $ip | {
  host { $host:
    ip => $ip,
  }
}

Each key specified must contain only the following characters:

  • a-z
  • A-Z
  • 0-9
  • The following special characters: ._:-/

Additionally, /./ and /../ are disallowed in all providers as key components. The key name also must begin with /

When any libkv function is called, it will first call lookup() and attempt to find a value for libkv::url from hiera. This url specifies the provider name, the host, the port, and the path in the underlying store. For example:

libkv::url: 'consul://127.0.0.1:8500/puppet'
libkv::url: 'consul+ssl://1.2.3.4:8501/puppet'
libkv::url: 'file://'
libkv::url: 'etcd://127.0.0.1:2380/puppet/%{environment}/'
libkv::url: 'consul://127.0.0.1:8500/puppet/%{trusted.extensions.pp_department}/%{environment}'

Testing

Manual and automated tests require a shim to kick off Consul inside of Docker, before running. Travis is programmed to run the shim. To do so manually, first ensure you have set up Docker properly.

Next, run the shim:

$ ./prep_ci.sh

NOTE: There is a bug which will not allow the containers to deploy if selinux is enforcing. Set to permissive or disabled.

Run the unit tests:

$ bundle exec rake spec

Function reference

Connects to the backend and retrieves the data stored at key

Any $data = libkv::get(String key)

Returns: Any

Usage:

Sets the data at key to the specified value

Boolean $suceeeded = libkv::put(String key, Any value)

Returns: Boolean

Usage:

Deletes the specified key. Must be a single key

Boolean $suceeeded = libkv::delete(String key)

Returns: Boolean

Usage:

Returns true if key exists

Boolean $exists = libkv::exists(String key)

Returns: Boolean

Usage:

Lists all keys in the folder named key

Hash $list = libkv::list(String key)

Returns: Hash

Usage:

Deletes the whole folder named key. This action is inherently unsafe.

Boolean $succeeded = libkv::deletetree(String key)

Returns: Boolean

Usage:

Store value in key, but only if key does not exist already, and do so atomically

Boolean $suceeeded = libkv::atomic_create(String key, Any value)

Returns: Boolean

Usage:

Delete key, but only if key still matches the value of previous

Boolean $suceeded = libkv::atomic_delete(String key, Hash previous)

Returns: Boolean

Usage:

Get the value of key, but return it in a hash suitable for use with other atomic functions

Hash $previous = libkv::atomic_get(String key)

Returns: Hash

Usage:

Set key to value, but only if the key is still set to previous

Boolean $suceeeded = libkv::atomic_put(String key, Any value, Hash previous)

Returns: Boolean

Usage:

List all keys in folder key, but return them in a format suitable for other atomic functions

Hash $list = libkv::atomic_list(String key)

Returns: Hash

Usage:

Return an hash suitable for other atomic functions, that represents an empty value

Hash $empty_value = libkv::empty_value()

Returns: Hash

Usage:

Return a hash of informtion on the underlying provider. Provider specific

Hash $provider_information = libkv::info()

Returns: Hash

Usage:

Return an array of all supported functions

Array $supported_functions = libkv::supports()

Returns: Array

Usage:

Return the error message for the last call

Return the name of the current provider

String $provider_name = libkv::provider()

Returns: String

Usage:

Development

Please read our Contribution Guide.

Acceptance tests

This module includes Beaker acceptance tests using the SIMP Beaker Helpers. By default the tests use Vagrant with VirtualBox as a back-end; Vagrant and VirtualBox must both be installed to run these tests without modification. To execute the tests run the following:

bundle install
bundle exec rake beaker:suites

Please refer to the SIMP Beaker Helpers documentation for more information.