Vault
Client count FAQ
| Definitions |
|---|
| What is a client? |
| What is the difference between an entity client, non-entity client, and certificate client? |
| Vault auditor tool |
|---|
| What is the Vault auditor? |
| Are there any known client count issues in the auditor tool? |
Definitions
What is a client?
Any unique application, service, or user that authenticates to a HashiCorp Vault cluster. The client count metric is a combination of entity clients and non-entity clients.
For billing and consumption, only clients that are active during the billing period count toward total usage. Clients are only counted once within a billing period, regardless of how many times that client is active and when that client authenticates to a cluster, it has unlimited access to that cluster for the remainder of the billing period.
| Installation type | Billing period |
|---|---|
| HCP | monthly |
| Self-managed | annually |
Consult the clients and entities overview for more information on client definitions.
What is the difference between an entity client, non-entity client, and certificate client?
- Entity clients map to an active identity.
- Non-entity clients map to an active non-entity token.
- Certificate clients map to an active ACME PKI certificate.
Consult the clients and entities overview for more information about how Vault determines entity assignments.
Computing client count
Can I compute clients for Vault versions before v1.6?
Warning
You can still download the Vault auditor, but we no longer actively support the tool. We strongly encourage upgrading to an actively supported version of Vault.Yes.
Use the Vault auditor tool to compute and display client count data for Vault v1.3 – v1.5 using the client compute logic available in Vault 1.7. Auditor use with Vault versions older than 1.3 is untested.
Can I compute KMIP clients for Vault?
No.
Currently, KMIP clients are not available via the usage metrics UI or client count API.
Can I get monthly changes for Vault versions older than v1.10?
Yes, for Vault v1.8 – v1.10.
To calculate client counts for a given month, you must perform a series of billing period updates in the UI and manual calculations:
| Month | Billing period in UI | Result | Computation |
|---|---|---|---|
| January | January | JAN | None |
| February | January February | JAN_FEB | FEB = JAN_FEB - JAN |
| March | January February | JAN_MAR | MAR = JAN_MAR - JAN_FEB |
| April | January February | JAN_APR | APR = JAN_APR - JAN_MAR |
| May | January February | JAN_MAY | MAY = JAN_MAY - JAN_APR |
| June | January February | JAN_JUN | JUN = JAN_JUN - JAN_MAY |
| July | January February | JAN_JUL | JUL = JAN_JUL - JAN_JUN |
| August | January February | JAN_AUG | AUG = JAN_AUG - JAN_JUL |
| September | January September | JAN_SEP | SEP = JAN_SEP - JAN_AUG |
| October | January February | JAN_OCT | OCT = JAN_OCT - JAN_SEP |
| November | January February | JAN_NOV | NOV = JAN_NOV - JAN_OCT |
| December | January February | JAN_DEV | DEC = JAN_DEC - JAN_NOV |
Do child namespaces create duplication in the client count?
Maybe.
Tokens created in a parent namespace are recognized as the same client when used in a child namespace. But, tokens created across a parent/child namespace boundary may be counted as multiple clients. See the clients and entities overview for more details.
Does the Nomad-Vault integration affect client counts?
Maybe.
Nomad Vault integration uses token roles where a single token role creates tokens for many Nomad jobs. Unless you have configured explicit identity aliases for your Nomad tokens, Vault will record every running instance of a Nomad job as a unique client.
Are batch tokens counted differently than service tokens?
No.
Batch token clients are counted like service token clients. The batch token is mapped to either to the associated active entity or an artificial entity that Vault creates by combining the assigned namespace and policy. See the clients and entities overview for more details.
Do custom user filters affect client counts?
Yes.
Custom user filters can change the way that entity aliases are mapped, which can affect the client count computation.
Consult the clients and entities overview for more information about how Vault determines entity assignments.
Does mount migration affect client counts?
Maybe.
If you are using Vault 1.10+:
- Migrating mounts across namespace will create duplication in the client count.
- Migrating mounts within a namespace will not affect client count.
If you are using an older version of Vault, migrating mounts will always create duplication in the client count.
Upgrading and migration
How has client count changed across different Vault versions?
Client counts have been available via the usage metrics UI since Vault 1.6. We have made continual improvements to the Vault client count computation logic provided in the Vault UI and API.
| Version | Interface | Accuracy improvement |
|---|---|---|
| 1.6 | N/A | Introduced client counts as a metric |
| 1.8 | All | Omit wrapping tokens and control groups from client counts |
| 1.9 | All | Improved non-entity token tracking and local auth mount computation logic |
| 1.10 | API | Supported data export for unique clients contributing to the client count aggregate for a selected billing period |
| 1.10 | UI | Displayed clients per auth mount within a namespace |
| 1.11 | API | Supported unique client export for selected billing periods |
| 1.11 | UI | Displayed month over month calculations for client count |
The latest GA version of the Vault binary always contains the most updated version of the client count computation logic.
How has the usage metric UI changed across different Vault versions?
| Version | UI improvement |
|---|---|
| 1.9 | The dashboard added the ability to export client count data for all namespaces and tabs for Current month and Monthly history that list the top ten namespaces by client count |
| 1.10 | Added attribution of clients per authN mount to the Current month and Monthly history tabs |
| 1.11 | Added the ability to view changes in client counts month over month, the running client total, and new monthly clients. |
Are there any known client count issues in the UI/API?
Yes.
| Version | Client count issue |
|---|---|
| 1.9 | Billing period cannot be computed for start and end dates that fall in the middle of a month |
| 1.10 | KMIP clients are not provided. |
| 1.10 | Data on the Current month tab does not take the billing period into account. |
What happens to client count when I upgrade?
Vault will only reflect the number of active unique clients since the upgrade.
We recommend upgrading before your next billing period begins so that the usage metrics UI correctly reflects all clients for the current billing period.
Warning
If your billing period falls on either side of a Vault upgrade, the compute logic may be different across the billing period, which will change client count results and create noisy data.Vault 1.9 introduced changes to non-entity token and local auth mount logic for client counting that affects anyone upgrading from v1.8 to a newer version:
- Any non-entity tokens created before the upgrade will receive an artificial client ID the next time the token authenticates to Vault. As result, the token will be counted as a new client, but will not be recounted on subsequent connections.
- Any local auth mounts created before the upgrade will continue to count as a unique client, but new mounts created after the upgrade will receive an artificial client ID to avoid duplication in the client count.
Usage
Can I view the list of unique client IDs that contributed to my client count aggregate?
Yes, if you are using Vault 1.11 or later.
As of Vault 1.11, you can export the list of unique clients that contributed to your client count for a given billing period with the activity export API endpoint.
Is clientID viewable in the audit logs for non-entity tokens?
Yes, for Vault v1.9+.
As of Vault v1.9, audit logs include a field called clientID that records the
active or computed entity ID of the associated token.
Can I skip client computation for a period of time during the billing period?
Yes, but the data may be inaccurate.
Breaking up the data will likely result in client duplication. For example, assume your billing period runs from January 1st to December 31st, and you break the computation into two periods to exclude the month of April:
- Period1 runs from January 1st to March 31st
- Period2 runs from June 1st to December 31st
Vault treats the two requests independently so January 1st and June 1st are both used as a fresh start to re-count unique clients. Any client that was active during both periods will appear in both result sets, even though Vault will only counted that client once for the actual billing period.
Are there conditions that will cause me to lose client data?
Yes.
The Vault activity log handles client computation. The standby nodes track and accumulate activity log data then transmit updates to the active node over gRPC whenever the log grows by 8KB or 10 minutes has elapsed, whichever happens first.
If a node goes down during the accumulation phase you will lose the untransmitted data in addition to any client count data that would have been collected during the outage.
What happens if a portion of the data is missing for my billing period?
Vault only returns the most recent contiguous set of data.
For example, assume your billing period runs from January 1st to December 31st but you disabled tracking for the month of April. Vault will look for the largest, contiguous window of time where data is available, May through December, and compute results for that period of time. May 2021 through December 2021.
Can I disable client counting?
Yes.
You can use the Vault API to update the client count configuration and disable the tracking parameter. If you disable client counting in the middle of a month, Vault will discard any data currently recorded for the month. Data for previous months is preserved.
Can I configure Vault to log the client count data?
Yes.
You can use the Vault API to update the client count configuration and specify your preferred retention period.
Vault auditor tool
What is the Vault auditor?
Warning
You can still download the Vault auditor, but we no longer actively support the tool. We strongly encourage upgrading to an actively supported version of Vault.The Vault auditor tool lets customers running Vault v1.3 – v1.5 compute and display client count data using the client compute logic available in Vault 1.7. Auditor use with Vault versions older than 1.3 is untested.
The auditor may report that your audit logs are unreadable of the logs are too large or you are running an older version than Vault 1.6.
Are there any known client count issues in the auditor tool?
Yes.
The Vault auditor only includes the computation logic improvements from Vault v1.6 – v1.7. Running the auditor on Vault v1.8+ will result in discrepancies when comparing the result to data available through the Vault UI or API.