Monitor and troubleshoot HashiCorp Vault

Check the /health/status endpoint for Vault connectivity status.

Review Platform logs for Vault connection errors.

Set up alerts for Vault connection failures.

Verify the Vault URL

Confirm the vault_url value is correct, reachable from the Platform server, and includes the correct port (default: 8200).

Check Vault server status

Verify that Vault is running and unsealed. A sealed Vault returns errors for all requests.

vault status

Look for Sealed: false in the output.

Confirm authentication credentials

For token auth, verify that the token file exists and contains a valid, non-expired token:

cat /opt/vault/token.txt
vault token lookup <token>

For AppRole auth, verify the role_id and secret_id are correct and the secret_id has not expired.

Check network connectivity

Confirm that the Platform server can reach the Vault server:

curl -s https://vault.company.com:8200/v1/sys/health

A healthy Vault returns HTTP 200.

Review Platform logs

Check Platform logs for specific error messages:

# Platform 6
sudo journalctl -u itential-platform -f | grep -i vault
# Platform 2023.2
sudo journalctl -u automation-platform -f | grep -i vault

Create a certificate file

touch /tmp/vault.cert

Copy the Vault certificate chain into the file

Copy the contents of all SSL certificates in the chain in order: end-user certificate first, then intermediate certificates, then the root certificate.

-----BEGIN CERTIFICATE-----
<Content of end-user certificate>
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
<Content of intermediate certificate>
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
<Content of root certificate>
-----END CERTIFICATE-----

To retrieve the certificate chain directly from the Vault server:

openssl s_client -showcerts -connect vault.company.com:8200 </dev/null

Move the file to the certificates directory

sudo mv /tmp/vault.cert /etc/pki/tls/certs/vault.cert

Set file ownership and permissions

sudo chown itential:itential /etc/pki/tls/certs/vault.cert
sudo chmod 400 /etc/pki/tls/certs/vault.cert

Add the NODE_EXTRA_CA_CERTS environment variable to the Platform service file

Find the Platform service file path:

systemctl status itential-platform

Edit the service file and add this line in the [Service] section:

Environment="NODE_EXTRA_CA_CERTS=/etc/pki/tls/certs/vault.cert"

Reload the daemon and restart Platform

sudo systemctl daemon-reload
sudo systemctl restart itential-platform

Verify the secret reference format

Confirm the reference uses the correct syntax with a space between the path and key directives:

$SECRET_<path> $KEY_<key-name>

Common mistake: missing the space before $KEY_.

Verify the Vault path

Confirm the secret exists at the specified path in Vault. The path in a $SECRET reference is relative to the kv-v2 mount point and does not include /data/.

vault kv get <mount-point>/<path>

Confirm the secrets endpoint configuration

The vault_secrets_endpoint value must end with /data. For example, if the kv-v2 engine is mounted at kv-v2, the endpoint must be kv-v2/data.

Check Vault token permissions

Confirm the Vault token or AppRole has a policy that grants read access to the secret path:

vault token capabilities <token> <mount>/<path>

Check token TTL

vault token lookup <token>

Look for expire_time in the output.

Renew or replace the token

Renew the token if it is still valid:

vault token renew <token>

If the token has expired, generate a new one and update the token file at the path configured in vault_token. Restart Itential Platform after replacing the token.

Consider using AppRole authentication

AppRole authentication with a periodically-renewed secret_id is better suited for long-running production deployments than static tokens. See Connect Platform to HashiCorp Vault for AppRole configuration details.