Advanced Concepts Of Query API Version4 In PuppetDB

Root Endpoints

Root endpoints are used to query an entity.

What do we mean by query endpoints?
Query endpoints can be used to retrieve any known entities from databases. 
The root endpoint looks like:  /pdb/query/v4 - returns any known entity. The entity must be supplied using a query with the operator.
 

Response format - The response will be in application/JSON format and contain a list of JSON object results based on the entity.
 

URL parameters - 

1. query:  This is essential. Either a PQL query string or an AST JSON array containing the query in prefix notation
   (["from", "<ENTITY>", ["<OPERATOR>", "<FIELD>", "<VALUE>"]]). 
    
2. ast_only: It is a boolean value and is optional. When true, the query response will be the supplied query in AST, exactly as supplied from PQL. False is set by default.
    
3. Origin: This is optional. This is a string describing the source of the query. It can be anything and will be reported in the log when PuppetDB is configured to log queries. 
    
4. Explain: This is optional. The string value is analyzed. This is used to tell PuppetDB to return the execution plan of a statement instead of the query results.

Nodes Endpoint

Nodes are points where a message is created, transferred, or received. Therefore node endpoints are the points where the exchange of data takes place.
An HTTP request to the /nodes endpoint is used to query API in PuppetDB. 
 

Response format:
It returns JSON hashes. These are unsorted arrays that have JSON objects or strings as their keys. Each of these keys has either of these values:

1. String
2. Boolean
3. Null
4. Timestamp(can be non-null)
    

For example: "catalog_timestamp": <timestamp or null>
 

URL parameters:
Node endpoints support only one URL parameter, which is a query. It is optional. 
["<OPERATOR>", "<FIELD>", "<VALUE>"]) is the prefix notation of the JSON array of this query parameter.
This applies to all the URLs used to query API in puppetDB for node endpoints.
 

URLs to query node endpoints:

1.  /pdb/query/v4/nodes - returns matching nodes.
    
2. /pdb/query/v4/nodes/<NODE> - returns status of a given node(active or deactivated.)
    
3. /pdb/query/v4/nodes/<NODE>/facts - returns facts about a given node.
    
4. /pdb/query/v4/nodes/<NODE>/facts/<NAME> - returns facts about a given node with the node name.
    
5. /pdb/query/v4/nodes/<NODE>/facts/<NAME>/<VALUE> - returns facts about a given node with node name and values
    
6. /pdb/query/v4/nodes/<NODE>/resources - returns resources for a given node. You can also use /pdb/query/v4/resources.
    
7. /pdb/query/v4/nodes/<NODE>/resources/<TYPE> - returns specific type of resource for the given node.
    
8. pdb/query/v4/nodes/<NODE>/resources/<TYPE>/<TITLE> - returns specific type and title of resource for the given node.
    

Environments Endpoint

What are the environments in the query API version4 in puppetDB?
Environments are a group of isolated agent nodes(nodes fully controlled by puppet.) The primary server handles it. This help to check nodes before making changes. You can set the environment for a node in the puppet agent.

/environments endpoint is used to query a node's current or previous environments.
 

URL parameters:
Environments endpoints support only one URL parameter, which is a query. It is optional. 
["<OPERATOR>", "<FIELD>", "<VALUE>"]) is the prefix notation of the JSON array of this query parameter.
 

Response format:
It returns JSON hashes just like in the nodes endpoint. In this case, the key is the environment's name, and the value is always a string.
For example: {"name": <string>}
 

URLs to query environment endpoints:

1. /pdb/query/v4/environments - returns all the environments in puppetDB.
    
2. /pdb/query/v4/environments/<ENVIRONMENT> - returns name of active environments in puppetDB.
    
3. /pdb/query/v4/environments/<ENVIRONMENT>/[events|facts|reports|resources] - returns details about the environment of each of the events, facts, reports, and resources endpoints.
    

Producers Endpoint

What are the producers in the query API version4 in puppetDB?
As the name suggests, producers are creators of reports and catalogs in puppet servers.

/producers endpoint is used to query the current or previous producers of a report or catalog. 
 

