Client count FAQ

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.

Consult the clients and entities overview for more information on client definitions.

What is the difference between an entity client, non-entity client, certificate client, and secret sync 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.
• Secret sync clients map to an actively synced secret.

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?

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:

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?

Yes.

The Nomad Vault integration uses either Workload Identity (JWT) or token roles for client count:

- Vault bases Workload Identity client counts on the
  [`user_claim`](/vault/api-docs/auth/jwt#user_claim) field. The
  recommended default is `nomad_job`, which results in 1 client per
  Nomad job.
- Nomad deprecated token roles and will remove the feature in v1.10. Client
  counts for legacy token roles treat each unique policy combination as 1
    non-entity 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.

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?

Are there any known client count issues in the UI/API?

Yes.

What happens to client count when I 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.

Each unique combination of authN mount, namespace, and alias, will be counted
as a distinct client.

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:

• Period₁ runs from January 1st to March 31st
• Period₂ 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?

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.