Connect to Vault

By default an Agent keeps its recordings on its own disk. Connect it to Vault (Vault documentation) when you want those recordings stored centrally, on storage you control, and available to other applications. The Agent uploads each recording as soon as it is written; Vault decides where it is stored and who is told about it.

This page covers the Agent side of the connection. The Vault side, an account and a storage provider, is explained in the Vault docs.

Before you start

You need a running Vault with:

a provider (Vault documentation): the bucket or storage system the recordings end up in, and
an account (Vault documentation) linked to that provider. The account gives you the access key and secret key the Agent uploads with.

You also need the URL of the Vault API, for example https://vault.example.com/api. The Agent must be able to reach it.

Configure the Agent

Open the Agent’s web interface and go to Settings → Persistence.

In the Persistence block, select Vault.
Fill in the fields:
- Vault API URL: the address of the Vault API.
- Provider: the provider to send recordings to. Leave it empty to use the provider of the account.
- Directory: the subdirectory the recordings are stored in. Use one directory per Agent or per site. If you also use Hub, this must match the Hub username.
- Access key and Secret key: the keys of the Vault account.
Select Verify Connection. The Agent checks the keys against Vault and, when a provider or directory is set, uploads a short test recording to it.
Save the settings.

New recordings are uploaded from then on. By default the Agent removes each recording from its own disk once it is uploaded successfully, so its disk only acts as a buffer. Turn off Enable delete on upload if you want to keep a local copy as well.

Optional settings

Custom upload headers: a JSON object such as {"site_id":"site-1","line_id":"line-2"}. The Agent sends these as headers with every upload, and Vault adds them to the metadata of its integration messages (Vault documentation), so your consumers know where a recording came from.
Max retries and Timeout: how persistent the Agent is when an upload fails.
Secondary Persistence: a second Vault the Agent uploads to when the primary one is unavailable or times out. Useful for failover.

Configure with environment variables

For automated deployments, set the same values as environment variables instead of using the web interface:

Variable	Setting
`AGENT_CLOUD`	`kstorage` selects Vault.
`AGENT_KERBEROSVAULT_URI`	Vault API URL
`AGENT_KERBEROSVAULT_ACCESS_KEY`	Access key
`AGENT_KERBEROSVAULT_SECRET_KEY`	Secret key
`AGENT_KERBEROSVAULT_PROVIDER`	Provider (optional)
`AGENT_KERBEROSVAULT_DIRECTORY`	Directory
`AGENT_KERBEROSVAULT_CUSTOM_HEADERS`	Custom upload headers (JSON on one line)
`AGENT_KERBEROSVAULT_MAX_RETRIES`, `AGENT_KERBEROSVAULT_TIMEOUT`	Retry behaviour
`AGENT_KERBEROSVAULT_SECONDARY_*`	The same settings for the secondary Vault, except max retries and timeout
`AGENT_REMOVE_AFTER_UPLOAD`	Remove recordings after a successful upload (`true` by default)

docker run -p 80:80 --name mycamera \
  -e AGENT_CLOUD=kstorage \
  -e AGENT_KERBEROSVAULT_URI=https://vault.example.com/api \
  -e AGENT_KERBEROSVAULT_ACCESS_KEY=xxx \
  -e AGENT_KERBEROSVAULT_SECRET_KEY=xxx \
  -e AGENT_KERBEROSVAULT_DIRECTORY=agent1 \
  -d --restart=always kerberos/agent:latest

The Agent repository lists every variable. If you manage many Agents on Kubernetes, Factory (Factory documentation) sets these values for you.

Using Vault together with Hub

Hub (Hub documentation) can show the recordings your Agent stores in Vault. Three things connect the three products:

The Agent’s Directory must equal the Hub username of the account the recordings belong to. Otherwise Hub can’t match the recordings to that account. Vault only uses the Agent’s directory when the Vault account’s directory is *. See Hub username (Vault documentation).
Vault needs the Hub integration (Vault documentation), so every new recording is sent on to the Hub pipeline (Hub documentation).
Hub needs the Vault URL and account keys, so it can play the recordings. See Connect Vault (Hub documentation).

The Agent also connects to Hub directly, for status, live view and camera control. That is a separate setting, described in Connect to Hub.

Troubleshooting

Verify Connection fails. Check that the URL ends with the API path (usually /api) and that the Agent can reach it from its network. A wrong access or secret key is rejected by Vault.
Uploads succeed but you can’t find the recordings. Look in the provider set on the Agent. If that provider is empty, doesn’t exist or is disabled in Vault, Vault uses the provider of the account instead. Recordings are stored under the Agent’s directory, unless the account sets a fixed directory (anything other than *), which then takes precedence.
Recordings reach Vault but not Hub. Check the directory and the Hub integration as described in Using Vault together with Hub.

Connect to Hub License