Модуль community.postgresql.postgresql_user – создание, изменение или удаление пользователя (роли) в экземпляре сервера PostgreSQL

Примечание

Этот модуль входит в коллекцию community.postgresql (версия 4.2.0).

Возможно, эта коллекция уже установлена, если вы используете пакет ansible. Она не входит в ansible-core. Чтобы проверить, установлена ли она, выполните ansible-galaxy collection list.

Чтобы установить её, используйте: ansible-galaxy collection install community.postgresql. Для использования этого модуля необходимы дополнительные требования. Подробности см. в разделе Требования.

Чтобы использовать модуль в плейбуке, укажите: community.postgresql.postgresql_user.

Краткое описание
Требования
Параметры
Атрибуты
Примечания
См. также
Примеры
Возвращаемые значения

Краткое описание

Создаёт, изменяет или удаляет пользователя (роль) в экземпляре сервера PostgreSQL («кластере» в терминологии PostgreSQL) и, при необходимости, предоставляет пользователю доступ к существующей базе данных или таблицам.
Пользователь — это роль с правом на вход.
Нельзя удалить пользователя, если ему всё ещё предоставлены какие-либо привилегии в какой-либо базе данных.
Установите для fail_on_user значение false, чтобы модуль игнорировал ошибки при попытке удалить пользователя. В этом случае модуль, как обычно, сообщает, произошли ли изменения, и отдельно указывает, был ли удалён пользователь.

Требования

На узле, выполняющем этот модуль, должны быть установлены следующие компоненты.

psycopg2 >= 2.5.1

Параметры

