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 policy for Puppet can be configured through the rest authconfig file.

Testing REST API

Curl utility can be used as a basic utility 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 
aliases: {} 
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 (Valid, signed certificate required).

Catalogs

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

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

Certificate Revocation List

GET /certificate_revocation_list/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/puppetclient

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/puppetclient

Status − Used for Testing

GET /{environment}/status/{anything}  

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

Puppet Agent API Reference

When a new agent is set up on any machine, by default Puppet agent does not listen to HTTP request. It needs to be enabled in Puppet by adding “listen=true” in puppet.conf file. This will enable Puppet agents to listen 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 client to update like 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}
Advertisements