Forge Home

Modules

Puppet

Resources

PuppetEcosystemPuppet CommunityUpdates

connect

A replacement for YAML in hiera
Project URLRSS FeedReport issues

19,638 downloads

5,922 latest version

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

Support the Puppet Community by contributing to this module

You are welcome to contribute to this module by suggesting new features, currency updates, or fixes. Every contribution is valuable to help ensure that the module remains compatible with the latest Puppet versions and continues to meet community needs. Complete the following steps:

  1. Review the module’s contribution guidelines and any licenses. Ensure that your planned contribution aligns with the author’s standards and any legal requirements.
  2. Fork the repository on GitHub, make changes on a branch of your fork, and submit a pull request. The pull request must clearly document your proposed change.

For questions about updating the module, contact the module’s author.

Version information

  • 0.0.24 (latest)
  • 0.0.23
  • 0.0.22
  • 0.0.21
  • 0.0.20
  • 0.0.19
  • 0.0.17
  • 0.0.16
  • 0.0.15
  • 0.0.14
  • 0.0.13
  • 0.0.12
  • 0.0.11
  • 0.0.10
  • 0.0.9
  • 0.0.8
  • 0.0.7
  • 0.0.6
  • 0.0.5
  • 0.0.4
  • 0.0.3
  • 0.0.2
  • 0.0.1
released May 28th 2017
This version is compatible with:
  • Puppet Enterprise >=3.4.3
  • Puppet >=3.4.3
  • , , , , , , ,

Start using this module

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

Add this module to your Puppetfile:

mod 'hajee-connect', '0.0.24'
Learn more about managing modules with a Puppetfile

Add this module to your Bolt project:

bolt module add hajee-connect
Learn more about using this module with an existing project

Manually install this module globally with Puppet module tool:

puppet module install hajee-connect --version 0.0.24

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

Documentation

hajee/connect — version 0.0.24 May 28th 2017

Build Status Coverage StatusCode Climate

####Table of Contents

  1. Overview
  2. Module Description - What Connect does and why it is useful
  3. Setup - The basics of getting started with connect
  4. Usage - Configuration options and additional functionality
  5. Troubleshooting
  6. Limitations - OS compatibility, etc.
  7. Development - Guide for contributing to the module

##Overview

Connect is a replacement for YAML in hiera. When you start with Puppet, using hiera with YAML is an excellent way to split code and configuration data. But when your configuration grows, you start to notice some troubles with this combination:

  • Your YAML files start to become bigger and bigger and bigger and slowly but surely become incomprehensible.
  • You would like to reference other values. YAML supports this..... but not between different files. Besides the & and * anchor syntax becomes a hassle, when you use it much.
  • You have found the yaml interpolation using "%{hiera('lookup_value')" to lookup values over you whole YAML structure..... but noticed, you can only use this for strings, and not for other data types.

If you recognize any of these problems, Connect might be for you! If you haven't run into these problems, Connect is probably like taking a sledgehammer to crack a nut, and it is best to stay with YAML.

Want to know the details, Check the Connect Language, in a Nutshell, for more intro into the language.

##Module Description

Connect is a hiera backend. Using the Connect language, you can describe your Puppet parameters in an simple and concise way. You can:

  • separate your config files into separate files and include them when you need them.
  • You can easily reference variables. These variables can be in any other configuration file. They can be in an included configuration, or they can be defined at another hiera hierarchy level.
  • You can import data from other sources like PuppetDb and mix and match them with your own parameter settings.
  • You can reference encrypted variables in a safe way.

...and much more.

##Example

domain_name = 'example.com'
import from puppetdb into datacenter:: {
  ntp_servers = 'Class[Ntp::Server]'  # Fetches all NTP nodes from puppetdb 
                                      # into the array datacenter::ntp_servers

  dns_servers = 'Class[Dns::Server]'  # Fetches all DNS nodes from puppetdb 
                                      # into the array datacenter::dns_servers
}
ftp_node    = "ftp.${domain_name}"
all_nodes   = [
  ntp_servers,
  dns_servers,
  ftp_node,
]

include 'generic_settings/*'        # include all settings
include "${domain_name}/settings"   # include specific setting for domain

Check the Connect Language, in a Nutshell, for more intro into the language.

##Setup

###Installing the module

To use the connect hiera module, you first have to make sure it is installed.

