Update version to 1.0.0; add docs for conversion

This commit adds documentation for converting a stack deployed with
peadm 0.5.x to be compatible with changes in the 1.x version of the
module.

Author: reidmv

README.md

@@ -22,3 +22,4 @@ Reference:
 * [Classification](documentation/classification.md)
 * [Architectures](documentation/architectures.md)
 * [Testing](documentation/pre_post_checks.md)
+* [Converting From Old Versions of peadm](documentation/old_versions_of_peadm.md)

documentation/old_versions_of_peadm.md

@@ -0,0 +1,56 @@
+# Old Versions of Puppet Enterprise (pe) Administration (adm) Module
+
+Prior to the 1.0.0 release of peadm, the pp\_application and pp\_cluster trusted facts were used to identify peadm server roles and availability groups. In order to avoid conflict with customer use of these trusted facts, in 1.0.0 peadm switched to using its own custom OID trusted facts for the purpose instead.
+
+Puppet Enterprise systems deployed with peadm 1.0.0 will use the correct trusted facts, but any system deployed with peadm 0.5.x or older will still be relying on pp\_application and pp\_cluster. It is recommended that for these systems, you either A) continue to use an older version of peadm to perform upgrades; B) deploy new PE infrastructure using a 1.0.0 version of peadm or newer; or C) use the peadm::misc::upgrade\_trusted\_facts plan to re-issue certificates for each server to include the new custom OID trusted facts.
+
+
+Prepare to run the plan against all servers in the PE infrastructure, using a params.json file such as this one:
+
+```json
+{
+  "master_host": "pe-xl-core-0.lab1.puppet.vm",
+  "targets": [
+    "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-compiler-0.lab1.puppet.vm",
+    "pe-xl-compiler-1.lab1.puppet.vm"
+  ],
+}
+```
+
+Run the plan. Note that this cannot be done using the Orchestrator transport; it must be performed over ssh.
+
+```
+bolt plan run peadm::misc::upgrade_trusted_facts --params @params.json 
+```
+
+To complete the conversion, the PE node groups in the console should be updated to use the new trusted fact OIDs, and not pp\_application or pp\_cluster anymore. This can be accomplished by re-applying the peadm::setup::node\_manager class to the master.
+
+Tip: use the `--noop` flag to validate that the changes which will be made are the changes expected before applying the configuration change.
+
+```
+bolt apply --target pe-xl-core-0.lab1.puppet.vm -e <<EOF
+
+  file { 'node_manager.yaml':
+    ensure  => file,
+    mode    => '0644',
+    path    => Deferred('peadm::node_manager_yaml_location'),
+    content => epp('peadm/node_manager.yaml.epp', {
+      server => 'pe-xl-core-0.lab1.puppet.vm',,
+    }),
+  }
+
+  class { 'peadm::setup::node_manager':
+    master_host                    => 'pe-xl-core-0.lab1.puppet.vm',
+    master_replica_host            => 'pe-xl-core-2.lab1.puppet.vm',
+    puppetdb_database_host         => 'pe-xl-core-1.lab1.puppet.vm',
+    puppetdb_database_replica_host => 'pe-xl-core-3.lab1.puppet.vm',
+    compiler_pool_address          => 'puppet.lab1.puppet.vm',
+    require                        => File['node_manager.yaml'],
+  }
+
+EOF
+```

metadata.json

@@ -1,6 +1,6 @@
 {
   "name": "puppetlabs-peadm",
-  "version": "0.5.2",
+  "version": "1.0.0",
   "author": "Puppet Labs Solutions Architecture",
   "summary": "Bolt plans used to deploy an at-scale Puppet Enterprise architecture",
   "license": "Apache-2.0",

plans/misc/upgrade_trusted_facts.pp

@@ -8,6 +8,9 @@
   $all_targets   = peadm::get_targets($targets)
   $master_target = peadm::get_targets($master_host, 1)
 
+  # This plan doesn't work over the orchestrator due to certificates being revoked.
+  $all_targets.peadm::fail_on_transport('pcp')
+
   $certdata = run_task('peadm::trusted_facts', $all_targets).reduce({}) |$memo,$result| {
     # Keep the the OID-form trusted fact key/value pairs. If we accidentally
     # include an OID and also a shortname that resolves to the same OID,
@@ -35,15 +38,32 @@
 
     run_command("${pserver} ca clean --certname ${certdata[$target]['certname']}", $master_target)
     run_command("${puppet} ssl clean --certname ${certdata[$target]['certname']}", $target)
-    run_command("${puppet} ssl submit_request --certname ${certdata[$target]['certname']}", $target)
-
-    ctrl::sleep(2) # some lag sometimes before the cert is available to sign
 
-    if !$autosign {
-      run_command("${pserver} ca sign --certname ${certdata[$target]['certname']}", $master_target)
+    # The procedure for regenerating an agent's cert
+    if ($target != $master_target) {
+      run_command("${puppet} ssl submit_request --certname ${certdata[$target]['certname']}", $target)
+      ctrl::sleep(2) # some lag sometimes before the cert is available to sign
+      if !$autosign {
+        run_command("${pserver} ca sign --certname ${certdata[$target]['certname']}", $master_target)
+      }
+      run_command("${puppet} ssl download_cert --certname ${certdata[$target]['certname']}", $target)
     }
 
-    run_command("${puppet} ssl download_cert --certname ${certdata[$target]['certname']}", $target)
+    # The procedure for regenerating the master's cert
+    else {
+      $alt_names_flag = $certdata[$target]['dns-alt-names'] ? {
+        undef   => '',
+        default => "--subject-alt-names ${certdata[$target]['dns-alt-names'].join(',')}",
+      }
+      run_task('service', $target, {action => 'stop', name => 'pe-puppetserver'})
+      run_command(@("HEREDOC"/L), $master_target)
+        ${pserver} ca generate \
+          --certname ${certdata[$target]['certname']} \
+          ${alt_names_flag} \
+          --ca-client \
+        | HEREDOC
+      run_task('service', $target, {action => 'start', name => 'pe-puppetserver'})
+    }
   }
 
 }

plans/upgrade.pp

@@ -53,6 +53,16 @@
     $memo + { $result.target => $result['extensions'] }
   }
 
+  # Ensure needed trusted facts are available
+  if $trusted_facts.any |$t,$ext| { $ext[peadm::oid('peadm_role')] == undef } {
+    fail_plan(@(HEREDOC/L))
+      Required trusted facts are not present; upgrade cannot be completed. If \
+      this infrastructure was provisioned with an old version of peadm, you may \
+      need to run the peadm::misc::upgrade_trusted_facts plan against each of the \
+      infrastructure nodes.
+      | HEREDOC
+  }
+
   # Determine which compilers are associated with which HA group
   $compiler_m1_targets = $compiler_targets.filter |$target| {
     ($trusted_facts[$target][peadm::oid('peadm_availability_group')]