vHSM Agent quickstart
Learn to start vHSM Agent and to load data to vHSM server
vHSM Agent acts as a client-side daemon that handles authentication and communication with vHSM on behalf of client applications. It simplifies authentication by obtaining and managing client tokens, eliminating the need for applications or users to manually renew or re-authenticate as tokens expire.
Additionally, vHSM Agent supports Consul Template markup, allowing it to render secrets into files. This enables client applications to seamlessly access and load the required data.
By the end of this tutorial, you'll learn how to seamlessly manage secrets using vHSM without modifying your client application’s code. The client application loads data from the customer.json
file, while vHSM Agent's Template feature dynamically injects secrets into the file. This approach ensures secure and automated secret management without requiring direct integration with vHSM.
Prerequisites
1. Create a directory for storing test files and configuration.
mkdir -p $HOME/vhsm-test && cd $HOME/vhsm-test
2. Create a mock dataset data.json
representing a customer record, using an editor of your choice:
{
"organization": "Enclaive",
"customer_id": "ABXX2398YZPIE7391",
"region": "US-West",
"zip_code": "94105",
"type": "premium",
"contact_email": "[email protected]",
"status": "active"
}
Upload the test data to the vHSM KV v2 secrets engine:
vhsm kv put secret/customers/enclaive @data.json
4. Create the agent configuration file agent-config.json
to enable automatic authentication and token management.
pid_file = "./pidfile"
vault {
address = "$VAULT_ADDR"
tls_skip_verify = true
}
auto_auth {
method {
type = "token_file"
config = {
token_file_path = "$HOME/.vault-token"
}
}
sink "file" {
config = {
path = "$HOME/vault-token-via-agent"
}
}
}
Note: For production, consider robust auth methods such as AppRole, Kubernetes Auth, and others.
Start the vHSM Agent:
vhsm agent -config=agent-config.json
Expected log output will confirm:
Token sink created
Auth handler started and authenticated
==> vHSM Agent started! Log data will stream in below:
==> vHSM Agent configuration:
Api Address 1: http://bufconn
Cgo: disabled
Log Level:
Version: Vhsm v1.3.2-0 heads/main-0-g1b8bb7c 2024-10-10T01:15:29+00:00
2025-03-08T17:00:28.700Z [INFO] agent.sink.file: creating file sink
2025-03-08T17:00:28.700Z [INFO] agent.sink.file: file sink configured: path=/tmp/secrets/vault-token mode=-rw-r-----
2025-03-08T17:00:28.701Z [INFO] agent.exec.server: starting exec server
2025-03-08T17:00:28.701Z [INFO] agent.exec.server: no env templates or exec config, exiting
2025-03-08T17:00:28.701Z [INFO] agent.auth.handler: starting auth handler
2025-03-08T17:00:28.701Z [INFO] agent.auth.handler: authenticating
2025-03-08T17:00:28.701Z [INFO] agent.sink.server: starting sink server
2025-03-08T17:00:28.701Z [INFO] agent.template.server: starting template server
6. Stop the running vHSM Agent (Ctrl + C)
7. Use the template rendering feature of vHSM Agent to dynamically fetch and inject secrets into application configuration files and create a template file, customer.json.tmpl
:
{
{{ with secret "secret/data/customers/acme" }}
"Organization": "{{ .Data.data.organization }}",
"ID": "{{ .Data.data.customer_id }}",
"Contact": "{{ .Data.data.contact_email }}"
{{ end }}
}
Create an additional config
agent-template.json
for templates:
template {
source = "$HOME/vhsm-test/customer.json.tmpl"
destination = "$HOME/vhsm-test/customer.json"
}
Restart vHSM Agent with both configs:
vhsm agent -config=agent-config.json -config=agent-template.json
You should see a rendered file at $HOME/vhsm-test/customer.json
.
Verify rendered output:
cat customer.json
Output is similar to:
{
"Organization": "Enclaive",
"ID": "ABXX2398YZPIE7391",
"Contact": "[email protected]"
}
11. Enable logging using the -log-file
flag:
vhsm agent -config=agent-config.json \
-log-file=$HOME/vhsm-test/vhsm-agent.log
vHSM appends a timestamp to the log file.
Check the log file:
ls | grep .log
cat vhsm-agent-<timestamp>.log
Last updated
Was this helpful?