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

• Install vHSM CLI

• Install vHSM and start a Dev server

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": "[e-mail]",
   "status": "active"
}

1. 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.

1. 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 }}
}

1. Create an additional config agent-template.jsonfor templates:

template {
  source      = "$HOME/vhsm-test/customer.json.tmpl"
  destination = "$HOME/vhsm-test/customer.json"
}

1. 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.

1. Verify rendered output:

cat customer.json

Output is similar to:

{
  "Organization": "Enclaive",
  "ID": "ABXX2398YZPIE7391",
  "Contact": "[e-mail]"
}

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.

1. Check the log file:

ls | grep .log
cat vhsm-agent-<timestamp>.log