URL parameters:
Producers endpoints support only one URL parameter, which is a query. It is optional. 
["<OPERATOR>", "<FIELD>", "<VALUE>"]) is the prefix notation of the JSON array of this query parameter.
 

Response format:
It returns JSON hashes just like in all the above endpoints. In this case, the key is the environment's name, and the value is always a string.
For example: {"name": <string>}
 

URLs to query producers' endpoints:

1. /pdb/query/v4/producers - returns all the producers in puppetDB.
    
2. /pdb/query/v4/producers/<PRODUCERS> - returns names of active producers in puppetDB.
    
3. /pdb/query/v4/producers/<PRODUCERS>/[catalogs|factsets|reports] - returns producers of catalogs, factsets, and reports in puppetDB.
    

Factsets Endpoint

What are the factsets in the query API version4 in puppetDB?
The sets of all the facts related to a certificate in Puppet (safety certificate for nodes in puppet) are called factsets.

/factsets endpoint is used to query these sets of facts for a node certificate.
 

URL parameters:
Factsets endpoints support only one URL parameter, which is a query. It is optional. 
["<OPERATOR>", "<FIELD>", "<VALUE>"]) is the prefix notation of the JSON array of this query parameter.
 

Response format:
It returns JSON hashes just like in all the above endpoints. The key, in this case, is the certificate's name, and the values vary according to the type of the certificate.
For example: {"environment": <node environment>}
 

URLs to query factsets endpoints:

1. /pdb/query/v4/factsets - returns all the factsets of the query node in puppetDB.
    
2. /pdb/query/v4/factsets/<NODES> - returns recent factset of a node.
    
3. /pdb/query/v4/factsets/<NODES>/facts - returns all facts of specific factsets about a node's certificate.
    

Facts Endpoint

What are the facts in the query API version4 in puppetDB?
As the name suggests, facts are information about a node in puppetDB. It consists of the node's name, value, certificate name, and environment details.

/facts endpoint is used to query facts about nodes in puppetDB.
 

URL parameters:
Facts endpoints support only one URL parameter, which is a query. It is optional. 
["<OPERATOR>", "<FIELD>", "<VALUE>"]) is the prefix notation of the JSON array of this query parameter.
 

Response format:
It returns JSON hashes just like in all the above endpoints. In this case, the key is the fact's name; the values are either fact/node name, fact-value, or fact environment.
For example: {"name": <string>}
 

URLs to query facts endpoints:

1. /pdb/query/v4/facts - returns all the facts of the query node in puppetDB.
    
2. /pdb/query/v4/facts/<FACT NAME> - returns names of facts along with the facts about the nodes.
    
3. /pdb/query/v4/facts/<FACT NAME>/<VALUE> - returns the names and values of facts and the facts about the nodes.
    

Fact-names Endpoint

/fact-names endpoint is used to query all the fact names for a particular node or nodes.
 

URL parameters:
Fact-name endpoints support only one URL parameter, which is a query. It is optional. 
["<OPERATOR>", "<FIELD>", "<VALUE>"]) is the prefix notation of the JSON array of this query parameter.
 

Response format:
It returns a JSON array of the name of the facts of a node. The occurrence of each fact is one.
For example: [<fact>, <fact>, ..., <fact>, <fact>]
 

URL to query fact-names endpoints:
/pdb/query/v4/fact-names - returns all the names of facts in puppetDB in alphabetical order.
 

Fact-paths Endpoint

Fact-path refers to the path from a node's root to the subsets to the end of the node. 

/fact-paths endpoint is used to query paths followed by all facts for all nodes.
 

URL parameters:
Fact-path endpoints support only one URL parameter, which is a query. It is optional. 
["<OPERATOR>", "<FIELD>", "<VALUE>"]) is the prefix notation of the JSON array of this query parameter.
 

Response format:
It returns a JSON array with fact path and type as keys and values of the array. 
For example: {"path": <fact-node path>}
 

URL to query fact-paths endpoints:
/pdb/query/v4/fact-paths - returns all the paths followed by facts in puppetDB.
 

