Skip to content

Commit f4e5668

Browse files
gvasquezvargasgvasquezvargas
authored
Merge pull request #777 from EnterpriseDB/TPA/23.42
Release branch for TPA
2 parents c6df39e + 857d639 commit f4e5668

26 files changed

+1141
-71
lines changed

‎product_docs/docs/tpa/23/INSTALL-repo.mdx‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -22,15 +22,15 @@ the source and [run TPA in a Docker container](reference/INSTALL-docker/).
2222
## Quickstart
2323

2424
First, you must install the various dependencies Python 3, Python
25-
venv, git, openvpn and patch. Installing from EDB repositories
25+
venv, git, and openvpn. Installing from EDB repositories
2626
would install these automatically along with the TPA
2727
packages.
2828

2929
Before you install TPA, you must install the required packages:
3030

31-
- **Debian/Ubuntu** <br/> `sudo apt-get install python3 python3-pip python3-venv git openvpn patch`
32-
- **Redhat, Rocky or AlmaLinux (RHEL7)** <br/> `sudo yum install python3 python3-pip epel-release git openvpn patch`
33-
- **Redhat, Rocky or AlmaLinux (RHEL8)** <br/>`sudo yum install python36 python3-pip epel-release git openvpn patch`
31+
- **Debian/Ubuntu** <br/> `sudo apt-get install python3 python3-pip python3-venv git openvpn`
32+
- **Redhat, Rocky or AlmaLinux (RHEL7)** <br/> `sudo yum install python3 python3-pip epel-release git openvpn`
33+
- **Redhat, Rocky or AlmaLinux (RHEL8)** <br/>`sudo yum install python36 python3-pip epel-release git openvpn`
3434

3535
## Clone and setup
3636

‎product_docs/docs/tpa/23/INSTALL.mdx‎

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -64,7 +64,7 @@ to the target instances.
6464
## Installing TPA packages
6565

