Конфигурация HashiCorp

Обзор

В этом разделе объясняется, как настроить Zabbix для получения секретов из HashiCorp Vault KV Secrets Engine - Version 2.

Хранилище должно быть развернуто и настроено в соответствии с официальной документацией HashiCorp.

Подробнее о настройке TLS в Zabbix см. в разделе Хранение секретов.

Получение учетных данных базы данных

Для успешного получения секрета с учетными данными базы данных необходимо настроить оба компонента:

• сервер Zabbix/прокси
• веб-интерфейс Zabbix

Сервер/прокси

Чтобы настроить сервер или прокси Zabbix, укажите следующие параметры конфигурации в файле конфигурации:

• Vault — поставщик хранилища, который следует использовать.
• VaultToken — токен аутентификации хранилища (подробности см. в файле конфигурации сервера/прокси Zabbix); нельзя использовать вместе с VaultAppRoleID.
• VaultAppRoleID и VaultAppSecretID — идентификатор роли и секретный идентификатор для аутентификации в хранилище (подробности см. в файле конфигурации сервера/прокси Zabbix); нельзя использовать вместе с VaultToken.
• VaultURL — URL-адрес HTTP(S) сервера хранилища.
• VaultDBPath — путь к секрету хранилища, содержащему учетные данные базы данных (этот параметр можно использовать только в том случае, если DBUser и DBPassword не указаны). Сервер или прокси Zabbix получит учетные данные по ключам "password" и "username".
• VaultPrefix — пользовательский префикс пути или запроса к хранилищу, в зависимости от хранилища; если он не указан, будет использовано наиболее подходящее значение по умолчанию. Обратите внимание, что префикс должен начинаться и заканчиваться символом /.

Сервер Zabbix и прокси Zabbix считывают параметры конфигурации, связанные с хранилищем, из файлов zabbix_server.conf и zabbix_proxy.conf при запуске.

Кроме того, сервер Zabbix и прокси Zabbix один раз при запуске считывают переменную окружения VAULT_TOKEN и удаляют ее, чтобы она не была доступна через разветвленные скрипты; если параметры VaultToken и VAULT_TOKEN содержат значения одновременно, это считается ошибкой.

Пример

1. Настройте параметры сервера Zabbix.

• Если используется переменная окружения VAULT_TOKEN, укажите следующие параметры в файле конфигурации сервера Zabbix (zabbix_server.conf) и задайте переменную:

Vault=HashiCorp
VaultURL=https://127.0.0.1:8200
VaultDBPath=database
VaultPrefix=/v1/secret/data/zabbix/

Задайте переменную окружения VAULT_TOKEN для сервера Zabbix до его запуска:

export VAULT_TOKEN=hvs.CAESIIG_PILmULFYOsEyWHxkZ2mF2a8VPKNLE8eHqd4autYGGh4KHGh2cy5aeTY0NFNSaUp3ZnpWbDF1RUNjUkNTZEg
zabbix_server -c /etc/zabbix/zabbix_server.conf

• Если используется параметр VaultToken, укажите следующие параметры в файле конфигурации сервера Zabbix:

Vault=HashiCorp
VaultToken=hvs.CAESIIG_PILmULFYOsEyWHxkZ2mF2a8VPKNLE8eHqd4autYGGh4KHGh2cy5aeTY0NFNSaUp3ZnpWbDF1RUNjUkNTZEg
VaultURL=https://127.0.0.1:8200
VaultDBPath=database
VaultPrefix=/v1/secret/data/zabbix/

• Если используется параметр VaultAppRoleID, укажите следующие параметры в файле конфигурации сервера Zabbix:

Vault=HashiCorp
VaultAppRoleID=6f1567f1-538d-7d70-e8e4-5d3e59471b2e
VaultAppSecretID=89dac8b1-f7d6-96a7-2ecf-f94d2de3d6f1
VaultURL=https://127.0.0.1:8200
VaultDBPath=database
VaultPrefix=/v1/secret/data/zabbix/

2. Выполните следующие команды CLI, чтобы создать необходимый секрет в хранилище:

# Включите точку монтирования "secret/", если она еще не включена; обратите внимание, что необходимо использовать "kv-v2".
vault secrets enable -path=secret/ kv-v2

# Поместите новые секреты с ключами username и password в точку монтирования "secret/" по пути "zabbix/database".
vault kv put -mount=secret zabbix/database username=zabbix password=<password>

# Проверьте, что секрет успешно добавлен.
vault kv get secret/zabbix/database

# Наконец, выполните проверку с помощью Curl; обратите внимание, что после точки монтирования необходимо вручную добавить "data", а перед точкой монтирования — "/v1"; также см. параметр --capath.
curl --header "X-Vault-Token: <VaultToken>" https://127.0.0.1:8200/v1/secret/data/zabbix/database

3. В результате сервер Zabbix получит следующие учетные данные для аутентификации в базе данных:

• Имя пользователя: zabbix
• Пароль: <password>

Веб-интерфейс

Веб-интерфейс Zabbix можно настроить для получения учетных данных базы данных из хранилища либо во время установки веб-интерфейса, либо путем обновления файла конфигурации веб-интерфейса (zabbix.conf.php).