Fact-contents Endpoint

What is the use of fact-contents in the query API version4 in puppetDB?
As the name suggests, fact-contents help query structured facts of a node distributed into categories, including the paths and the value of nodes and facts.

/fact-contents endpoint is used to query all the details about facts in puppetDB
 

URL parameters:
Fact-content endpoints support only one URL parameter, which is a query. It is optional. 
["<OPERATOR>", "<FIELD>", "<VALUE>"]) is the prefix notation of the JSON array of this query parameter.
 

Response format:
It returns a JSON array just like in all the above fact-related endpoints. The key, in this case, is the contents of facts like certname, fact name, and values are the responses of these facts.
For example: {"environment": <node environment>}
 

URL to query fact-contents endpoints:
/pdb/query/v4/fact-contents - returns all the contents inside the fact of nodes in puppetDB
 

Inventory Endpoint

What is the inventory in the query API version4 in puppetDB?
As the name suggests, an inventory in puppetDB stores information about the nodes. 

/inventory endpoint is used to query the information or facts of a node. It can be used in place of all facts-related endpoints, including structured facts.
 

URL parameters:
Inventory endpoints support only one URL parameter, which is a query. It is optional. 
["<OPERATOR>", "<FIELD>", "<VALUE>"]) is the prefix notation of the JSON array of this query parameter.
 

Response format:
It returns a JSON array, just like in all the above endpoints. In this case, the key: value pair consists of information about the node and the information, respectively.
For example: {"certname": <node certname>}
 

URL to query inventory endpoints:
/pdb/query/v4/inventory - returns all the information stored in the inventory regarding a node.
 

Catalog Endpoint

What are the catalogs in the query API version4 in puppetDB?
Catalogs is a file that contains all the details for the desired infrastructure. The user gives it. We can consider this a checklist is given by the customer to help us know what they want better.

/catalogs endpoint is used to query catalogs. It is the most used endpoint, as every configuration detail for each node is stored in the catalog.  
 

URL parameters:
Catalog endpoints support only one URL parameter, which is a query. It is optional. 
["<OPERATOR>", "<FIELD>", "<VALUE>"]) is the prefix notation of the JSON array of this query parameter.
 

Response format:
It returns a JSON array, just like in all the above endpoints. In this case, the key: value pair consists of information about the infrastructure or the catalog and the information, respectively.
For example: {"version" : <catalog version>}
 

URLs to query catalog endpoints:

/pdb/query/v4/catalog - returns the recent catalog given by the user.

Frequently Asked Questions

What is Puppet forge?

Puppet forge is a collection of modules. All these modules are pre-made by puppet and stored in a forge.

Is Ansible better or Puppet?

Ansible is better as it pushes the configuration to the node instantaneously. Thus it is more scalable than Puppet. Puppet is built on Ruby, whereas Ansible is built on Python.

What is a factor?

A factor library tracks down and informs the Puppet Master of Facts pertinent to each Agent. The Manifests of the Puppet Master then contain the facts as variables.

What is a puppet catalog?

The Puppet Agent configures a node using a document called the Puppet Catalog. The Puppet Master provides the catalog for the agent to download. Each resource that must be managed has the desired state described in the catalog.

How to set up PuppetDB?

The steps to set up puppetDB are as follows:

1. Install PuppetDB.
2. Install and configure PostgreSQL.
3. Configure PuppetDB to use PostgreSQL.
4. Start PuppetDB and open the firewall.
5. Configure the Puppet master
6.  Use PuppetDB.

Conclusion

In this article, we discussed advanced concepts of query API version4 in puppetDB. We also learned about various endpoints to query API version4 in puppet DB.

To learn more about puppetDB, refer to the overview of puppetDB, configuring in PuppetDB, and metadata API in puppetDB.

Check out this problem - Connect Nodes At Same Level

Please refer to our guided paths on Coding Ninjas Studio to learn more about DSA, Competitive Programming, JavaScript, System Design, etc. And also, enroll in our courses and refer to the mock test and problems available. Have a look at the interview experiences and interview bundle for placement preparations.

Happy Learning!