(maint) Update documentation with how to use SSL connections

And fix the puppetdb_host in the pg_ident rule.

Author: Filipovici-Andrei

README.md

@@ -85,6 +85,7 @@ your manifest will look like:
     node <hostname> {
       # Configure puppetdb and its underlying database
       class { 'puppetdb': }
+      
       # Configure the Puppet master to use puppetdb
       class { 'puppetdb::master::config': }
     }
@@ -133,6 +134,55 @@ This should be all it takes to get a 3-node, distributed installation of
 PuppetDB up and running. Note that, if you prefer, you could easily move two of
 these classes to a single node and end up with a 2-node setup instead.
 
+### Enable SSL connections
+
+To use SSL connections for the single node setup, use the following manifest:
+
+    node <hostname> {
+      # Here we configure puppetdb and PostgreSQL to use ssl connections
+      class { 'puppetdb':
+        postgresql_ssl_on => true,
+        database_host => '<hostname>',
+        database_listen_address => '0.0.0.0'
+      }
+      
+      # Configure the Puppet master to use puppetdb
+      class { 'puppetdb::master::config': }
+
+To use SSL connections for the multiple nodes setup, use the following manifest:
+
+    $puppetdb_host = 'puppetdb.example.lan'
+    $postgres_host = 'postgres.example.lan'
+
+    node 'master.example.lan' {
+      # Here we configure the Puppet master to use PuppetDB,
+      # telling it the hostname of the PuppetDB node.
+      class { 'puppetdb::master::config':
+        puppetdb_server => $puppetdb_host,
+      }
+    }
+
+    node 'postgres.example.lan' {
+      # Here we install and configure PostgreSQL and the PuppetDB
+      # database instance, and tell PostgreSQL that it should
+      # listen for connections to the `$postgres_host`. 
+      # We also enable SSL connections.
+      class { 'puppetdb::database::postgresql':
+        listen_addresses => $postgres_host,
+        postgresql_ssl_on => true,
+        puppetdb_server => $puppetdb_host
+      }
+    }
+
+    node 'puppetdb.example.lan' {
+      # Here we install and configure PuppetDB, and tell it where to
+      # find the PostgreSQL database. We also enable SSL connections.
+      class { 'puppetdb::server':
+        database_host => $postgres_host,
+        postgresql_ssl_on => true
+      }
+    }
+
 ### Beginning with PuppetDB
 
 Whether you choose a single node development setup or a multi-node setup, a
@@ -360,6 +410,11 @@ If true, open the `ssl_listen_port` on the firewall. Defaults to `undef`.
 
 Specify the supported SSL protocols for PuppetDB (e.g. TLSv1, TLSv1.1, TLSv1.2.)
 
+### `postgresql_ssl_on`
+
+If `true`, it configures SSL connections between PuppetDB and the PostgreSQL database.
+Defaults to `false`.
+
 #### `cipher_suites`
 
 Configure jetty's supported `cipher-suites` (e.g. `SSL_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384`).

manifests/database/postgresql.pp

@@ -2,6 +2,7 @@
 # information.
 class puppetdb::database::postgresql(
   $listen_addresses            = $puppetdb::params::database_host,
+  $puppetdb_server             = $puppetdb::params::puppetdb_server,
   $database_name               = $puppetdb::params::database_name,
   $database_username           = $puppetdb::params::database_username,
   $database_password           = $puppetdb::params::database_password,
@@ -34,6 +35,7 @@
       class { 'puppetdb::database::ssl_configuration':
         database_name               => $database_name,
         database_username           => $database_username,
+        puppetdb_server             => $puppetdb_server,
         postgresql_ssl_key_path     => $postgresql_ssl_key_path,
         postgresql_ssl_cert_path    => $postgresql_ssl_cert_path,
         postgresql_ssl_ca_cert_path => $postgresql_ssl_ca_cert_path

manifests/database/ssl_configuration.pp

@@ -3,6 +3,7 @@
 class puppetdb::database::ssl_configuration(
   $database_name               = $puppetdb::params::database_name,
   $database_username           = $puppetdb::params::database_username,
+  $puppetdb_server             = $puppetdb::params::puppetdb_server,
   $postgresql_ssl_key_path     = $puppetdb::params::postgresql_ssl_key_path,
   $postgresql_ssl_cert_path    = $puppetdb::params::postgresql_ssl_cert_path,
   $postgresql_ssl_ca_cert_path = $puppetdb::params::postgresql_ssl_ca_cert_path
@@ -74,7 +75,7 @@
 
   postgresql::server::pg_ident_rule {"Map the SSL certificate of the server as a ${database_username} user":
     map_name          => $identity_map_key,
-    system_username   => $::fqdn,
+    system_username   => $puppetdb_server,
     database_username => $database_username,
   }
 }

manifests/init.pp

@@ -57,6 +57,7 @@
   $puppetdb_service_status                 = $puppetdb::params::puppetdb_service_status,
   $puppetdb_user                           = $puppetdb::params::puppetdb_user,
   $puppetdb_group                          = $puppetdb::params::puppetdb_group,
+  $puppetdb_server                         = $puppetdb::params::puppetdb_server,
   $read_database                           = $puppetdb::params::read_database,
   $read_database_host                      = $puppetdb::params::read_database_host,
   $read_database_port                      = $puppetdb::params::read_database_port,
@@ -184,6 +185,7 @@
     class { '::puppetdb::database::postgresql':
       listen_addresses    => $database_listen_address,
       database_name       => $database_name,
+      puppetdb_server     => $puppetdb_server,
       database_username   => $database_username,
       database_password   => $database_password,
       database_port       => $database_port,

manifests/params.pp

@@ -36,6 +36,7 @@
   $jdbc_ssl_properties    = ''
   $database_validate      = true
   $database_max_pool_size = undef
+  $puppetdb_server        = $::fqdn
 
   # These settings manage the various auto-deactivation and auto-purge settings
   $node_ttl               = '7d'

spec/unit/classes/database/ssl_configuration_spec.rb

@@ -118,5 +118,22 @@
         .with_system_username(facts[:fqdn])
         .with_database_username(params[:database_name])
     end
+
+    context 'when the puppetdb_server is set' do
+      let(:params) do
+        {
+          puppetdb_server: 'puppetdb_fqdn',
+          database_name: 'puppetdb',
+          database_username: 'puppetdb',
+        }
+      end
+
+      it 'has ident rule with the specified puppetdb_server host' do
+        is_expected.to contain_postgresql__server__pg_ident_rule("Map the SSL certificate of the server as a #{params[:database_username]} user")
+          .with_map_name(identity_map)
+          .with_system_username(params[:puppetdb_server])
+          .with_database_username(params[:database_name])
+      end
+    end
   end
 end

spec/unit/classes/init_spec.rb

@@ -71,11 +71,18 @@ class { 'postgresql::server':
         let(:params) do
           {
             postgresql_ssl_on: true,
+            puppetdb_server: 'puppetdb_host',
           }
         end
 
         it { is_expected.to contain_class('puppetdb::server').with('postgresql_ssl_on' => true) }
-        it { is_expected.to contain_class('puppetdb::database::postgresql').with('postgresql_ssl_on' => true) }
+        it {
+          is_expected.to contain_class('puppetdb::database::postgresql')
+            .with(
+              'postgresql_ssl_on' => true,
+              'puppetdb_server' => 'puppetdb_host',
+            )
+        }
       end
     end
   end