Konfiguracja HashiCorp

Przegląd

W tej sekcji wyjaśniono, jak skonfigurować Zabbix do pobierania sekretów z HashiCorp Vault KV Secrets Engine - Version 2.

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

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

Pobieranie danych uwierzytelniających do bazy danych

Aby pomyślnie pobrać sekret zawierający dane uwierzytelniające do bazy danych, należy skonfigurować oba elementy:

  • serwer/proxy Zabbix
  • frontend Zabbix

Serwer/proxy

Aby skonfigurować serwer lub proxy Zabbix, określ następujące parametry konfiguracji w pliku konfiguracyjnym:

  • Vault - dostawca vault, który ma być używany.
  • VaultToken - token uwierzytelniania vault (szczegółowe informacje znajdziesz w pliku konfiguracyjnym serwera/proxy Zabbix); nie może być używany razem z VaultAppRoleID.
  • VaultAppRoleID i VaultAppSecretID - identyfikator roli i identyfikator sekretu używane do uwierzytelniania vault (szczegółowe informacje znajdziesz w pliku konfiguracyjnym serwera/proxy Zabbix); nie mogą być używane razem z VaultToken.
  • VaultURL - adres URL HTTP(S) serwera vault.
  • VaultDBPath - ścieżka do sekretu vault zawierającego dane uwierzytelniające do bazy danych (tej opcji można używać tylko wtedy, gdy nie określono DBUser i DBPassword). Serwer lub proxy Zabbix pobierze dane uwierzytelniające za pomocą kluczy „password” i „username”.
  • VaultPrefix - niestandardowy prefiks ścieżki lub zapytania vault, zależnie od vault; jeśli nie zostanie określony, zostanie użyta najbardziej odpowiednia wartość domyślna. Pamiętaj, że prefiks musi zaczynać się i kończyć znakiem /.

Parametry konfiguracji Vault, VaultToken (lub VaultAppRoleID/VaultAppSecretID), VaultURL i VaultPrefix są również używane do uwierzytelniania w vault podczas przetwarzania makr sekretów vault przez serwer Zabbix (oraz proxy Zabbix, jeśli zostało skonfigurowane). Serwer Zabbix i proxy nie otworzą makr sekretów vault zawierających dane uwierzytelniające do bazy danych z VaultDBPath.

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

Serwer Zabbix i proxy Zabbix odczytują parametry konfiguracji związane z vault z plików zabbix_server.conf i zabbix_proxy.conf podczas uruchamiania.

Dodatkowo serwer Zabbix i proxy Zabbix odczytają zmienną środowiskową VAULT_TOKEN jednokrotnie podczas uruchamiania i usuną ją, aby nie była dostępna za pośrednictwem skryptów uruchamianych przez forkowanie; wystąpienie wartości zarówno w parametrze VaultToken, jak i w parametrze VAULT_TOKEN jest błędem.

Przykład
  1. Skonfiguruj parametry serwera Zabbix.

Nie używaj w środowiskach produkcyjnych przykładowych wartości tokenu, identyfikatora roli ani identyfikatora sekretu podanych w dokumentacji.

  • Jeśli używasz zmiennej środowiskowej VAULT_TOKEN, określ następujące parametry w pliku konfiguracyjnym serwera Zabbix (zabbix_server.conf) i ustaw zmienną:
Vault=HashiCorp
VaultURL=https://127.0.0.1:8200
VaultDBPath=database
VaultPrefix=/v1/secret/data/zabbix/

Ustaw zmienną środowiskową VAULT_TOKEN dla serwera Zabbix przed jego uruchomieniem:

export VAULT_TOKEN=hvs.CAESIIG_PILmULFYOsEyWHxkZ2mF2a8VPKNLE8eHqd4autYGGh4KHGh2cy5aeTY0NFNSaUp3ZnpWbDF1RUNjUkNTZEg
zabbix_server -c /etc/zabbix/zabbix_server.conf
  • Jeśli używasz parametru VaultToken, określ następujące parametry w pliku konfiguracyjnym serwera Zabbix:

Jeśli używasz parametru VaultToken, token jest przechowywany w postaci zwykłego tekstu w pliku konfiguracyjnym. Ustaw uprawnienia do pliku na 0600, aby tylko użytkownik uruchamiający serwer Zabbix lub proxy mógł go odczytać.

Vault=HashiCorp
VaultToken=hvs.CAESIIG_PILmULFYOsEyWHxkZ2mF2a8VPKNLE8eHqd4autYGGh4KHGh2cy5aeTY0NFNSaUp3ZnpWbDF1RUNjUkNTZEg
VaultURL=https://127.0.0.1:8200
VaultDBPath=database
VaultPrefix=/v1/secret/data/zabbix/
  • Jeśli używasz parametru VaultAppRoleID, określ następujące parametry w pliku konfiguracyjnym serwera Zabbix:

Jeśli używasz parametru VaultAppSecretID, identyfikator sekretu jest przechowywany w postaci zwykłego tekstu w pliku konfiguracyjnym. Ustaw uprawnienia do pliku na 0600, aby tylko użytkownik uruchamiający serwer Zabbix lub proxy mógł go odczytać.

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 magazynie:
# Włącz punkt montowania "secret/", jeśli nie został jeszcze włączony; pamiętaj, że należy użyć "kv-v2".
vault secrets enable -path=secret/ kv-v2

# Umieść 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 po punkcie montowania należy ręcznie dodać "data", a przed punktem montowania "/v1"; zobacz także 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 dane uwierzytelniające 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 vaulta podczas instalacji frontendu lub po zaktualizowaniu pliku konfiguracyjnego frontendu (zabbix.conf.php).

Jeśli dane uwierzytelniające vaulta 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 vaultem w formacie scheme://host:port
Vault prefix no /v1/secret/data/ Podaj niestandardowy prefiks ś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 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 vaulta:
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 vaulta znajdziesz w dokumentacji HashiCorp.
To pole 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.
To pole jest dostępne tylko wtedy, gdy jako typ uwierzytelniania vaulta 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 vaulta wybrano AppRole.

Pobieranie wartości makr użytkownika

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

serwer Zabbix (oraz proxy Zabbix, jeśli jest skonfigurowane) wymagają dostępu do wartości makr typu Vault secret w vault. frontend Zabbix nie wymaga 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 serwera/proxy Zabbix (za pomocą parametru VaultToken) musi zapewniać dostęp tylko do odczytu do tej ścieżki.

Szczegółowe informacje na temat przetwarzania wartości makr przez Zabbix znajdziesz w sekcji Makra typu Vault secret.

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 za pomocą 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ł odpieczętowany (jest to wymagane w konfiguracji domyślnej, ale 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życia w HashiCorp Vault.