Configure Vault for storing secrets

Legacy 'nms' references
Some commands, file paths, and configuration references still use nms due to the ongoing transition from NGINX Management Suite (NMS) to NGINX Instance Manager (NIM). These will be updated in future releases.

HashiCorp’s Vault is a popular solution for storing secrets. While F5 NGINX Instance Manager provides encryption-at-rest for secrets stored on disk, you may prefer to store all secrets in one place if you have an existing Vault installation. NGINX Instance Manager provides a driver to connect to existing Vault installations and store secrets.

Before you begin

To complete the steps in this guide, you need:

A working understanding of Vault and its operations.
A running version of Vault 1.8.8 or later.

Create periodic service tokens

Access to a Vault requires a renewable token.

Note:
If you attempt to use the Vault’s Root Token, NGINX Instance Manager won’t start the secrets driver, as that token is not renewable.

To create a periodic service token for NGINX Instance Manager:

Use the Vault user interface to create a new policy.

The “default” policy doesn’t allow storing or retrieving secrets, and the root policy is too broad. Create a policy called nms_secrets with these capabilities:
```
path "secret/*" {
  capabilities = ["create", "read", "update", "delete", "list"]
}
```
Create a renewable service token. We recommend a period of 24 hours. NGINX Instance Manager renews tokens automatically, so shorter periods also work. Run the following, replacing $VAULT_ROOT_TOKEN with your Vault’s Root Token and $VAULT_ADDR with your Vault’s address:
```
curl -X POST --header "X-Vault-Token: $VAULT_ROOT_TOKEN" \
  --data '{"policies": "nms_secrets", "period": "24h"}' \
  $VAULT_ADDR/v1/auth/token/create | jq -r ".auth.client_token" > periodic_token.txt
```

Verify the token works:

curl --header "X-Vault-Token: $(cat periodic_token.txt)" \
  $VAULT_ADDR/v1/auth/token/lookup-self | jq .data

If everything works, stop the nms-core service and configure NGINX Instance Manager to use the token:

sudo systemctl stop nms-core
sudo NMS_VAULT_TOKEN=$(cat periodic_token.txt) nms-core secret vault-token
sudo systemctl restart nms-core

Start using Vault to store secrets

Open the /etc/nms/nms.conf file on the NGINX Instance Manager server.

Update the secrets section under core to specify how to manage secrets.

For example, an internal Vault installation might use:

secrets:
  # change driver to "local" if you want to stop using vault
  driver: vault
  config:
    # local file path for stored secrets when using the local driver
    path: /var/lib/nms/secrets
    # key_file is required for local driver
    key_file: /var/lib/nms/secrets/key
    # vault address for when using the vault driver
    address: http://127.0.0.1:8200/v1
    # isolation is used to store secrets in a specific namespace and prefix to better restrict access rights
    # on the local file system or shared vault server.
    isolation:
      namespace: secret
      prefix: secureString

Save the changes and close the file.
Restart the NGINX Instance Manager services to start using Vault:
```
sudo systemctl restart nms
```

Switch between Vault and local encryption

After setting up Vault, you can switch between local encryption and Vault.

Switch to local encryption

Stop NGINX Instance Manager:
```
sudo systemctl stop nms
```

Migrate secrets to local storage:

sudo nms-core secret migrate-secrets-to-local

Update the core/secrets/driver in /etc/nms/nms.conf to use the local driver:
```
driver: local
```
Restart NGINX Instance Manager:
```
sudo systemctl start nms
```

Switch to Vault

To switch from using local encryption back to Vault:

Stop NGINX Instance Manager:
```
sudo systemctl stop nms
```

Migrate secrets to Vault:

sudo nms-core secret migrate-secrets-to-vault

Update the core/secrets/driver line in /etc/nms/nms.conf to use the Vault driver:
```
driver: vault
```
Restart NGINX Instance Manager:
```
sudo systemctl start nms
```

Troubleshooting

Token has expired

If the Vault service token is revoked or expires, access to stored secrets will fail. To resolve this, generate and supply a new service token using nms-core secret vault-token. See create periodic service tokens for details.

Missing certs after switching

When switching to Vault, NGINX Instance Manager doesn’t migrate existing secrets. Reupload missing certs or switch back to the original storage method to recover access. Restart the service to view the restored secrets.

Last modified January 2, 2025