README.md

@@ -1,10 +1,10 @@
-# Puppet Enterprise Extra Large
+# Puppet Enterprise (pe) Administration (adm) Module
 
-This Puppet module contains Puppet Task Plans used to deploy an at-scale Puppet Enterprise architecture.
+This Puppet module contains Puppet Task Plans used to deploy and manage at-scale Puppet Enterprise architecture.
 
-Use this module to deploy Puppet Enterprise 2019.0.x Extra Large architecture.
+Use this module to deploy Puppet Enterprise 2019.x Standard, Large, and Extra Large architecture.
 
-* This deployment depends on and assumes the use of trusted facts. Specifically, `pp_role` and `pp_environment`.
+* This deployment depends on and assumes the use of trusted facts. Specifically, `pp_application` and `pp_cluster`.
 * This deployment assumes that at least for PE infrastructure nodes, Puppet certnames are correct, resolvable FQDNs.
 
 ## Documentation

documentation/basic_usage.md

@@ -9,26 +9,26 @@ The current versions of those plans can be found at:
 * [provision.pp](../plans/provision.pp)
 * [upgrade.pp](../plans/upgrade.pp)
 
-Provisioning can be broken down into two actions: [install](../plans/unit/install.pp), and [configure](../plans/unit/configure.pp). Installation currently requires ssh access to the un-provisioned nodes, but configure can be performed using the Orchestrator transport if installation has already been completed.
+Provisioning can be broken down into two actions: [install](../plans/action/install.pp), and [configure](../plans/action/configure.pp). Installation currently requires ssh access to the un-provisioned nodes, but configure can be performed using the Orchestrator transport if installation has already been completed.
 
 Besides getting Puppet Enterprise installed, the key configuration supporting Large and Extra Large architectures is laid out in four classification groups. Links are provided below to a Markdown document that describes the groups, and also to the Puppet manifest that actually configures them:
 
 * [classification.md](classification.md)
