Using TPAexec v4
With TPAexec you configure, provision, and deploy your EDB Postgres Distributed clusters.
Configure
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> [options]
The required configuration options include:
| Flags | Description |
|---|---|
--architecture | Required. Set to BDR-Always-ON for EDB Postgres Distributed deployments. |
--layout | Required. Specify one of the four supported architectures: bronze, silver, gold, and platinum. See Choosing your architecture for more information. |
--harp-consensus-protocol | Required. Use bdr if your layout is bronze or silver. Use etcd if your layout is gold or platinum. |
For example:
[tpa]$ tpaexec configure ~/clusters/speedy \
--architecture BDR-Always-ON \
--layout gold \
--harp-consensus-protocol etcd \ The first argument must be the cluster directory, for example, speedy or ~/clusters/speedy (the cluster is named speedy in both cases). We recommend that you keep all your clusters in a common directory, for example, ~/clusters. The next argument must be --architecture to select an architecture, followed by --layout.
The command creates a directory named ~/clusters/speedy and generates a configuration file named config.yml that follows the layout of the BDR-Always-ON architecture and gold layout. You can use the tpcaexec info command to see what values are supported for the configuration options based on what you specified when running the configure command.
Common configuration options
Other configuration options include:
Owner
Every cluster must be directly traceable to a person responsible for the provisioned resources.
By default, a cluster is tagged as being owned by the login name of the user running tpaexec provision. If this name does not identify a person (for example, postgres, ec2-user), you must specify --owner SomeId to set an identifiable owner.
You may use your initials, or "Firstname Lastname", or anything else that identifies you uniquely.
Platform options
The default value for --platform is aws. It is the platform supported by the BDR-Always-ON architecture.
Specify --region to specify any existing AWS region that you have access to (and that permits the required number of instances to be created). The default region is eu-west-1.
Specify --instance-type with any valid instance type for AWS. The default is t3.micro.
Subnet selection
By default, each cluster is assigned a random /28 subnet under 10.33/16, but depending on the architecture, there may be one or more subnets, and each subnet may be anywhere between a /24 and a /29.
Specify --subnet to use a particular subnet. For example, --subnet 192.0.2.128/27.
Alternatively, specify --subnet-pattern to generate random subnets (as many as required by the architecture) matching the given pattern. For example, --subnet-pattern 192.0.x.x.
Disk space
Specify --root-volume-size to set the size of the root volume in GB. For example, --root-volume-size 64. The default is 16GB. (Depending on the image used to create instances, there may be a minimum size for the root volume.)
For architectures that support separate postgres and barman volumes:
Specify --postgres-volume-size to set the size of the Postgres volume in GB. The default is 16GB.
Specify --barman-volume-size to set the size of the Barman volume in GB. The default is 32GB.
Distribution
Specify --os or --distribution to specify the OS to be used on the cluster's instances. The value is case-sensitive.
The selected platform determines which distributions are available and which one is used by default. For more details, see tpaexec info platforms/<platformname>.
In general, you can use "Debian", "RedHat", and "Ubuntu" to select TPA images that have Postgres and other software preinstalled (to reduce deployment times). To use stock distribution images instead, append "-minimal" to the value, for example, --distribution Debian-minimal.
2ndQuadrant repositories
By default, TPAexec installs the 2ndQuadrant public repository and adds on any product repositories that the architecture requires.
Specify --2Q-repositories source/name/release … to specify the complete list of 2ndQuadrant repositories to install on each instance in addition to the 2ndQuadrant public repository.
If you do this, you must first export TPA_2Q_SUBSCRIPTION_TOKEN=xxx before you run tpaexec. You can get a subscription token from the EnterpriseDB customer portal (Support > Software subscriptions > Add).
Software versions
By default TPAexec uses the latest major version of Postgres. Specify --postgres-version to install an earlier supported major version.
By default, TPAexec always installs the latest version of every package. This is usually the desired behavior, but in some testing scenarios, it may be necessary to select specific package versions. For example,
--postgres-package-version 10.4-2.pgdg90+1 --repmgr-package-version 4.0.5-1.pgdg90+1 --barman-package-version 2.4-1.pgdg90+1 --pglogical-package-version '2.2.0*' --bdr-package-version '3.0.2*' --pgbouncer-package-version '1.8*'
Specify --extra-packages or --extra-postgres-packages to install additional packages. The former lists packages to install along with system packages, while the latter lists packages to install later along with postgres packages. (If you mention packages that depend on Postgres in the former list, the installation fails because Postgres is not yet installed.) The arguments are passed on to the package manager for installation without any modifications.
The --extra-optional-packages option behaves like --extra-packages, but it is not an error if the named packages cannot be installed.
Hostnames
By default, tpaexec configure randomly selects as many hostnames as it needs from a pre-approved list of several dozen names. This should be enough for most clusters.
Specify --hostnames-from to select names from a different list (for example, if you need more names than are available in the canned list). The file must contain one hostname per line.
Specify --hostnames-pattern to restrict hostnames to those matching the egrep-syntax pattern. If you choose to do this, you must ensure that the pattern matches only valid hostnames ([a-zA-Z0-9-]) and finds a sufficient number thereof.
Locations
By default, tpaexec configure uses the names first, second, and so on for any locations used by the selected architecture.
Specify --location-names to provide more meaningful names for each location.
Enable Commit At Most Once
Specify --enable-camo to set the pair of BDR primary instances in each region to be each other's Commit At Most Once (CAMO) partners. See Commit At Most Once (CAMO) for more information.
Provision
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).
Deploy
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, EDB Postgres Distributed is up and running.
Test
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.
For more information, see TPAexec.