Instance configuration
======================

This is an overview of the TPA settings you can use to customize the
deployment process on cluster instances.

There’s also :ref:`an overview of configuring a cluster <Cluster configuration>`  , which explains how to use cluster and
instance variables together to write a concise, easy-to-review
``config.yml`` .

System-level configuration
--------------------------

The first thing TPA does is to ensure that Python is bootstrapped and
ready to execute Ansible modules (a distribution-specific process). Then
it completes various system-level configuration tasks before it
:ref:`configures Postgres <#postgres>`  .

-  :ref:`Distribution support <Distribution support>`  

-  :ref:`Setting up the TPA Python environment <Setting up the TPA Python environment>`  (`preferred_python_version` ) 

-  :ref:`Environment variables <Environment>`  (for example, `https_proxy` ) 

Package repositories
^^^^^^^^^^^^^^^^^^^^

You can use the :ref:`pre-deploy hook <TPA hooks>` 

to execute tasks before any package repositories are configured.

-  :ref:`Configure YUM repositories <Configuring YUM repositories>`  

(for RHEL, Rocky, and AlmaLinux)

-  :ref:`Configure APT repositories <Configuring APT repositories>`  

(for Debian and Ubuntu)

-  :ref:`Configure 2ndQuadrant and EDB repositories <How TPA uses 2ndQuadrant and EDB repositories>`  

(on any system)

-  :ref:`Configure a local package repository <Creating and using a local repository>`  

(to ship packages to target instances)

You can use the :ref:`post-repo hook <TPA hooks>` 

to execute tasks after package repository configuration. For example,
you can use it to correct a problem with the repository configuration
before installing any packages.

Package installation
^^^^^^^^^^^^^^^^^^^^

Once the repositories are configured, packages are installed at various
stages throughout the deployment, beginning with a batch of system
packages:

-  :ref:`Install non-Postgres packages <Installing packages>`  

(for example, acl, openssl, sysstat)

Postgres and other components (for example, Barman, repmgr, pgbouncer)
are installed separately according to the cluster configuration. See
:ref:`Other components <Other components>`  .

Other system-level tasks
^^^^^^^^^^^^^^^^^^^^^^^^

-  :ref:`Create and mount file systems <Filesystem configuration>`  (including RAID, LUKS setup) 

-  :ref:`Upload artifacts <Uploading artifacts>`  (files, directories, tar archives) 

-  :ref:`Set sysctl values <Setting sysctl values>`  

-  :ref:`Configure /etc/hosts <Configuring /etc/hosts>`  

-  :ref:`Manage ssh_known_hosts entries <Managing SSH host keys>`  

-  :ref:`Add system locale <Locale>`  

Skipping deployment completely
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

To prevent TPA from doing any part of the deployment process on an
instance - in other words, if you want TPA to provision the instance and
then leave it alone - set the ``provision_only`` setting for the
instance to ``true`` in ``config.yml`` . This setting will make TPA omit
the instance entirely from the inventory which ``tpaexec deploy`` sees.

Postgres
--------

Postgres configuration is an extended process that’s interleaved with
the configuration of other components like repmgr and pgbouncer. The
first step is to install Postgres.

Version selection
^^^^^^^^^^^^^^^^^

Use the :ref:`configure options <Cluster configuration>`  to select a Postgres flavor and version, or set
``postgres_version`` in ``config.yml`` to specify the Postgres major
version you want to install.

That’s all you need to do to set up a working cluster. Everything else
described here is optional. You can control every aspect of the
deployment if you want to, but the defaults are carefully selected to
give you a sensible cluster as a starting point.

Installation
^^^^^^^^^^^^

The default ``postgres_installation_method`` is to install packages for
the version of Postgres you selected, along with various extensions,
according to the architecture’s needs:

-  :ref:`Install Postgres and Postgres-related packages <Installing Postgres-related packages>`  

(for example, pglogical, BDR, and so on)

-  :ref:`Build and install Postgres and extensions from source <Postgres source installation>`  

(for development and testing)

Whichever installation method you choose, TPA can give you the same
cluster configuration with a minimum of effort.

Configuration
^^^^^^^^^^^^^

-  :ref:`Configure the postgres Unix user <The postgres Unix user>`  

-  :ref:`Run initdb to create the PGDATA directory <Running initdb>`  

-  :ref:`Configure pg_hba.conf <pg_hba.conf>`  

-  :ref:`Configure pg_ident.conf <pg_ident.conf>`  

-  :ref:`Configure postgresql.conf <postgresql.conf>`  

You can use the :ref:`postgres-config hook <TPA hooks>` 

to execute tasks after the Postgres configuration files are installed
(for example, to install additional configuration files).

Once the Postgres configuration is in place, TPA installs and configures
other components, such as Barman, repmgr, pgbouncer, and haproxy,
according to the details of the architecture.

Other components
----------------

-  :ref:`Configure Barman <Barman>`  

-  :ref:`Configure pgbouncer <Configuring pgbouncer>`  

-  :ref:`Configure haproxy <Configuring haproxy>`  

-  :ref:`Configure HARP <Configuring HARP>`  

-  :ref:`Configure EFM <Configuring EFM>`  

Configuring and starting services
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

TPA installs systemd service unit files for each service. The service
for Postgres is named ``postgres.service`` . You can use
``systemctl start postgres`` to start it and ``systemctl stop postgres``
to stop it.

If you’re deploying a cluster for the first time, TPA starts the
Postgres service at this point. On an existing cluster, if there are any
relevant configuration changes, TPA reloads or restarts the Postgres
service as appropriate. If there are no changes and Postgres is already
running, it leaves the service alone. (If Postgres isn’t running on an
existing cluster, TPA starts it.)

In any case, Postgres is running at the end of this step.

After starting Postgres
-----------------------

-  :ref:`Create Postgres users <The postgres Unix user>`  

-  :ref:`Create Postgres tablespaces <Creating Postgres tablespaces>`  

-  :ref:`Create Postgres databases <Creating Postgres databases>`  

-  :ref:`Configure pglogical replication <pglogical configuration>`  

-  :ref:`Configure .pgpass <Configuring .pgpass>`  

You can use the :ref:`postgres-config-final hook <TPA hooks>` 

to execute tasks after the post-startup Postgres configuration is
complete (for example, to perform SQL queries to create objects or load
data).

-  :ref:`Configure BDR <EDB Postgres Distributed configuration>`  

You can use the :ref:`post-deploy hook <TPA hooks>` 

to execute tasks after the deployment process is complete.