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

This page presents an overview of the various controls that TPA offers
to customise the deployment process on cluster instances, with links to
more detailed documentation.

Before you dive into the details of deployment, it may be helpful to
read :ref:`Cluster configuration <Cluster configuration>`  to understand how cluster and instance variables and
the other mechanisms in config.yml work together to allow you to write a
concise, easy-to-review configuration.

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 moving on
to :ref:`Postgres flavour and version <Postgres flavour and version>`  below.

- :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>`  (e.g., `https_proxy` ) 

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

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

to execute tasks before any package repositories are configured.

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

(for RHEL, Rocky and AlmaLinux)

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

(for Debian and Ubuntu)

- :ref:`Configuring EDB Repos 2.0 repositories <Configuring EDB Repos 2.0 repositories>`  

(on any system)

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

(to ship packages to target instances)

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

to execute tasks after package repositories have been configured (e.g.,
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:`Installing packages <Installing packages>`  

(e.g., acl, openssl, sysstat)

Postgres and other components (e.g., Barman, repmgr, pgbouncer) will be
installed separately according to the cluster configuration; these are
documented in their own sections below.

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

- :ref:`Filesystem configuration <Filesystem configuration>`  (including RAID, LUKS setup) 

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

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

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

- :ref:`Managing SSH host keys <Managing SSH host keys>`  

- :ref:`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 goes hand-in-hand
with setting up other components like repmgr and pgbouncer. It begins
with installing Postgres itself.

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

Use the :ref:`Software versions <Software versions>`  to select a Postgres flavour and version, or set
``postgres_version`` in config.yml to specify which Postgres major
version you want to install.

That’s all you really need to do to set up a working cluster. Everything
else on this page is optional. You can control every aspect of the
deployment if you want to, but the defaults are carefully tuned 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:`Installing Postgres-related packages <Installing Postgres-related packages>`  

(e.g., pglogical, BDR, etc.)

- :ref:`Postgres source installation <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:`The postgres Unix user <The postgres Unix user>`  

- :ref:`Running initdb <Running initdb>`  

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

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

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

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

to execute tasks after the Postgres configuration files have been
installed (e.g., to install additional configuration files).

Once the Postgres configuration is in place, TPA will go on to install
and configure other components such as Barman, repmgr, pgbouncer, and
haproxy, according to the details of the architecture.

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

- :ref:`barman-pre-config <barman-pre-config>`  

- :ref:`Repmgr redirect pgbouncer <Repmgr redirect pgbouncer>`  

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

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

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

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

TPA will now install systemd service unit files for each service. The
service for Postgres is named ``postgres.service`` , and can be started
or stopped with ``systemctl start postgres`` .

In the first deployment, the Postgres service will now be started. If
you are running ``tpaexec deploy`` again, the service may be reloaded or
restarted depending on what configuration changes you may have made. Of
course, if the service is already running and there are no changes, then
it’s left alone.

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

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

- :ref:`Creating Postgres users <Creating Postgres users>`  

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

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

- :ref:`pglogical <pglogical>`  

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

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

to execute tasks after the post-startup Postgres configuration has been
completed (e.g., to perform SQL queries to create objects or load data).

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

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

to execute tasks after the deployment process has completed.