Forge Home

Modules

Resources

PuppetEcosystemPuppet CommunityUpdates

libkv

LibKV providers
Project URLRSS FeedReport issues

46,646 downloads

46,473 latest version

2.4 quality score

We run a couple of automated
scans to help you access a
module's quality. Each module is
given a score based on how well
the author has formatted their
code and documentation and
modules are also checked for
malware using VirusTotal.

Please note, the information below
is for guidance only and neither of
these methods should be considered
an endorsement by Puppet.

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
  • ,

Start using this module

  • r10k or Code Manager
  • Bolt
  • Manual installation
  • Direct download

Add this module to your Puppetfile:

mod 'simp-libkv', '0.6.1'
Learn more about managing modules with a Puppetfile

Add this module to your Bolt project:

bolt module add simp-libkv
Learn more about using this module with an existing project

Manually install this module globally with Puppet module tool:

puppet module install simp-libkv --version 0.6.1

Direct download is not typically how you would use a Puppet module to manage your infrastructure, but you may want to download the module in order to inspect the code.

Download
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.