Параметр	Комментарии
ca_cert псевдонимы: ssl_rootcert string	Задаёт имя файла, содержащего сертификат или сертификаты центра сертификации (CA) для SSL. Если файл существует, проверяет, подписан ли сертификат сервера одним из этих центров.
comment string добавлено в community.postgresql 0.2.0	Добавляет комментарий к пользователю (эквивалент оператора `COMMENT ON ROLE`). Чтобы сбросить комментарий, передайте пустую строку.
configuration dictionary добавлено в community.postgresql 3.5.0	Параметры конфигурации для конкретной роли, которые в противном случае задавались бы с помощью `ALTER ROLE user SET variable TO value;`. Принимает словарь, где ключ — это имя параметра конфигурации. Если ключ содержит специальные символы, например `.` и `-`, его необходимо заключить в кавычки, чтобы YAML был корректным. Задаёт или обновляет каждый параметр из списка, который отсутствует в базе данных или имеет неверное значение. Удаляет у пользователя все параметры, не перечисленные здесь. Параметры, присутствующие в базе данных, но не включённые в этот список, сбрасываются только в том случае, если `reset_unspecified_configuration=true`. Входные данные для `user`, а также ключи и значения этого параметра заключаются модулем в кавычки. Если требуется, чтобы пользователь содержал `"`, его необходимо продублировать, иначе модуль завершится с ошибкой. `"` и `'` недопустимы в ключах конфигурации, а любые `'` в значении конфигурации будут экранированы этим модулем. Кроме того, модуль проверяет параметры и значения на случай, если `trust_input` имеет значение `false`. По умолчанию: `{}`
conn_limit integer	Задаёт лимит подключений пользователя (роли).
connect_params dictionary добавлено в community.postgresql 2.3.0	Любые дополнительные параметры, передаваемые в libpg. Эти параметры имеют приоритет. По умолчанию: `{}`
encrypted boolean	Определяет, хранится ли пароль в базе данных в виде хеша. Можно указать пароль без хеширования; PostgreSQL сохранит его в виде хеша, если задано encrypted=true. Если указан хешированный пароль, модуль использует его как есть, независимо от значения encrypted. Примечание: PostgreSQL 10 и более поздние версии не поддерживают пароли без хеширования. До Ansible 2.6 по умолчанию использовалось значение `false`. Варианты: `false` `true` ← (по умолчанию)
expires string	Дата истечения срока действия пароля пользователя. Если задано значение `'infinity'`, срок действия пароля пользователя не истекает. Обратите внимание, что это значение должно соответствовать допустимому типу даты и времени SQL.
fail_on_user псевдонимы: fail_on_role boolean	Если `true`, завершает работу с ошибкой, когда пользователя (роль) не удаётся удалить. В противном случае только записывает сообщение в журнал и продолжает работу. Варианты: `false` `true` ← (по умолчанию)
login_db псевдонимы: db string	Имя базы данных, к которой нужно подключиться и в которой предоставляются разрешения пользователю. Псевдоним `db` устарел и будет удалён в версии 5.0.0. По умолчанию: `""`
login_host псевдонимы: host string	Узел, на котором работает база данных. Если при использовании `localhost` возникают проблемы с подключением, попробуйте вместо этого использовать `127.0.0.1`. По умолчанию: `""`
login_password string	Пароль, который модуль должен использовать для установления сеанса PostgreSQL. По умолчанию: `""`
login_port псевдонимы: port integer	Порт базы данных для подключения. Псевдоним `port` устарел и будет удалён в следующем основном выпуске. Вместо него используйте `login_port`. По умолчанию: `5432`
login_unix_socket псевдонимы: unix_socket string	Путь к доменному сокету Unix для локальных подключений. По умолчанию: `""`
login_user псевдонимы: login string	Имя пользователя, которое модуль должен использовать для установления сеанса PostgreSQL. По умолчанию: `"postgres"`
name псевдонимы: user string / обязательный	Имя пользователя (роли), которого нужно добавить или удалить.
no_password_changes boolean	Если `true`, не проверяет базу данных на наличие изменений пароля. Если пользователь уже существует, пропускает все проверки, связанные с паролем. Полезно, когда `pg_authid` недоступен (например, в AWS RDS). В противном случае при необходимости изменяет пароль. Варианты: `false` ← (по умолчанию) `true`
password string	Задаёт пароль пользователя; до версии 1.4 этот параметр был обязательным. Пароль можно передать без хеширования или в хешированном виде (хеш MD5). Пароль без хеширования автоматически хешируется при сохранении в базе данных, если задан параметр encrypted; в противном случае он сохраняется в открытом виде. При передаче пароля с хешем MD5 необходимо сгенерировать его в формате `'str["md5"] + md5[ password + username ]'`; в итоге строка должна содержать 35 символов. Простой способ сделать это — echo "md5`echo -n 'verysecretpasswordJOE' \| md5sum \| awk '{print $1}'`". Обратите внимание: если переданная строка пароля уже имеет формат хеша MD5, она используется как есть независимо от параметра encrypted.
quote_configuration_values boolean добавлено в community.postgresql 3.11.0	Автоматически заключает в кавычки значения переменных конфигурации, добавленных с помощью configuration. По умолчанию задано значение `true`; установка значения `false` оставляет эти параметры уязвимыми для SQL-инъекций и возлагает на пользователя ответственность за корректное заключение значений в кавычки. Для изменения таких параметров, как `search_path`, которые должны быть без кавычек, этому параметру необходимо задать значение `false`. Если задано значение `false`, также необходимо убедиться, что строки заключены в кавычки надлежащим образом. Например, `"'16MB'"` для `work_mem`. Устанавливайте значение `false`, только если знаете, что делаете! Варианты: `false` `true` ← (по умолчанию)
reset_unspecified_configuration boolean добавлено в community.postgresql 3.5.0	Если задано значение `true`, параметры конфигурации пользователя по умолчанию будут сброшены, если они не включены в `configuration`; в противном случае существующие параметры не будут изменяться, если они не включены в `configuration`. Варианты: `false` ← (по умолчанию) `true`
role_attr_flags string	Строка атрибутов пользователя PostgreSQL в формате: CREATEDB,CREATEROLE,SUPERUSER. Обратите внимание, что «[NO]CREATEUSER» считается устаревшим. Чтобы создать простую роль для использования в качестве группы, используйте флаг `NOLOGIN`. Полный список поддерживаемых флагов см. в документации для вашей версии PostgreSQL. По умолчанию: `""`
session_role string	Переключается на роль сеанса после подключения. Указанная роль сеанса должна быть ролью, членом которой является текущий login_user. Проверка разрешений для команд SQL выполняется так, как если бы исходный вход в систему был выполнен под указанной ролью сеанса.
ssl_cert path добавлено в community.postgresql 2.4.0	Задаёт имя файла клиентского сертификата SSL.
ssl_key path добавлено в community.postgresql 2.4.0	Задаёт расположение секретного ключа, используемого для клиентского сертификата.
ssl_mode string	Определяет способ согласования SSL-сеанса с сервером. Дополнительные сведения о режимах см. на странице https://www.postgresql.org/docs/current/static/libpq-ssl.html. Значение по умолчанию `prefer` соответствует значению по умолчанию libpq. Варианты: `"allow"` `"disable"` `"prefer"` ← (по умолчанию) `"require"` `"verify-ca"` `"verify-full"`
state string	Состояние пользователя (роли). Варианты: `"absent"` `"present"` ← (по умолчанию)
trust_input boolean добавлено в community.postgresql 0.2.0	Если `false`, проверяет, могут ли значения параметров name, password, expires, role_attr_flags, comment, session_role представлять опасность. Использовать `false` имеет смысл только в том случае, если через параметры возможны SQL-инъекции. Варианты: `false` `true` ← (по умолчанию)

