Merge pull request #5782 from EnterpriseDB/DOCS-780-pull-tpa-docs-for…

…-23-33-release-on-24th-june TPA23.33
EnterpriseDB · Jun 24, 2024 · 3fe81d7 · 3fe81d7 · github-actions · Jun 24, 2024
2 parents 95e3933 + f569b63
commit 3fe81d7
Show file tree

Hide file tree

Showing 84 changed files with 356 additions and 82 deletions.
diff --git a/product_docs/docs/tpa/23/INSTALL-repo.mdx b/product_docs/docs/tpa/23/INSTALL-repo.mdx
@@ -1,5 +1,6 @@
 ---
 navTitle: Install from Source
+description: Installing and running TPA from a copy of the source code repository.
 title: Installing TPA from source
 originalFilePath: INSTALL-repo.md
 
@@ -9,6 +10,7 @@ This document explains how to use TPA from a copy of the source code
 repository.
 
 !!! Note
+
       EDB customers must [install TPA from packages](INSTALL/) in
       order to receive EDB support for the software.
 

diff --git a/product_docs/docs/tpa/23/INSTALL.mdx b/product_docs/docs/tpa/23/INSTALL.mdx
@@ -1,5 +1,6 @@
 ---
 navTitle: Installation
+description: Installing TPA packages and setting up the Python environment.
 title: TPA installation
 originalFilePath: INSTALL.md
 
@@ -16,6 +17,7 @@ See [Distribution support](reference/distributions/) for information
 on what platforms are supported.
 
 !!! Info
