Skip to content

Commit 6a97e10

Browse files
odyody
committed
Provide documentation on expanding a deployment
Commit creates documentation/expansion.md which explains how to use the add_compiler, add_database, and add_replica to expand your PE deployment, converting to a new architecture, adding disaster recovery, or increasing compilation capacity
1 parent 57f5a9b commit 6a97e10

File tree

2 files changed

+205
-3
lines changed

2 files changed

+205
-3
lines changed

‎README.md‎

Lines changed: 9 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -60,12 +60,18 @@ Follow the links below to usage instructions for each peadm plan.
6060

6161
## Reference
6262

63-
Additional documentation and information pertaining to various aspects or elements of peadm.
63+
Information from the Puppet documentation site that will help you understand which architecture is right for you.
6464

65-
* [DR Component Recovery](https://github.com/puppetlabs/puppetlabs-peadm/blob/main/documentation/recovery.md)
6665
* [PE Architecture Documentation](https://puppet.com/docs/pe/latest/choosing_an_architecture.html)
67-
* [Classification](https://github.com/puppetlabs/puppetlabs-peadm/blob/main/documentation/classification.md)
66+
* [PE Multi-region reference architecture](https://puppet.com/docs/patterns-and-tactics/latest/reference-architectures/pe-multi-region-reference-architectures.html)
67+
68+
69+
Documentation pertaining to additional uses of peadm.
70+
71+
* [DR Component Recovery](https://github.com/puppetlabs/puppetlabs-peadm/blob/main/documentation/recovery.md)
6872
* [Architectures](https://github.com/puppetlabs/puppetlabs-peadm/blob/main/documentation/architectures.md)
73+
* [Expanding Deployment](https://github.com/puppetlabs/puppetlabs-peadm/blob/main/documentation/expanding.md)
74+
* [Classification](https://github.com/puppetlabs/puppetlabs-peadm/blob/main/documentation/classification.md)
6975
* [Testing](https://github.com/puppetlabs/puppetlabs-peadm/blob/main/documentation/pre_post_checks.md)
7076
* [Docker Based Examples](https://github.com/puppetlabs/puppetlabs-peadm/blob/main/documentation/docker_examples.md)
7177

‎documentation/expanding.md‎

Lines changed: 196 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,196 @@
1+
# Expanding your deployment
2+
3+
Documentation which provides instructions for expanding existing PEADM based deployments of Puppet Enterprise with compilers, disaster recovery replicas, and external databases.
4+
5+
* [Adding External Databases with peadm::add_database](#adding-external-databases-with-peadmadd_database)
6+
* [Enable Disaster Recovery and Add a Replica with peadm::add_replica](#enable-disaster-recovery-and-add-a-replica-with-peadmadd_replica)
7+
* [Adding Compilers with peadm::add_compiler](#adding-compilers-with-peadmadd_compiler)
8+
9+
### Key
10+
* _\<primary-server-fqdn\>_ - The FQDN and certname of the Primary Puppet server
11+
* _\<new-postgres-server-fqdn\>_ - The FQDN and certname of the new PE-PostgreSQL server to initialize
12+
* _\<new-replica-server-fqdn\>_ - The FQDN and certname of the new Replica Puppet server to initialize
13+
* _\<replica-postgres-server-fqdn\>_ - The FQDN and certname of the Replica PE-PostgreSQL server
14+
* _\<new-compiler-fqdn\>_ - The FQDN and certname of the new Compiler to initialize
15+
* _\<new-compiler-target-group\>_ - The target availability group letter to assign to the new Compiler
16+
* _\<target-group-server-fqdn\>_ - The FQDN and certname of the Primary Puppet server that is assigned to the new Compiler's target availability group letter
17+
* _\<target-group-postgresql-fqdn\>_ - The FQDN and certname of the PE-PostgreSQL server that is assigned to the new Compiler's target availability group letter
18+
19+
## Adding External Databases with peadm::add_database
20+
21+
An external PE-PostgreSQL database is the component which separates Extra Large from Large deployments. These external database servers are PuppetDB specific and do not serve any other data storage services to other components of Puppet Enterprise. When the Extra Large architecture is being utilized and disaster recovery (DR) is enabled, two external PE-PostgreSQL servers must be provisioned and it is required that both PE-PostgreSQL servers exist prior to provisioning a Replica because it is immediately dependent upon this second external database server. One should notice that in both variations of this action, with **no DR** plans and when preparing to enable it for the first time, the command is exactly the same. This specific plan is intelligent enough to determine the most appropriate values for your second external database by examining the values which were used for the first.
22+
23+
### Add an external PE-PostgreSQL server in all scenarios
24+
25+
bolt plan run peadm::add_database -t <new-postgres-server-fqdn> primary_host=<primary-server-fqdn>
26+
27+
## Enable Disaster Recovery and Add a Replica with peadm::add_replica
28+
29+
All three architectures have two variations, disaster recovery (DR) enabled or disabled. This does not have an effect on the deployed architecture naming, a Standard deployment which deploys a DR Replica is still referred to as the Standard architecture. The basic process remains the same when adding a Replica to any architecture but there are differences in CLI arguments when operating on an Extra Large deployment. When DR is enabled using PEADM, a second availability group will be created, **B**. When DR is not enabled, only one exists, **A**. These availability groups are created for pairing subsets of Compilers with the backend source which will configure them, among other things. By default the initial Primary is assigned availability group **A** and the initial Replica is assigned **B**. The availability group assignments stay with the server and importantly not with the role of the server. If you choose to promote the Replica assigned to **B** to a Primary than availability group **B** is now simply the group containing the Primary. When adding a Replica you do not need to know the availability group of the Primary it is being paired with, the `peadm::add_replica` plan will determine the appropriate group by looking up which group the Primary is assigned.
30+
31+
### Adding a Replica to Standard and Large deployments
32+
33+
bolt plan run peadm::add_replica primary_host=<primary-server-fqdn> replica_host=<new-replica-server-fqdn>
34+
35+
### Adding a Replica to Extra Large deployments
36+
37+
In Extra Large deployments you must provide the `replica_postgresql_host` parameter set to PE-PostgreSQL host which will be collocated within the same availability group as the new Replica. The `peadm::get_peadm_config` again helps you figure this out. In the **Example** section below, the task has figured out which PE-PostgreSQL server is the Replica database host. You'll find the value at `params.replica_postgresql_host`, which is equal to `pe-psql-6251cd-1.us-west1-b.c.slice-cody.internal`. Reminder, the Replica PE-PostgreSQL server **MUST** be provisioned and deployed prior to initializing a Replica Puppet server.
38+
39+
bolt plan run peadm::get_peadm_config --targets <primary-server-fqdn>
40+
bolt plan run peadm::add_replica primary_host=<primary-server-fqdn> replica_host=<new-replica-server-fqdn> replica_postgresql_host=<replica-postgres-server-fqdn>
41+
42+
**Example**
43+
44+
% bolt task run peadm::get_peadm_config --targets pe-server-6251cd-0.us-west1-a.c.slice-cody.internal -- INSERT --
45+
Started on pe-server-6251cd-0.us-west1-a.c.slice-cody.internal...
46+
Finished on pe-server-6251cd-0.us-west1-a.c.slice-cody.internal:
47+
{
48+
"params": {
49+
"primary_host": "pe-server-6251cd-0.us-west1-a.c.slice-cody.internal",
50+
"replica_host": null,
51+
"primary_postgresql_host": "pe-psql-6251cd-0.us-west1-a.c.slice-cody.internal",
52+
"replica_postgresql_host": "pe-psql-6251cd-1.us-west1-b.c.slice-cody.internal",
53+
"compilers": [
54+
"pe-compiler-6251cd-0.us-west1-a.c.slice-cody.internal",
55+
"pe-compiler-6251cd-1.us-west1-b.c.slice-cody.internal"
56+
],
57+
"compiler_pool_address": "puppet.pe-compiler-lb-6251cd.il4.us-west1.lb.slice-cody.internal",
58+
"internal_compiler_a_pool_address": "pe-server-6251cd-0.us-west1-a.c.slice-cody.internal",
59+
"internal_compiler_b_pool_address": null
60+
},
61+
"role-letter": {
62+
"server": {
63+
"A": "pe-server-6251cd-0.us-west1-a.c.slice-cody.internal",
64+
"B": null
65+
},
66+
"postgresql": {
67+
"A": "pe-psql-6251cd-0.us-west1-a.c.slice-cody.internal",
68+
"B": "pe-psql-6251cd-1.us-west1-b.c.slice-cody.internal"
69+
},
70+
"compilers": {
71+
"A": [
72+
"pe-compiler-6251cd-0.us-west1-a.c.slice-cody.internal",
73+
"pe-compiler-6251cd-1.us-west1-b.c.slice-cody.internal"
74+
],
75+
"B": [
76+
77+
]
78+
}
79+
}
80+
}
81+
Successful on 1 target: pe-server-6251cd-0.us-west1-a.c.slice-cody.internal
82+
Ran on 1 target in 2.56 sec
83+
84+
## Adding Compilers with peadm::add_compiler
85+
86+
Standard deployments are the only architecture of the three which do not have Compilers available upon initial deployment, the lack of them is what differentiates Standard from Large. Architecture has no effect on the process for adding Compilers to a deployment. The [peadm::add_compiler](https://github.com/puppetlabs/puppetlabs-peadm/blob/main/plans/add_compiler.pp) plan functions identical in all three architecture, even if you're adding the 1st or the 100th but some options do change slightly depending.
87+
88+
### Adding Compilers to Standard and Large without disaster recovery
89+
90+
The command invocation is identical when adding compilers to a Standard or Large deployment if disaster recovery (DR) is not enabled and a Replica has not been provisioned. Take note of the values for `avail_group_letter` and `primary_postgresql_host`, in this **no DR** scenario, the value of these parameter will always be set to **A** and the FQDN of the Primary Puppet server.
91+
92+
bolt plan run peadm::add_compiler primary_host=<primary-server-fqdn> compiler_host=<new-compiler-fqdn> avail_group_letter=A primary_postgresql_host=<primary-server-fqdn>
93+
94+
### Adding Compilers to Extra Large without disaster recovery
95+
96+
When adding a compiler to an Extra Large deployment in a **no DR** scenario, the only difference is that the `primary_postgresql_host` changes to be the value of the Primary PE-PostgreSQL server as opposed to the Primary Puppet server.
97+
98+
bolt plan run peadm::add_compiler primary_host=<primary-server-fqdn> compiler_host=<new-compiler-fqdn> avail_group_letter=A primary_postgresql_host=<primary-postgresql-server-fqdn>
99+
100+
### Adding Compilers to Standard and Large when disaster recovery has been enabled
101+
102+
When disaster recovery (DR) is enabled and a Replica provisioned, PEADM creates a second availability group. You must take this into consideration when adding new compilers and ensure you are assigning appropriate values for the group the compiler is targeted for. It is a good idea to keep these two availability groups populated with an equal quantity of compilers. Besides the value of `avail_group_letter` being dependent on which group the new compiler is targeted towards, the value of `primary_postgresql_host` will also vary.
103+
104+
The name of the `primary_postgresql_host` parameter can be confusing, it is **NOT** always equal to the Primary Puppet server or Primary PE-PostgreSQL server, it can also be equal to the Replica Puppet server or Replica PE-PostgreSQL server. It should be set to the server which is a member of the compiler's target availability group. The easiest way to determine this value is to first run the `peadm::get_peadm_config` task and source the value from its output. In the **Example** section the value to use when targeting the **B** group is `pe-server-59ab63-1.us-west1-b.c.slice-cody.internal`. You'll find the value at `role-letter.server.B`.
105+
106+
bolt plan run peadm::get_peadm_config --targets <primary-server-fqdn>
107+
bolt plan run peadm::add_compiler primary_host=<primary-server-fqdn> compiler_host=<new-compiler-fqdn> avail_group_letter=<new-compiler-target-group> primary_postgresql_host=<target-group-server-fqdn>
108+
109+
**Example**
110+
111+
% bolt task run peadm::get_peadm_config --targets pe-server-59ab63-0.us-west1-a.c.slice-cody.internal
112+
Started on pe-server-59ab63-0.us-west1-a.c.slice-cody.internal...
113+
Finished on pe-server-59ab63-0.us-west1-a.c.slice-cody.internal:
114+
{
115+
"params": {
116+
"primary_host": "pe-server-59ab63-0.us-west1-a.c.slice-cody.internal",
117+
"replica_host": "pe-server-59ab63-1.us-west1-b.c.slice-cody.internal",
118+
"primary_postgresql_host": null,
119+
"replica_postgresql_host": null,
120+
"compilers": [
121+
"pe-compiler-59ab63-0.us-west1-a.c.slice-cody.internal",
122+
"pe-compiler-59ab63-1.us-west1-b.c.slice-cody.internal"
123+
],
124+
"compiler_pool_address": "puppet.pe-compiler-lb-59ab63.il4.us-west1.lb.slice-cody.internal",
125+
"internal_compiler_a_pool_address": "pe-server-59ab63-0.us-west1-a.c.slice-cody.internal",
126+
"internal_compiler_b_pool_address": "pe-server-59ab63-1.us-west1-b.c.slice-cody.internal"
127+
},
128+
"role-letter": {
129+
"server": {
130+
"A": "pe-server-59ab63-0.us-west1-a.c.slice-cody.internal",
131+
"B": "pe-server-59ab63-1.us-west1-b.c.slice-cody.internal"
132+
},
133+
"postgresql": {
134+
"A": null,
135+
"B": null
136+
},
137+
"compilers": {
138+
"A": [
139+
"pe-compiler-59ab63-0.us-west1-a.c.slice-cody.internal"
140+
],
141+
"B": [
142+
"pe-compiler-59ab63-1.us-west1-b.c.slice-cody.internal"
143+
]
144+
}
145+
}
146+
}
147+
Successful on 1 target: pe-server-59ab63-0.us-west1-a.c.slice-cody.internal
148+
Ran on 1 target in 2.46 sec
149+
150+
### Adding compilers to Extra Large when disaster recovery has been enabled
151+
152+
Adding a compiler to an Extra Large deployment with disaster recovery (DR) enabled is similar to Standard and Large but the value of `primary_postgresql_host` will not correspond to the Primary or Replica since PuppetDB databases are now hosted external. In the **Example** section the value to use when targeting the **A** group is `pe-psql-65e03f-0.us-west1-a.c.slice-cody.internal`. You'll find the value at `role-letter.postgresql.A`.
153+
154+
155+
bolt plan run peadm::get_peadm_config --targets <primary-server-fqdn>
156+
bolt plan run peadm::add_compiler primary_host=<primary-server-fqdn> compiler_host=<new-compiler-fqdn> avail_group_letter=<new-compiler-target-availability-group> primary_postgresql_host=<target-availability-group-postgresql-fqdn>
157+
158+
**Example**
159+
160+
% bolt task run peadm::get_peadm_config --targets pe-server-65e03f-0.us-west1-a.c.slice-cody.internal
161+
Started on pe-server-65e03f-0.us-west1-a.c.slice-cody.internal...
162+
Finished on pe-server-65e03f-0.us-west1-a.c.slice-cody.internal:
163+
{
164+
"params": {
165+
"primary_host": "pe-server-65e03f-0.us-west1-a.c.slice-cody.internal",
166+
"replica_host": "pe-server-65e03f-1.us-west1-b.c.slice-cody.internal",
167+
"primary_postgresql_host": "pe-psql-65e03f-0.us-west1-a.c.slice-cody.internal",
168+
"replica_postgresql_host": "pe-psql-65e03f-1.us-west1-b.c.slice-cody.internal",
169+
"compilers": [
170+
"pe-compiler-65e03f-0.us-west1-a.c.slice-cody.internal"
171+
],
172+
"compiler_pool_address": "puppet.pe-compiler-lb-65e03f.il4.us-west1.lb.slice-cody.internal",
173+
"internal_compiler_a_pool_address": "pe-server-65e03f-0.us-west1-a.c.slice-cody.internal",
174+
"internal_compiler_b_pool_address": "pe-server-65e03f-1.us-west1-b.c.slice-cody.internal"
175+
},
176+
"role-letter": {
177+
"server": {
178+
"A": "pe-server-65e03f-0.us-west1-a.c.slice-cody.internal",
179+
"B": "pe-server-65e03f-1.us-west1-b.c.slice-cody.internal"
180+
},
181+
"postgresql": {
182+
"A": "pe-psql-65e03f-0.us-west1-a.c.slice-cody.internal",
183+
"B": "pe-psql-65e03f-1.us-west1-b.c.slice-cody.internal"
184+
},
185+
"compilers": {
186+
"A": [
187+
"pe-compiler-65e03f-0.us-west1-a.c.slice-cody.internal"
188+
],
189+
"B": [
190+
"pe-compiler-65e03f-1.us-west1-b.c.slice-cody.internal"
191+
]
192+
}
193+
}
194+
}
195+
Successful on 1 target: pe-server-65e03f-0.us-west1-a.c.slice-cody.internal
196+
Ran on 1 target in 2.35 sec

0 commit comments

Comments
 (0)