Во время установки веб-интерфейса параметры подключения необходимо указать на шаге Configure DB Connection.

Пример конфигурации с использованием аутентификации по токену:

Пример конфигурации с использованием аутентификации AppRole:

Получение значений пользовательских макросов

Чтобы использовать HashiCorp Vault для хранения значений пользовательских макросов типа секрет Vault, убедитесь, что:

• Zabbix server/прокси настроен для работы с HashiCorp Vault.
• Параметр Провайдер Vault в разделе Администрирование > Общие > Прочее имеет значение «HashiCorp Vault» (по умолчанию).

Значение макроса должно содержать ссылочный путь (в формате path:key, например macros:password). Токен аутентификации, указанный при настройке Zabbix server/прокси (с помощью параметра VaultToken), должен предоставлять доступ только для чтения к этому пути.

Подробную информацию об обработке значений макросов в Zabbix см. в разделе Макросы — секреты Vault.

Синтаксис пути

Символы прямой слэш ("/") и двоеточие (":") зарезервированы.

Прямой слэш можно использовать только для разделения точки монтирования и пути (например, secret/zabbix, где точка монтирования — "secret", а путь — "zabbix"). В случае макросов Vault двоеточие можно использовать только для разделения пути/запроса и ключа.

При необходимости создать точку монтирования с именем, содержащим прямой слэш (например, foo/bar/zabbix, где точка монтирования — "foo/bar", а путь — "zabbix", можно закодировать как "foo%2Fbar/zabbix"), а также если имя точки монтирования или путь должны содержать двоеточие, можно использовать URL-кодирование символов прямой слэш и двоеточие.

Пример

1. В Zabbix добавьте пользовательский макрос {$PASSWORD} типа "Vault secret" со значением macros:password

2. Выполните следующие команды CLI, чтобы создать необходимый секрет в vault:

# Включите точку монтирования "secret/", если она еще не включена; обратите внимание, что необходимо использовать "kv-v2".
vault secrets enable -path=secret/ kv-v2

# Поместите новый секрет с ключом "password" в точку монтирования "secret/" и путь "zabbix/macros".
vault kv put -mount=secret zabbix/macros password=<password>

# Проверьте, что секрет успешно добавлен.
vault kv get secret/zabbix/macros

# Наконец, проверьте с помощью Curl; обратите внимание, что "data" нужно вручную добавить после точки монтирования и "/v1" перед точкой монтирования, также см. параметр --capath.
curl --header "X-Vault-Token: <VaultToken>" https://127.0.0.1:8200/v1/secret/data/zabbix/macros

3. В результате Zabbix разрешит макрос {$PASSWORD} в значение: <password>

Обновление существующей конфигурации

Чтобы обновить существующую конфигурацию для получения секретов из HashiCorp Vault:

1. Обновите параметры конфигурационного файла сервера или прокси Zabbix, как описано в разделе Учетные данные базы данных.

2. Обновите параметры конфигурационного файла веб-интерфейса Zabbix:

С использованием токена Vault:

$DB['VAULT']                    = 'HashiCorp';
$DB['VAULT_URL']                = 'https://localhost:8200';
$DB['VAULT_DB_PATH']            = 'database';
$DB['VAULT_TOKEN']              = 'hvs.CAESIIG_PILmULFYOsEyWHxkZ2mF2a8VPKNLE8eHqd4autYGGh4KHGh2cy5aeTY0NFNSaUp3ZnpWbDF1RUNjUkNTZEg';
$DB['VAULT_PREFIX']             = '/v1/secret/data/zabbix/';

Или с использованием метода AppRole Vault:

$DB['VAULT']                    = 'HashiCorp';
$DB['VAULT_URL']                = 'https://localhost:8200';
$DB['VAULT_DB_PATH']            = 'database';
$DB['VAULT_APP_ROLE_ID']        = '6f1567f1-538d-7d70-e8e4-5d3e59471b2e';
$DB['VAULT_APP_SECRET_ID']      = '89dac8b1-f7d6-96a7-2ecf-f94d2de3d6f1';
$DB['VAULT_PREFIX']             = '/v1/secret/data/zabbix/';

3. При необходимости настройте пользовательские макросы, как описано в разделе Значения пользовательских макросов.

Чтобы обновить существующую конфигурацию для получения секретов из CyberArk Vault, см. раздел Конфигурация CyberArk.

Устранение неполадок

1. В файле журнала сервера/прокси Zabbix:

237839:20260729:130916.425 Vault token renew started to fail: cannot login into HashiCorp vault with AppRole method: unsuccessful response code "503"

Возможная причина: HashiCorp Vault был перезапущен, но не был разблокирован (требуется в конфигурации по умолчанию; не требуется, если настроена функция Auto Unseal).

2. В файле журнала сервера/прокси Zabbix:

235545:20260729:125617.944 Vault token renew started to fail: cannot login into HashiCorp vault with AppRole method: unsuccessful response code "400"

или

235545:20260729:125718.537 Vault token renew failed: cannot login into HashiCorp vault with AppRole method: unsuccessful response code "400"

Возможная причина: срок действия VaultAppSecretID истёк или было достигнуто ограничение на его использование в HashiCorp Vault.