Adding support for legacy compilers

.github/workflows/test-upgrade-legacy.yaml

@@ -0,0 +1,163 @@
+---
+name: "Upgrade PE with one legacy compiler"
+
+on:
+  pull_request:
+    paths:
+      - ".github/workflows/**/*"
+      - "spec/**/*"
+      - "lib/**/*"
+      - "tasks/**/*"
+      - "functions/**/*"
+      - "types/**/*"
+      - "plans/**/*"
+      - "hiera/**/*"
+      - "manifests/**/*"
+      - "templates/**/*"
+      - "files/**/*"
+      - "metadata.json"
+      - "Rakefile"
+      - "Gemfile"
+      - "provision.yaml"
+      - ".rspec"
+      - ".rubocop.yml"
+      - ".puppet-lint.rc"
+      - ".fixtures.yml"
+    branches: [main]
+  workflow_dispatch:
+      ssh-debugging:
+        description: "Boolean; whether or not to pause for ssh debugging"
+        required: true
+        default: "false"
+
+jobs:
+  test-install:
+    name: "PE ${{ matrix.version }} ${{ matrix.architecture }} on ${{ matrix.image }}"
+    runs-on: ubuntu-20.04
+    env:
+      BOLT_GEM: true
+      BOLT_DISABLE_ANALYTICS: true
+      LANG: "en_US.UTF-8"
+    strategy:
+      fail-fast: false
+      matrix:
+        architecture:
+          - "large-with-two-compilers"
+        image:
+          - "almalinux-cloud/almalinux-8"
+        version:
+          - "2023.6.0"
+        to_version:
+          - "2023.7.0"
+
+    steps:
+      - name: "Start SSH session"
+        if: ${{ github.event.inputs.ssh-debugging == 'true' }}
+        uses: luchihoratiu/debug-via-ssh@main
+        with:
+          NGROK_AUTH_TOKEN: ${{ secrets.NGROK_AUTH_TOKEN }}
+          SSH_PASS: ${{ secrets.SSH_PASS }}
+
+      - name: "Checkout Source"
+        uses: actions/checkout@v2
+
+      - name: "Activate Ruby 2.7"
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "2.7"
+          bundler-cache: true
+
+      - name: "Print bundle environment"
+        if: ${{ github.repository_owner == 'puppetlabs' }}
+        run: |
+          echo ::group::info:bundler
+            bundle env
+          echo ::endgroup::
+
+      - name: "Provision test cluster"
+        timeout-minutes: 15
+        run: |
+          echo ::group::prepare
+            mkdir -p $HOME/.ssh
+            echo 'Host *'                      >  $HOME/.ssh/config
+            echo '    ServerAliveInterval 150' >> $HOME/.ssh/config
+            echo '    ServerAliveCountMax 2'   >> $HOME/.ssh/config
+            bundle exec rake spec_prep
+          echo ::endgroup::
+
+          echo ::group::provision
+            bundle exec bolt plan run peadm_spec::provision_test_cluster \
+              --modulepath spec/fixtures/modules \
+              provider=provision_service \
+              image=${{ matrix.image }} \
+              architecture=${{ matrix.architecture }}
+          echo ::endgroup::
+
+          echo ::group::info:request
+            cat request.json || true; echo
+          echo ::endgroup::
+
+          echo ::group::info:inventory
+            sed -e 's/password: .*/password: "[redacted]"/' < spec/fixtures/litmus_inventory.yaml || true
+          echo ::endgroup::
+
+      - name: Set up yq
+        uses: frenck/action-setup-yq@v1
+        with:
+          version: v4.30.5
+
+      - name: 'Install PE on test cluster'
+        timeout-minutes: 120
+        run: |
+          bundle exec bolt plan run peadm_spec::install_test_cluster \
+            --inventoryfile spec/fixtures/litmus_inventory.yaml \
+            --modulepath spec/fixtures/modules \
+            architecture="large" \
+            version=${{ matrix.version }}
+
+      - name: 'Wait as long as the file ${HOME}/pause file is present'
+        if: ${{ always() && github.event.inputs.ssh-debugging == 'true' }}
+        run: |
+          while [ -f "${HOME}/pause" ] ; do
+            echo "${HOME}/pause present, sleeping for 60 seconds..."
+            sleep 60
+          done 
+          echo "${HOME}/pause absent, continuing workflow."
+
+      - name: 'Convert one compiler to legacy'
+        timeout-minutes: 120
+        run: |
+          primary=$(yq '.groups[].targets[] | select(.vars.role == "primary") | .uri' spec/fixtures/litmus_inventory.yaml)
+          compiler=$(yq '.groups[].targets[] | select(.vars.role == "compiler") | .uri' spec/fixtures/litmus_inventory.yaml | head -n 1)
+
+          bundle exec bolt plan run peadm::convert_compiler_to_legacy \
+            --inventoryfile spec/fixtures/litmus_inventory.yaml \
+            --modulepath spec/fixtures/modules \
+            --no-host-key-check \
+            primary_host=$primary \
+            legacy_hosts=$compiler
+
+
+      - name: 'Upgrade PE on test cluster'
+        timeout-minutes: 120
+        run: |
+          bundle exec bolt plan run peadm_spec::upgrade_test_cluster \
+            --inventoryfile spec/fixtures/litmus_inventory.yaml \
+            --modulepath spec/fixtures/modules \
+            --no-host-key-check \
+            architecture="large" \
+            version=${{ matrix.to_version }}
+
+      - name: "Tear down test cluster"
+        if: ${{ always() }}
+        continue-on-error: true
+        run: |
+          if [ -f spec/fixtures/litmus_inventory.yaml ]; then
+            echo ::group::tear_down
+              bundle exec rake 'litmus:tear_down'
+            echo ::endgroup::
+
+            echo ::group::info:request
+              cat request.json || true; echo
+            echo ::endgroup::
+          fi