-* [pe\_xl::node\_manager class](../manifests/node_manager.pp)
+* [peadm::node\_manager class](../manifests/node_manager.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 master, and the master replica nodes.
 
 ## Basic usage instructions
 
 1. Install Bolt on a jumphost. This can be the master, or any other system.
-2. Download or git clone the pe\_xl module and put it somewhere on the jumphost. e.g. ~/modules/pe\_xl.
+2. Download or git clone the peadm module and put it somewhere on the jumphost. e.g. ~/modules/peadm.
 2. Download or git clone the module dependencies, and put them somewhere on the jumphost. e.g. ~/modules/stdlib, ~/modules/node\_manager, etc.
 2. 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.
 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:
+6. Run the peadm::provision plan with the inputs created. Example:
 
-        bolt plan run pe_xl::provision \
+        bolt plan run peadm::provision \
           --inventory nodes.yaml \
           --modulepath ~/modules \
           --params @params.json 
@@ -38,7 +38,7 @@ Example nodes.yaml Bolt inventory file:
 ```yaml
 ---
 groups:
-  - name: pe_xl_nodes
+  - name: pe_nodes
     config:
       transport: ssh
       ssh:
@@ -74,3 +74,13 @@ Example params.json Bolt parameters file:
   "version": "2019.1.1"
 }
 ```
+
+## Offline usage
+
+The peadm::provision plan downloads installation content from an online repository by default. To perform an offline installation, you can prefetch the needed content and place it in the staging directory. If content is available in the staging directory, peadm::provision will not try to download it.
+
+The default staging directory is `/tmp`. If a different staging dir is being used, it can be specified using the `stagingdir` parameter to the peadm::provision plan.
+
+The content needed is the PE installation tarball for the target version. The installation content should be in the staging dir, and should have its original name. E.g. `/tmp/puppet-enterprise-2019.2.2-el-7-x86_64.tar.gz`.
+
+Installation content can be downloaded from [https://puppet.com/try-puppet/puppet-enterprise/download/](https://puppet.com/try-puppet/puppet-enterprise/download/).

documentation/install_and_configure_without_ha.md

@@ -9,12 +9,12 @@ The install, configure, and upgrade plans covered in the [basic_usage.md](basic_
 
 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 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.
+3. Download or git clone the peadm module and put it somewhere on the jumphost, e.g. ~/modules/peadm.
 4. Create an inventory file with connection information. An example is included below.
 5. Create a parameters file. An example is included below. Note the omission of the `master_replica_host` and `puppetdb_database_replica_host` parameters.
-6. Run the pe\_xl plan with the inputs created. Example:
+6. Run the peadm plan with the inputs created. Example:
 ```
-        bolt plan run pe_xl::provision \
+        bolt plan run peadm::provision \
           --inventory nodes.yaml \
           --modulepath ~/modules \
           --params @params.json 
@@ -26,7 +26,7 @@ The install, configure, and upgrade plans covered in the [basic_usage.md](basic_
 
 ---
 groups:
-  - name: pe_xl_nodes
+  - name: peadm_nodes
     config:
       transport: ssh
       ssh:

documentation/large_deploy.md

@@ -24,14 +24,14 @@ deploy a PE Large Architecture.
 
 Ensuring that the parameters above are omitted from the `params.json` file,
 the [basic usage instructions](basic_usage.md#basic-usage-instructions) can be
-used to run the `pe_xl` plan in order to install and configure the deployment.
+used to run the `peadm` plan in order to install and configure the deployment.
 
 Example nodes.yaml Bolt inventory file:
 
 ```yaml
 ---
 groups:
-  - name: pe_xl_nodes
+  - name: peadm_nodes
     config:
       transport: ssh
       ssh:

documentation/upgrade.md

@@ -0,0 +1,108 @@
+# Upgrade Puppet Enterprise using the peadm module
+
+Puppet Enterprise deployments provisioned using the peadm module can be upgrading using the peadm module as well.
+
+## Usage
+
+The `peadm::upgrade` plan requires as input the version of PE to upgrade to, and the names of each PE infrastructure host. Master, replica, compilers, etc.
+
+The following is an example parameters file for upgrading an Extra Large architecture deployment of PE 2019.0.1 to PE 2019.2.2.
+
+```json
+{
+  "version": "2019.2.2",
+  "master_host": "pe-master-09a40c-0.us-west1-a.c.reidmv-peadm.internal",
+  "puppetdb_database_host": "pe-psql-09a40c-0.us-west1-a.c.reidmv-peadm.internal",
+  "master_replica_host": "pe-master-09a40c-1.us-west1-b.c.reidmv-peadm.internal",
+  "puppetdb_database_replica_host": "pe-psql-09a40c-1.us-west1-b.c.reidmv-peadm.internal",
+  "compiler_hosts": [
+    "pe-compiler-09a40c-0.us-west1-a.c.reidmv-peadm.internal",
+    "pe-compiler-09a40c-1.us-west1-b.c.reidmv-peadm.internal",
+    "pe-compiler-09a40c-2.us-west1-c.c.reidmv-peadm.internal",
+    "pe-compiler-09a40c-3.us-west1-a.c.reidmv-peadm.internal"
+  ]
+}
+```
+
+The upgrade plan may be run as:
+
+```
+bolt plan run peadm::upgrade --params @params.json 
+```
+
+## Offline Usage
+
+The peadm::upgrade plan downloads installation content from an online repository by default. To perform an offline installation, you can prefetch the needed content and place it in the staging directory. If content is available in the staging directory, peadm::upgrade will not try to download it.
+
+The default staging directory is `/tmp`. If a different staging dir is being used, it can be specified using the `stagingdir` parameter to the peadm::upgrade plan.
+
+The content needed is the PE installation tarball for the target version. The installation content should be in the staging dir, and should have its original name. E.g. `/tmp/puppet-enterprise-2019.2.2-el-7-x86_64.tar.gz`.
+
+Installation content can be downloaded from [https://puppet.com/try-puppet/puppet-enterprise/download/](https://puppet.com/try-puppet/puppet-enterprise/download/).
+
+## Usage over the Orchestrator transport
+
+The peadm::upgrade plan can be used with the Orchestrator (pcp) transport, provided that the Bolt executor is running as root on the master. To use the Orchestrator transport prepare an inventory file such as the following to set the default transport to be `pcp`, but the master specifically to be `local`.
+
+```
+---
+version: 2
+config:
+  transport: pcp
+  pcp:
+    cacert: /etc/puppetlabs/puppet/ssl/certs/ca.pem
+    service-url: https://pe-master-ad1d88-0.us-west1-a.c.reidmv-peadm.internal:8143
+    task-environment: production
+    token-file: /root/.puppetlabs/token
+groups:
+  - name: pe-targets
+    targets:
+      - name: "pe-master-ad1d88-0.us-west1-a.c.reidmv-peadm.internal"
+        config:
+          transport: local
+      - name: "pe-master-ad1d88-1.us-west1-b.c.reidmv-peadm.internal"
+      - name: "pe-compiler-ad1d88-0.us-west1-a.c.reidmv-peadm.internal"
+      - name: "pe-compiler-ad1d88-1.us-west1-b.c.reidmv-peadm.internal"
+      - name: "pe-compiler-ad1d88-2.us-west1-c.c.reidmv-peadm.internal"
+      - name: "pe-compiler-ad1d88-3.us-west1-a.c.reidmv-peadm.internal"
+      - name: "pe-psql-ad1d88-0.us-west1-a.c.reidmv-peadm.internal"
+      - name: "pe-psql-ad1d88-1.us-west1-b.c.reidmv-peadm.internal"
+```
+
+Additionally, you MUST pre-stage a copy of the PE installation media in /tmp on the PuppetDB PostgreSQL node(s), if present. The Orchestrator transport cannot be used to send large files to remote systems, and the plan will fail if tries.
+
+Pre-staging the installation media and using an inventory definition such as the example above, the peadm::upgrade plan can be run as normal. It will not rely on the Orchestrator service to operate on the master, and it will use the Orchestrator transport to operate on other PE nodes.
+
+```
+bolt plan run peadm::upgrade --params @params.json 
+```
+
+## Manual Upgrades
+
+In the event a manual upgrade is required, the steps may be followed along by reading directly from [the upgrade plan](../plans/upgrade.pp), which is itself the most accurate technical description of the steps required. In general form, the upgrade process is as given below.
+
+Note: it is assumed that the Puppet master is in cluster A when the upgrade starts, and that the replica is in cluster B. If the master is in cluster B, the A/B designations in the instruction should be inverted.
+
+**Phase 1: stop puppet service**
+
+* Stop the `puppet` service on all PE infrastructure nodes to prevent normal automatic runs from interfering with the upgrade process
+
+**Phase 2: upgrade HA cluster A**
+
+1. Shut down the `pe-puppetdb` service on the compilers in cluster A
+2. If different from the master, run the `install-puppet-enterprise` script for the new PE version on the PuppetDB PostgreSQL node for cluster A
+3. Run the `install-puppet-enterprise` script for the new PE version on the master
+4. If different from the master, Run `puppet agent -t` on the PuppetDB PostgreSQL node for cluster A
+5. Perform the standard `curl upgrade.sh | bash` procedure on the compilers for cluster A
+
+**Phase 3: upgrade HA cluster B**
+
+1. Shut down the `pe-puppetdb` service on the compilers in cluster B
+2. If different from the master (replica), run the `install-puppet-enterprise` script for the new PE version on the PuppetDB PostgreSQL node for cluster B
+3. If different from the master (replica), Run `puppet agent -t` on the PuppetDB PostgreSQL node for cluster B
+4. Perform the standard `curl upgrade.sh | bash` procedure on the master (replica)
+5. Perform the standard `curl upgrade.sh | bash` procedure on the compilers for cluster B
+
+**Phase 4: resume puppet service**
+
+* Ensure the `puppet` service on all PE infrastructure nodes is running again

functions/fail_on_transport.pp

@@ -2,7 +2,7 @@
 #
 # Useful for excluding PCP when it's not appopriate
 #
-function pe_xl::fail_on_transport (
+function peadm::fail_on_transport (
   TargetSpec $nodes,
   String     $transport,
 ) {

functions/flatten_compact.pp

@@ -1,4 +1,4 @@
-function pe_xl::flatten_compact (
+function peadm::flatten_compact (
   Array $input,
 ) {
   $input.flatten.filter |$value| {

functions/generate_pe_conf.pp

@@ -5,7 +5,7 @@
 #   undef will not be included in the config file. This is done to reduce the
 #   amount of logic required within plans if parameters are not passed in.
 #
-function pe_xl::generate_pe_conf (
+function peadm::generate_pe_conf (
   Hash $settings,
 ) {
   # Check that console_admin_password is present

functions/get_targets.pp

@@ -2,7 +2,7 @@
 # This differs from get_target() in that:
 #   - It returns an Array[Target, 1, 0], rather than a Target
 #   - It will accept undef and return [ ].
-function pe_xl::get_targets(
+function peadm::get_targets(
   Variant[TargetSpec, Undef] $spec,
   Optional[Integer[1,1]]     $count = undef,
 ) {

functions/target_host.pp → functions/target_name.pp

@@ -1,15 +1,18 @@
-function pe_xl::target_host(
+function peadm::target_name(
   Variant[Target, Array[Target,0,1]] $target,
 ) >> Variant[String, Undef] {
   case $target {
     Target: {
-      $target.host
+      $target.name
     }
     Array[Target,1,1]: {
-      $target[0].host
+      $target[0].name
     }
     Array[Target,0,0]: {
       undef
     }
+    default: {
+      fail('Unexpected input type to peadm::target_name function')
+    }
   }
 }

functions/validate_architecture.pp

@@ -1,4 +1,4 @@
-function pe_xl::validate_architecture (
+function peadm::validate_architecture (
   TargetSpec                 $master_host,
   Variant[TargetSpec, Undef] $master_replica_host = undef,
   Variant[TargetSpec, Undef] $puppetdb_database_host = undef,
@@ -18,7 +18,7 @@ function pe_xl::validate_architecture (
       }})
     }
     [true, true, false, false]: {  # Standard or Large, HA
-      ({ 'high-availability' => false, 'architecture' => $compiler_hosts ? {
+      ({ 'high-availability' => true, 'architecture' => $compiler_hosts ? {
         undef   => 'standard',
         default => 'large',
       }})