.gitattributes

@@ -0,0 +1 @@
+*.png filter=lfs diff=lfs merge=lfs -text

README.md

@@ -0,0 +1,68 @@
+# Puppet Enterprise Extra Large
+
+This Puppet module contains profile classes used to deploy an at-scale Puppet Enterprise architecture.
+
+It SHOULD contain instructions for how to set that all up, too. Right now it doesn't. Big To-do.
+
+Note pending more detailed instructions:
+
+* This deployment depends on and assumes the use of trusted facts. Specifically, `pp_role` and `pp_environment`.
+* This deployment assumes that at least for PE infrastructure nodes, Puppet certnames are correct, resolvable FQDNs.
+* This deployment assumes the control repository to manage PE is independent of the normal "customer" control-repo.
+
+## Documentation
+
+See this README file and any documents in the [docs](docs) directory.
+
+## Architecture
+
+![architecture](docs/images/architecture.png)
+
+## Installation
+
+These are just sketched out instructions right now. It's likely there are big gaps still.
+
+### Prepare the Control Repositories
+
+You'll need two control repositories configured. One dedicated to managing Puppet Enterprise nodes (consider it kinda like an appliance), and another for your regular Puppet code used to manage your infrastructure.
+
+### Installing the Primary Master
+
+1. Download and extract the Puppet Enterprise installer
+2. Place the csr\_attributes.yaml file from installer/primary-master in /etc/puppetlabs/puppet/csr\_attributes.yaml
+3. Place the pe.conf file from installer/primary-master in the working directory, and edit it to fill in required values
+4. Run the installer, passing the appropriate flags to use the prepared pe.conf file
+5. Set up the ssh private keys needed to access the configured control repositories
+6. For each environment configured (however many you want to initially deploy), run e.g.
+
+        puppet code deploy production --wait
+        puppet code deploy pe_production --wait
+
+7. Using the same list of environments deployed above, run e.g.
+
+        puppet apply --environment pe_production --exec '
+          class { "pe_xl::node_manager":
+            environments => ["production", "pe_production"],
+          }
+        '
+
+5. Perform the PuppetDB Database installation (described below)
+6. Run `puppet agent -t`
+
+### Installing the PuppetDB Database
+
+1. Download and extract the Puppet Enterprise installer
+2. Place the csr\_attributes.yaml file from installer/puppetdb-database in /etc/puppetlabs/puppet/csr\_attributes.yaml
+3. Place the pe.conf file from installer/puppetdb-database in the working directory, and edit it to fill in required values
+4. Run the installer, passing the appropriate flags to use the prepared pe.conf file
+5. Finish the Primary Master installation (described above)
+6. Run `puppet agent -t`
+
+### Installing a Compile Master
+
+```
+curl -k https://primary-master.example.com:8140/packages/current/install.bash | sudo bash -s \
+  main:certname=<certname> \
+  extension_requests:pp_role="pe_xl::compile_master" \
+  extension_requests:pp_environment="pe_production"
+```

docs/basic_usage.md