REFERENCE.md

@@ -10,6 +10,7 @@
 
 * `peadm::setup::convert_node_manager`: Used during the peadm::convert plan
 * `peadm::setup::convert_pre20197`: Defines configuration needed for converting PE 2018
+* `peadm::setup::legacy_compiler_group`
 * `peadm::setup::node_manager`: Configures PEAdm's required node groups
 * `peadm::setup::node_manager_yaml`: Set up the node_manager.yaml file in the temporary Bolt confdir
 
@@ -106,6 +107,7 @@
 * `peadm::add_replica`: Replace a replica host for a Standard or Large architecture.
 Supported use cases:
 1: The existing replica is broken, we have a fresh new VM we want to provision the replica to.
+* `peadm::convert_compiler_to_legacy`
 * `peadm::misc::divert_code_manager`: This plan exists to account for a scenario where a PE XL
 * `peadm::modify_cert_extensions`
 * `peadm::subplans::component_install`: Install a new PEADM component
@@ -115,6 +117,7 @@ Supported use cases:
 * `peadm::subplans::modify_certificate`
 * `peadm::subplans::prepare_agent`
 * `peadm::uninstall`: Single-entry-point plan for uninstalling Puppet Enterprise
+* `peadm::update_compiler_extensions`
 * `peadm::util::code_sync_status`
 * `peadm::util::copy_file`
 * `peadm::util::db_disable_pglogical`

documentation/convert.md

@@ -15,18 +15,32 @@ Prepare to run the plan against all servers in the PE infrastructure, using a pa
     "pe-xl-compiler-1.lab1.puppet.vm"
   ],
 
-  "compiler_pool_address": "puppet.lab1.puppet.vm",
+  "compiler_pool_address": "puppet.lab1.puppet.vm"
 }
 ```
 
-See the [install](install.md#reference-architectures) documentation for a list of supported architectures. Note that for convert, *all infrastructure being converted must already be functional*; you cannot use convert to add new systems to the infrastructure, nor can you use it to change your architecture.
+See the [install](install.md#reference-architectures) documentation for a list of supported architectures. Note that for convert, _all infrastructure being converted must already be functional_; you cannot use convert to add new systems to the infrastructure, nor can you use it to change your architecture.
 
 ```