puppet module install hajee/connect

If you are using a Puppetfile, you need the following lines:

mod 'hajee-connect'

###Enabling Connect in hiera

To start using the connect hiera backend, you have to enable it in the hiera config file. Add the connect line to the :backends: array. The order of the entries in the array, is the order hiera will use to resolve the lookups. 

---
:backends:
  - yaml
  - connect

...

:connect:
  :datadir: /etc/puppet/config

...

Add a :datadir: entry for the connect backend. The default is /etc/puppet/config.

###What connect affects

If you have configured connect, like specified in the hiera.yaml ALL hiera lookups will be passed to the Connect backend.

###Setup Requirements

Because connect is based on hiera and puppet, you need to have both the hiera and puppet gem installed.

Some of the data sources require extra Ruby gems or other components. Check their documentation for details

###Beginning with connect module

To test if everything works, ue the next steps:

  • add connect to the hiera.yaml. You can find an example here
  • Create a common.config in the folder /etc/puppet/config. You can find an example here.
  • Create a test.pp with this content
  • Run the small test manifest and check the output
$ puppet apply test.pp
Notice: Scope(Class[Test]): it works
Notice: Compiled catalog for 10.0.2.15 in environment production in 0.20 seconds
Notice: Finished catalog run in 0.03 seconds

You can also use the values inpsector to check the value:

$ puppet connect values test::parameter

###Tools

The values inspector

Bundled with connect comes the values inspector. This tool lets you see the interpreted value of a specified parameter. In lay man's terms, it parses your connect file's and shows you the value.

$ puppet connect values my_parameter

You can also use a wildcard for the parameter. Wildcards are specified as regular expressions.

$ puppet connect values my_scope::.*

This will show all parameters in the scope my_scope.

puppet connect values will also show you where your parameters are defined and referenced. This is a tremendous help when debugging or just understand a complex set of connect configuration files.

The objects inspector

Similar to the values inspector, is the objects inspector This tool lets you see the interpreted value of a specified object. Just like the values inspector, it parses your connect file's and shows you the contents of your objects.

$ puppet connect objects  my_node

You can also use a wildcard for the parameter. Wildcards are specified as regular expressions.

$ puppet connect objects my_*.

This will show all objects starting with my_.

If you just want to see the objects of a certain type, use --type or -t

$ puppet connect objects --type host my_*.

Will show you all just starting with my_

puppet connect objects will also show you where your objects are defined and referenced. This is a tremendous help when debugging or just understand a complex set of connect configuration files.

###Using the accompanying Vagrant box

You can also get started with a Vagrant box that is preconfigured.

$ vagrant up
Bringing machine 'default' up with 'virtualbox' provider...
==> default: Importing base box 'hajee/centos-5.10-x86_64'...
==> default: Matching MAC address for NAT networking...
...
    default: Running: inline script
==> default: Running provisioner: shell...
    default: Running: inline script
==> default: Running provisioner: shell...
    default: Running: inline script
$ vagrant ssh
Last login: Sun Dec 14 17:08:18 2014 from 10.0.2.2
$ sudo su -               # Make yourself root
$ cd /vagrant/tests/      # Goto the folder containing the test manifest
$ puppet apply test.pp    # Apply it.
Notice: Scope(Class[Test]): it works localhost
Notice: Compiled catalog for localhost.localdomain in environment production in 0.39 seconds
Notice: Finished catalog run in 0.03 seconds
$

On your host os, you can edit the `examples/default.config' file to experiment with the Connect language.

##detailed description

Check the Connect Language, in a Nutshell, for more intro into the language.

##Troubleshooting

If you make mistakes in the config files, Connect will show you a parse error. The parse error shows the file and the line number of the parse error. This should help you pinpoint any errors. The parsing of the connect files will be done once before the real puppet run starts. This ensures's Puppet can only start after it has made certain the Connect configs are syntactically correct

##Limitations

This module is tested CentOS and Redhat. It will probably work on other Linux distributions.

##Development

This is an open source project, and contributions are welcome.

###OS support

Currently we have tested:

  • CentOS 5
  • Redhat 5

###Testing

Make sure you have:

  • rake
  • bundler

Install the necessary gems:

bundle install

And run the tests from the root of the source code:

rake spec

We are currently working on getting the acceptance test running as well.