Configuración de HashiCorp

Descripción general

Esta sección explica cómo configurar Zabbix para recuperar secretos de HashiCorp Vault KV Secrets Engine - Version 2.

El vault debe implementarse y configurarse como se describe en la documentación oficial de HashiCorp.

Para obtener información sobre cómo configurar TLS en Zabbix, consulte Storage of secrets.

Recuperación de credenciales de base de datos

Para recuperar correctamente un secreto con credenciales de base de datos, es necesario configurar ambos:

• Zabbix server/proxy
• Zabbix frontend

Server/proxy

Para configurar Zabbix server o proxy, especifique los siguientes parámetros de configuración en el archivo de configuración:

• Vault - qué proveedor de vault debe utilizarse;
• VaultToken - token de autenticación de vault (consulte el archivo de configuración de Zabbix server/proxy para obtener más detalles); no se puede usar con VaultAppRoleID;
• VaultAppRoleID y VaultAppSecretID - ID de rol y ID secreto de autenticación de vault (consulte el archivo de configuración de Zabbix server/proxy para obtener más detalles); no se puede usar con VaultToken;
• VaultURL - URL HTTP[S] del servidor vault;
• VaultDBPath - ruta al secreto de vault que contiene las credenciales de base de datos (esta opción solo se puede usar si DBUser y DBPassword no están especificados); Zabbix server o proxy recuperará las credenciales mediante las claves "password" y "username";
• VaultPrefix - prefijo personalizado para la ruta o consulta de vault, según el vault; si no se especifica, se utilizará el valor predeterminado más adecuado.

Zabbix server y Zabbix proxy leen los parámetros de configuración relacionados con vault desde zabbix_server.conf y zabbix_proxy.conf al iniciarse. Además, Zabbix server y Zabbix proxy leerán la variable de entorno VAULT_TOKEN una sola vez durante el inicio y la eliminarán para que no esté disponible a través de scripts bifurcados; es un error si tanto VaultToken como VAULT_TOKEN contienen un valor.

Ejemplo

1. En zabbix_server.conf, especifique los siguientes parámetros.

Usando VaultToken:

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

O, usando VaultAppRoleID:

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. Ejecute los siguientes comandos CLI para crear el secreto requerido en el vault:

# Habilite el punto de montaje "secret/" si aún no está habilitado; tenga en cuenta que debe usarse "kv-v2".
vault secrets enable -path=secret/ kv-v2

# Coloque nuevos secretos con las claves username y password bajo el punto de montaje "secret/" y la ruta "zabbix/database".
vault kv put -mount=secret zabbix/database username=zabbix password=<password>

# Compruebe que el secreto se haya agregado correctamente.
vault kv get secret/zabbix/database

# Finalmente, pruebe con Curl; tenga en cuenta que "data" debe agregarse manualmente después del punto de montaje y "/v1" antes del punto de montaje; consulte también el parámetro --capath.
curl --header "X-Vault-Token: <VaultToken>" https://127.0.0.1:8200/v1/secret/data/zabbix/database

3. Como resultado, Zabbix server recuperará las siguientes credenciales para la autenticación de la base de datos:

• Usuario: zabbix
• Contraseña: <password>

Frontend

Zabbix frontend se puede configurar para recuperar las credenciales de la base de datos desde el vault ya sea durante la instalación del frontend o mediante la actualización del archivo de configuración del frontend (zabbix.conf.php).

Durante la instalación del frontend, los parámetros de conexión deben especificarse en el paso Configure DB Connection.

Ejemplo de configuración usando autenticación por token:

Ejemplo de configuración usando autenticación AppRole:

Recuperación de valores de macros de usuario

Para usar HashiCorp Vault para almacenar valores de macros de usuario de Vault secret, asegúrese de que:

• Zabbix server/proxy esté configurado para funcionar con HashiCorp Vault.
• El parámetro Vault provider en Administration > General > Other esté establecido en "HashiCorp Vault" (valor predeterminado).

El valor de la macro debe contener una ruta de referencia (como path:key, por ejemplo, macros:password). El token de autenticación especificado durante la configuración de Zabbix server/proxy (mediante el parámetro VaultToken) debe proporcionar acceso de solo lectura a esta ruta.

Consulte Vault secret macros para obtener información detallada sobre el procesamiento de valores de macro por parte de Zabbix.

Sintaxis de la ruta

Los símbolos barra diagonal ("/") y dos puntos (":") están reservados.

Una barra diagonal solo se puede usar para separar un punto de montaje de una ruta (por ejemplo, secret/zabbix, donde el punto de montaje es "secret" y la ruta es "zabbix"). En el caso de los macros de Vault, un dos puntos solo se puede usar para separar una ruta/consulta de una clave.

Es posible codificar en URL los símbolos barra diagonal y dos puntos si es necesario crear un punto de montaje con un nombre que esté separado por una barra diagonal (por ejemplo, foo/bar/zabbix, donde el punto de montaje es "foo/bar" y la ruta es "zabbix", puede codificarse como "foo%2Fbar/zabbix") y si el nombre de un punto de montaje o una ruta necesita contener un dos puntos.

Ejemplo

1. En Zabbix, agregue una macro de usuario {$PASSWORD} de tipo "Vault secret" y con el valor macros:password

2. Ejecute los siguientes comandos CLI para crear el secreto requerido en el vault:

# Habilite el punto de montaje "secret/" si aún no está habilitado; tenga en cuenta que se debe usar "kv-v2".
vault secrets enable -path=secret/ kv-v2

# Coloque un nuevo secreto con la clave "password" bajo el punto de montaje "secret/" y la ruta "zabbix/macros".
vault kv put -mount=secret zabbix/macros password=<password>

# Compruebe que el secreto se haya agregado correctamente.
vault kv get secret/zabbix/macros

# Finalmente, pruebe con Curl; tenga en cuenta que "data" debe agregarse manualmente después del punto de montaje y "/v1" antes del punto de montaje; consulte también el parámetro --capath.
curl --header "X-Vault-Token: <VaultToken>" https://127.0.0.1:8200/v1/secret/data/zabbix/macros

3. Como resultado, Zabbix resolverá la macro {$PASSWORD} al valor: <password>

Actualización de la configuración existente

Para actualizar una configuración existente para recuperar secretos de un HashiCorp Vault:

1. Actualice los parámetros del archivo de configuración del server o proxy de Zabbix como se describe en la sección Credenciales de base de datos.

2. Actualice la configuración de conexión a la base de datos reconfigurando el frontend de Zabbix y especificando los parámetros requeridos como se describe en la sección Frontend. Para reconfigurar el frontend de Zabbix, abra la URL de configuración del frontend en el navegador:

• para Apache: http://<server_ip_or_name>/zabbix/setup.php
• para Nginx: http://<server_ip_or_name>/setup.php

Como alternativa, estos parámetros se pueden establecer en el archivo de configuración del frontend (zabbix.conf.php).

Usando el token de 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/';

O, usando el método Vault AppRole:

$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. Configure las macros de usuario como se describe en la sección Valores de macros de usuario, si es necesario.

Para actualizar una configuración existente para recuperar secretos de un CyberArk Vault, consulte Configuración de CyberArk.

Solución de problemas

1. En el archivo de registro de Zabbix server/proxy:

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

Causa probable: HashiCorp Vault se ha (re)iniciado, pero no se ha desbloqueado (requisito en la configuración predeterminada; no es necesario si Auto Unseal está configurado).

2. En el archivo de registro de Zabbix server/proxy:

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

o

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

Causa probable: VaultAppSecretID ha caducado o ha alcanzado su límite de uso en HashiCorp vault.