Skip to content

Commit

Permalink
Merge pull request #5175 from EnterpriseDB/release/2024-01-23
Browse files Browse the repository at this point in the history 
Release/2024 01 23
  • Loading branch information
@djw-m
djw-m authored Jan 23, 2024
2 parents 820b037 + 420c60b commit ffce0fc
Show file tree
Hide file tree
Showing 20 changed files with 534 additions and 468 deletions.
140 changes: 72 additions & 68 deletions product_docs/docs/tpa/23/ansible-and-sudo.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,26 +5,27 @@ originalFilePath: ansible-and-sudo.md
---

TPA uses Ansible with sudo to execute tasks with elevated privileges
on target instances. This page explains how Ansible uses sudo (which is
in no way TPA-specific), and the consequences to systems managed
on target instances.
It's important to understand how Ansible uses sudo (which isn't specific to TPA)
and the consequences to systems managed
with TPA.

TPA needs root privileges;

- to install packages (required packages using the operating system's
native package manager, and optional packages using pip)
- to stop, reload and restart services (i.e Postgres, repmgr, efm, etcd,
haproxy, pgbouncer etc.)
- to perform a variety of other tasks (e.g., gathering cluster facts,
performing switchover, setting up cluster nodes)
- To install packages (required packages using the operating system's
native package manager and optional packages using pip)
- To stop, reload, and restart services (that is, Postgres, repmgr, efm, etcd,
haproxy, pgbouncer, and so on)
- To perform a variety of other tasks (such as gathering cluster facts,
performing switchover, and setting up cluster nodes)

TPA also needs to be able to use sudo. You can make it ssh in as root
directly by setting `ansible_user: root`, but it will still use sudo to
execute tasks as other users (e.g., postgres).
TPA also must be able to use sudo. You can make it ssh in as root
directly by setting `ansible_user: root`, but it still uses sudo to
execute tasks as other users (for example, postgres).

## Ansible sudo invocations

When Ansible runs a task using sudo, you will see a process on the
When Ansible runs a task using sudo, you see a process on the
target instance that looks something like this:

```
Expand All @@ -33,113 +34,116 @@ target instance that looks something like this:
/usr/bin/python2'"'"' && sleep 0'
```