+
     Please make absolutely sure that your system has the correct
     date and time set, because various things will fail otherwise. We
     recommend you use a network time, for example `sudo ntpdate
@@ -129,6 +131,7 @@ Next, run `tpaexec setup` to create an isolated Python environment and
 install the correct versions of all required modules.
 
 !!! Note
+
     On Ubuntu versions prior to 20.04, please use `sudo -H tpaexec setup`
     to avoid subsequent permission errors during `tpaexec configure`
 
@@ -167,9 +170,18 @@ If your internet-connected machine uses the same operating system as the
 target, we recommend using `yumdownloader` (RHEL-like) or `apt download`
 (Debian-like) to download the packages.
 
-If this is not possible, please contact EDB support and we will provide
-you with a download link or instructions appropriate to your
-subscription.
+Alternatively, you can download packages for any platform from your 
+browser by visiting [EDB Repos](https://www.enterprisedb.com/repos) and
+selecting either 'Enterprise', 'Standard' or 'Community 360' under the 
+heading 'Download EDB software packages from your browser'. 
+To install TPA you need these packages:
+
+-   tpaexec
+-   tpaexec-deps
+-   edb-python39
+
+Once you have transferred the downloaded packages to the target server,
+you must install them using the appropriate tool for your platform.
 
 ### Installing without access to a Python package index
 

diff --git a/product_docs/docs/tpa/23/ansible-and-sudo.mdx b/product_docs/docs/tpa/23/ansible-and-sudo.mdx
@@ -1,5 +1,8 @@
 ---
-title: TPA, Ansible, and sudo
+description: >-
+  How TPA uses Ansible with sudo to execute tasks with elevated privileges on
+  target instances.
+title: 'TPA, Ansible, and sudo'
 originalFilePath: ansible-and-sudo.md
 
 ---

diff --git a/product_docs/docs/tpa/23/architecture-BDR-Always-ON.mdx b/product_docs/docs/tpa/23/architecture-BDR-Always-ON.mdx
@@ -1,4 +1,5 @@
 ---
+description: Configuring a BDR-Always-ON cluster with TPA.
 title: BDR-Always-ON
 originalFilePath: architecture-BDR-Always-ON.md
 

diff --git a/product_docs/docs/tpa/23/architecture-M1.mdx b/product_docs/docs/tpa/23/architecture-M1.mdx
@@ -1,4 +1,5 @@
 ---
+description: Configuring the M1 architecture with TPA.
 title: M1
 originalFilePath: architecture-M1.md
 
@@ -78,16 +79,17 @@ More detail on the options is provided in the following section.
 
 #### Additional Options
 
-| Parameter                   | Description                                                                                                                                                                                                            | Behaviour if omitted                            |
-| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- |
-| `--platform`                | One of `aws`, `docker`, `bare`.                                                                                                                                                                                        | Defaults to `aws`.                              |
-| `--location-names`          | A space-separated list of location names. The number of active locations is equal to the number of names supplied, minus one for each of the witness-only location and the single-node location if they are requested. | A single location called "main" is used.        |
-| `--primary-location`        | The location where the primary server will be. Must be a member of `location-names`.                                                                                                                                   | The first listed location is used.              |
-| `--data-nodes-per-location` | A number from 1 upwards. In each location, one node will be configured to stream directly from the cluster's primary node, and the other nodes, if present, will stream from that one.                                 | Defaults to 2.                                  |
-| `--witness-only-location`   | A location name, must be a member of `location-names`.                                                                                                                                                                 | No witness-only location is added.              |
-| `--single-node-location`    | A location name, must be a member of `location-names`.                                                                                                                                                                 | No single-node location is added.               |
-| `--enable-haproxy`          | 2 additional nodes will be added as a load balancer layer.<br/>Only supported with Patroni as the failover manager.                                                                                                    | HAproxy nodes will not be added to the cluster. |
-| `--patroni-dcs`             | Select the Distributed Configuration Store backend for patroni.<br/>Only option is `etcd` at this time. <br/>Only supported with Patroni as the failover manager.                                                      | Defaults to `etcd`.                             |
+| Parameter                   | Description                                                                                                                                                                                                            | Behaviour if omitted                             |
+| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ |
+| `--platform`                | One of `aws`, `docker`, `bare`.                                                                                                                                                                                        | Defaults to `aws`.                               |
+| `--location-names`          | A space-separated list of location names. The number of active locations is equal to the number of names supplied, minus one for each of the witness-only location and the single-node location if they are requested. | A single location called "main" is used.         |
+| `--primary-location`        | The location where the primary server will be. Must be a member of `location-names`.                                                                                                                                   | The first listed location is used.               |
+| `--data-nodes-per-location` | A number from 1 upwards. In each location, one node will be configured to stream directly from the cluster's primary node, and the other nodes, if present, will stream from that one.                                 | Defaults to 2.                                   |
+| `--witness-only-location`   | A location name, must be a member of `location-names`.                                                                                                                                                                 | No witness-only location is added.               |
+| `--single-node-location`    | A location name, must be a member of `location-names`.                                                                                                                                                                 | No single-node location is added.                |
+| `--enable-haproxy`          | 2 additional nodes will be added as a load balancer layer.<br/>Only supported with Patroni as the failover manager.                                                                                                    | HAproxy nodes will not be added to the cluster.  |
+| `--enable-pgbouncer`        | PgBouncer will be configured in the Postgres nodes to pool connections for the primary.                                                                                                                                | PgBouncer will not be configured in the cluster. |
+| `--patroni-dcs`             | Select the Distributed Configuration Store backend for patroni.<br/>Only option is `etcd` at this time. <br/>Only supported with Patroni as the failover manager.                                                      | Defaults to `etcd`.                              |
 
 <br/><br/>
 

diff --git a/product_docs/docs/tpa/23/architecture-PGD-Always-ON.mdx b/product_docs/docs/tpa/23/architecture-PGD-Always-ON.mdx
@@ -1,4 +1,5 @@
 ---
+description: Configuring a PGD-Always-ON cluster with TPA.
 title: PGD-Always-ON
 originalFilePath: architecture-PGD-Always-ON.md
 
@@ -61,6 +62,8 @@ More detail on the options is provided in the following section.
 | `--enable-camo`                  | Sets two data nodes in each location as CAMO partners.                                                      | CAMO will not be enabled.                                   |
 | `--bdr-database`                 | The name of the database to be used for replication.                                                        | Defaults to `bdrdb`.                                        |
 | `--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.                                        |
+| `--proxy-listen-port`            | The port on which proxy nodes will route traffic to the write leader.                                       | Defaults to 6432                                            |
+| `--proxy-read-only-port`         | The port on which proxy nodes will route read-only traffic to shadow nodes.                                 | Defaults to 6433                                            |
 
 <br/><br/>
 
