Skip to content

Commit

Permalink
Merge pull request #2719 from EnterpriseDB/release/2022-05-25
Browse files Browse the repository at this point in the history 
Release: 2022-05-25
  • Loading branch information
@drothery-edb
drothery-edb authored May 25, 2022
2 parents d6aed73 + f619ced commit a6282ff
Show file tree
Hide file tree
Showing 8 changed files with 249 additions and 78 deletions.
76 changes: 10 additions & 66 deletions product_docs/docs/pgd/4/deployments/tpaexec/index.mdx
View file
Original file line number Diff line number Diff line change
@@ -1,78 +1,19 @@
---
title: TPAexec
navigation:
- overview
- configuration_syntax
- installing_tpaexec
- using_tpaexec
- quick_start

---

The standard way of deploying EDB Distributed Postgres in a self managed setting,
including physical and virtual machines, both self-hosted and in the cloud
(EC2) is to use EDB's deployment tool called TPAexec.
(EC2), is to use EDB's deployment tool called TPAexec.

TPAexec is an orchestration tool that uses Ansible to build Postgres clusters as specified by TPA (Trusted Postgres Architecture), a set of reference architectures that document how to set up and operate Postgres in various scenarios. TPA represents the best practices followed by EDB, and its recommendations are as applicable to quick testbed setups as to production environments.
TPAexec is an orchestration tool that uses Ansible to build Postgres clusters as specified by Trusted Postgres Architecture (TPA), a set of reference architectures that documents how to set up and operate Postgres in various scenarios. TPA represents the best practices followed by EDB and its recommendations are as applicable to quick testbed setups as to production environments.

TPAexec packages are only available to EDB customers with an active BDR subscription. Please contact your account manager to request access.

## Capabilities and supported software

### Configuration
The `tpaexec configure` command generates a simple YAML configuration file to describe a cluster, based on the options you select. The configuration is ready for immediate use, and you can modify it to better suit your needs. Editing the configuration file is the usual way to make any configuration changes to your cluster, both before and after it's created.

The syntax is:

```
tpaexec configure <cluster_dir> --architecture <architecture_name> --layout <layout> --bdr-version <bdr_version> --<postgresql_flavour> --2Q-repositories <repositories_to_be_used> --extra-packages edb-livecompare edb-lasso --platform <platform>
```

The primary configuration options include:

| Flags | Description |
| ---------------------------- | ----------- |
| --architecture BDR-Always-ON | Required. Set to 'BDR-Always-ON' for EDB Postgres Distributed deployments |
| --layout layoutname | Required. Specify one of the four supported architectures: bronze, silver, gold, and platinum. See [Choosing your architecture](/pgd/4/architectures) for more information. |
| --harp-consensus-protocol | Required. `bdr` is recommended if your layout is bronze or silver. `etcd` is recommended if your layout is gold or platinum. |
| --bdr-node-group groupname | Optional. Set the name of the BDR node group. The default is `bdrgroup`. |
| --bdr-database dbname | Optional. Set the name of the database with BDR enabled. The default is `bdrdb`. |
| --enable-camo | Optional. Set the pair of BDR primary instances in each region to be each other's CAMO partners. |

For example:

```
[tpa]$ tpaexec configure ~/clusters/bdr \
--architecture BDR-Always-ON \
--layout gold \
--harp-consensus-protocol etcd \
--platform aws --region eu-west-1 --instance-type t3.micro \
--distribution Debian-minimal
```

You may also specify any of the options described in the online help for configure-options:
```
tpaexec help configure-options
```

### Provisioning
The `tpaexec provision` command creates instances and other resources required by the cluster. The details of the process depend on the architecture (for example, BDR-Always-ON) and platform (for example, AWS) that you selected while configuring the cluster.

For example, given AWS access with the necessary privileges, TPAexec provisions EC2 instances, VPCs, subnets, routing tables, internet gateways, security groups, EBS volumes, elastic IPs, and so on.

You can also "provision" existing servers by selecting the "bare" platform and providing connection details. Whether these are bare metal servers or those provisioned separately on a cloud platform, they can be used just as if they had been created by TPAexec.

You are not restricted to a single platform—you can spread your cluster out across some AWS instances (in multiple regions) and some on-premise servers, or servers in other data centres, as needed.

At the end of the provisioning stage, you will have the required number of instances with the basic operating system installed, which TPAexec can access via SSH (with sudo to root).

