Skip to content

Commit 0318550

Browse files
ragingraCoMfUcIoSNeil AndersonAaronShannon
authored
Adding support for legacy compilers (#448)
* Adding support for legacy compilers * Adding inventoryfile to test upgrade legacy workflow * feat(documentation): add instructions for converting compilers to legacy This commit introduces a new section in the `convert.md` documentation. It provides instructions on how to convert compilers to legacy compilers for Puppet Enterprise installations using puppetlabs-peadm version 3.21 or later, as well as for versions prior to 3.21. The new section includes specific commands to run and references to other relevant documentation. * Fixing lint and regenerating referencemd * PE-38772 Node groups added for legacy compilers (#455) * Fixing typo for parameter in docs --------- Co-authored-by: Ioannis Karasavvaidis <ioannis@puppet.com> Co-authored-by: Neil Anderson <neil.anderson@perforce.com> Co-authored-by: Aaron Shannon <aaron.shannon@puppet.com>
1 parent 4743ffd commit 0318550

File tree

13 files changed

+437
-5
lines changed

13 files changed

+437
-5
lines changed

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

Lines changed: 163 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,163 @@
1+
---
2+
name: "Upgrade PE with one legacy compiler"
3+
4+
on:
5+
pull_request:
6+
paths:
7+
- ".github/workflows/**/*"
8+
- "spec/**/*"
9+
- "lib/**/*"
10+
- "tasks/**/*"
11+
- "functions/**/*"
12+
- "types/**/*"
13+
- "plans/**/*"
14+
- "hiera/**/*"
15+
- "manifests/**/*"
16+
- "templates/**/*"
17+
- "files/**/*"
18+
- "metadata.json"
19+
- "Rakefile"
20+
- "Gemfile"
21+
- "provision.yaml"
22+
- ".rspec"
23+
- ".rubocop.yml"
24+
- ".puppet-lint.rc"
25+
- ".fixtures.yml"
26+
branches: [main]
27+
workflow_dispatch:
28+
ssh-debugging:
29+
description: "Boolean; whether or not to pause for ssh debugging"
30+
required: true
31+
default: "false"
32+
33+
jobs:
34+
test-install:
35+
name: "PE ${{ matrix.version }} ${{ matrix.architecture }} on ${{ matrix.image }}"
36+
runs-on: ubuntu-20.04
37+
env:
38+
BOLT_GEM: true
39+
BOLT_DISABLE_ANALYTICS: true
40+
LANG: "en_US.UTF-8"
41+
strategy:
42+
fail-fast: false
43+
matrix:
44+
architecture:
45+
- "large-with-two-compilers"
46+
image:
47+
- "almalinux-cloud/almalinux-8"
48+
version:
49+
- "2023.6.0"
50+
to_version:
51+
- "2023.7.0"
52+
53+
steps:
54+
- name: "Start SSH session"
55+
if: ${{ github.event.inputs.ssh-debugging == 'true' }}
56+
uses: luchihoratiu/debug-via-ssh@main
57+
with:
58+
NGROK_AUTH_TOKEN: ${{ secrets.NGROK_AUTH_TOKEN }}
59+
SSH_PASS: ${{ secrets.SSH_PASS }}
60+
61+
- name: "Checkout Source"
62+
uses: actions/checkout@v2
63+
64+
- name: "Activate Ruby 2.7"
65+
uses: ruby/setup-ruby@v1
66+
with:
67+
ruby-version: "2.7"
68+
bundler-cache: true
69+
70+
- name: "Print bundle environment"
71+
if: ${{ github.repository_owner == 'puppetlabs' }}
72+
run: |
73+
echo ::group::info:bundler
74+
bundle env
75+
echo ::endgroup::
76+
77+
- name: "Provision test cluster"
78+
timeout-minutes: 15
79+
run: |
80+
echo ::group::prepare
81+
mkdir -p $HOME/.ssh
82+
echo 'Host *' > $HOME/.ssh/config
83+
echo ' ServerAliveInterval 150' >> $HOME/.ssh/config
84+
echo ' ServerAliveCountMax 2' >> $HOME/.ssh/config
85+
bundle exec rake spec_prep
86+
echo ::endgroup::
87+
88+
echo ::group::provision
89+
bundle exec bolt plan run peadm_spec::provision_test_cluster \
90+
--modulepath spec/fixtures/modules \
91+
provider=provision_service \
92+
image=${{ matrix.image }} \
93+
architecture=${{ matrix.architecture }}
94+
echo ::endgroup::
95+
96+
echo ::group::info:request
97+
cat request.json || true; echo
98+
echo ::endgroup::
99+
100+
echo ::group::info:inventory
101+
sed -e 's/password: .*/password: "[redacted]"/' < spec/fixtures/litmus_inventory.yaml || true
102+
echo ::endgroup::
103+
104+
- name: Set up yq
105+
uses: frenck/action-setup-yq@v1
106+
with:
107+
version: v4.30.5
108+
109+
- name: 'Install PE on test cluster'
110+
timeout-minutes: 120
111+
run: |
112+
bundle exec bolt plan run peadm_spec::install_test_cluster \
113+
--inventoryfile spec/fixtures/litmus_inventory.yaml \
114+
--modulepath spec/fixtures/modules \
115+
architecture="large" \
116+
version=${{ matrix.version }}
117+
118+
- name: 'Wait as long as the file ${HOME}/pause file is present'
119+
if: ${{ always() && github.event.inputs.ssh-debugging == 'true' }}
120+
run: |
121+
while [ -f "${HOME}/pause" ] ; do
122+
echo "${HOME}/pause present, sleeping for 60 seconds..."
123+
sleep 60
124+
done
125+
echo "${HOME}/pause absent, continuing workflow."
126+
127+
- name: 'Convert one compiler to legacy'
128+
timeout-minutes: 120
129+
run: |
130+
primary=$(yq '.groups[].targets[] | select(.vars.role == "primary") | .uri' spec/fixtures/litmus_inventory.yaml)
131+
compiler=$(yq '.groups[].targets[] | select(.vars.role == "compiler") | .uri' spec/fixtures/litmus_inventory.yaml | head -n 1)
132+
133+
bundle exec bolt plan run peadm::convert_compiler_to_legacy \
134+
--inventoryfile spec/fixtures/litmus_inventory.yaml \
135+
--modulepath spec/fixtures/modules \
136+
--no-host-key-check \
137+
primary_host=$primary \
138+
legacy_hosts=$compiler
139+
140+
141+
- name: 'Upgrade PE on test cluster'
142+
timeout-minutes: 120
143+
run: |
144+
bundle exec bolt plan run peadm_spec::upgrade_test_cluster \
145+
--inventoryfile spec/fixtures/litmus_inventory.yaml \
146+
--modulepath spec/fixtures/modules \
147+
--no-host-key-check \
148+
architecture="large" \
149+
version=${{ matrix.to_version }}
150+
151+
- name: "Tear down test cluster"
152+
if: ${{ always() }}
153+
continue-on-error: true
154+
run: |
155+
if [ -f spec/fixtures/litmus_inventory.yaml ]; then
156+
echo ::group::tear_down
157+
bundle exec rake 'litmus:tear_down'
158+
echo ::endgroup::
159+
160+
echo ::group::info:request
161+
cat request.json || true; echo
162+
echo ::endgroup::
163+
fi

‎REFERENCE.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@
1010

1111
* `peadm::setup::convert_node_manager`: Used during the peadm::convert plan
1212
* `peadm::setup::convert_pre20197`: Defines configuration needed for converting PE 2018
13+
* `peadm::setup::legacy_compiler_group`
1314
* `peadm::setup::node_manager`: Configures PEAdm's required node groups
1415
* `peadm::setup::node_manager_yaml`: Set up the node_manager.yaml file in the temporary Bolt confdir
1516

@@ -106,6 +107,7 @@
106107
* `peadm::add_replica`: Replace a replica host for a Standard or Large architecture.
107108
Supported use cases:
108109
1: The existing replica is broken, we have a fresh new VM we want to provision the replica to.
110+
* `peadm::convert_compiler_to_legacy`
109111
* `peadm::misc::divert_code_manager`: This plan exists to account for a scenario where a PE XL
110112
* `peadm::modify_cert_extensions`
111113
* `peadm::subplans::component_install`: Install a new PEADM component
@@ -115,6 +117,7 @@ Supported use cases:
115117
* `peadm::subplans::modify_certificate`
116118
* `peadm::subplans::prepare_agent`
117119
* `peadm::uninstall`: Single-entry-point plan for uninstalling Puppet Enterprise
120+
* `peadm::update_compiler_extensions`
118121
* `peadm::util::code_sync_status`
119122
* `peadm::util::copy_file`
120123
* `peadm::util::db_disable_pglogical`

‎documentation/convert.md‎

Lines changed: 17 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -15,18 +15,32 @@ Prepare to run the plan against all servers in the PE infrastructure, using a pa
1515
"pe-xl-compiler-1.lab1.puppet.vm"
1616
],
1717

18-
"compiler_pool_address": "puppet.lab1.puppet.vm",
18+
"compiler_pool_address": "puppet.lab1.puppet.vm"
1919
}
2020
```
2121

22-
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.
22+
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.
2323

2424
```
25-
bolt plan run peadm::convert --params @params.json
25+
bolt plan run peadm::convert --params @params.json
2626
```
2727

2828
## Retry or resume plan
2929

3030
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.
3131

3232
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`.
33+
34+
## Convert compilers to legacy
35+
36+
### Puppet Enterprise installed with puppetlabs-peadm version 3.21 or later
37+
38+
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.
39+
40+
```shell
41+
bolt plan run peadm::convert_compiler_to_legacy legacy_hosts=compiler1.example.com,compiler2.example.com primary_host=primary.example.com
42+
```
43+
44+
### Puppet Enterprise installed with puppetlabs-peadm version prior to 3.21
45+
46+
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‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
# Upgrade Puppet Enterprise with legacy compilers
2+
3+
## What is a legacy compiler and a current compiler
4+
5+
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.
6+
7+
## Who is this documentation for
8+
9+
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.
10+
11+
## Who is this documentation not for
12+
13+
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:
14+
15+
```shell
16+
bolt plan run peadm::convert_compiler_to_legacy legacy_hosts=compiler1.example.com,compiler2.example.com primary_host=primary.example.com
17+
```
18+
19+
## How to upgrade Puppet Enterprise with legacy compilers
20+
21+
### 1. Revert changes to the legacy compilers nodes
22+
23+
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.
24+
25+
### 2. Update certificate extensions for NON legacy compilers
26+
27+
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:
28+
29+
```shell
30+
bolt plan run peadm::update_compiler_extensions primary_host=primary.example.com compiler_hosts=compiler1.example.com,compiler2.example.com
31+
```
32+
33+
### 3. Use the convert legacy compiler plan
34+
35+
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:
36+
37+
```shell
38+
bolt plan run peadm::convert_compiler_to_legacy legacy_hosts=compiler1.example.com,compiler2.example.com primary_host=primary.example.com
39+
```
40+
41+
The above will create the needed Node group and Classifier rules to make the compilers legacy. Also will add certificate extensions to those nodes.
42+
43+
### 4. Upgrade Puppet Enterprise
44+
45+
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‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@ function peadm::oid (
44
case $short_name {
55
'peadm_role': { '1.3.6.1.4.1.34380.1.1.9812' }
66
'peadm_availability_group': { '1.3.6.1.4.1.34380.1.1.9813' }
7+
'peadm_legacy_compiler': { '1.3.6.1.4.1.34380.1.1.9814' }
78
'pp_application': { '1.3.6.1.4.1.34380.1.1.8' }
89
'pp_cluster': { '1.3.6.1.4.1.34380.1.1.16' }
910
'pp_role': { '1.3.6.1.4.1.34380.1.1.13' }

‎manifests/setup/legacy_compiler_group.pp‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
# @api private
2+
class peadm::setup::legacy_compiler_group (
3+
String[1] $primary_host
4+
) {
5+
Node_group {
6+
purge_behavior => none,
7+
}
8+
9+
node_group { 'PE Legacy Compiler':
10+
parent => 'PE Master',
11+
rule => ['and',
12+
['=', ['trusted', 'extensions', peadm::oid('peadm_legacy_compiler')], 'true'],
13+
['=', ['trusted', 'extensions', 'pp_auth_role'], 'pe_compiler'],
14+
],
15+
classes => {
16+
'pe_repo' => {},
17+
'puppet_enterprise::profile::master' => { 'code_manager_auto_configure' => true, 'replication_mode' => 'none' },
18+
},
19+
data => {
20+
'pe_repo' => { 'compile_master_pool_address' => $primary_host },
21+
},
22+
variables => {
23+
'pe_master' => true,
24+
},
25+
}
26+
27+
node_group { 'PE Legacy Compiler Group A':
28+
ensure => 'present',
29+
parent => 'PE Legacy Compiler',
30+
rule => ['and',
31+
['=', ['trusted', 'extensions', 'pp_auth_role'], 'pe_compiler'],
32+
['=', ['trusted', 'extensions', peadm::oid('peadm_availability_group')], 'A'],
33+
['=', ['trusted', 'extensions', peadm::oid('peadm_legacy_compiler')], 'true'],
34+
],
35+
}
36+
37+
node_group { 'PE Legacy Compiler Group B':
38+
ensure => 'present',
39+
parent => 'PE Legacy Compiler',
40+
rule => ['and',
41+
['=', ['trusted', 'extensions', 'pp_auth_role'], 'pe_compiler'],
42+
['=', ['trusted', 'extensions', peadm::oid('peadm_availability_group')], 'B'],
43+
['=', ['trusted', 'extensions', peadm::oid('peadm_legacy_compiler')], 'true'],
44+
],
45+
}
46+
47+
node_group { 'PE Compiler':
48+
rule => ['and', ['=', ['trusted', 'extensions', peadm::oid('peadm_legacy_compiler')], 'false']],
49+
}
50+
}

0 commit comments

Comments
 (0)