Konfiguracja HashiCorp

Przegląd

Ta sekcja wyjaśnia, jak skonfigurować Zabbix do pobierania sekretów z HashiCorp Vault KV Secrets Engine - Version 2.

Vault powinien być wdrożony i skonfigurowany zgodnie z opisem w oficjalnej dokumentacji HashiCorp.

Aby dowiedzieć się, jak skonfigurować TLS w Zabbix, zobacz Przechowywanie sekretów.

Pobieranie poświadczeń bazy danych

Aby pomyślnie pobrać sekret z poświadczeniami bazy danych, należy skonfigurować oba elementy:

  • Zabbix server/proxy
  • Zabbix frontend
Serwer/proxy

Aby skonfigurować Zabbix serwer lub proxy, należy określić następujące parametry konfiguracyjne w pliku konfiguracyjnym:

  • Vault - który dostawca vault ma być używany;
  • VaultToken - token uwierzytelniania vault (szczegóły znajdują się w pliku konfiguracyjnym Zabbix server/proxy); nie może być używany z VaultAppRoleID;
  • VaultAppRoleID i VaultAppSecretID - identyfikator roli uwierzytelniania vault i identyfikator sekretu (szczegóły znajdują się w pliku konfiguracyjnym Zabbix server/proxy); nie mogą być używane z VaultToken;
  • VaultURL - adres HTTP[S] serwera vault;
  • VaultDBPath - ścieżka do sekretu vault zawierającego poświadczenia bazy danych (tej opcji można użyć tylko wtedy, gdy nie określono DBUser i DBPassword); Zabbix server lub proxy pobierze poświadczenia według kluczy "password" i "username";
  • VaultPrefix - niestandardowy prefiks dla ścieżki lub zapytania vault, zależnie od vault; jeśli nie zostanie określony, zostanie użyta najbardziej odpowiednia wartość domyślna.

Parametry konfiguracyjne Vault, VaultToken (lub VaultAppRoleID/VaultAppSecretID), VaultURL i VaultPrefix są również używane do uwierzytelniania w vault podczas przetwarzania makr sekretów vault przez Zabbix server (oraz Zabbix proxy, jeśli został skonfigurowany). Zabbix server i proxy nie otworzą makr sekretów vault, które zawierają poświadczenia DB z VaultDBPath.

Zdecydowanie zaleca się używanie różnych tokenów dla różnych proxy.

Zabbix server i Zabbix proxy odczytują parametry konfiguracyjne związane z vault z plików zabbix_server.conf i zabbix_proxy.conf podczas uruchamiania. Dodatkowo Zabbix server i Zabbix proxy odczytają zmienną środowiskową VAULT_TOKEN tylko raz podczas uruchamiania i wyczyszczą ją, aby nie była dostępna dla uruchamianych procesów potomnych; wystąpi błąd, jeśli zarówno VaultToken, jak i VAULT_TOKEN będą zawierać wartość.

Przykład

  1. W pliku zabbix_server.conf określ następujące parametry.

Korzystając z VaultToken:

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

Lub korzystając z 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/
  1. Uruchom następujące polecenia CLI, aby utworzyć wymagany sekret w vault:
# Włącz punkt montowania "secret/", jeśli nie jest jeszcze włączony; pamiętaj, że należy użyć "kv-v2".
vault secrets enable -path=secret/ kv-v2

# Dodaj nowe sekrety z kluczami username i password w punkcie montowania "secret/" oraz ścieżce "zabbix/database".
vault kv put -mount=secret zabbix/database username=zabbix password=<password>

# Sprawdź, czy sekret został pomyślnie dodany.
vault kv get secret/zabbix/database

# Na koniec przetestuj za pomocą Curl; pamiętaj, że "data" należy ręcznie dodać po punkcie montowania, a "/v1" przed punktem montowania; zobacz też parametr --capath.
curl --header "X-Vault-Token: <VaultToken>" https://127.0.0.1:8200/v1/secret/data/zabbix/database
  1. W rezultacie serwer Zabbix pobierze następujące poświadczenia do uwierzytelniania w bazie danych:
  • Nazwa użytkownika: zabbix
  • Hasło: <password>
Frontend

Frontend Zabbixa można skonfigurować tak, aby pobierał poświadczenia bazy danych z vaulta podczas instalacji frontendu albo przez aktualizację pliku konfiguracyjnego frontendu (zabbix.conf.php).

Jeśli poświadczenia vaulta zostały zmienione od czasu poprzedniej instalacji frontendu, uruchom ponownie instalację frontendu lub zaktualizuj zabbix.conf.php. Zobacz także: Aktualizacja istniejącej konfiguracji.

Podczas instalacji frontendu parametry połączenia muszą zostać podane na etapie Configure DB Connection.

Przykład konfiguracji z użyciem uwierzytelniania tokenem:

Przykład konfiguracji z użyciem uwierzytelniania AppRole:

Parameter Mandatory Default value Description
Store credentials in no Wybierz HashiCorp Vault.
Vault API endpoint yes https://localhost:8200 Podaj adres URL do połączenia z vaultem w formacie scheme://host:port
Vault prefix no /v1/secret/data/ Podaj niestandardowy prefiks dla ścieżki lub zapytania vaulta. Jeśli nie zostanie określony, zostanie użyta wartość domyślna.
Przykład: /v1/secret/data/zabbix/
Vault secret path yes Ścieżka do sekretu, z którego poświadczenia bazy danych mają zostać pobrane za pomocą kluczy "password" i "username".
Przykład: database
Vault authentication type no Wybierz typ uwierzytelniania vaulta:
Token - użyj uwierzytelniania tokenem;
AppRole - użyj metody uwierzytelniania AppRole.
Vault authentication token yes Podaj token uwierzytelniania do dostępu tylko do odczytu do ścieżki sekretu.
Informacje o tworzeniu tokenów i polityk vaulta znajdziesz w dokumentacji HashiCorp.
Pole to jest dostępne tylko wtedy, gdy jako typ uwierzytelniania vaulta wybrano Token.
Vault authentication role ID yes Podaj identyfikator roli AppRole.
Informacje o AppRole znajdziesz w dokumentacji HashiCorp.
Pole to jest dostępne tylko wtedy, gdy jako typ uwierzytelniania vaulta wybrano AppRole.
Vault authentication secret ID yes Podaj secret ID wydany dla AppRole.
Informacje o AppRole znajdziesz w dokumentacji HashiCorp.
Pole to jest dostępne tylko wtedy, gdy jako typ uwierzytelniania vaulta wybrano AppRole.

Pobieranie wartości makr użytkownika

Aby używać HashiCorp Vault do przechowywania wartości makr użytkownika Vault secret, upewnij się, że:

Zabbix server (oraz Zabbix proxy, jeśli jest skonfigurowany) wymaga dostępu do wartości makr Vault secret z vault. Zabbix frontend nie potrzebuje takiego dostępu.

Wartość makra powinna zawierać ścieżkę referencyjną (w formacie path:key, na przykład macros:password). Token uwierzytelniający określony podczas konfiguracji Zabbix server/proxy (za pomocą parametru VaultToken) musi zapewniać dostęp tylko do odczytu do tej ścieżki.

Szczegółowe informacje o przetwarzaniu wartości makr przez Zabbix znajdziesz w sekcji Vault secret macros.

Składnia ścieżki

Symbole ukośnika ("/") i dwukropka (":") są zarezerwowane.

Ukośnik może być używany wyłącznie do oddzielenia punktu montowania od ścieżki (np. secret/zabbix, gdzie punktem montowania jest "secret", a ścieżką "zabbix"). W przypadku makr Vault dwukropek może być używany wyłącznie do oddzielenia ścieżki/zapytania od klucza.

Możliwe jest zakodowanie znaków ukośnika i dwukropka w formacie URL, jeśli istnieje potrzeba utworzenia punktu montowania o nazwie zawierającej ukośnik (np. foo/bar/zabbix, gdzie punktem montowania jest "foo/bar", a ścieżką "zabbix", można zakodować jako "foo%2Fbar/zabbix") oraz jeśli nazwa punktu montowania lub ścieżka muszą zawierać dwukropek.

Przykład

  1. W Zabbix dodaj makro użytkownika {$PASSWORD} typu "Vault secret" i z wartością macros:password

  1. Uruchom następujące polecenia CLI, aby utworzyć wymagany sekret w vault:
# Włącz punkt montowania "secret/", jeśli nie jest jeszcze włączony; pamiętaj, że należy użyć "kv-v2".
vault secrets enable -path=secret/ kv-v2

# Dodaj nowy sekret z kluczem "password" w punkcie montowania "secret/" i ścieżce "zabbix/macros".
vault kv put -mount=secret zabbix/macros password=<password>

# Sprawdź, czy sekret został pomyślnie dodany.
vault kv get secret/zabbix/macros

# Na koniec przetestuj za pomocą Curl; pamiętaj, że "data" należy ręcznie dodać po punkcie montowania, a "/v1" przed punktem montowania; zobacz też parametr --capath.
curl --header "X-Vault-Token: <VaultToken>" https://127.0.0.1:8200/v1/secret/data/zabbix/macros
  1. W rezultacie Zabbix rozwiąże makro {$PASSWORD} do wartości: <password>

Aktualizacja istniejącej konfiguracji

Aby zaktualizować istniejącą konfigurację pobierania sekretów z HashiCorp Vault:

  1. Zaktualizuj parametry pliku konfiguracyjnego serwera lub proxy Zabbix, jak opisano w sekcji Database credentials.

  2. Zaktualizuj ustawienia połączenia z bazą danych, rekonfigurując frontend Zabbix i określając wymagane parametry, jak opisano w sekcji Frontend. Aby skonfigurować frontend Zabbix, otwórz w przeglądarce adres URL konfiguracji frontendu:

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

Alternatywnie, parametry te można ustawić w pliku konfiguracyjnym frontendu (zabbix.conf.php).

Przy użyciu tokenu 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/';

Lub przy użyciu metody 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/';
  1. W razie potrzeby skonfiguruj makra użytkownika, jak opisano w sekcji User macro values.

Aby zaktualizować istniejącą konfigurację pobierania sekretów z CyberArk Vault, zobacz CyberArk configuration.

Rozwiązywanie problemów

  1. W pliku dziennika serwera/proxy Zabbix:
237839:20260729:130916.425 Vault token renew started to fail: cannot login into HashiCorp vault with AppRole method: unsuccessful response code "503"

Prawdopodobna przyczyna: HashiCorp Vault został uruchomiony ponownie, ale nie został odblokowany (wymagane w konfiguracji domyślnej, nie jest wymagane, jeśli skonfigurowano Auto Unseal).

  1. W pliku dziennika serwera/proxy Zabbix:
235545:20260729:125617.944 Vault token renew started to fail: cannot login into HashiCorp vault with AppRole method: unsuccessful response code "400"

lub

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

Prawdopodobna przyczyna: VaultAppSecretID wygasł lub osiągnął limit użyć w HashiCorp vault.