Атрибуты

Атрибут	Поддержка	Описание
check_mode	Поддержка: полная	Может работать в режиме check_mode и возвращать прогноз статуса изменений, не изменяя целевой узел.

Примечания

Примечание

По умолчанию модуль создаёт пользователя (роль) с правом на вход. Используйте NOLOGIN role_attr_flags, чтобы изменить это поведение.
Если в качестве пользователя (роли) указать PUBLIC, изменения привилегий применяются ко всем пользователям (ролям). Если указан пользователь PUBLIC, задавать пароль или role_attr_flags нельзя.
Пароли с хешем SCRAM-SHA-256 (аутентификация SASL) требуют PostgreSQL версии 10 или новее. В предыдущих версиях вся строка хеша используется в качестве пароля.
При работе с паролями с хешем SCRAM-SHA-256 обязательно используйте переменную environment: PGOPTIONS: "-c password_encryption=scram-sha-256", если она не является значением по умолчанию для вашей версии PostgreSQL (см. приведённый пример).
В некоторых системах (например, AWS RDS) pg_authid недоступен, поэтому модуль не может сравнить текущий и желаемый password. В этом случае модуль предполагает, что пароли различаются, и изменяет пароль, сообщая об изменении состояния. Чтобы пропустить все проверки паролей для существующих пользователей, используйте no_password_changes=true.
В некоторых системах (например, AWS RDS) SUPERUSER недоступен. Это означает, что параметры SUPERUSER и NOSUPERUSER role_attr_flags не следует указывать, чтобы сохранить идемпотентность и избежать ошибок InsufficientPrivilege.
По умолчанию предполагается, что вы входите в систему или переключаетесь с помощью sudo на учётную запись postgres на узле.
Чтобы избежать ошибки «Peer authentication failed for user postgres», используйте пользователя postgres в качестве become_user.
Этот модуль использует psycopg — адаптер Python для баз данных PostgreSQL. Перед использованием модуля необходимо убедиться, что на узле установлен psycopg2 >= 2.5.1 или psycopg3 >= 3.1.8.
Если удалённый узел является сервером PostgreSQL (что используется по умолчанию), PostgreSQL также должен быть установлен на удалённом узле.
В системах на базе Ubuntu перед использованием этого модуля установите на удалённом узле пакеты postgresql, libpq-dev и python3-psycopg2.

