Merge pull request #9 from github/kpaulisse-pe-doc-update

Update documentation and examples for puppetdb SSL settings

Author: kpaulisse

doc/configuration-puppetdb.md

@@ -16,6 +16,8 @@ For this to work, you will need to configure or provide information about your P
 
 - **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.
 
+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](https://docs.puppet.com/puppetdb/latest/configure.html#certificate-whitelist) in the Puppet documentation for additional information.
+
 ## Supplying necessary information via configuration files
 
 The following settings can be used in a [configuration file](/doc/configuration.md).
@@ -24,8 +26,9 @@ The following settings can be used in a [configuration file](/doc/configuration.
 | --- | --- |
 | `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 is typically found in `/etc/puppetlabs/puppetdb/ssl/ca.pem` on your PuppetDB server. This file should contain only the public certificate, so it is safe to distribute to developer workstations or CI environments. |
-| `settings[:puppetdb_ssl_client_cert]` | Path to the certificate of the client SSL keypair. You should generate a keypair specifically for this client (or if you are running this on a machine managed by Puppet, you may be able to use the keypair for the client machine). You should **NOT** copy the certificate from your PuppetDB server itself. |
-| `settings[:puppetdb_ssl_client_key]` | Path to the private key of the client SSL keypair. You should generate a keypair specifically for this client (or if you are running this on a machine managed by Puppet, you may be able to use the keypair for the client machine). You should **NOT** copy the private key from your PuppetDB server itself. |
+| `settings[:puppetdb_ssl_client_cert]` | TEXT of the certificate of the client SSL keypair. You should generate a keypair specifically for this client (or if you are running this on a machine managed by Puppet, you may be able to use the keypair for the client machine). You should **NOT** copy the certificate from your PuppetDB server itself. Note: This variable needs to be set to the TEXT of the certificate, and not the file path. This 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]` | Path to the private key of the client SSL keypair. You should generate a keypair specifically for this client (or if you are running this on a machine managed by Puppet, you may be able to use the keypair for the client machine). You should **NOT** copy the private key from your PuppetDB server itself.  Note: This variable needs to be set to the TEXT of the key, and not the file path. This 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. |
 
 ## Supplying necessary information via the command line

examples/octocatalog-diff.cfg.rb

@@ -76,19 +76,36 @@ def self.config
       # puppetdb_ssl_client_key
       # puppetdb_ssl_client_password
       # puppetdb_ssl_client_cert
+      # puppetdb_ssl_client_pem
+      #
+      #   This sets up SSL authentication for PuppetDB.
+      #
       #   For SSL authentication, the key and certificate used for SSL client authentication.
       #   Don't set these if your PuppetDB is unauthenticated. The provided example may work if you
       #   run octocatalog-diff on a machine managed by Puppet, and your PuppetDB authenticates
-      #   clients with that same CA. Otherwise, just provide the actual path to the key and the
+      #   clients with that same CA. Otherwise, fill in the actual path to the key and the
       #   certificate in the relevant settings. If the key is password protected, set
       #   :puppetdb_ssl_client_password to the text of the password.
+      #
+      #   You can configure this in one of two ways:
+      #     1. Set `puppetdb_ssl_client_key` and `puppetdb_ssl_client_cert` individually.
+      #     2. Set `puppetdb_ssl_client_pem` to the concatenation of the key and the certificate.
+      #
+      #   VERY IMPORTANT: settings[:puppetdb_ssl_client_key], settings[:puppetdb_ssl_client_cert], and
+      #     settings[:puppetdb_ssl_client_pem] need to be set to the TEXT OF THE CERTIFICATE/KEY, not
+      #     just the file name of the certificate. You'll probably need to use something like this:
+      #        settings[:puppetdb_ssl_client_WHATEVER] = File.read("...")
+      #
       #   More: https://github.com/github/octocatalog-diff/blob/master/doc/configuration-puppetdb.md
       ##############################################################################################
 
       # require 'socket'
       # fqdn = Socket.gethostbyname(Socket.gethostname).first
-      # settings[:puppetdb_ssl_client_key] = "/etc/puppetlabs/puppet/ssl/private_keys/#{fqdn}.pem"
-      # settings[:puppetdb_ssl_client_cert] = "/etc/puppetlabs/puppet/ssl/certs/#{fqdn}.pem"
+      # settings[:puppetdb_ssl_client_key] = File.read("/etc/puppetlabs/puppet/ssl/private_keys/#{fqdn}.pem")
+      # settings[:puppetdb_ssl_client_cert] = File.read("/etc/puppetlabs/puppet/ssl/certs/#{fqdn}.pem")
+
+      # For keys generated by Puppet, passwords are not needed so the next setting can be left commented.
+      # If you generated your own key outside of Puppet and it has a password, specify it here.
       # settings[:puppetdb_ssl_client_password] = 'your-password-here'
 
       ##############################################################################################