Configuración de HashiCorp
Descripción general
Esta sección explica cómo configurar Zabbix para recuperar secretos de HashiCorp Vault KV Secrets Engine - Versión 2.
El vault debe implementarse y configurarse tal como se describe en la documentación oficial de HashiCorp.
Para obtener información sobre la configuración de TLS en Zabbix, consulte Almacenamiento de secretos.
Recuperación de credenciales de la base de datos
Para recuperar correctamente un secreto con credenciales de la base de datos, es necesario configurar ambos:
- Zabbix server/proxy
- Zabbix frontend
Server/proxy
Para configurar el server o el proxy de Zabbix, especifique los siguientes parámetros de configuración en el archivo de configuración:
Vault: proveedor de vault que se utilizará.VaultToken: token de autenticación de vault (consulte el archivo de configuración del server/proxy de Zabbix para obtener más información); no se puede utilizar conVaultAppRoleID.VaultAppRoleIDyVaultAppSecretID: ID de rol y ID secreto de autenticación de vault (consulte el archivo de configuración del server/proxy de Zabbix para obtener más información); no se pueden utilizar conVaultToken.VaultURL: URL HTTP(S) del server de vault.VaultDBPath: ruta al secreto de vault que contiene las credenciales de la base de datos (esta opción solo se puede utilizar si no se especifican DBUser y DBPassword). El server o proxy de Zabbix 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. Tenga en cuenta que el prefijo debe comenzar y terminar con/.
Los parámetros de configuración Vault, VaultToken (o VaultAppRoleID/VaultAppSecretID), VaultURL y VaultPrefix también se utilizan para la autenticación de vault al procesar macros secretas de vault mediante el server de Zabbix (y el proxy de Zabbix, si está configurado). El server de Zabbix y los proxies no abrirán las macros secretas de vault que contengan credenciales de la base de datos de VaultDBPath.
Se recomienda encarecidamente utilizar tokens diferentes para distintos proxies.
El server de Zabbix y el proxy de Zabbix leen los parámetros de configuración relacionados con vault de zabbix_server.conf y zabbix_proxy.conf al iniciarse.
Además, el server de Zabbix y el proxy de Zabbix leerán la variable de entorno VAULT_TOKEN una vez durante el inicio y la desactivarán para que no esté disponible mediante scripts bifurcados; se produce un error si los parámetros VaultToken y VAULT_TOKEN contienen un valor.
Ejemplo
- Configure los parámetros del Zabbix server.
No utilice en entornos de producción los valores de ejemplo del token, el ID de rol ni el ID secreto incluidos en la documentación.
- Si utiliza la variable de entorno
VAULT_TOKEN, especifique los siguientes parámetros en el archivo de configuración del server de Zabbix (zabbix_server.conf) y establezca la variable:
Vault=HashiCorp
VaultURL=https://127.0.0.1:8200
VaultDBPath=database
VaultPrefix=/v1/secret/data/zabbix/Establezca la variable de entorno VAULT_TOKEN para el Zabbix server antes de iniciarlo:
export VAULT_TOKEN=hvs.CAESIIG_PILmULFYOsEyWHxkZ2mF2a8VPKNLE8eHqd4autYGGh4KHGh2cy5aeTY0NFNSaUp3ZnpWbDF1RUNjUkNTZEg
zabbix_server -c /etc/zabbix/zabbix_server.conf- Si utiliza el parámetro
VaultToken, especifique los siguientes parámetros en el archivo de configuración del Zabbix server:
Si utiliza el parámetro VaultToken, el token se almacena en texto plano en el archivo de configuración.
Establezca los permisos del archivo en 0600 para que solo el usuario que ejecuta el Zabbix server o el proxy pueda leerlo.
Vault=HashiCorp
VaultToken=hvs.CAESIIG_PILmULFYOsEyWHxkZ2mF2a8VPKNLE8eHqd4autYGGh4KHGh2cy5aeTY0NFNSaUp3ZnpWbDF1RUNjUkNTZEg
VaultURL=https://127.0.0.1:8200
VaultDBPath=database
VaultPrefix=/v1/secret/data/zabbix/- Si utiliza el parámetro
VaultAppRoleID, especifique los siguientes parámetros en el archivo de configuración del Zabbix server:
Si utiliza el parámetro VaultAppSecretID, el ID secreto se almacena en texto plano en el archivo de configuración.
Establezca los permisos del archivo en 0600 para que solo el usuario que ejecuta el Zabbix server o el proxy pueda leerlo.
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/- Ejecute los siguientes comandos de la 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 utilizarse "kv-v2".
vault secrets enable -path=secret/ kv-v2
# Coloque nuevos secretos con las claves username y password en 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 añadido correctamente.
vault kv get secret/zabbix/database
# Finalmente, realice una prueba con Curl; tenga en cuenta que debe añadir manualmente "data" 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- Como resultado, el Zabbix server recuperará las siguientes credenciales para la autenticación en la base de datos:
- Nombre de usuario: zabbix
- Contraseña: <password>
Frontend
El frontend de Zabbix se puede configurar para recuperar las credenciales de la base de datos desde el vault durante la instalación del frontend o actualizando el archivo de configuración del frontend (zabbix.conf.php).
Si las credenciales del vault han cambiado desde la instalación anterior del frontend, actualice la configuración existente.
Durante la instalación del frontend, los parámetros de conexión deben especificarse en el paso Configure DB Connection.
Ejemplo de configuración mediante autenticación con token:
Ejemplo de configuración mediante autenticación AppRole:
| Parameter | Mandatory | Default value | Description |
|---|---|---|---|
| Store credentials in | no | Seleccione HashiCorp Vault. | |
| Vault API endpoint | yes | https://localhost:8200 | Especifique la URL para conectarse al vault con el formato scheme://host:port |
| Vault prefix | no | /v1/secret/data/ | Proporcione un prefijo personalizado para la ruta o consulta del vault. Si no se especifica, se utiliza el valor predeterminado. Ejemplo: /v1/secret/data/zabbix/ |
| Vault secret path | yes | Ruta al secreto desde la que se recuperarán las credenciales de la base de datos mediante las claves "password" y "username". Ejemplo: database |
|
| Vault authentication type | no | Seleccione el tipo de autenticación del vault: Token: utilizar autenticación con token; AppRole: utilizar el método de autenticación AppRole. |
|
| Vault authentication token | yes | Proporcione un token de autenticación con acceso de solo lectura a la ruta del secreto. Consulte la documentación de HashiCorp para obtener información sobre la creación de tokens y las políticas del vault. Este campo solo está disponible si se selecciona Token como tipo de autenticación del vault. |
|
| Vault authentication role ID | yes | Proporcione el ID de rol de AppRole. Consulte la documentación de HashiCorp para obtener información sobre AppRole. Este campo solo está disponible si se selecciona AppRole como tipo de autenticación del vault. |
|
| Vault authentication secret ID | yes | Proporcione el ID secreto emitido para AppRole. Consulte la documentación de HashiCorp para obtener información sobre AppRole. Este campo solo está disponible si se selecciona AppRole como tipo de autenticación del vault. |
Recuperación de valores de macros de usuario
Para utilizar HashiCorp Vault para almacenar valores de macros de usuario de tipo Vault secret, asegúrese de que:
- El server/proxy de Zabbix esté configurado para trabajar con HashiCorp Vault.
- El parámetro Vault provider en Administration > General > Other esté establecido en "HashiCorp Vault" (valor predeterminado).
El server de Zabbix (y el proxy de Zabbix, si está configurado) requiere acceso a los valores de macros de tipo Vault secret desde el vault. El frontend de Zabbix no necesita dicho acceso.
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 del server/proxy de Zabbix (mediante el parámetro VaultToken) debe proporcionar acceso de solo lectura a esta ruta.
Consulte Macros de tipo Vault secret para obtener información detallada sobre el procesamiento de los valores de macros 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
- En Zabbix, agregue una macro de usuario {$PASSWORD} de tipo "Vault secret" y con el valor
macros:password
- 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- 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:
-
Actualice los parámetros del archivo de configuración del Zabbix server o proxy, tal como se describe en la sección Credenciales de la base de datos.
-
Actualice los parámetros del archivo de configuración del frontend de Zabbix:
Uso de un 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 bien, mediante el método AppRole de 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/';- Configure las macros de usuario tal como se describe en la sección Valores de las 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
- En el archivo de registro del server/proxy de Zabbix:
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 desellado (es necesario en la configuración predeterminada; no es necesario si Auto Unseal está configurado).
- En el archivo de registro del server/proxy de Zabbix:
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.