The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.


Puppet::Classify - Connects to the Puppet Classifier API (PE Console groups)


version 0.003


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.



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( '' );
    my $classify = Puppet::Classify->new( puppet_db => $puppet_db);


The puppet master that is running the classifier API. Connects to localhost by default.



Connect to the Puppet Classifier server on port 4433 by default - this can be overidden when consumed.



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;


The environment to use for the classification - this can be overidden when consumed. Defaults to 'dev'.



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.



Set the path to the Puppet SSL certs, it uses the Puppet enterprise path by default.



The connection timeout. Defaults to 360 seconds.



The puppet DB object used to interact with the Puppet DB.



Updates the class cache.



Gets a list of all the class information.

    my $classes = $classify->get_classes( $group );


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 );


Returns the group ID given the group name.

    my $group_name = "Production environment";
    my $group_id = $classify->get_group_id( $group_name );


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 );


Returns an array ref of all the group data structures

    my $groups = $classify->get_groups;
    say Dumper( $groups );


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 );


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 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 );


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 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 );


Replaces a groups rule with a new one. The group is specified by its group ID.

    $classify->update_group_rule( $gid, $rule );


Sets the environment for a group. The group is specified by its group ID.

    $classify->update_group_environment( $gid, $environment );


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 );


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 );


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.


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.


Converts a classifier node matching rule into a form that is compatible with the PuppetDB

    my $rule2 = $classify->convert_rule_for_puppetdb( $rule1 );


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.


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 );


This lists the nodes in a group to STDOUT.

    $classify->list_nodes_pinned_in_group( $group_name );


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 );


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 );


    $classify->list_membership_of_nodes( $parent_name );


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 );


Remove all pinned nodes from a group leaving other rules in place

    $classify->empty_group_of_pinned_nodes( $group_name );


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 the specified group

    my $nodes = [ qw( node1 node2 ) ];
    $classify->pin_nodes_to_group( $group_name $nodes );


Matthew Mallard <>


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.