diff --git a/commercial/README.md b/commercial/README.md index 1cf9458b..61b22878 100644 --- a/commercial/README.md +++ b/commercial/README.md @@ -16,12 +16,15 @@ which you will run your Puppet Infrastructure. + [Code Manager Setup](#code-manager-setup) + [Verifying status](#verifying-status) - [Additional Customization](#further-customization) - + [puppet](#puppet) - + [pe-orchestration-services](#pe-orchestration-services) - + [pe-console-services](#pe-console-services) - + [pe-bolt-server](#pe-bolt-server) - + [puppetdb](#puppetdb) - + [postgres](#postgres) + + [Service-specific Docker configuration via environment variables](#Service-specific-docker-configuration-via-environment-variables) + * [puppet](#puppet) + * [pe-orchestration-services](#pe-orchestration-services) + * [pe-console-services](#pe-console-services) + * [pe-bolt-server](#pe-bolt-server) + * [puppetdb](#puppetdb) + * [postgres](#postgres) + + [External PostgreSQL](#external-postgresql) + + [External CA Support](#external-ca-support) - [Additional Information](#additional-information) @@ -192,6 +195,134 @@ The following values, many of which are already overriden in the `docker-compose | **PE_CONSOLE_SERVICES_CERTNAME** | The primary DNS name of the pe-console-services certificate

`pe-console-services` | | **PE_ORCHESTRATION_SERVICES_CERTNAME** | The primary DNS name on the pe-orchestration-services certificate

`pe-orchestration-services` | +## External PostgreSQL + +An external PostgreSQL database can be used instead of using a containerized version of Postgres. This requires setting the Postgres environment variables on the `puppet`, `pe-orchestration-services`, `pe-console-services` and `puppetdb` services and *removing* the `postgres` service and the `puppetdb-postgres` volume from the `docker-compose.yml` configuration. + +The PostgreSQL version should be 9.6 or newer. + +The databases `pe-classifier`, `pe-rbac`, `pe-activity`, `pe-inventory`, and `pe-orchestrator` all must exist. Each database requires the extensions `citext`, `pg_trgm`, `plpsql`, and `pgcrypto`. This may be setup by running the following SQL script: + +``` +CREATE DATABASE "pe-classifier" OWNER "puppetdb"; +CREATE DATABASE "pe-rbac" OWNER "puppetdb"; +CREATE DATABASE "pe-activity" OWNER "puppetdb"; +CREATE DATABASE "pe-inventory" OWNER "puppetdb"; +CREATE DATABASE "pe-orchestrator" OWNER "puppetdb"; + +\c "pe-rbac" +CREATE EXTENSION IF NOT EXISTS citext; +CREATE EXTENSION IF NOT EXISTS pg_trgm; +CREATE EXTENSION IF NOT EXISTS plpgsql; +CREATE EXTENSION IF NOT EXISTS pgcrypto; + +\c "pe-orchestrator" +CREATE EXTENSION IF NOT EXISTS citext; +CREATE EXTENSION IF NOT EXISTS pg_trgm; +CREATE EXTENSION IF NOT EXISTS plpgsql; +CREATE EXTENSION IF NOT EXISTS pgcrypto; + +\c "pe-inventory" +CREATE EXTENSION IF NOT EXISTS citext; +CREATE EXTENSION IF NOT EXISTS pg_trgm; +CREATE EXTENSION IF NOT EXISTS plpgsql; +CREATE EXTENSION IF NOT EXISTS pgcrypto; + +\c "puppetdb" +CREATE EXTENSION IF NOT EXISTS citext; +CREATE EXTENSION IF NOT EXISTS pg_trgm; +CREATE EXTENSION IF NOT EXISTS plpgsql; +CREATE EXTENSION IF NOT EXISTS pgcrypto; + +\c "pe-classifier" +CREATE EXTENSION IF NOT EXISTS citext; +CREATE EXTENSION IF NOT EXISTS pg_trgm; +CREATE EXTENSION IF NOT EXISTS plpgsql; + +\c "pe-activity" +CREATE EXTENSION IF NOT EXISTS citext; +CREATE EXTENSION IF NOT EXISTS pg_trgm; +CREATE EXTENSION IF NOT EXISTS plpgsql; + +-- used for the healthcheck SSL check +\c "postgres" +CREATE EXTENSION IF NOT EXISTS sslinfo; +``` + +### PostgreSQL SSL setup + +The PE services connections to PostgreSQL is only supported over SSL. + +#### postgresql.conf + +The PostgreSQL node will require the complete certificate authority certificate chain for the external party CA, in PEM format. In the default configuration, these files are stored in the `$PGDATA` directory. The follow settings must be enabled in `$PGDATA/postgresql.conf` to correctly enable SSL: + +``` +ssl=on +# Certificate for the trusted certificate authority (i.e. Puppet master) +ssl_ca_file=root.crt +# Certificate for Postgres, signed by the CA +ssl_cert_file=server.crt +# Certificate revocation list from the CA +ssl_crl_file=root.crl +# Private key for Postgres certificate +ssl_key_file=server.key +``` + +#### pg_ident.conf + +The `$PGDATA/pg_ident.conf` must map certificate names for `pe-console-services`, `pe-orchestration-services` and `puppetdb` services to the `puppetdb` user properly, like: + +``` +# MAPNAME SYSTEM-USERNAME PG-USERNAME +usermap pe-console-services.test puppetdb +usermap pe-orchestration-services.test puppetdb +usermap puppetdb.test puppetdb +``` + +#### pg_hba.conf + +Additionally, `$PGDATA/pg_hba.conf` must be configured with this line to enable the ssl connnections: + +``` +# TYPE DATABASE USER ADDRESS METHOD +hostssl all all all cert map=usermap +``` + +## External CA Support + +To use certificates from an external CA rather than using the ones generated by the Puppet master CA requires performing a few operations: + +* All the named volumes for the compose stack should be created. This can be done by executing `docker-compose up --no-start`. +* For each of the volumes for a given service, the appropriate certificate files should be copied to the correct location inside the volume using the [`docker cp SRC_PATH CONTAINER:DEST_PATH`](https://docs.docker.com/engine/reference/commandline/cp/) command. The specific path depends on the container. +* Entrypoint scripts will automatically change ownership and set permissions on SSL files when the containers first start. + +### Cert File Locations + +For the services `puppet`, `pe-orchestration-services`, `pe-console-services`, `pe-bolt-server` and `puppetdb`, the directory structure follows the following conventions. The value for `` will be one of: `puppetserver`, `orchestration-services`, `console-services`, `bolt-server`, or `puppetdb`. The full path is always available inside the container as the environment variable `$SSLDIR` + +- 'ssl-ca-cert' + `/opt/puppetlabs/server/data//certs/certs/ca.pem` + +- 'ssl-cert' + `/opt/puppetlabs/server/data//certs/certs/.pem` + +- 'ssl-key' + `/opt/puppetlabs/server/data//certs/private_keys/.pem` + +The Postgres container pathing is slightly different and cannot follow the same pathing structure due to the design of the Postgres container. Paths for Postgres are typically: + +- 'ssl-ca-cert' + `/var/lib/postgresql/data/certs/certs/ca.pem` + +- 'ssl-cert' + `/var/lib/postgresql/data/certs/certs/.pem` + +- 'ssl-key' + `/var/lib/postgresql/data/certs/private_keys/.pem` + +NOTE: The files at these paths are copied to the location that Postgres is configured to use when the container starts (details in prior section). + # Additional Information See https://github.com/puppetlabs/pupperware for more information.