Skip to content

Latest commit

 

History

History
79 lines (53 loc) · 8.12 KB

configuration-puppetdb.md

File metadata and controls

79 lines (53 loc) · 8.12 KB
Raw

Configuring octocatalog-diff to use PuppetDB

octocatalog-diff can interact with PuppetDB in the following ways:

  • Retrieving the most recent set of facts for a node
  • Query for exported resources during a Puppet run with storeconfigs enabled
  • Retrieving a catalog for a node

For this to work, you will need to configure or provide information about your PuppetDB server to octocatalog-diff. You can provide this information via a configuration file, via environment variables, or via command line parameters.

Required information

  • Version of PuppetDB: octocatalog-diff supports PuppetDB's query API v4, which requires that you be running PuppetDB 2.3 or higher.

  • URL to PuppetDB: This is the URL with the host name and port number to reach your PuppetDB instance. If you have already set up your Puppet master to communicate with PuppetDB, you can see the URL by reviewing /etc/puppetlabs/puppet/puppetdb.conf (on Puppet Server) or /etc/puppet/puppetdb.conf (on Puppet Master 3.x). The URL (or URLs) to your PuppetDB installation are visible in the server_urls configuration setting.

    To use basic authentication, place the username and password in the URL, e.g.:

    https://username:password@puppetdb.example.net:8081

  • SSL Authentication Information: Whether your PuppetDB instance requires clients to authenticate via SSL certificates. Unless you have made a special effort to configure your PuppetDB instance not to require client certificates, it is likely that client certificate authentication is required. Please see the separate section below concerning SSL certificates.

NOTE: In certain situations, you may need to define or alter the certificate-whitelist setting in your PuppetDB configuration to whitelist the certificate used by octocatalog-diff. Please see Configuring PuppetDB in the Puppet documentation for additional information.

Supplying necessary information via configuration files

The following settings can be used in a configuration file.

Setting Description
settings[:puppetdb_url] PuppetDB URL settings. If this is a string, it will set a single PuppetDB URL. If it is an array, it will set multiple URLs, which will be tried in a random order until one responds.
settings[:puppetdb_ssl_ca] Path to the certificate of the CA that signed PuppetDB's certificate. This file should contain only the public certificate, so it is safe to distribute to developer workstations or CI environments.
settings[:puppetdb_ssl_crl] Path to the Certificate Revocation List provided by Puppetserver.
settings[:puppetdb_ssl_client_cert] TEXT of the certificate of the client SSL keypair used to authenticate to PuppetDB. Note: This variable is not set to a file path, which means you will likely want to use File.read(...) if you are configuring this to be read from a file.
settings[:puppetdb_ssl_client_key] TEXT of the private key of the client SSL keypair used to authenticate to PuppetDB. Note: This variable is not set to a file path, which means you will likely want to use means you will likely want to use File.read(...) if you are configuring this to be read from a file.
settings[:puppetdb_ssl_client_pem] Concatenation of the text of puppetdb_ssl_client_key and puppetdb_ssl_client_cert as previously described. This is a good alternative if your certificate chain is complex and it's easier just to put everything in a single place. Note: this option is second in precedence; if settings[:puppetdb_ssl_client_cert] and settings[:puppetdb_ssl_client_key] are both set, this will be ignored.
settings[:puppetdb_ssl_client_password] Plain text string containing the password to unlock the private key. For keys generated by the Puppet Master CA, this is not required and should be left undefined.
settings[:puppetdb_token] TEXT containing the PE RBAC token used to authenticate to PuppetDB. Note: This variable is not set to a file path, which means you will likely want to use File.read(...) if you are configuring this to be read from a file.

Supplying necessary information via the command line

The following arguments can be used on the command line.

Setting Description
--puppetdb-url https://puppetdb.example.net:8081 PuppetDB URL. The argument should match the server_urls configuration setting as described previously. Please note that only one URL is supported via the command line method, so if you have multiple server_urls URLs specified, you can only choose one. To use multiple URLs for failover purposes, please configure via configuration files.
--puppetdb-ssl-ca FILENAME Path to the certificate of the CA that signed PuppetDB's certificate. This file should contain only the public certificate, so it is safe to distribute to developer workstations or CI environments.
--puppetdb-ssl-crl FILENAME Path to the Certificate Revocation List of the CA that signed PuppetDB's certificate.
--puppetdb-ssl-client-cert FILENAME Path to the certificate of the client SSL keypair.
--puppetdb-ssl-client-key FILENAME Path to the private key of the client SSL keypair.
--puppetdb-ssl-client-password PASSWORD_STRING Plain text string containing the password to unlock the private key. For keys generated by the Puppet Master CA, this is not required.
--puppetdb-token STRING String containing the PE RBAC token used to authenticate to PuppetDB.
--puppetdb-token-file FILENAME Path to the PE RBAC token file used to authenticate to PuppetDB.

Supplying necessary information via the environment

⚠️ While this method of configuring octocatalog-diff for use with PuppetDB is currently supported, we recommend that configuration is done via the command line or in configuration files.

Set the environment variable PUPPETDB_URL to match the server_urls configuration setting as described previously. Please note that only one URL is supported via the environment variable method, so if you have multiple server_urls URLs specified, you can only choose one. To use multiple URLs for failover purposes, please configure via configuration files.

Environment variable support is not currently available for SSL client authentication settings.

Notes about SSL certificates

SSL support is enabled via any of the --puppetdb-ssl-... command line options or puppetdb_ssl_... configuration settings as described above. Please note the following concerning these SSL certificates.

  • The CA certificate should be the public certificate of the CA that signed your PuppetDB server's certificate. This file can be found in /etc/puppetlabs/puppetdb/ssl/ca.pem on a PuppetDB server. Since this is a public certificate, it is safe (and recommended) to distribute this file to any clients that may connect to this PuppetDB instance.

  • The client keypair (key, certificate, and optionally password) should be generated individually for each client. You should NOT copy SSL keypairs from your PuppetDB server (or anywhere else) to your clients. If you are using octocatalog-diff on a system that is managed by Puppet, you may wish to use the same SSL credentials that the system uses to authenticate to Puppet. With recent versions of the Puppet agent, those certificates are found in /etc/puppetlabs/puppet/ssl.

Puppet Enterprise PuppetDB Package Inventory

Puppet Enterprise customers have an optional package inventory feature which can be enabled. When this feature is enabled an inventory of all system packages is performed and uploaded as a fact which is then processed and stored independently of the normal Facter data in PuppetDB. Most environments won't need to replicate the package inventory facts for testing with Octocatalog-Diff but if you want the package inventory data (if present) to be included in the facts retrieved from PuppetDB by Octocatalog-Diff you should specify the --puppetdb-package-inventory flag. When enabled, this flag will instruct Octocatalog-Diff to retrieve any package data found for a node from PuppetDB and include it in the facts used during the Octocatalog-Diff compile.