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 Zabbix można skonfigurować tak, aby pobierał dane uwierzytelniające do bazy danych z sejfu podczas instalacji frontendu lub przez zaktualizowanie pliku konfiguracyjnego frontendu (zabbix.conf.php).

Jeśli dane uwierzytelniające do sejfu zmieniły się od czasu poprzedniej instalacji frontendu, zaktualizuj istniejącą konfigurację.

Podczas instalacji frontendu parametry połączenia należy określić w kroku Configure DB Connection.

Przykład konfiguracji z uwierzytelnianiem za pomocą tokenu:

Przykład konfiguracji z uwierzytelnianiem AppRole:

Parameter Mandatory Default value Description
Store credentials in no Wybierz HashiCorp Vault.
Vault API endpoint yes https://localhost:8200 Określ URL połączenia z sejfem w formacie scheme://host:port
Vault prefix no /v1/secret/data/ Podaj niestandardowy prefiks ścieżki lub zapytania sejfu. 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 dane uwierzytelniające do bazy danych będą pobierane za pomocą kluczy „password” i „username”.
Przykład: database
Vault authentication type no Wybierz typ uwierzytelniania sejfu:
Token - użyj uwierzytelniania za pomocą tokenu;
AppRole - użyj metody uwierzytelniania AppRole.
Vault authentication token yes Podaj token uwierzytelniania zapewniający dostęp tylko do odczytu do ścieżki sekretu.
Informacje o tworzeniu tokenów i zasad sejfu znajdziesz w dokumentacji HashiCorp.
To pole jest dostępne tylko wtedy, gdy jako typ uwierzytelniania sejfu wybrano Token.
Vault authentication role ID yes Podaj identyfikator roli AppRole.
Informacje o AppRole znajdziesz w dokumentacji HashiCorp.
To pole jest dostępne tylko wtedy, gdy jako typ uwierzytelniania sejfu wybrano AppRole.
Vault authentication secret ID yes Podaj identyfikator sekretu wydany dla AppRole.
Informacje o AppRole znajdziesz w dokumentacji HashiCorp.
To pole jest dostępne tylko wtedy, gdy jako typ uwierzytelniania sejfu 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>

Aktualizowanie istniejącej konfiguracji

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

  1. Zaktualizuj parametry pliku konfiguracyjnego serwera Zabbix lub proxy zgodnie z opisem w sekcji Dane uwierzytelniające bazy danych.

  2. Zaktualizuj parametry pliku konfiguracyjnego frontend Zabbix:

Korzystanie z 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 korzystanie z 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 zgodnie z opisem w sekcji Wartości makr użytkownika.

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

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, niewymagane, 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.