-bolt plan run peadm::convert --params @params.json 
+bolt plan run peadm::convert --params @params.json
 ```
 
 ## Retry or resume plan
 
 This plan is broken down into steps. Normally, the plan runs through all the steps from start to finish. The name of each step is displayed during the plan run, as the step begins.
 
 The `begin_at_step` parameter can be used to facilitate re-running this plan after a failed attempt, skipping past any steps that already completed successfully on the first try and picking up again at the step specified. The step name to resume at can be read from the previous run logs. A full list of available values for this parameter can be viewed by running `bolt plan show peadm::convert`.
+
+## Convert compilers to legacy
+
+### Puppet Enterprise installed with puppetlabs-peadm version 3.21 or later
+
+To convert compilers to legacy compilers use the `peadm::convert_compiler_to_legacy` plan. This plan will create the needed Node group and Classifier rules to make the compilers legacy. Also will add certificate extensions to those nodes.
+
+```shell
+bolt plan run peadm::convert_compiler_to_legacy legacy_hosts=compiler1.example.com,compiler2.example.com primary_host=primary.example.com
+```
+
+### Puppet Enterprise installed with puppetlabs-peadm version prior to 3.21
+
+Follow Steps 1 to 3 in the [Upgrade Puppet Enterprise with legacy compilers](upgrade_with_legacy_compilers.md) documentation.

documentation/upgrade_with_legacy_compilers.md

@@ -0,0 +1,45 @@
+# Upgrade Puppet Enterprise with legacy compilers
+
+## What is a legacy compiler and a current compiler
+
+As a legacy compiler we refer to a compiler that doesn't have PuppetDB. And a current Compiler is a compiler that has PuppetDB. By default, latest versions of Puppet enterprise comes with compilers that have PuppetDB.If your primary server and compilers are connected with high-latency links or congested network segments, you might experience better PuppetDB performance with legacy compilers.
+
+## Who is this documentation for
+
+For those users that have installed Puppet Enterprise with puppetlabs-peadm prior version 3.21 and manually converted their existing complilers (all of the or at least 1) to legacy compilers.
+
+## Who is this documentation not for
+
+For those users that have installed Puppet Enterprise with PEADM with 3.21 version or later, there is no need to follow this documentation. The install process will automatically have created the necessary configurations for you and you can use the `peadm::convert_compiler_to_legacy` plan if you need a legacy compiler. example:
+
+```shell
+bolt plan run peadm::convert_compiler_to_legacy legacy_hosts=compiler1.example.com,compiler2.example.com primary_host=primary.example.com
+```
+
+## How to upgrade Puppet Enterprise with legacy compilers
+
+### 1. Revert changes to the legacy compilers nodes
+
+Usually users pin the nodes in the Pe Master Node Group and then manually removing PuppetDB from compilers nodes. To revert this changes go to your Puppet Enterprise console and unpin the compilers nodes from the Group.
+
+### 2. Update certificate extensions for NON legacy compilers
+
+If you have NON legacy compilers in your infrastructure, you have to add a certificate extension to them that recognizes them as NON legacy compilers. To do this, execute the following plan:
+
+```shell
+bolt plan run peadm::update_compiler_extensions primary_host=primary.example.com compiler_hosts=compiler1.example.com,compiler2.example.com
+```
+
+### 3. Use the convert legacy compiler plan
+
+Now that we have unpinned the compilers nodes from the PE Master node group, execute the following plan to convert your needed compilers to legacy compilers:
+
+```shell
+bolt plan run peadm::convert_compiler_to_legacy legacy_hosts=compiler1.example.com,compiler2.example.com primary_host=primary.example.com
+```
+
+The above will create the needed Node group and Classifier rules to make the compilers legacy. Also will add certificate extensions to those nodes.
+
+### 4. Upgrade Puppet Enterprise
+
+After you have completed the above steps, you can proceed with the upgrade of Puppet Enterprise as usual using the puppetlabs-peadm module. There is no need to do the above ever again.

functions/oid.pp

@@ -4,6 +4,7 @@ function peadm::oid (
   case $short_name {
     'peadm_role':  { '1.3.6.1.4.1.34380.1.1.9812' }
     'peadm_availability_group': { '1.3.6.1.4.1.34380.1.1.9813' }
+    'peadm_legacy_compiler': { '1.3.6.1.4.1.34380.1.1.9814' }
     'pp_application': { '1.3.6.1.4.1.34380.1.1.8' }
     'pp_cluster': { '1.3.6.1.4.1.34380.1.1.16' }
     'pp_role': { '1.3.6.1.4.1.34380.1.1.13' }

manifests/setup/legacy_compiler_group.pp

@@ -0,0 +1,50 @@
+# @api private
+class peadm::setup::legacy_compiler_group (
+  String[1] $primary_host
+) {
+  Node_group {
+    purge_behavior => none,
+  }
+
+  node_group { 'PE Legacy Compiler':
+    parent    => 'PE Master',
+    rule      => ['and',
+      ['=', ['trusted', 'extensions', peadm::oid('peadm_legacy_compiler')], 'true'],
+      ['=', ['trusted', 'extensions', 'pp_auth_role'], 'pe_compiler'],
+    ],
+    classes   => {
+      'pe_repo'                            => {},
+      'puppet_enterprise::profile::master' => { 'code_manager_auto_configure' => true, 'replication_mode' => 'none' },
+    },
+    data      => {
+      'pe_repo' => { 'compile_master_pool_address' => $primary_host },
+    },
+    variables => {
+      'pe_master' => true,
+    },
+  }
+
+  node_group { 'PE Legacy Compiler Group A':
+    ensure => 'present',
+    parent => 'PE Legacy Compiler',
+    rule   => ['and',
+      ['=', ['trusted', 'extensions', 'pp_auth_role'], 'pe_compiler'],
+      ['=', ['trusted', 'extensions', peadm::oid('peadm_availability_group')], 'A'],
+      ['=', ['trusted', 'extensions', peadm::oid('peadm_legacy_compiler')], 'true'],
+    ],
+  }
+
+  node_group { 'PE Legacy Compiler Group B':
+    ensure => 'present',
+    parent => 'PE Legacy Compiler',
+    rule   => ['and',
+      ['=', ['trusted', 'extensions', 'pp_auth_role'], 'pe_compiler'],
+      ['=', ['trusted', 'extensions', peadm::oid('peadm_availability_group')], 'B'],
+      ['=', ['trusted', 'extensions', peadm::oid('peadm_legacy_compiler')], 'true'],
+    ],
+  }
+
+  node_group { 'PE Compiler':
+    rule   => ['and', ['=', ['trusted', 'extensions', peadm::oid('peadm_legacy_compiler')], 'false']],
+  }
+}