Puppet Enterprise 2017.3

By default, Puppet Enterprise includes its own database backend, PE-PostgreSQL, which is installed alongside PuppetDB. You can optionally install a separate, standalone instance of PE-PostgreSQL or use an external PostgreSQL instance instead. 

Install standalone PE-PostgreSQL

You can install a separate, standalone instance of PE-PostgreSQL if you don't want to use the database that's installed by default alongside PuppetDB.

Before you begin

You must have root access to the node on which you plan to install PE-PostgreSQL, as well as the ability to SSH and copy files to the node.

  1. Prepare your pe.conf file by specifying parameters required for PostgreSQL

    "puppet_enterprise::puppet_master_host": "<MASTER OF MASTERS HOSTNAME>" "puppet_enterprise::console_admin_password": "<CONSOLE ADMIN PASSWORD>" "puppet_enterprise::database_host": "<PE-POSTGRESQL NODE HOSTNAME>"

  2. Follow the instructions to Install using text mode (mono configuration), running the installer with the -c flag.

    The installer fails halfway through, because it can't contact the database. Components that rely on the database also fail to start. The next installation run corrects this issue.

  3. Copy the pe.conf file you created to the PE-PostgreSQL node and SSH into that node.
  4. Run the installer with the -c flag, using the same pe.conf file.
  5. When the installation process finishes on the PE-PostgreSQL node, SSH into the master of masters and complete the installation:
    puppet infrastructure configure; puppet agent -t;

    The master of masters is configured to use the standalone PE-PostgreSQL installation on the PE-PostgreSQL node.

Install external PostgreSQL

You can configure an external PostgreSQL database to work with PE by setting up SSL between PE and an external PostgreSQL database. This configuration enables use of services such as Amazon RDS PostgreSQL, where non-root users typically don't have access to the file system or the ability to manage certificates.

Before you begin
You must have:
  • PostgreSQL 9.6 or later.

  • The complete certificate authority certificate chain for the external party CA, in PEM format.

  • The DNS-addressable name, username, and password for the external PostgreSQL database.

Set up your external PostgreSQL instance and create PE databases before installing PE. During installation with the web-based installer, select to Use an existing PostgreSQL instance. After PE is installed, you can then establish SSL between PE and your external PostgreSQL instance.  

Warning: The procedure in this document has been created and verified by Puppet Professional Services engineers. It has not gone through the usual quality assurance process. Before undertaking any of these procedures, we strongly advise that you review them thoroughly and test them in non-production environments. Beyond validation from our Professional Services engineers, Puppet does not offer support for this procedure outside of a Professional Services engagement.

Create the external PostgreSQL instance

Create the external PostgreSQL instance, and,if you haven't already, retrieve the necessary certificate chain and credentials from your database administrator.

For example, for RDS, the root certificate is available here.

Create PE databases on the PostgreSQL instance

  1. Log in to the external PostgreSQL instance with the client of your choice.
  2. Create databases for the orchestrator, RBAC, activity service, and the node classifier.
    CREATE USER "pe-puppetdb" PASSWORD '<PASSWORD>';
    GRANT "pe-puppetdb" TO <ADMIN USER>;
    CREATE DATABASE "pe-puppetdb" OWNER "pe-puppetdb"
    ENCODING 'utf8' LC_CTYPE 'en_US.utf8' LC_COLLATE 'en_US.utf8' template template0;
    
    CREATE USER "pe-orchestrator" PASSWORD '<PASSWORD>';
    GRANT "pe-orchestrator" TO <ADMIN USER>;
    CREATE DATABASE "pe-orchestrator" OWNER "pe-orchestrator"
    ENCODING 'utf8' LC_CTYPE 'en_US.utf8' LC_COLLATE 'en_US.utf8' template template0;
    
    CREATE USER "pe-activity" PASSWORD '<PASSWORD>';
    GRANT "pe-activity" TO <ADMIN USER>;
    CREATE DATABASE "pe-activity" OWNER "pe-activity"
    ENCODING 'utf8' LC_CTYPE 'en_US.utf8' LC_COLLATE 'en_US.utf8' template template0;
    
    CREATE USER "pe-classifier" PASSWORD '<PASSWORD>';
    GRANT "pe-classifier" TO <ADMIN USER>;
    CREATE DATABASE "pe-classifier" OWNER "pe-classifier"
    ENCODING 'utf8' LC_CTYPE 'en_US.utf8' LC_COLLATE 'en_US.utf8' template template0;
    
    CREATE USER "pe-rbac" PASSWORD '<PASSWORD>';
    GRANT "pe-rbac" TO <ADMIN USER>;
    CREATE DATABASE "pe-rbac" OWNER "pe-rbac"
    ENCODING 'utf8' LC_CTYPE 'en_US.utf8' LC_COLLATE 'en_US.utf8' template template0;
    
    \c "pe-rbac"
    CREATE EXTENSION citext;
    CREATE EXTENSION pg_trgm;
    CREATE EXTENSION plpgsql;
    CREATE EXTENSION pgcrypto;
    
    \c "pe-orchestrator"
    CREATE EXTENSION citext;
    CREATE EXTENSION pg_trgm;
    CREATE EXTENSION plpgsql;
    
    \c "pe-puppetdb"
    CREATE EXTENSION citext;
    CREATE EXTENSION pg_trgm;
    CREATE EXTENSION plpgsql;
    CREATE EXTENSION pgcrypto;
    
    \c "pe-classifier"
    CREATE EXTENSION citext;
    CREATE EXTENSION pg_trgm;
    CREATE EXTENSION plpgsql;
    
    \c "pe-activity"
    CREATE EXTENSION citext;
    CREATE EXTENSION pg_trgm;
    CREATE EXTENSION plpgsql;

