community.general.postgresql_membership – Add or remove PostgreSQL roles from groups

From Get docs
Ansible/docs/2.10/collections/community/general/postgresql membership module


community.general.postgresql_membership – Add or remove PostgreSQL roles from groups

Note

This plugin is part of the community.general collection (version 1.3.2).

To install it use: ansible-galaxy collection install community.general.

To use it in a playbook, specify: community.general.postgresql_membership.


Synopsis

  • Adds or removes PostgreSQL roles from groups (other roles).
  • Users are roles with login privilege.
  • Groups are PostgreSQL roles usually without LOGIN privilege.
  • Common use case:
    1. add a new group (groups) by community.general.postgresql_user module with role_attr_flags=NOLOGIN
    1. grant them desired privileges by community.general.postgresql_privs module
    1. add desired PostgreSQL users to the new group (groups) by this module

Requirements

The below requirements are needed on the host that executes this module.

  • psycopg2

Parameters

Parameter Choices/Defaults Comments

ca_cert

string

Specifies the name of a file containing SSL certificate authority (CA) certificate(s).

If the file exists, the server's certificate will be verified to be signed by one of these authorities.


aliases: ssl_rootcert

db

string

Name of database to connect to.


aliases: login_db

fail_on_role

boolean

  • no
  • yes

If yes, fail when group or target_role doesn't exist. If no, just warn and continue.

groups

list / elements=string / required

The list of groups (roles) that need to be granted to or revoked from target_roles.


aliases: group, source_role, source_roles

login_host

string

Host running the database.

login_password

string

The password used to authenticate with.

login_unix_socket

string

Path to a Unix domain socket for local connections.

login_user

string

Default:

"postgres"

The username used to authenticate with.

port

integer

Default:

5432

Database port to connect to.


aliases: login_port

session_role

string

Switch to session_role after connecting. The specified session_role must be a role that the current login_user is a member of.

Permissions checking for SQL commands is carried out as though the session_role were the one that had logged in originally.

ssl_mode

string

  • allow
  • disable
  • prefer

  • require
  • verify-ca
  • verify-full

Determines whether or with what priority a secure SSL TCP/IP connection will be negotiated with the server.

See https://www.postgresql.org/docs/current/static/libpq-ssl.html for more information on the modes.

Default of prefer matches libpq default.

state

string

  • absent
  • present

Membership state.

state=present implies the groupsmust be granted to target_roles.

state=absent implies the groups must be revoked from target_roles.

target_roles

list / elements=string / required

The list of target roles (groups will be granted to them).


aliases: target_role, users, user

trust_input

boolean

added in 0.2.0 of community.general

  • no
  • yes

If no, check whether values of parameters groups, target_roles, session_role are potentially dangerous.

It makes sense to use no only when SQL injections via the parameters are possible.



Notes

Note

  • The default authentication assumes that you are either logging in as or sudo’ing to the postgres account on the host.
  • To avoid “Peer authentication failed for user postgres” error, use postgres user as a become_user.
  • This module uses psycopg2, a Python PostgreSQL database adapter. You must ensure that psycopg2 is installed on the host before using this module.
  • If the remote host is the PostgreSQL server (which is the default case), then PostgreSQL must also be installed on the remote host.
  • For Ubuntu-based systems, install the postgresql, libpq-dev, and python-psycopg2 packages on the remote host before using this module.
  • The ca_cert parameter requires at least Postgres version 8.4 and psycopg2 version 2.4.3.


See Also

See also

community.general.postgresql_user
The official documentation on the community.general.postgresql_user module.
community.general.postgresql_privs
The official documentation on the community.general.postgresql_privs module.
community.general.postgresql_owner
The official documentation on the community.general.postgresql_owner module.
PostgreSQL role membership reference
Complete reference of the PostgreSQL role membership documentation.
PostgreSQL role attributes reference
Complete reference of the PostgreSQL role attributes documentation.


Examples

- name: Grant role read_only to alice and bob
  community.general.postgresql_membership:
    group: read_only
    target_roles:
    - alice
    - bob
    state: present

# you can also use target_roles: alice,bob,etc to pass the role list

- name: Revoke role read_only and exec_func from bob. Ignore if roles don't exist
  community.general.postgresql_membership:
    groups:
    - read_only
    - exec_func
    target_role: bob
    fail_on_role: no
    state: absent

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key Returned Description

granted

dictionary

if state=present

Dict of granted groups and roles.


Sample:

{'ro_group': ['alice', 'bob']}

queries

string

always

List of executed queries.


Sample:

['GRANT "user_ro" TO "alice"']

revoked

dictionary

if state=absent

Dict of revoked groups and roles.


Sample:

{'ro_group': ['alice', 'bob']}

state

string

always

Membership state that tried to be set.


Sample:

present




Authors

  • Andrew Klychkov (@Andersson007)

© 2012–2018 Michael DeHaan
© 2018–2019 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.10/collections/community/general/postgresql_membership_module.html