@@ -79,6 +82,7 @@ regions, your own data centres, or any other designation to identify
 where your servers are hosted.
 
 !!! Note for AWS users
+
     If you are using TPA to provision an AWS cluster, the locations will
     be mapped to separate availability zones within the `--region` you
     specify.

diff --git a/product_docs/docs/tpa/23/configure-cluster.mdx b/product_docs/docs/tpa/23/configure-cluster.mdx
@@ -1,4 +1,5 @@
 ---
+description: How to configure a TPA cluster.
 title: Cluster configuration
 originalFilePath: configure-cluster.md
 

diff --git a/product_docs/docs/tpa/23/configure-instance.mdx b/product_docs/docs/tpa/23/configure-instance.mdx
@@ -1,4 +1,5 @@
 ---
+description: Customising the deployment process on cluster instances.
 title: Instance configuration
 originalFilePath: configure-instance.md
 

diff --git a/product_docs/docs/tpa/23/configure-source.mdx b/product_docs/docs/tpa/23/configure-source.mdx
@@ -1,10 +1,12 @@
 ---
+description: How to build Postgres and other components from source with TPA.
 title: Building from source
 originalFilePath: configure-source.md
 
 ---
 
 !!!Warning
+
 This option is intended for developers and advanced users. 
 Only software built and tested by EDB is supported by EDB. Please refer to 
 [Self-Managed Supported Open Source Software](https://www.enterprisedb.com/product-compatibility/edb-supported-open-source-software.pdf).

diff --git a/product_docs/docs/tpa/23/firstclusterdeployment.mdx b/product_docs/docs/tpa/23/firstclusterdeployment.mdx
@@ -1,5 +1,6 @@
 ---
 navTitle: Tutorial
+description: A simple tutorial to deploy a Postgres cluster with TPA on Docker.
 title: A First Cluster Deployment
 originalFilePath: firstclusterdeployment.md
 
@@ -38,11 +39,13 @@ newgrp docker
 ```
 
 !!! Warning
+
     Giving a user the ability to speak to the Docker daemon
     lets them trivially gain root on the Docker host. Only trusted users
     should have access to the Docker daemon.
 
 !!! Note on RHEL 7 instances
+
     To use RHEL 7 instances your host must be configured to run cgroups v1. 
     Refer to documentation for your system to verify and alter cgroups configuration, 
     or choose another operating system for your containers to follow this tutorial.

diff --git a/product_docs/docs/tpa/23/misc-configure-putty.mdx b/product_docs/docs/tpa/23/misc-configure-putty.mdx
@@ -1,5 +1,6 @@
 ---
 navTitle: PuTTY configuration
+description: How to configure PuTTY to connect to a TPA cluster.
 title: TPA - PuTTY Configuration guide
 originalFilePath: misc-configure-putty.md
 

diff --git a/product_docs/docs/tpa/23/misc-troubleshooting.mdx b/product_docs/docs/tpa/23/misc-troubleshooting.mdx
@@ -1,4 +1,5 @@
 ---
+description: How to troubleshoot TPA installations
 title: Troubleshooting
 originalFilePath: misc-troubleshooting.md
 
@@ -70,7 +71,7 @@ An easy way to smoketest an existing cluster is to run:
 This will do a functional test of the cluster components, followed by a performance test of the cluster, using pgbench. As pgbench can take a while to complete, benchmarking can be omitted by running:
 
 ```
-[tpa]$ tpaexec test <clustername> --excluded_tasks pgbench
+[tpa]$ tpaexec test <clustername> --excluded_tasks=pgbench
 ```
 
 ### TPA server test

diff --git a/product_docs/docs/tpa/23/opensourcetpa.mdx b/product_docs/docs/tpa/23/opensourcetpa.mdx
@@ -1,5 +1,6 @@
 ---
 navTitle: Open Source
+description: Open source Trusted Postgres Architect (TPA) documentation.
 title: Open source TPA
 originalFilePath: opensourcetpa.md
 

diff --git a/product_docs/docs/tpa/23/platform-aws.mdx b/product_docs/docs/tpa/23/platform-aws.mdx
@@ -1,5 +1,6 @@
 ---
 navTitle: AWS
+description: Provisioning production clusters on AWS EC2 with TPA.
 title: aws
 originalFilePath: platform-aws.md
 

diff --git a/product_docs/docs/tpa/23/platform-bare.mdx b/product_docs/docs/tpa/23/platform-bare.mdx
@@ -1,5 +1,6 @@
 ---
 navTitle: Bare metal
+description: Provisioning and managing bare(-metal) servers with TPA.
 title: bare(-metal servers)
 originalFilePath: platform-bare.md
 

diff --git a/product_docs/docs/tpa/23/platform-docker.mdx b/product_docs/docs/tpa/23/platform-docker.mdx
@@ -1,4 +1,5 @@
 ---
+description: Provisioning and deploying to Docker containers with TPA.
 title: Docker
 originalFilePath: platform-docker.md
 

diff --git a/product_docs/docs/tpa/23/reference/2q_and_edb_repositories.mdx b/product_docs/docs/tpa/23/reference/2q_and_edb_repositories.mdx
@@ -1,4 +1,5 @@
 ---
+description: How TPA uses 2ndQuadrant and EDB repositories.
 title: How TPA uses 2ndQuadrant and EDB repositories
 originalFilePath: 2q_and_edb_repositories.md
 
@@ -33,6 +34,7 @@ that you have [exported the token](#authenticating-with-package-sources)
 before running `tpaexec deploy` or the operation will fail.
 
 !!! Note
+
     EDB is in the process of publishing all software through Repos 2.0,
     and will eventually remove the older repositories.
 

diff --git a/product_docs/docs/tpa/23/reference/INSTALL-docker.mdx b/product_docs/docs/tpa/23/reference/INSTALL-docker.mdx
@@ -1,4 +1,7 @@
 ---
+description: >-
+  How to run TPA itself from within a Docker container, for systems where TPA is
+  not supported natively.
 title: Running TPA in a Docker container
 originalFilePath: INSTALL-docker.md
 

diff --git a/product_docs/docs/tpa/23/reference/air-gapped.mdx b/product_docs/docs/tpa/23/reference/air-gapped.mdx
@@ -1,4 +1,5 @@
 ---
+description: How to manage clusters in a disconnected or air-gapped environment
 title: Managing clusters in a disconnected or air-gapped environment
 originalFilePath: air-gapped.md
 
@@ -19,6 +20,7 @@ follow the instructions below to either copy an existing cluster
 configuration or create a new cluster.
 
 !!! Note
+
     If the air-gapped server does not already have TPA installed,
     follow the instructions
     [here](../INSTALL/#installing-tpa-without-internet-or-network-access-air-gapped)

diff --git a/product_docs/docs/tpa/23/reference/apt_repositories.mdx b/product_docs/docs/tpa/23/reference/apt_repositories.mdx
@@ -1,4 +1,5 @@
 ---
+description: Configuring APT repositories for Debian and Ubuntu systems.
 title: Configuring APT repositories
 originalFilePath: apt_repositories.md
 

diff --git a/product_docs/docs/tpa/23/reference/artifacts.mdx b/product_docs/docs/tpa/23/reference/artifacts.mdx
@@ -1,4 +1,5 @@
 ---
+description: Uploading files and directories to target instances with TPA.
 title: Uploading artifacts
 originalFilePath: artifacts.md
 

diff --git a/product_docs/docs/tpa/23/reference/barman.mdx b/product_docs/docs/tpa/23/reference/barman.mdx
@@ -1,4 +1,5 @@
 ---
+description: Configuring Barman for backup and recovery with TPA.
 title: Barman
 originalFilePath: barman.md
 

diff --git a/product_docs/docs/tpa/23/reference/bdr.mdx b/product_docs/docs/tpa/23/reference/bdr.mdx
@@ -1,4 +1,5 @@
 ---
+description: How to configure and deploy EDB Postgres Distributed (PGD) with TPA.
 title: EDB Postgres Distributed configuration
 originalFilePath: bdr.md
 

diff --git a/product_docs/docs/tpa/23/reference/beacon-agent.mdx b/product_docs/docs/tpa/23/reference/beacon-agent.mdx
@@ -0,0 +1,48 @@
+---
+description: Integrating TPA deployments with EDB Postgres AI using the agent
+title: Configuring the beacon agent
+originalFilePath: beacon-agent.md
+
+---
+
+TPA installs and configures the beacon agent on nodes which have
+the role `beacon-agent` in `config.yml`. If `--enable-beacon-agent` is
+passed to `tpaexec configure`, then all of the postgres nodes in the
+cluster have this role.
+
+## Beacon agent configuration
+
+The beacon agent configuration contains two parameters which must be set
+per-cluster, the access key and the project id.
+
+The access key is kept encrypted in the cluster directory and can be
+set or read using tpa's `store-password` and `show-password` commands:
+
+```bash
+$ tpaexec store-password . beacon_agent_access_key
+Password:
+```
+
+```bash
+$ tpaexec show-password . beacon_agent_access_key
+```
+
+If the environment variable BEACON_AGENT_ACCESS_KEY is set when `tpaexec
+provision` is run, the access key is set from its value.
+
+The project id is stored in `config.yml` under the
+`beacon_agent_project_id` key in `cluster_vars`. If the
+`--beacon_agent_project_id` argument is passed to `tpaexec configure`
+then its value is written to `config.yml` appropriately.
+
+## Installing the beacon agent
+
+TPA installs the beacon agent from EDB's repositories and creates an
+operating system user called `beacon` and a database user called
+`beacon`. A configuration file for the agent is written to
+`.beacon/beacon_agent.yaml` in the beacon user's home directory.
+
+## Running the beacon agent
+
+TPA installs a systemd service unit file to start the agent at
+boot-time, running as the beacon user.
diff --git a/product_docs/docs/tpa/23/reference/distributions.mdx b/product_docs/docs/tpa/23/reference/distributions.mdx
@@ -1,4 +1,5 @@
 ---
+description: Which Linux distributions are supported by TPA.
 title: Distribution support
 originalFilePath: distributions.md
 
@@ -14,11 +15,15 @@ and is not suitable for production use.
 Fully supported platforms are supported both as host systems for running
 TPA and target systems on which TPA deploys the Postgres cluster.
 
+## Debian ARM64
+
+-   Debian 12/bookworm is fully supported
+
 ## Debian x86
 
 -   Debian 12/bookworm is fully supported
 -   Debian 11/bullseye is fully supported
--   Debian 10/buster is fully supported
+-   Debian 10/buster is a legacy distribution
 -   Debian 9/stretch is a legacy distribution
 -   Debian 8/jessie is a legacy distribution
 
@@ -29,24 +34,24 @@ TPA and target systems on which TPA deploys the Postgres cluster.
 -   Ubuntu 18.04/bionic is a legacy distribution
 -   Ubuntu 16.04/xenial is a legacy distribution
 
-## Oracle Linux
+## Oracle Linux x86
 
 -   Oracle Linux 9.x is fully supported (docker only)
 -   Oracle Linux 8.x is fully supported (docker only)
--   Oracle Linux 7.x is fully supported (docker only)
+-   Oracle Linux 7.x is a legacy distribution (docker only)
 
 ## RedHat x86
 
 -   RHEL/Rocky/AlmaLinux/Oracle Linux 9.x is fully supported (python3 only)
 -   RHEL/CentOS/Rocky/AlmaLinux 8.x is fully supported (python3 only)
--   RHEL/CentOS 7.x is fully supported (python2 only)
+-   RHEL/CentOS 7.x is a legacy distribution (python2 only)
 
 ## RedHat ppc64le
 
 -   RHEL/Rocky/AlmaLinux 9.x is fully supported (python3 only)
 -   RHEL/AlmaLinux 8.x is fully supported (python3 only)
 
-## SLES
+## SLES x86
 
 -   SLES 15.x is fully supported
 

diff --git a/product_docs/docs/tpa/23/reference/edb_repositories.mdx b/product_docs/docs/tpa/23/reference/edb_repositories.mdx
@@ -1,4 +1,5 @@
 ---
+description: How to configure EDB Repos 2.0 package repositories on any system.
 title: Configuring EDB Repos 2.0 repositories
 originalFilePath: edb_repositories.md