Next, install PE. If you use the web-based installer, select to Use an existing PostgreSQL instance and specify details about your PostgreSQL configuration.

Establish SSL between PE and the external PostgreSQL instance

Before you begin

Install PE. If you use the web-based installer, select to Use an existing PostgreSQL instance and specify details about your PostgreSQL configuration.

  1. Log in to the master (monolithic installation) or into the master, console, and PuppetDB nodes (split installation), and stop the agent service:
    /opt/puppetlabs/puppet/bin/puppet resource service puppet ensure=stopped
  2. On the master (monolithic installation), or on the console and PuppetDB nodes (split installation), create a location to store the CA cert from the external PostgreSQL instance, for example /etc/puppetlabs/puppet/ssl/.
  3. Transfer the CA cert from the external PostgreSQL instance to the directories that you created.
  4. Ensure that the certificate and directories are owned by the pe-puppet user: chown -R pe-puppet:pe-puppet <PATH TO DIRECTORY>
  5. Update PE Infrastructure classification to require SSL for database connections.
    1. In the console, click Classification, and select the PE Infrastructure node group.
    2. On the Configuration tab, find the class puppet_enterprise, specify paramaters, then click Add parameter and commit changes.
      ParameterValue
      database_ssl true
  6. Update PE PuppetDB classification to provide the database properties.
    1. In the console, click Classification, and in the PE Infrastructure node group, select the PE PuppetDB node group.
    2. On the Configuration tab, find the class puppet_enterprise::profile::puppetdb, specify paramaters, then click Add parameter and commit changes.
      ParameterValue
      database_properties ?ssl=true&sslfactory=org.postgresql.ssl.jdbc4.LibPQFactory&sslmode=verify-full&sslrootcert=<PATH TO EXTERNAL POSTGRESQL CA CERT>
  7. Navigate to the /etc/puppetlabs/console-services/conf.d file and add required subname settings to configuration files. 
    Configuration filesubname setting
    activity-database.conf "//<POSTGRESQL_SERVER_HOSTNAME>:5432/pe-activity?ssl=true&sslfactory=org.postgresql.ssl.jdbc4.LibPQFactory&sslmode=verify-full&sslrootcert=<PATH TO EXTERNAL POSTGRESQL CA CERT>"
    classifier-database.conf "//<POSTGRESQL_SERVER_HOSTNAME>:5432/pe-classifier?ssl=true&sslfactory=org.postgresql.ssl.jdbc4.LibPQFactory&sslmode=verify-full&sslrootcert=<PATH TO EXTERNAL POSTGRESQL CA CERT>"
    rbac-database.conf "//<POSTGRESQL_SERVER_HOSTNAME>:5432/pe-rbac?ssl=true&sslfactory=org.postgresql.ssl.jdbc4.LibPQFactory&sslmode=verify-full&sslrootcert=<PATH TO EXTERNAL POSTGRESQL CA CERT>"
  8. On the master (monolithic installation) or console node (split installation), reload pe-console-services: service pe-console-services reload
  9. On the master (monolithic installation) or on the console and PuppetDB nodes (split installation), start the agent service: puppet resource service puppet ensure=running
  10. On the master (monolithic installation) or on the console node (split installation), run Puppet.

External PostgreSQL options for web-based installation

During a web-based installation, if you select to Use an existing PostgreSQL instance, you must specify these details about your PostgreSQL configuration.

OptionDefault
PostgreSQL server DNS name
Port number used by the PostgreSQL server5432
PuppetDB database namepe-puppetdb
PuppetDB database userpe-puppetdb
PuppetDB database password
RBAC database namepe-rbac
RBAC database userpe-rbac
RBAC database password
Node classifier database namepe-classifier
Node classifier database userpe-classifier
Node classifier database password
Activity database namepe-activity
Activity database userpe-activity
Activity database password
Orchestrator database namepe-orchestrator
Orchestrator database userpe-orchestrator
Orchestrator database password
Back to top