6666
To install TPA, you must first [subscribe to an EDB repository](https://www.enterprisedb.com/docs/repos/getting_started/).
67-
TPA is available in all EDB repositories.
67+
TPA is available in all EDB repositories.
6868

6969
Install TPA as follows:
7070

@@ -107,6 +107,9 @@ install the correct versions of all required modules.
107107
sudo /opt/EDB/TPA/bin/tpaexec setup
108108
```
109109

110+
`tpaexec setup` will automatically use a suitable version of the
111+
requirements.txt file to install the correct modules for your system.
112+
110113
You must run this as root because it writes to `/opt/EDB/TPA`,
111114
but the process will not affect any system-wide Python modules you may
112115
have installed (including Ansible).
@@ -138,10 +141,10 @@ If your internet-connected machine uses the same operating system as the
138141
target, we recommend using `yumdownloader` (RHEL-like) or `apt download`
139142
(Debian-like) to download the packages.
140143

141-
Alternatively, you can download packages for any platform from your
144+
Alternatively, you can download packages for any platform from your
142145
browser by visiting [EDB Repos](https://www.enterprisedb.com/repos) and
143-
selecting either 'Enterprise', 'Standard' or 'Community 360' under the
144-
heading 'Download EDB software packages from your browser'.
146+
selecting either 'Enterprise', 'Standard' or 'Community 360' under the
147+
heading 'Download EDB software packages from your browser'.
145148
To install TPA you need these packages:
146149

147150
- tpaexec

‎product_docs/docs/tpa/23/ansible-and-sudo.mdx‎

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -118,6 +118,116 @@ the sudo options only if there is a specific need to do so. The defaults
118118
were chosen for good reasons. For example, removing `-S -n` will cause
119119
tasks to timeout if password-less sudo is incorrectly configured.
120120

121+
## Managing privilege escalation configuration
122+
123+
### Default sudo configuration
124+
125+
By default, TPA automatically manages sudo-related configuration on target
126+
instances, including installing the sudo package if not present and
127+
configuring sudoers files for various components.
128+
129+
The default value of `privilege_escalation_command` is `"sudo"`, which enables
130+
TPA to manage sudo installation and configuration.
131+
132+
### Using an alternative privilege escalation command
133+
134+
If your environment uses a different privilege escalation command, you can
135+
configure TPA to use an alternative by setting `privilege_escalation_command`
136+
in `cluster_vars`:
137+
138+
```yaml
139+
cluster_vars:
140+
privilege_escalation_command: other_tool # replaces sudo; may include arguments
141+
```
142+
143+
The value is used as a direct in-place replacement for `sudo` in each
144+
privilege escalation command TPA generates for managed applications. It may
145+
include additional arguments if needed (e.g., `other_tool --flag`).
146+
147+
You can set it to any privilege escalation command supported by Ansible's
148+
become mechanism. Refer to the
149+
[Ansible privilege escalation documentation](https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_privilege_escalation.html)
150+
for the complete list of supported methods.
151+
152+
**Important:** `sudo` is the only privilege escalation command officially
153+
supported by EDB. When using alternative commands, you are responsible for
154+
ensuring compatibility and proper configuration. EDB Support may have limited
155+
ability to assist with issues related to alternative privilege escalation
156+
mechanisms.
157+
158+
#### Ansible's become method vs. `privilege_escalation_command`
159+
160+
There are two separate privilege escalation settings to be aware of:
161+
162+
- **`ansible_become_method`** controls how Ansible itself escalates privileges
163+
when running deployment tasks on target instances. This is an Ansible variable
164+
set in your inventory or `ansible.cfg`.
165+
- **`privilege_escalation_command`** controls the command that the managed
166+
applications (EFM, repmgr, HARP) invoke at runtime to escalate privileges
167+
for service management operations, independently of Ansible.
168+
169+
Because they serve different purposes, both must be configured consistently.
170+
If your environment uses an alternative tool instead of sudo, you must set
171+
`privilege_escalation_command` in `cluster_vars` *and* configure
172+
`ansible_become_method` in your Ansible inventory or `ansible.cfg` to match.
173+
174+
#### Recommended approach: Using hooks
175+
176+
If you need to use an alternative privilege escalation command, we recommend
177+
using [TPA hooks](tpaexec-hooks/) to configure your privilege escalation
178+
mechanism. Hooks allow you to run custom tasks at specific points during
179+
deployment, giving you full control over how privilege escalation is configured
180+
whilst keeping your customisations separate from TPA's core deployment logic.
181+
182+
For example, you can use a `post-repo` hook to install and configure your
183+
privilege escalation command after repositories are configured, or a `pre-deploy`
184+
hook to set up the necessary permissions before the main deployment begins.
185+
This approach provides better maintainability and makes it easier to manage
186+
environment-specific requirements.
187+
188+
#### Manual configuration requirements
189+
190+
When using an alternative privilege escalation command (anything other than
191+
`"sudo"`), TPA will skip sudo package installation and sudoers configuration.
192+
You must install and configure the chosen privilege escalation command
193+
on all target systems, either manually or with hooks, before running
194+
`tpaexec deploy`.
195+
196+
**1. Service management permissions for the postgres user**
197+
198+
Your privilege escalation mechanism must allow the postgres system user to
199+
execute systemctl commands for starting, stopping, restarting, and reloading
200+
PostgreSQL and related services. This is required for failover managers
201+
(repmgr, HARP, EFM) to function correctly during automatic failover operations.
202+
203+
For example, with sudo, TPA would configure the following permissions:
204+
205+
```
206+
postgres ALL=(ALL) NOPASSWD: /bin/systemctl start postgresql
207+
postgres ALL=(ALL) NOPASSWD: /bin/systemctl stop postgresql
208+
postgres ALL=(ALL) NOPASSWD: /bin/systemctl restart postgresql
209+
postgres ALL=(ALL) NOPASSWD: /bin/systemctl reload postgresql
210+
```
211+
212+
You must configure equivalent permissions in your chosen privilege escalation
213+
system.
214+
215+
**2. EFM database function permissions (EFM clusters only)**
216+
217+
If your cluster uses EFM as the failover manager, your privilege escalation
218+
mechanism must allow the EFM system user to execute the `efm_db_functions`
219+
script as the postgres user. This is required for EFM to perform health checks
220+
and failover operations.
221+
222+
For example, with sudo, TPA would configure:
223+
224+
```
225+
efm ALL=(postgres) NOPASSWD: /usr/edb/efm-X.Y/bin/efm_db_functions
226+
```
227+
228+
Configure equivalent permissions in your privilege escalation system to allow
229+
the efm user to run this script as the postgres user.
230+
121231
## Logging
122232

123233
For playbook executions, the sudo logs will show mostly invocations of

‎product_docs/docs/tpa/23/architecture-PGD-S.mdx‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -45,10 +45,10 @@ More detail on the options is provided in the following section.
4545

4646
#### Mandatory Options
4747

48-
| Options | Description |
49-
| ----------------------------------------------------- | ----------------------------------------------------------------------------------------- |
50-
| `--architecture` (`-a`) | Must be set to `PGD-S` |
51-
| Postgres flavour and version (e.g. `--postgresql 15`) | A valid [flavour and version specifier](tpaexec-configure/#postgres-flavour-and-version). |
48+
| Options | Description |
49+
| ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
50+
| `--architecture` (`-a`) | Must be set to `PGD-S` |
51+
| Postgres flavour and version (e.g. `--postgresql 15`) | A valid [flavour and version specifier](tpaexec-configure/#postgres-flavour-and-version). Supports Postgres 14-18. |
5252

5353
<br/><br/>
5454

‎product_docs/docs/tpa/23/architecture-PGD-X.mdx‎

Lines changed: 16 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -49,27 +49,27 @@ More detail on the options is provided in the following section.
4949

5050
#### Mandatory Options
5151

52-
| Options | Description |
53-
| ----------------------------------------------------- | ----------------------------------------------------------------------------------------- |
54-
| `--architecture` (`-a`) | Must be set to `PGD-X` |
55-
| Postgres flavour and version (e.g. `--postgresql 15`) | A valid [flavour and version specifier](tpaexec-configure/#postgres-flavour-and-version). |
56-
| `--pgd-routing` | Must be either `global` or `local`. |
52+
| Options | Description |
53+
| ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
54+
| `--architecture` (`-a`) | Must be set to `PGD-X` |
55+
| Postgres flavour and version (e.g. `--postgresql 15`) | A valid [flavour and version specifier](tpaexec-configure/#postgres-flavour-and-version). Supports Postgres 14-18. |
56+
| `--pgd-routing` | Must be either `global` or `local`. |
5757

5858
<br/><br/>
5959

6060
#### Additional Options
6161

62-
| Options | Description | Behaviour if omitted |
63-
| --------------------------- | ----------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- |
64-
| `--platform` | One of `aws`, `docker`, `bare`. | Defaults to `aws`. |
65-
| `--location-names` | A space-separated list of location names. The number of locations is equal to the number of names supplied. | TPA will configure a single location with three data nodes. |
66-
| `--witness-only-location` | A location name, must be a member of `location-names`. | No witness-only location is added. |
67-
| `--data-nodes-per-location` | The number of data nodes in each location, must be at least 2. | Defaults to 3. |
68-
| `--enable-camo` | Sets two data nodes in each location as CAMO partners. | CAMO will not be enabled. |
69-
| `--bdr-database` | The name of the database to be used for replication. | Defaults to `bdrdb`. |
70-
| `--enable-pgd-probes` | Enable http(s) api endpoints for pgd-proxy such as `health/is-ready` to allow probing proxy's health. | Disabled by default. |
71-
| `--proxy-listen-port` | The port on which proxy nodes will route traffic to the write leader. | Defaults to 6432 |
72-
| `--proxy-read-only-port` | The port on which proxy nodes will route read-only traffic to shadow nodes. | Defaults to 6433 |
62+
| Options | Description | Behaviour if omitted |
63+
| --------------------------- | ----------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
64+
| `--platform` | One of `aws`, `docker`, `bare`. | Defaults to `aws`. |
65+
| `--location-names` | A space-separated list of location names. The number of locations is equal to the number of names supplied. | TPA will configure a single location with three data nodes. |
66+
| `--witness-only-location` | A location name, must be a member of `location-names`. | No witness-only location is added. |
67+
| `--data-nodes-per-location` | The number of data nodes in each location, must be at least 2. | Defaults to 3. |
68+
| `--enable-camo` | Sets two data nodes in each location as CAMO partners. | CAMO will not be enabled. |
69+
| `--bdr-database` | The name of the database to be used for replication. | Defaults to `bdrdb`. |
70+
| `--enable-pgd-probes` | Enable http(s) api endpoints for pgd-proxy such as `health/is-ready` to allow probing proxy's health. | Disabled by default. |
71+
| `--read-write-port` | The port for Connection Manager to listen on for read-write connections. | Left empty in config.yml, allowing default of the postgres port + 1000 |
72+
| `--read-only-port` | The port for Connection Manager to listen on for read-only connections. | Left empty in config.yml, allowing default of the read-write port + 1 |
7373

7474
<br/><br/>
7575

‎product_docs/docs/tpa/23/configure-cluster.mdx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -132,6 +132,7 @@ postgres_version: '14' # Defined at top-level
132132
cluster_vars:
133133
postgres_version: "{{ postgres version }}" # Templated with top-level variable
134134
postgres_data_dir: "/data/{{ cluster_name }}/edb{{ postgres_version }}/data" # Templated with top-level variable
135+
privilege_escalation_command: sudo
135136
```
136137

137138
In this case, `tpaexec provision` will write three variables (a

‎product_docs/docs/tpa/23/firstclusterdeployment.mdx‎

Lines changed: 0 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -44,12 +44,6 @@ newgrp docker
4444
lets them trivially gain root on the Docker host. Only trusted users
4545
should have access to the Docker daemon.
4646

47-
!!! Note on RHEL 7 instances
48-
49-
To use RHEL 7 instances your host must be configured to run cgroups v1.
50-
Refer to documentation for your system to verify and alter cgroups configuration,
51-
or choose another operating system for your containers to follow this tutorial.
52-
5347
### Creating a configuration with TPA
5448

5549
The next step in this process is to create a configuration. TPA does most of the work for you through its `configure` command. All you have to do is supply command line flags and options to select, in broad terms, what you want to deploy. Here's our `tpaexec configure` command:

‎product_docs/docs/tpa/23/images/m1.dot‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# © Copyright EnterpriseDB UK Limited 2015-2025 - All rights reserved.
1+
# © Copyright EnterpriseDB UK Limited 2015-2026 - All rights reserved.
22

33
digraph M1 {
44
backup [shape=box];

‎product_docs/docs/tpa/23/index.mdx‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -44,11 +44,11 @@ title: Trusted Postgres Architect
4444
originalFilePath: index.md
4545
pdf: true
4646
directoryDefaults:
47-
version: 23.41.0
47+
version: 23.42.0
4848

4949
---
5050

51-
© Copyright EnterpriseDB UK Limited 2015-2025 - All rights reserved.
51+
© Copyright EnterpriseDB UK Limited 2015-2026 - All rights reserved.
5252

5353
## Introduction
5454

‎product_docs/docs/tpa/23/platform-docker.mdx‎

Lines changed: 12 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -53,11 +53,19 @@ and launch Docker from the application menu.
5353

5454
### Cgroups
5555

56-
TPA supports Docker containers on hosts running cgroups version 1 or 2.
57-
On a host running cgroups2, instances running RHEL 7 are not supported.
56+
All [currently-supported operating systems](reference/distributions/) provide support cgroups
57+
version 2. You should always use cgroups version 2 on the host machine
58+
when deploying to Docker unless you are using a legacy operating system.
5859

59-
If you need to use RHEL 7 instances but your host is running cgroups
60-
version 2, you can switch to cgroups version 1 as follows.
60+
!!!Important
61+
62+
Instructions for using legacy systems are provided purely for
63+
testing or to support migrating away from those platforms.
64+
!!!
65+
66+
For some legacy platforms, in particular RHEL 7, you will need to
67+
configure your host to use version 1. You can switch to cgroups version
68+
1 as follows.
6169

6270
On Debian-family Linux distributions:
6371

0 commit comments

Comments
 (0)