People who were expecting something like `sudo yum install -y xyzpkg`
are often surprised by this. By and large, most tasks in Ansible will
invoke a Python interpreter to execute Python code, rather than
executing recognisable shell commands. (Playbooks may execute `raw`
Users who were expecting something like `sudo yum install -y xyzpkg`
are often surprised by this. By and large, most tasks in Ansible
invoke a Python interpreter to execute Python code rather than
executing recognizable shell commands. (Playbooks can execute `raw`
shell commands, but TPA uses such tasks only to bootstrap a Python
interpreter.)

Ansible modules contain Python code of varying complexity, and an
Ansible playbook is not just a shell script written in YAML format.
There is no way to “extract” shell commands that would do the same thing
Ansible playbook isn't just a shell script written in YAML format.
There's no way to “extract” shell commands that do the same thing
as executing an arbitrary Ansible playbook.

There is one significant consequence of how Ansible uses sudo: [privilege
escalation must be general](https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_privilege_escalation.html#privilege-escalation-must-be-general). That, it is not possible
to limit sudo invocations to specific commands in sudoers.conf,
as some administrators are used to doing. Most tasks will just invoke python.
You could have restricted sudo access to python if it were not
for the random string in every command—but once Python is running as root,
One significant consequence of how Ansible uses sudo is that [privilege
escalation must be general](https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_privilege_escalation.html#privilege-escalation-must-be-general). It isn't possible
to limit sudo invocations to specific commands in `sudoers.conf`,
as some administrators are used to doing. Most tasks just invoke Python.
You could have restricted sudo access to Python if it weren't
for the random string in every command. However, once Python is running as root,
there's no effective limit on what it can do anyway.

Executing Python modules on target hosts is just the way Ansible works.
None of this is specific to TPA in any way, and these considerations
would apply equally to any other Ansible playbook.
Executing Python modules on target hosts is how Ansible works.
None of this is specific to TPA, and these considerations
apply equally to any other Ansible playbook.

## Recommendations

- Use SSH public key-based authentication to access target instances.
- Use SSH public-key-based authentication to access target instances.

- Allow the SSH user to execute sudo commands without a password.

- Restrict access by time, rather than by command.
- Restrict access by time rather than by command.

TPA needs access only when you are first setting up your cluster or
running `tpaexec deploy` again to make configuration changes, e.g.,
TPA needs access only when you're first setting up your cluster or
running `tpaexec deploy` again to make configuration changes, for example,
during a maintenance window. Until then, you can disable its access
entirely (a one-line change for both ssh and sudo).
entirely, which is a one-line change for both ssh and sudo.

During deployment, everything Ansible does is generally predictable
based on what the playbooks are doing and what parameters you provide,
and each action is visible in the system logs on the target instances,
as well as the Ansible log on the machine where tpaexec itself runs.
based on what the playbooks are doing and the parameters you provide.
Each action is visible in the system logs on the target instances
as well as in the Ansible log on the machine where tpaexec runs.

Ansible's focus is less to impose fine-grained restrictions on what
actions may be executed and more to provide visibility into what it does
as it executes, so elevated privileges are better assigned and managed
Ansible's focus is less to impose fine-grained restrictions on the
actions you can execute and more to provide visibility into what it does
as it executes. Thus elevated privileges are better assigned and managed
by time rather than by scope.

## SSH and sudo passwords

We *strongly* recommend setting up password-less SSH key authentication
and password-less sudo access, but it is possible to use passwords too.
We strongly recommend setting up passwordless SSH key authentication
and passwordless sudo access. However, it's possible to use passwords too.

If you set `ANSIBLE_ASK_PASS=yes` and `ANSIBLE_BECOME_ASK_PASS=yes`
in your environment before running tpaexec, Ansible will prompt you to
in your environment before running tpaexec, Ansible prompts you to
enter a login password and a sudo password for the remote servers. It
will then negotiate the login/sudo password prompt on the remote server
and send the password you specify (which will make your playbooks take
noticeably longer to run).
then negotiates the login/sudo password prompt on the remote server
and sends the password you specify, which makes your playbooks take
noticeably longer to run.

We do not recommend this mode of operation because we feel it is a more
We don't recommend this mode of operation because it's a more
effective security control to completely disable access through a
particular account when not needed than to use a combination of
passwords to restrict access. Using public key authentication for ssh
provides an effective control over who can access the server, and it's
easier to protect a single private key per authorised user than it is to
easier to protect a single private key per authorized user than it is to
protect a shared password or multiple shared passwords. Also, if you
limit access at the ssh/sudo level to when it is required, the passwords
do not add any extra security during your maintenance window.
limit access at the ssh/sudo level to when it's required, the passwords
don't add any extra security during your maintenance window.

## sudo options

To use Ansible with sudo, you must not set `requiretty` in sudoers.conf.
To use Ansible with sudo, don't set `requiretty` in `sudoers.conf`.

If needed, you can change the sudo options that Ansible uses
(`-H -S -n`) by setting `become_flags` in the
`[privilege_escalation]` section of ansible.cfg, or
`ANSIBLE_BECOME_FLAGS` in the environment, or `ansible_become_flags`
in the inventory. All three methods are equivalent, but please change
the sudo options only if there is a specific need to do so. The defaults
(`-H -S -n`) by setting either:

- `become_flags` in the `[privilege_escalation]` section of `ansible.cfg`
- `ANSIBLE_BECOME_FLAGS` in the environment
- `ansible_become_flags` in the inventory

All three methods are equivalent, but change
the sudo options only if there's a specific need to do so. The defaults
were chosen for good reasons. For example, removing `-S -n` will cause
tasks to timeout if password-less sudo is incorrectly configured.
tasks to time out if passwordless sudo is incorrectly configured.

## Logging

For playbook executions, the sudo logs will show mostly invocations of
Python (just as it will show only an invocation of bash when someone
uses `sudo -i`).
For playbook executions, the sudo logs show mostly invocations of
Python, just as it shows only an invocation of bash when
`sudo -i` is used.

For more detail, the syslog will show the exact arguments to each module
For more detail, the syslog shows the exact arguments to each module
invocation on the target instance. For a higher-level view of why that
module was invoked, the ansible.log on the controller shows what that
module was invoked, the `ansible.log` on the controller shows what that
task was trying to do, and the result.

If you want even more detail, or an independent source of audit data,
If you want even more detail or an independent source of audit data,
you can run auditd on the server and use the SELinux log files. You can
get still more fine-grained syscall-level information from bpftrace/bcc
(e.g., opensnoop shows every file opened on the system, and execsnoop
shows every process executed on the system). You can do any or all of
get still more fine-grained syscall-level information from bpftrace/bcc.
(For example, opensnoop shows every file opened on the system, and execsnoop
shows every process executed on the system.) You can do any or all of
these things, depending on your needs, with the obvious caveat of
increasing overhead with increased logging.

## Local privileges

The
[installation instructions for TPA](INSTALL/)
mention sudo only as shorthand for “run these commands as root somehow”.
Once TPA is installed and you have run `tpaexec setup`, TPA
itself does not require elevated privileges on the local machine. (But
mention sudo only as shorthand for “run these commands as root somehow.”
Once TPA is installed and you've run `tpaexec setup`, TPA
doesn't require elevated privileges on the local machine. (But
if you use Docker, you must run tpaexec as a user that belongs to a
group that is permitted to connect to the Docker daemon.)
Unix group that has permission to connect to the Docker daemon.)
77 changes: 36 additions & 41 deletions product_docs/docs/tpa/23/architecture-BDR-Always-ON.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,28 +5,28 @@ originalFilePath: architecture-BDR-Always-ON.md
---

EDB Postgres Distributed 3.7 or 4 in an Always-ON
configuration, suitable for use in test and production.
configuration is suitable for use in test and production.

This architecture requires a subscription to the legacy 2ndQuadrant
repositories, and some options require a subscription to EDB Repos 1.0.
See [How TPA uses 2ndQuadrant and EDB repositories](reference/2q_and_edb_repositories/)
for more detail on this topic.
for more detail.

The BDR-Always-ON architecture has four variants, which can be
selected with the `--layout` configure option:

1. bronze: 2×bdr+primary, bdr+witness, barman, 2×harp-proxy
- `bronze`: 2×bdr+primary, bdr+witness, barman, 2×harp-proxy

2. silver: bronze, with bdr+witness promoted to bdr+primary, and barman
- `silver`: bronze, with bdr+witness promoted to bdr+primary, and barman
moved to separate location

3. gold: two symmetric locations with 2×bdr+primary, 2×harp-proxy,
- `gold`: two symmetric locations with 2×bdr+primary, 2×harp-proxy,
and barman each; plus a bdr+witness in a third location

4. platinum: gold, but with one bdr+readonly (logical standby) added to
- `platinum`: gold, but with one bdr+readonly (logical standby) added to
each of the main locations

You can check EDB's Postgres Distributed Always On Architectures
See EDB's Postgres Distributed Always On Architectures
[whitepaper](https://www.enterprisedb.com/promote/bdr-always-on-architectures)
for the detailed layout diagrams.

Expand All @@ -36,8 +36,7 @@ This architecture is meant for use with PGD versions 3.7 and 4.

### Overview of configuration options

An example invocation of `tpaexec configure` for this architecture
is shown below.
This example shows an invocation of `tpaexec configure` for this architecture:

```shell
tpaexec configure ~/clusters/bdr \
Expand All @@ -49,59 +48,55 @@ tpaexec configure ~/clusters/bdr \
--harp-consensus-protocol bdr
```

You can list all available options using the help command.
You can list all available options using the `help` command.

```shell
tpaexec configure --architecture BDR-Always-ON --help
```

The tables below describe the mandatory options for BDR-Always-ON
and additional important options.
More detail on the options is provided in the following section.
#### Mandatory options

#### Mandatory Options

| Option | Description |
| ----------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `--architecture` (`-a`) | Must be set to `BDR-Always-ON`. |
| Postgres flavour and version (e.g. `--postgresql 14`) | A valid [flavour and version specifier](tpaexec-configure/#postgres-flavour-and-version). |
| `--layout` | One of `bronze`, `silver`, `gold`, `platinum`. |
| `--harp-consensus-protocol` | One of `bdr`, `etcd`. |
| Option | Description |
| ------------------------------- | ------------------------------------------------------------------------------------------- |
| `--architecture` (`-a`) | Must be set to `BDR-Always-ON`. |
| `--postgresql 14` (for example) | Any valid [flavour and version specifier](tpaexec-configure/#postgres-flavour-and-version). |
| `--layout` | One of `bronze`, `silver`, `gold`, `platinum`. |
| `--harp-consensus-protocol` | One of `bdr`, `etcd`. |

<br/><br/>

#### Additional Options
#### Additional options

| Option | Description | Behaviour if omitted |
| ---------------------- | ----------------------------------------------------------------------------------------------- | ------------------------- |
| `--platform` | One of `aws`, `docker`, `bare`. | Defaults to `aws`. |
| `--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-harp-probes` | Enable http(s) api endpoints for harp such as `health/is-ready` to allow probing harp's health. | Disabled by default. |
| Option | Description | Behavior if omitted |
| ---------------------- | ----------------------------------------------------------------------------------------------- | -------------------- |
| `--platform` | One of `aws`, `docker`, `bare`. | Defaults to `aws`. |
| `--enable-camo` | Sets two data nodes in each location as CAMO partners. | CAMO isn't enabled. |
| `--bdr-database` | The name of the database to be used for replication. | Defaults to `bdrdb`. |
| `--enable-harp-probes` | Enable http(s) api endpoints for harp such as `health/is-ready` to allow probing harp's health. | Disabled by default. |

<br/><br/>

### More detail about BDR-Always-ON configuration

You must specify `--layout layoutname` to set one of the supported BDR
use-case variations. The permitted arguments are bronze, silver, gold, and
platinum. The bronze, gold and platinum layouts have a PGD witness node
to ensure odd number of nodes for Raft consensus majority. Witness nodes do
not participate in the data replication.
Specify `--layout layoutname` to choose a layout:
`bronze`, `silver`, `gold`, or
`platinum`. The bronze, gold, and platinum layouts have a PGD witness node
to ensure an odd number of nodes for Raft consensus majority. Witness nodes don't
participate in the data replication.

You must specify `--harp-consensus-protocol protocolname`. The supported
protocols are bdr and etcd; see [`Configuring HARP`](reference/harp/) for more details.
protocols are bdr and etcd. See [`Configuring HARP`](reference/harp/) for more details.

You may optionally specify `--bdr-database dbname` to set the name of
the database with PGD enabled (default: bdrdb).
You can optionally specify `--bdr-database dbname` to set the name of
the database with PGD enabled (default: `bdrdb`).

You may optionally specify `--enable-camo` to set the pair of PGD
You can optionally specify `--enable-camo` to set the pair of PGD
primary instances in each region to be each other's CAMO partners.

You may optionally specify `--enable-harp-probes [{http, https}]` to
enable http(s) api endpoints that will allow to easily probe harp's health.
You can optionally specify `--enable-harp-probes [{http, https}]` to
enable http(s) api endpoints that allow you to easily probe harp's health.

Please note we enable HARP2 by default in BDR-Always-ON architecture.
HARP2 is enabled by default in the BDR-Always-ON architecture.

You may also specify any of the options described by
You can also specify any of the options described by
[`tpaexec help configure-options`](tpaexec-configure/).
Loading

2 comments on commit ffce0fc

@github-actions
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎉 Published on https://edb-docs.netlify.app as production
🚀 Deployed on https://65afebe6f4f1250825df1538--edb-docs.netlify.app

@github-actions
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎉 Published on https://edb-docs-staging.netlify.app as production
🚀 Deployed on https://65afec66029462090ab131a6--edb-docs-staging.netlify.app

Please sign in to comment.