### Deployment
The `tpaexec deploy` command installs and configures Postgres and other software on the provisioned servers (which may or may not have been created by TPAexec; but it doesn't matter who created them so long as SSH and sudo access is available). This includes setting up replication, backups, and so on.

At the end of the deployment stage, Postgres is up and running.

### Testing
The `tpaexec test` command executes various architecture and platform-specific tests against the deployed cluster to ensure that it is working as expected.

At the end of the testing stage, you will have a fully-functioning cluster.

## Incremental changes
TPAexec is carefully designed so that provisioning, deployment, and testing are idempotent. You can run through them, make a change to config.yml, and run through the process again to deploy the change. If nothing has changed in the configuration or on the instances, then rerunning the entire process does not change anything either.
Expand All @@ -89,8 +30,11 @@ Once your cluster is up and running, TPAexec provides convenient cluster managem
TPAexec can create complex clusters with many features configured, but the result is just Postgres. The installation follows some conventions designed to make life simpler, but there is no hidden magic or anything standing in the way between you and the database. You can do everything on a TPA cluster that you could do on any other Postgres installation.

## Getting started
See these topics to get complete your installation and then configure your first cluster:
- [TPAexec installation](https://documentation.enterprisedb.com/tpa/release/22.13-1/INSTALL/) for more detailed instructions
- [Quick start](quick_start)
See these topics to install TPAexec and use it to deploy your first EDB Postgres Distributed cluster:
- [Installing TPAexec](installing_tpaexec)
- [Using TPAexec](using_tpaexec)
- [Example: Deploying EDB Postgres Distributed](quick_start)

For more information, see [TPAexec](https://documentation.enterprisedb.com/tpa/release/latest/).


63 changes: 63 additions & 0 deletions product_docs/docs/pgd/4/deployments/tpaexec/installing_tpaexec.mdx
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,63 @@
---
title: "Installing TPAexec"
---

The TPAexec install package in available from the EDB customer portal. You must have a subscription to access the repository and the TPAexec install package.

## Prerequisites

### Access

Setting up the repository requires root user permissions. If you do not have direct root access, log in as superuser.

```shell
# To log in as a superuser:
sudo su -
```

If you are behind an HTTPS proxy, see [How to install RPM/APT repositories through a HTTPS proxy](https://techsupport.enterprisedb.com/kb/a/how-to-install-rpm-apt-repositories-through-a-https-proxy/).


### Token

You need your token to complete the install process. It is available from the [EnterpriseDB customer portal](https://techsupport.enterprisedb.com/customer_portal/). From the left navigation pane, select **Company info > Company**. The account information for your company displays. Copy your token.



## Installing TPAexec

The examples in this section assume you are using TPAexec v22.14 and installing Postgres 14.

1. Install the EnterpriseDB repository for TPAexec. Replace `token` with your company token. Replace `pgVersion` with the version of Postgres you are installing.

Syntax:
```
curl https://techsupport.enterprisedb.com/api/repository/<token>/products/tpa/release/<pgVersion>/rpm | bash
```

Example:
```
curl https://techsupport.enterprisedb.com/api/repository/xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx/products/tpa/release/14/rpm | bash
```

2. Install TPAexec:

- On RedHat

```
yum install tpaexec
```
- On Debian/Ubuntu
```
apt-get install tpaexec
```

3. Install additional dependencies:
```
/opt/EDB/TPA/bin/tpaexec setup
```
4. Verify the installation:
```
/opt/EDB/TPA/bin/tpaexec selftest
```

24 changes: 18 additions & 6 deletions product_docs/docs/pgd/4/deployments/tpaexec/quick_start.mdx
View file
Original file line number Diff line number Diff line change
@@ -1,24 +1,34 @@
---
title: "Quick start with TPAexec"
navTitle: "Quick start"
title: "Example: Deploying EDB Postgres Distributed"
navTitle: "Example: Deploying EDB Postgres Distributed"
---


The following steps setup EDB Postgres Distributed with the Always On Silver
architecture using Amazon EC2.

1. Generate a configuration file:

```
$ tpaexec configure myedbdpcluster --architecture BDR-Always-ON --layout Silver --platform aws
$ tpaexec configure myedbdpcluster --architecture BDR-Always-ON --layout Silver --platform aws --bdr-version 4 --2q --2Q-repositories products/2ndqpostgres/release
```

This creates a subdirectory directory in current working directory called `myedbdpcluster` containing the `config.yml` configuration file TPAexec uses to create the cluster. Edit the `config.yml` as needed, for example to change the IP address range used for servers or adjust locations of nodes.

1. Provision the cluster. :
We included options to specify using BDR 4 (the default version) and the 2ndQuadrant repositories to install EDB Postgres Extended Server. By default, TPAexec installs the 2ndQuadrant public repository and adds on any product repositories that the architecture requires. In this example, we specified `--2Q-repositories` so the complete list of 2ndQuadrant repositories is installed on each instance in addition to the 2ndQuadrant public repository. Since we did this, before the provisioning step, you must first export TPA_2Q_SUBSCRIPTION_TOKEN=xxx. You can get a subscription token from the [EnterpriseDB customer portal](https://techsupport.enterprisedb.com/customer_portal/) (**Support > Software subscriptions > Add**).

```
cd ~/clusters/myedbdpcluster
export TPA_2Q_SUBSCRIPTION_TOKEN=<token>
```

1. Provision the cluster:

```
tpaexec provision myedbdpcluster
```
Since we specified AWS as the platform, TCAexec provisions EC2 instances, VPCs, subnets, routing tables, internet gateways, security groups, EBS volumes, elastic IPs, and so on.
Since we specified AWS as the platform (the default platform), TCAexec provisions EC2 instances, VPCs, subnets, routing tables, internet gateways, security groups, EBS volumes, elastic IPs, and so on.

1. Deploy the needed packages, configuration and setup the actual EDB Postgres Distributed cluster:
```
Expand All @@ -30,4 +40,6 @@ After the successful run of the `deploy` command the cluster is ready to use. Yo
It's also possible to run a test that ensures the cluster is running as expected:
```
tpaexec test myedbdpcluster
```
```


Loading

0 comments on commit a6282ff

Please sign in to comment.