@@ -0,0 +1,80 @@
+# Basic usage
+
+This is a base reference implementation. Once a base stack is stood up, you may need to continue and perform additional configuration and adjustments to reach your target state, depending on your use case.
+
+The reference implementation currently includes Task Plans to install, configure, and later upgrade a new Extra Large HA stack.
+
+The current versions of those plans can be found at:
+
+* [install.pp](https://github.com/reidmv/reidmv-pe_xl/blob/master/plans/install.pp)
+* [configure.pp](https://github.com/reidmv/reidmv-pe_xl/blob/master/plans/configure.pp)
+* [upgrade.pp](https://github.com/reidmv/reidmv-pe_xl/blob/master/plans/upgrade.pp)
+
+These are still a work in progress and lack documentation. Reading through them can give you an idea of what steps we've found to be required to deploy and configure all of the Puppet Enterprise components.
+
+Besides getting everything installed the key configuration that makes this work is laid out in four classification groups. Links provided below to a Markdown document that describes the groups, and also to the Puppet manifest that actually configures them:
+
+* [classification.md](https://github.com/reidmv/reidmv-pe_xl/blob/master/docs/classification.md)
+* [configure\_node\_groups.pp](https://github.com/reidmv/reidmv-pe_xl/blob/master/tasks/configure_node_groups.pp)
+
+The reference implementation uses trusted facts to put nodes in the right groups. Because the important puppet\_enterprise::\* class parameters and data are specified in the console, it should also be safe to have a pe.conf present on both the primary master, and the primary master replica nodes.
+
+## Basic usage instructions
+
+1. Ensure the hostname of each system is set correctly, to the same value that will be used to connect to the system, and refer to the system as. If the hostname is not set as expected the installation plan will refuse to continue.
+2. Install Bolt on a jumphost. This can be the primary master, or any other system.
+3. Download or git clone the pe\_xl module and put it somewhere on the jumphost, e.g. ~/modules/pe\_xl.
+4. Create an inventory file with connection information. Example included below. Available Bolt configuration options are documented here.
+5. Create a parameters file. Example included below. Note at the top of the file are arguments which dictate which plans should be run, such as install+configure.
+6. Run the pe\_xl plan with the inputs created. Example:
+
+        bolt plan run pe_xl \
+          --inventory nodes.yaml \
+          --modulepath ~/modules \
+          --params @params.json 
+
+Example nodes.yaml Bolt inventory file:
+
+```yaml
+---
+groups:
+  - name: pe_xl_nodes
+    config:
+      transport: ssh
+      ssh:
+        host-key-check: false
+        user: centos
+        run-as: root
+        tty: true
+    nodes:
+      - pe-xl-core-0.lab1.puppet.vm
+      - pe-xl-core-1.lab1.puppet.vm
+      - pe-xl-core-2.lab1.puppet.vm
+      - pe-xl-core-3.lab1.puppet.vm
+      - pe-xl-compilemaster-0.lab1.puppet.vm
+      - pe-xl-compilemaster-1.lab1.puppet.vm
+```
+
+Example params.json Bolt parameters file:
+
+```json
+{
+  "install": true,
+  "configure": true,
+  "upgrade": false,
+
+  "primary_master_host": "pe-xl-core-0.lab1.puppet.vm",
+  "puppetdb_database_host": "pe-xl-core-1.lab1.puppet.vm",
+  "primary_master_replica_host": "pe-xl-core-2.lab1.puppet.vm",
+  "puppetdb_database_replica_host": "pe-xl-core-3.lab1.puppet.vm",
+  "compile_master_hosts": [
+    "pe-xl-compilemaster-0.lab1.puppet.vm",
+    "pe-xl-compilemaster-1.lab1.puppet.vm"
+  ],
+
+  "console_password": "puppetlabs",
+  "dns_alt_names": [ "puppet", "puppet.lab1.puppet.vm" ],
+  "compile_master_pool_address": "puppet.lab1.puppet.vm",
+  "version": "2018.1.4"
+}
+```

docs/classification.md

@@ -0,0 +1,75 @@
+# PE Extra Large architecture classification #
+
+## Overview
+
+This reference implementation uses four non-default node classification groups to implement the Extra Large HA architecture. Intentionally, classification of default, out-of-box node groups is not modified. This allows normal commands such as `puppet infrastructure enable replica` to behave more or less exactly as they would in Standard or Large architecture deployments.
+
+This image shows a fully expanded view of the PE Infrastructure node group, highlighting the new additions made to support the Extra Large archtecture.
+
+![PE Classification tree](images/pe-xl-classification.png)
+
+## Node Groups
+
+The new groups are:
+
+* PE Master A
+* PE Master B
+* PE Compile Master Group A
+* PE Compile Master Group B
+
+The configuration applied in each group looks as follows:
+
+### PE Master A
+
+![PE Master A group](images/pe-master-a.png)
+
+Notes for PE Master A:
+
+* The (initial) Primary Master is the only member of this node group
+* Sets as data two parameters
+    * `puppet_enterprise::profile::primary_master_replica::database_host_puppetdb`
+    * `puppet_enterprise::profile::puppetdb::database_host`
+* Sets both parameters to the name of the PuppetDB PostgreSQL node paired with this master
+* Uses a different PuppetDB PostgreSQL node than PE Master B
+
+### PE Master B
+![PE Master B group](images/pe-master-b.png)
+
+Notes for PE Master B:
+
+* The (initial) Primary Master Replica is the only member of this node group
+* Sets as data two parameters
+    * `puppet_enterprise::profile::primary_master_replica::database_host_puppetdb`
+    * `puppet_enterprise::profile::puppetdb::database_host`
+* Sets both parameters to the name of the PuppetDB PostgreSQL node paired with this master
+* Uses a different PuppetDB PostgreSQL node than PE Master A
+
+### PE Compile Master Group A
+![PE Compile Master Group A group](images/pe-compile-master-group-a.png)
+
+Notes for PE Compile Master Group A:
+
+* Half of the compile masters are members of this group
+* Applies the `puppet_enterprise::profile::puppetdb` class
+* Sets the `puppet_enterprise::profile::puppetdb::database_host` parameter
+    * Should be set to `"pdb-pg-a"`, where "pdb-pg-a" is the name of the PuppetDB PostgreSQL database host paired with the (initial) Primary Master
+* Modifies the `puppet_enterprise::profile::master::puppetdb_host` parameter
+    * Should be set to `[${clientcert}, "master-b"]`, where "master-b" is the name of the (initial) Primary Master Replica.
+    * If you have a load balancer for the compile masters in PE Compile Master Group B port 8081, you should use that load balancer address instead of "master-b"
+* Modifies the `puppet_enterprise::profile::master::puppetdb_port` parameter
+    * Should be set to `[8081]`
+
+### PE Compile Master Group B
+![PE Compile Master Group B group](images/pe-compile-master-group-b.png)
+
+Notes for PE Compile Master Group B:
+
+* The other half of the compile masters (those not in the PE Compile Master Group A node group) are members of this group
+* Applies the `puppet_enterprise::profile::puppetdb` class
+* Sets the `puppet_enterprise::profile::puppetdb::database_host` parameter
+    * Should be set to `"pdb-pg-b"`, where "pdb-pg-b" is the name of the PuppetDB PostgreSQL database host paired with the (initial) Primary Master Replica
+* Modifies the `puppet_enterprise::profile::master::puppetdb_host` parameter
+    * Should be set to `[${clientcert}, "master-a"]`, where "master-a" is the name of the PuppetDB PostgreSQL node paired with the (initial) Primary Master Replica.
+    * If you have a load balancer for the compile masters in PE Compile Master Group A port 8081, you should use that load balancer address instead of "master-a"
+* Modifies the `puppet_enterprise::profile::master::puppetdb_port` parameter
+    * Should be set to `[8081]`

examples/ruby_task.rb

@@ -0,0 +1,28 @@
+#!/opt/puppetlabs/puppet/bin/ruby
+require 'json'
+require 'logger'
+require 'open3'
+
+# Parameters expected:
+#   Hash
+#     String mom_host
+#     String database_host
+#     Boolean debug
+$params = JSON.parse(STDIN.read)
+
+$logger = Logger.new(STDOUT)
+$logger.level = $params['debug'] ? Logger::DEBUG : Logger::INFO
+
+def main
+end
+
+def run_command(*command)
+  stdout, status = Open3.capture2(*command)
+  unless status.success?
+    @logger.error "while running command: #{command}"
+    @logger.error stdout
+  end
+  stdout
+end
+
+main

functions/flatten_compact.pp

@@ -0,0 +1,11 @@
+function pe_xl::flatten_compact (
+  Array $input,
+) {
+  $input.flatten.reduce([]) |$output, $value| {
+    if ($value == undef) {
+      $output
+    } else {
+      $output << $value
+    }
+  }
+}

functions/install_module.pp

@@ -0,0 +1,29 @@
+function pe_xl::install_module(
+  String[1] $target,
+  String[1] $module,
+  String[1] $version,
+  String[1] $stagingdir = '/tmp',
+) {
+
+  $module_tarball = "${module.regsubst('/', '-')}-${version}.tar.gz"
+
+  pe_xl::retrieve_and_upload(
+    "https://forge.puppet.com/v3/files/${module_tarball}",
+    "${stagingdir}/${module_tarball}",
+    "/tmp/${module_tarball}",
+    $target
+  )
+
+  run_command(@("HEREDOC"), $target)
+    /opt/puppetlabs/bin/puppet module install \
+      --modulepath /etc/puppetlabs/code-staging/environments/production/modules \
+      --ignore-dependencies \
+      /tmp/$module_tarball
+    | HEREDOC
+
+  run_command('chown -R pe-puppet:pe-puppet /etc/puppetlabs/code-staging', $target)
+  run_task('pe_xl::code_manager', $target,
+    action => 'commit',
+  )
+
+}

functions/retrieve_and_upload.pp

@@ -0,0 +1,33 @@
+function pe_xl::retrieve_and_upload(
+  $source,
+  $local_path,
+  $upload_path,
+  $target,
+) {
+  $exists = without_default_logging() || {
+    run_command("test -e '${local_path}'", 'local://localhost',
+      _catch_errors => true,
+    ).ok()
+  }
+
+  unless $exists {
+    run_task('pe_xl::download', 'local://localhost',
+      source => $source,
+      path   => $local_path,
+    )
+  }
+
+  $local_size = run_task('pe_xl::filesize', 'local://localhost',
+    path => $local_path,
+  ).first['size']
+
+  $targets_needing_file = run_task('pe_xl::filesize', $target,
+    path => $upload_path,
+  ).filter |$result| {
+    $result['size'] != $local_size
+  }.map |$result| {
+    $result.target
+  }
+
+  upload_file($local_path, $upload_path, $targets_needing_file)
+}

installer/primary-master/csr_attributes.yaml

@@ -0,0 +1,4 @@
+---
+extension_requests:
+  pp_role: "pe_xl::primary_master"
+  pp_environment: "pe_production"