Puppet - RESTful API

Puppet uses RESTful API’s as the communication channel between both Puppet master and Puppet agents. Following is the basic URL to access this RESTful API.

https://brcleprod001:8140/{environment}/{resource}/{key} 
https://brcleprod001:8139/{environment}/{resource}/{key}

REST API Security

Puppet usually takes care of security and SSL certificate management. However, if one wishes to use the RESTful API outside the cluster one needs to manage the certificate on their own, when trying to connect to a machine. The security popcy for Puppet can be configured through the rest authconfig file.

Testing REST API

Curl utipty can be used as a basic utipty to rest RESTful API connectivity. Following is an example of how we can retrieve the catalog of node using REST API curl command.

curl --cert /etc/puppet/ssl/certs/brcleprod001.pem --key 
   /etc/puppet/ssl/private_keys/brcleprod001.pem

In the following set of commands we are just setting the SSL certificate, which will be different depending on where the SSL directory is and the name of the node being used. For example, let’s look at the following command.

curl --insecure -H  Accept: yaml  
https://brcleprod002:8140/production/catalog/brcleprod001 

In the above command, we just send a header specifying the format or formats we want back and a RESTful URL for generating a catalog of brcleprod001 in production environment, will generate a the following output.

--- &id001 !ruby/object:Puppet::Resource::Catalog 
apases: {} 
applying: false 
classes: [] 
...

Let’s assume another example, where we want to get the CA certificate back from Puppet master. It doesn’t require to be authenticated with own signed SSL certificate since that is something which is required before being authenticated.

curl --insecure -H  Accept: s  https://brcleprod001:8140/production/certificate/ca  

-----BEGIN CERTIFICATE----- 
MIICHTCCAYagAwIBAgIBATANBgkqhkiG9w0BAQUFADAXMRUwEwYDVQQDDAxwdXBw

Puppet Master and Agent Shared API Reference

GET /certificate/{ca, other}  

curl -k -H "Accept: s" https://brcelprod001:8140/production/certificate/ca 
curl -k -H "Accept: s" https://brcleprod002:8139/production/certificate/brcleprod002 

Puppet Master API Reference

Authenticated Resources (Vapd, signed certificate required).

Catalogs

GET /{environment}/catalog/{node certificate name} 

curl -k -H "Accept: pson" https://brcelprod001:8140/production/catalog/mycpent

Certificate Revocation List

GET /certificate_revocation_pst/ca 

curl -k -H "Accept: s" https://brcleprod001:8140/production/certificate/ca 

Certificate Request

GET /{environment}/certificate_requests/{anything} GET 
/{environment}/certificate_request/{node certificate name}  

curl -k -H "Accept: yaml" https://brcelprod001:8140/production/certificate_requests/all 
curl -k -H "Accept: yaml" https://brcleprod001:8140/production/certificate_request/puppetcpent 

Reports Submit a Report

PUT /{environment}/report/{node certificate name}  
curl -k -X PUT -H "Content-Type: text/yaml" -d "{key:value}" https://brcleprod002:8139/production

Node − Facts Regarding a Specific Node

GET /{environment}/node/{node certificate name}  

curl -k -H "Accept: yaml" https://brcleprod002:8140/production/node/puppetcpent 

Status − Used for Testing

GET /{environment}/status/{anything}  

curl -k -H "Accept: pson" https://brcleprod002:8140/production/certificate_request/puppetcpent

Puppet Agent API Reference

When a new agent is set up on any machine, by default Puppet agent does not psten to HTTP request. It needs to be enabled in Puppet by adding “psten=true” in puppet.conf file. This will enable Puppet agents to psten to HTTP request when the Puppet agent is starting up.

Facts

GET /{environment}/facts/{anything}  

curl -k -H "Accept: yaml" https://brcelprod002:8139/production/facts/{anything}

Run − Causes the cpent to update pke puppetturn or puppet kick.

PUT  /{environment}/run/{node certificate name}  

curl -k -X PUT -H "Content-Type: text/pson" -d "{}" 
https://brcleprod002:8139/production/run/{anything}