Skip to content

Commit 3ef10ca

Browse files
CoMfUcIoSragingraNeil AndersonAaronShannon
authored
(PE-38815-18) Official support of Add replica plan (#484)
* PE-38815 add_replica plan updated, test matrix added (#480) * (PE-38818) Removing experimental and private from add_replica (#478) * (PE-38818) Removing experimental and private from add_replica * Updating Reference.md --------- Co-authored-by: Neil Anderson <[email protected]> * (PE-38817) Adding docs for add replica (#477) Co-authored-by: Neil Anderson <[email protected]> * chore: update test-add-replica workflow - Remove unnecessary quotes from YAML keys and values - Standardize single quotes for string values - Improve readability by removing extra blank lines * feat(workflows): add console password to test-add-replica-matrix job - Included `console_password` parameter in the test-add-replica-matrix job. - Utilizes `${{ secrets.CONSOLE_PASSWORD }}` for secure password management. * (PE-38817) Text fixes for add_replica docs (#496) * PE-39228 add_replica smoke test (#497) * PE-39228 Smoke test created and added to workflow * PE-39228 Workflow updated * PE-39228 Spec updated, smoke test added to matrix * PE-39228 Versions updated, push trigger removed from matrix * PE-39228 whitespace fixed * chore(workflow): update test-add-replica-matrix to use single version - Removed version `2021.7.9` from the matrix, leaving only `2023.8.0`. This change simplifies the testing matrix by focusing on the latest version. * chore(workflow): update test-add-replica-matrix to use single version - Changed `version` matrix to use an array with only `2023.8.0`. This change simplifies the testing matrix by focusing on the latest version. * docs: update REFERENCE.md to use asterisks for list items - Changed list item markers from hyphens to asterisks for consistency. - Ensured all list items in the document follow the same format. * add_replica docs updated --------- Co-authored-by: Neil Anderson <[email protected]> Co-authored-by: Neil Anderson <[email protected]> Co-authored-by: Aaron Shannon <[email protected]>
1 parent 68329f0 commit 3ef10ca

File tree

9 files changed

+307
-21
lines changed

9 files changed

+307
-21
lines changed

‎.github/workflows/test-add-replica-matrix.yaml

+112
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
---
2+
name: Add replica matrix
3+
on:
4+
pull_request:
5+
paths:
6+
- .github/workflows/**/*
7+
- spec/**/*
8+
- lib/**/*
9+
- tasks/**/*
10+
- functions/**/*
11+
- types/**/*
12+
- plans/**/*
13+
- hiera/**/*
14+
- manifests/**/*
15+
- templates/**/*
16+
- files/**/*
17+
- metadata.json
18+
- Rakefile
19+
- Gemfile
20+
- provision.yaml
21+
- .rspec
22+
- .rubocop.yml
23+
- .puppet-lint.rc
24+
- .fixtures.yml
25+
branches: [main]
26+
workflow_dispatch: {}
27+
jobs:
28+
test-add-replica:
29+
name: PE ${{ matrix.version }} ${{ matrix.architecture }} on ${{ matrix.image }}
30+
runs-on: ubuntu-20.04
31+
env:
32+
BOLT_GEM: true
33+
BOLT_DISABLE_ANALYTICS: true
34+
LANG: en_US.UTF-8
35+
strategy:
36+
fail-fast: false
37+
matrix:
38+
architecture: [standard, standard-with-dr, large, extra-large]
39+
version: [2023.8.0]
40+
image: [almalinux-cloud/almalinux-8]
41+
steps:
42+
- name: Checkout Source
43+
uses: actions/checkout@v2
44+
- name: Activate Ruby 2.7
45+
uses: ruby/setup-ruby@v1
46+
with:
47+
ruby-version: '2.7'
48+
bundler-cache: true
49+
- name: Print bundle environment
50+
if: ${{ github.repository_owner == 'puppetlabs' }}
51+
run: |
52+
echo ::group::info:bundler
53+
bundle env
54+
echo ::endgroup::
55+
- name: Provision test cluster (specified architecture and a spare replica)
56+
timeout-minutes: 15
57+
run: |
58+
echo ::group::prepare
59+
mkdir -p $HOME/.ssh
60+
echo 'Host *' > $HOME/.ssh/config
61+
echo ' ServerAliveInterval 150' >> $HOME/.ssh/config
62+
echo ' ServerAliveCountMax 2' >> $HOME/.ssh/config
63+
bundle exec rake spec_prep
64+
echo ::endgroup::
65+
echo ::group::provision
66+
bundle exec bolt plan run peadm_spec::provision_test_cluster \
67+
--modulepath spec/fixtures/modules \
68+
provider=provision_service \
69+
image=${{ matrix.image }} \
70+
architecture=${{ matrix.architecture }}-and-spare-replica
71+
echo ::endgroup::
72+
echo ::group::info:request
73+
cat request.json || true; echo
74+
echo ::endgroup::
75+
echo ::group::info:inventory
76+
sed -e 's/password: .*/password: "[redacted]"/' < spec/fixtures/litmus_inventory.yaml || true
77+
echo ::endgroup::
78+
- name: Install PE on test cluster
79+
timeout-minutes: 120
80+
run: |
81+
bundle exec bolt plan run peadm_spec::install_test_cluster \
82+
--inventoryfile spec/fixtures/litmus_inventory.yaml \
83+
--modulepath spec/fixtures/modules \
84+
architecture=${{ matrix.architecture }} \
85+
version=${{ matrix.version }} \
86+
console_password=${{ secrets.CONSOLE_PASSWORD }} \
87+
code_manager_auto_configure=true
88+
- name: Run add_replica plan
89+
timeout-minutes: 60
90+
run: |
91+
bundle exec bolt plan run peadm_spec::add_replica -v \
92+
--inventoryfile spec/fixtures/litmus_inventory.yaml \
93+
--modulepath spec/fixtures/modules \
94+
--stream
95+
- name: Verify that replica was added
96+
timeout-minutes: 10
97+
run: |
98+
bundle exec bolt plan run peadm_spec::verify_replica -v \
99+
--inventoryfile spec/fixtures/litmus_inventory.yaml \
100+
--modulepath spec/fixtures/modules
101+
- name: Tear down test cluster
102+
if: ${{ always() }}
103+
continue-on-error: true
104+
run: |-
105+
if [ -f spec/fixtures/litmus_inventory.yaml ]; then
106+
echo ::group::tear_down
107+
bundle exec rake 'litmus:tear_down'
108+
echo ::endgroup::
109+
echo ::group::info:request
110+
cat request.json || true; echo
111+
echo ::endgroup::
112+
fi

‎.github/workflows/test-add-replica.yaml

+12-4
Original file line numberDiff line numberDiff line change
@@ -53,7 +53,7 @@ jobs:
5353
echo ::group::info:bundler
5454
bundle env
5555
echo ::endgroup::
56-
- name: Provision test cluster (specified architecture with added DR)
56+
- name: Provision test cluster (specified architecture with spare replica)
5757
timeout-minutes: 15
5858
run: |
5959
echo ::group::prepare
@@ -68,7 +68,7 @@ jobs:
6868
--modulepath spec/fixtures/modules \
6969
provider=provision_service \
7070
image=${{ matrix.image }} \
71-
architecture=${{ matrix.architecture }}-with-dr
71+
architecture=${{ matrix.architecture }}-and-spare-replica
7272
echo ::endgroup::
7373
echo ::group::info:request
7474
cat request.json || true; echo
@@ -84,11 +84,19 @@ jobs:
8484
--modulepath spec/fixtures/modules \
8585
architecture=${{ matrix.architecture }} \
8686
version=${{ matrix.version }} \
87-
console_password=${{ secrets.CONSOLE_PASSWORD }}
87+
console_password=${{ secrets.CONSOLE_PASSWORD }} \
88+
code_manager_auto_configure=true
8889
- name: Run add_replica plan
89-
timeout-minutes: 30
90+
timeout-minutes: 60
9091
run: |
9192
bundle exec bolt plan run peadm_spec::add_replica -v \
93+
--inventoryfile spec/fixtures/litmus_inventory.yaml \
94+
--modulepath spec/fixtures/modules \
95+
--stream
96+
- name: Verify that replica was added
97+
timeout-minutes: 10
98+
run: |
99+
bundle exec bolt plan run peadm_spec::verify_replica -v \
92100
--inventoryfile spec/fixtures/litmus_inventory.yaml \
93101
--modulepath spec/fixtures/modules
94102
- name: Wait as long as the file ${HOME}/pause file is present

‎REFERENCE.md

+49-3
Original file line numberDiff line numberDiff line change
@@ -90,6 +90,10 @@
9090

9191
* [`peadm::add_compiler`](#peadm--add_compiler): Add a new compiler to a PE architecture or replace an existing one with new configuration.
9292
* [`peadm::add_database`](#peadm--add_database)
93+
* [`peadm::add_replica`](#peadm--add_replica): Add or replace a replica host.
94+
Supported use cases:
95+
1: Adding a replica to an existing primary.
96+
2: The existing replica is broken, we have a fresh new VM we want to provision the replica to.
9397
* [`peadm::backup`](#peadm--backup): Backup puppet primary configuration
9498
* [`peadm::backup_ca`](#peadm--backup_ca)
9599
* [`peadm::convert`](#peadm--convert): Convert an existing PE cluster to a PEAdm-managed cluster
@@ -103,9 +107,6 @@
103107

104108
#### Private Plans
105109

106-
* `peadm::add_replica`: Replace a replica host for a Standard or Large architecture.
107-
Supported use cases:
108-
1: The existing replica is broken, we have a fresh new VM we want to provision the replica to.
109110
* `peadm::misc::divert_code_manager`: This plan exists to account for a scenario where a PE XL
110111
* `peadm::modify_cert_extensions`
111112
* `peadm::subplans::component_install`: Install a new PEADM component
@@ -1654,6 +1655,51 @@ Optional[Enum[
16541655

16551656

16561657

1658+
Default value: `undef`
1659+
1660+
### <a name="peadm--add_replica"></a>`peadm::add_replica`
1661+
1662+
Add or replace a replica host.
1663+
Supported use cases:
1664+
1: Adding a replica to an existing primary.
1665+
2: The existing replica is broken, we have a fresh new VM we want to provision the replica to.
1666+
1667+
#### Parameters
1668+
1669+
The following parameters are available in the `peadm::add_replica` plan:
1670+
1671+
* [`primary_host`](#-peadm--add_replica--primary_host)
1672+
* [`replica_host`](#-peadm--add_replica--replica_host)
1673+
* [`replica_postgresql_host`](#-peadm--add_replica--replica_postgresql_host)
1674+
* [`token_file`](#-peadm--add_replica--token_file)
1675+
1676+
##### <a name="-peadm--add_replica--primary_host"></a>`primary_host`
1677+
1678+
Data type: `Peadm::SingleTargetSpec`
1679+
1680+
- The hostname and certname of the primary Puppet server
1681+
1682+
##### <a name="-peadm--add_replica--replica_host"></a>`replica_host`
1683+
1684+
Data type: `Peadm::SingleTargetSpec`
1685+
1686+
- The hostname and certname of the replica VM
1687+
1688+
##### <a name="-peadm--add_replica--replica_postgresql_host"></a>`replica_postgresql_host`
1689+
1690+
Data type: `Optional[Peadm::SingleTargetSpec]`
1691+
1692+
- The hostname and certname of the host with the replica PE-PosgreSQL database.
1693+
Can be a separate host in an XL architecture, or undef in Standard or Large.
1694+
1695+
Default value: `undef`
1696+
1697+
##### <a name="-peadm--add_replica--token_file"></a>`token_file`
1698+
1699+
Data type: `Optional[String]`
1700+
1701+
- (optional) the token file in a different location than the default.
1702+
16571703
Default value: `undef`
16581704

16591705
### <a name="peadm--backup"></a>`peadm::backup`

‎documentation/add_replica.md

+89
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
# Add Replica
2+
3+
- [Add Replica](#Add-replica)
4+
- [Introduction](#Introduction)
5+
- [Adding a replica to standard and large infrastructures](#Adding-a-replica-to-standard-and-large-infrastructures)
6+
- [Adding a Replica to extra large infrastructure](#Adding-a-Replica-to-extra-large-infrastructure)
7+
- [Running the `add_replica` plan](#running-the-add_replica-plan)
8+
- [Parameters](#parameters)
9+
10+
## Introduction
11+
12+
The `peadm::add_replica` plan is designed to setup disaster recovery (DR) of a Puppet Enterprise primary server. This is achieved by adding a primary replica to your system. Although this plan doesn't change your PE architecture, adding DR depends on the structure of your current architecture.
13+
14+
In the case of standard and large installations, DR can be achieved by simply utilising this plan and adding the primary replica. In the case of an extra large infrastructure which includes an external DB, a replica DB is also required. This can be done with the `peadm::add_database` plan. For more detail see [Adding External Databases with peadm::add_database](expanding.md#adding-external-databases-with-peadmadd_database).
15+
16+
Please note, to setup a replica you must have Code Manager configured. To learn more about code manager, please see [Puppet Docs](help.puppet.com).
17+
18+
...
19+
20+
## Adding a replica to standard and large infrastructures
21+
Below is an example of the required parameters to add a primary replica. These parameters can be passed in-line or as a params file.
22+
23+
```json
24+
{
25+
"primary_host": "pe-core-0.lab1.puppet.vm",
26+
"replica_host": "pe-replica-0.lab1.puppet.vm"
27+
}
28+
```
29+
30+
## Adding a Replica to extra large infrastructure
31+
In the below example, we already have an external DB and a replica of it. This means that we should pass in the additional parameter of the replica's hostname.
32+
33+
```json
34+
{
35+
"primary_host": "pe-xl-core-0.lab1.puppet.vm",
36+
"compiler_host": "pe-xl-replica-0.lab1.puppet.vm",
37+
"replica_postgresql_host": "pe-xl-postgresql-replica-0.lab1.puppet.vm"
38+
}
39+
```
40+
41+
## Running the `add_replica` plan
42+
43+
```
44+
bolt plan run peadm::add_replica --params @params.json
45+
```
46+
47+
The plan performs the following steps:
48+
49+
1. Installs the Puppet agent on the new replica host.
50+
2. Updates classifications with new replica configuration.
51+
3. Provisions the infrastructure with PE.
52+
53+
## Parameters
54+
55+
### `primary_host`
56+
57+
- **Type:** `Peadm::SingleTargetSpec`
58+
- **Description:**
59+
The hostname and certname of the PE primary server.
60+
61+
### `replica_host`
62+
63+
- **Type:** `Peadm::SingleTargetSpec`
64+
- **Description:**
65+
The hostname and certname of the replica VM.
66+
67+
### `primary_postgresql_host`
68+
69+
- **Type:** `Optional[Peadm::SingleTargetSpec]`
70+
- **Description:**
71+
The target specification for the primary PostgreSQL host that the new replica will synchronize with. This is the database server from which the replica will replicate data.
72+
73+
### `token_file`
74+
75+
- **Type:** `Optional[String]`
76+
- **Description:**
77+
The Path to token file, only required if located in a non-default location.
78+
79+
80+
81+
## Replica promotion and Replica replacement
82+
83+
Please see the notes on these scenarios in [automated Recovery](automated_recovery.md#recover-from-failed-primary-puppet-server)
84+
85+
## Known Issue on Puppet Enterprise Version 2021.x
86+
87+
When running the add_replica plan to replace an existing replica in your infrastructure, the old replica will not be removed as expected. Instead, both the old and new primary replicas will be present.
88+
89+
This is a known issue and will be fixed in a future release.

‎documentation/expanding.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,7 @@ An external PE-PostgreSQL server is the component which separates the Extra Larg
3232

3333
### Add an external PE-PostgreSQL server in all scenarios
3434

35-
bolt plan run peadm::add_database -t <new-postgres-server-fqdn> primary_host=<primary-server-fqdn>:w
35+
bolt plan run peadm::add_database -t <new-postgres-server-fqdn> primary_host=<primary-server-fqdn>
3636

3737
## Enable Disaster Recovery and Add a Replica with peadm::add_replica
3838

‎plans/add_replica.pp

+8-12
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,12 @@
1-
# This plan is still in development and currently considered experimental.
2-
#
3-
# @api private
4-
#
5-
# @summary Replace a replica host for a Standard or Large architecture.
1+
# @summary Add or replace a replica host.
62
# Supported use cases:
7-
# 1: The existing replica is broken, we have a fresh new VM we want to provision the replica to.
3+
# 1: Adding a replica to an existing primary.
4+
# 2: The existing replica is broken, we have a fresh new VM we want to provision the replica to.
85
# @param primary_host - The hostname and certname of the primary Puppet server
96
# @param replica_host - The hostname and certname of the replica VM
107
# @param replica_postgresql_host - The hostname and certname of the host with the replica PE-PosgreSQL database.
11-
# @param token_file - (optional) the token file in a different location than the default.
12-
#
138
# Can be a separate host in an XL architecture, or undef in Standard or Large.
9+
# @param token_file - (optional) the token file in a different location than the default.
1410
plan peadm::add_replica(
1511
# Standard or Large
1612
Peadm::SingleTargetSpec $primary_host,
@@ -90,10 +86,10 @@
9086
}
9187

9288
run_plan('peadm::util::update_classification', $primary_target,
93-
server_a_host => $replica_avail_group_letter ? { 'A' => $replica_host, default => undef },
94-
server_b_host => $replica_avail_group_letter ? { 'B' => $replica_host, default => undef },
95-
internal_compiler_a_pool_address => $replica_avail_group_letter ? { 'A' => $replica_host, default => undef },
96-
internal_compiler_b_pool_address => $replica_avail_group_letter ? { 'B' => $replica_host, default => undef },
89+
server_a_host => $replica_avail_group_letter ? { 'A' => $replica_target.peadm::certname(), default => undef },
90+
server_b_host => $replica_avail_group_letter ? { 'B' => $replica_target.peadm::certname(), default => undef },
91+
internal_compiler_a_pool_address => $replica_avail_group_letter ? { 'A' => $replica_target.peadm::certname(), default => undef },
92+
internal_compiler_b_pool_address => $replica_avail_group_letter ? { 'B' => $replica_target.peadm::certname(), default => undef },
9793
peadm_config => $peadm_config
9894
)
9995

‎spec/acceptance/peadm_spec/plans/add_replica.pp

+1-1
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@
99
}
1010

1111
$primary_host = $t.filter |$n| { $n.vars['role'] == 'primary' }
12-
$replica_host = $t.filter |$n| { $n.vars['role'] == 'replica' }
12+
$replica_host = $t.filter |$n| { $n.vars['role'] == 'spare-replica' }
1313
$replica_postgresql_host = $t.filter |$n| { $n.vars['role'] == 'replica-pdb-postgresql' }
1414

1515
if $replica_host == [] {

0 commit comments

Comments
 (0)