The Perl Toolchain Summit 2025 Needs You: You can help 🙏 Learn more

 / 
Puppet-Classify-0.003
River stage zero No dependents
/ Puppet::Classify

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.