NAME
Puppet::Classify - Connects to the Puppet Classifier API (PE Console groups)
VERSION
version 0.003
SYNOPSIS
This module interacts with the Puppet Classifier API (i.e. Puppet Enterprise Console Classification groups)
use Puppet::Classify;
# Create a Puppet classification object
my $classify = Puppet::Classify->new(
cert_name => $config->{puppet_classify_cert},
server_name => $config->{puppet_classify_host},
server_port => $config->{puppet_classify_port},
puppet_ssl_path => $config->{puppet_ssl_path},
puppet_db => $puppet_db,
);
# Get a group's rule
my $rule = $classify->get_group_rule( $group_name );
# Convert the rule for use with the PuppetDB
$rule = $classify->convert_rule_for_puppetdb( $rule );It requires the Puppet::DB module.
METHODS
new
Create the Puppet::Classify object. The following can be set at creation time (defaults shown):
my $puppet_db = Puppet::DB->new;
my $classify = Puppet::Classify->new(
server_name => 'localhost',
server_port => 4433,
puppet_ssl_path => '/etc/puppetlabs/puppet/ssl',
puppet_db => $puppet_db,
);otherwise to create the object:
my $puppet_db = Puppet::DB->new;
my $classify = Puppet::Classify->new;
my $classify = Puppet::Classify->new( 'puppet.example.com' );
my $classify = Puppet::Classify->new( puppet_db => $puppet_db);server_name
The puppet master that is running the classifier API. Connects to localhost by default.
$classify->server_name('puppet.example.com');server_port
Connect to the Puppet Classifier server on port 4433 by default - this can be overidden when consumed.
$classify->server_port(8754);access_token
Use an access_token instead of a certificate to connect to the API. This loads the authentication token saved in your home, but it can be set manually if it is not stored there.
say $classify->access_token;environment
The environment to use for the classification - this can be overidden when consumed. Defaults to 'dev'.
$classify->environment('test');cert_name
the basename of the certificate to be used for authentication. This is a certificate that has been generated on the Puppet Master and added to the whitelist. This can be used instead of using an auth token.
$classify->cert_name('api_access');puppet_ssl_path
Set the path to the Puppet SSL certs, it uses the Puppet enterprise path by default.
$classify->server_name('puppet.example.com');timeout
The connection timeout. Defaults to 360 seconds.
$classify->timeout(30);puppet_db
The puppet DB object used to interact with the Puppet DB.
$classify->puppet_db(Puppet::DB->new);update_classes
Updates the class cache.
$classify->update_classes;get_classes
Gets a list of all the class information.
my $classes = $classify->get_classes( $group );get_group_rule
Returns the rule as a Perl data structure given the group name.
my $group_name = "Production";
my $group_rule = $classify->get_group_rule( $group_name );get_group_id
Returns the group ID given the group name.
my $group_name = "Production environment";
my $group_id = $classify->get_group_id( $group_name );get_groups_match
Returns an array ref of a list of group data structures where their names match the given string
my $groups = $classify->get_groups_match( "Roles" );
say Dumper( $groups );get_groups
Returns an array ref of all the group data structures
my $groups = $classify->get_groups;
say Dumper( $groups );get_group_children
Returns an array ref of all the group data structures according to the specified parent group ID
my $parent = "Production environment";
my $parent_gid = $classify->get_group_id( $parent );
my $children = $classify->get_group_children( $parent_gid );
say Dumper( $children );add_group_safe
Creates a new group, but checks if one already exists by the same name. If it does, the force option can be specified to remove it first - thus redefining it.
The example data structure is the minimum. See https://puppet.com/docs/pe/latest/groups_endpoint.html#post-v1-groups for more info on the fields.
my $parent = "Production environment";
my $parent_gid = $classify->get_group_id( $parent );
my $name = 'A group';
my $force = 1;
my $group = {
name => $name,
parent => $parent_id,
};
$classify->add_group_safe( $name, $group, $force );create_group
Use with caution. It is preferable to use add_group_safe
Creates a new group (or overwrites another). The example data structure is the minimum. See https://puppet.com/docs/pe/latest/groups_endpoint.html#post-v1-groups for more info on the fields.
my $parent = "Production environment";
my $parent_gid = $classify->get_group_id( $parent );
my $group = {
name => 'A group',
parent => $parent_id,
};
$classify->create_group( $group );update_group_rule
Replaces a groups rule with a new one. The group is specified by its group ID.
$classify->update_group_rule( $gid, $rule );update_group_environment
Sets the environment for a group. The group is specified by its group ID.
$classify->update_group_environment( $gid, $environment );update_group
Updates a groups info according to the specified hash. Only the elements specified in the hash are updated (replaced).
my $config = {
environment => $environment,
parent => $parent_id,
};
$classify->update_group( $gid, $config );remove_group_safe
Removes a group unless it has pinned nodes. It can still be deleted if it has pinned nodes if a force option is turned on.
my $force = 1;
$classify->create_group( $group_name, $force );try_remove_group
This will remove a group, but first check if it has children (it which case it will just log an error rather than doing anything)
$classify->create_group( $group_name );It is preferable to call remove_group_safe.
delete_group
Deletes a group. This will work ever if nodes are pinned to the group, but it cannot delete groups that have children groups (the children must be removed first).
$classify->delete_group( $id );It is preferable to call remove_group_safe.
convert_rule_for_puppetdb
Converts a classifier node matching rule into a form that is compatible with the PuppetDB
my $rule2 = $classify->convert_rule_for_puppetdb( $rule1 );get_nodes_matching_group
Returns an array ref list of nodes matching a group.
my $nodes = $classify->get_nodes_matching_group( $group_name );This can take some time to run as it needs to connect to the PuppetDB to find out the nodes.
get_hosts_from_pinned_rule
Returns an array ref list of nodes pinned to a group (you need to pass the rule of the group).
my $group_rule = $classify->get_group_rule( $group_name );
my $nodes = $classify->get_hosts_from_pinned_rule( $group_rule );list_nodes_pinned_in_group
This lists the nodes in a group to STDOUT.
$classify->list_nodes_pinned_in_group( $group_name );purge_old_nodes
This will purge all the pinned nodes from the children of the specified group if those nodes cannot be found in the Puppet DB anymore.
$classify->purge_old_nodes( $parent_id );list_membership_of_nodes
For a list of nodes and a parent group, maps which child group each node is pinned to. If no nodes are specified, it will be assumed to be all the nodes matching the parent.
my $nodes = [ qw( node1 node2 ) ];
$classify->list_membership_of_nodes( $parent_name, $nodes );or
$classify->list_membership_of_nodes( $parent_name );remove_nodes_from_all_groups
Removes all the specified nodes from all the child groups of the specified parent group.
my $parent = "Production environment";
my $parent_gid = $classify->get_group_id( $parent );
my $nodes = [ qw( node1 node2 ) ];
$classify->remove_nodes_from_all_groups( $parent_gid, $nodes );empty_group_of_pinned_nodes
Remove all pinned nodes from a group leaving other rules in place
$classify->empty_group_of_pinned_nodes( $group_name );remove_pinned_node_from_group
Remove specified pinned nodes from a group leaving other rules in place
my $nodes = [ qw( node1 node2 ) ];
$classify->remove_pinned_node_from_group( $group_name, $nodes );pin_nodes_to_group
Pin nodes to the specified group
my $nodes = [ qw( node1 node2 ) ];
$classify->pin_nodes_to_group( $group_name $nodes );AUTHOR
Matthew Mallard <mqtech@cpan.org>
COPYRIGHT AND LICENSE
This software is copyright (c) 2019 by Matthew Mallard.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.