См. также

community.postgresql.postgresql_privs: Предоставление или отзыв привилегий для объектов базы данных PostgreSQL.
community.postgresql.postgresql_membership: Добавление ролей PostgreSQL в группы или их удаление из групп.
community.postgresql.postgresql_owner: Изменение владельца объекта базы данных PostgreSQL.
Роли базы данных PostgreSQL: Полный справочник по ролям базы данных PostgreSQL.
Аутентификация SASL в PostgreSQL: Полный справочник по аутентификации SASL в PostgreSQL.

Примеры

- name: Connect to acme database, create django user
  community.postgresql.postgresql_user:
    login_db: acme
    name: django
    password: ceec4eif7ya
    expires: "Jan 31 2020"

- name: Add a comment on django user
  community.postgresql.postgresql_user:
    login_db: acme
    name: django
    comment: This is a test user

# Connect to default database, create rails user, set its password (MD5- or SHA256-hashed),
# and set flags to allow the user to create databases
# and demote rails from super user status if user exists
# the hash from the corresponding pg_authid entry.
- name: Create rails user, set MD5-hashed password, set flags
  community.postgresql.postgresql_user:
    name: rails
    password: md59543f1d82624df2b31672ec0f7050460
    # password: SCRAM-SHA-256$4096:zFuajwIVdli9mK=NJkcv1Q++$JC4gWIrEHmF6sqRbEiZw5FFW45HUPrpVzNdoM72o730+;fqA4vLN3mCZGbhcbQyvNYY7anCrUTsem1eCh/4YA94=
    role_attr_flags: CREATEDB,NOSUPERUSER
  # When using sha256-hashed password:
  # environment:
  #   PGOPTIONS: "-c password_encryption=scram-sha-256"

- name: Connect to test database, remove test user from cluster
  community.postgresql.postgresql_user:
    login_db: test
    name: test
    state: absent

- name: Connect to acme database and set user's password with no expire date
  community.postgresql.postgresql_user:
    login_db: acme
    name: django
    password: mysupersecretword
    expires: infinity

- name: Connect to test database and remove an existing user's password
  community.postgresql.postgresql_user:
    login_db: test
    user: test
    password: ""

# Create user with a cleartext password if it does not exist or update its password.
# The password will be encrypted with SCRAM algorithm (available since PostgreSQL 10)
- name: Create appclient user with SCRAM-hashed password
  community.postgresql.postgresql_user:
    name: appclient
    password: "secret123"
  environment:
    PGOPTIONS: "-c password_encryption=scram-sha-256"

# Create a user and set a default-configuration that is active when they start a session
- name: Create a user with config-parameter
  community.postgresql.postgresql_user:
    name: appclient
    password: "secret123"
    configuration:
      work_mem: "16MB"

# Make sure user has only specified default configuration parameters
- name: Clear all configuration that is not explicitly defined for user
  community.postgresql.postgresql_user:
    name: appclient
    password: "secret123"
    configuration:
      work_mem: "16MB"
    reset_unspecified_configuration: true

- name: Set search_path for user
  community.postgresql.postgresql_user:
    name: postgres_exporter
    quote_configuration_values: false
    configuration:
      search_path: postgres_exporter, pg_catalog, public

Возвращаемые значения

Общие возвращаемые значения описаны здесь; ниже перечислены поля, уникальные для этого модуля:

Ключ	Описание
queries list / elements=string	Список выполненных запросов. Возвращается: при успешном выполнении Пример: `["CREATE USER \"alice\"", "GRANT CONNECT ON DATABASE \"acme\" TO \"alice\""]`

Авторы

Основная команда Ansible

Ссылки на коллекцию

© 2012–2018 Michael DeHaan
© 2018–2025 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/projects/ansible/latest/collections/community/postgresql/postgresql_user_module.html