Frequently asked questions (FAQ)
This FAQ section contains frequently asked questions about the client count feature.
- Q: What is a client?
- Q: Where can I learn more about Vault clients?
- Q: What is the difference between a direct entity and a non-entity token?
- Q: Post Vault 1.9, will the clientID be viewable via the audit logs when non-entity tokens are used?
- Q: What does the usage metrics UI look like for Vault 1.9?
- Q: Under what conditions can cause the loss of client data?
- Q: Do child namespaces create duplicate tokens?
Q: What is a client?
Clients are unique applications, services, or users that authenticate to a HashiCorp Vault cluster. For billing and consumption, only unique and active clients during the billing period (monthly in the case of HCP and annual in the case of self-managed Vault) count towards totals. Each client is counted just once within a billing period, regardless of how many times it's been active. When a client authenticates to a cluster, those clients have unlimited access to that cluster for the remainder of the billing period. The client metric is a combination of active identity entities and active non-entity tokens. To learn more, refer to the documentation on What is a Client?.
Q: Where can I learn more about Vault clients?
Refer to the table below for documentation resources.
| Resource | Description |
|---|---|
| What is a Client? | Provides a conceptual overview of Vault client |
| Usage Metrics UI | Provides an overview of the client count dashboard and how to use it |
| Client Count API | Provides information about the client count API endpoints |
Q: What is the difference between a direct entity and a non-entity token?
While the definition of clients appears to be simple on the surface, there are many nuances involved in the computation of clients. As mentioned, clients are unique applications, services, and/or users that authenticate to a Vault cluster. When anything authenticates to Vault, it is associated with a unique identity entity within the Vault Identity system. The name reported to the identity systems by the different types of authentication methods varies, and each entity is created or verified during authorization.
One thing to note is that Vault clients are a combination of active identities as well as non-entity tokens. Identity entities are unique users, and when identities authenticate to Vault, corresponding tokens are generated. However, there are some situations in which tokens are generated without corresponding identities (e.g., when using the token auth method to create a token for someone else whose identity is unknown). As such, these non-entity tokens also represent users, and are counted towards the overall client aggregates. Here are some situations in which non-entity tokens get created within Vault.
- Tokens within Vault are the core method for authentication. You can use Tokens to authenticate directly, or use the auth methods to dynamically generate tokens based on external identities.
- There are scenarios where tokens are created outside of the identity system without an associated entity. For this reason, unique identity entities alone cannot always add up to the total unique authentications made to Vault over a stipulated time period.
- In a scenario where tokens are created outside of the identity system, these tokens are considered clients. Note that it should be rare for production usage to have any tokens created outside any identity systems.
- There are a few ways of creating tokens without entities: Token Roles, Token Create APIs, Wrapping Tokens, and Control Groups. For more information, refer to the What is a Client? documentation.
Client counts are not computed solely using a combination of unique identity entities within Vault but also computed using a combination of unique identity entities and non-entity tokens.
Q: Post Vault 1.9, will the clientID be viewable via the audit logs when non-entity tokens are used?
Yes, beginning with Vault 1.9, audit logs have a new field called clientID, which is the entity ID or the computed client ID of the corresponding non-entity token.
Q: What does the usage metrics UI look like for Vault 1.9?
In Vault 1.9, the client count dashboard provides two separate tabs: the Current month and the Monthly history. In addition to usage totals (active client count and its breakdown into entities and non-entity tokens), each tab will include a list of the top ten namespaces by client count and the ability to export client count data for all namespaces. Here is a screenshot for your reference:
Q: Under what conditions can cause the loss of client data?
The activity log (component within Vault responsible for computing clients) is tracked on standby nodes and periodically transmitted to the active node over gRPC. The transmission is triggered when the information on the standby node reaches a maximum size of 8KB or 10 minutes has elapsed.
Should a Vault node go down any time during the 10-minute window (e.g., at the 8-minute mark of that 10-minute window), any client activity from those 8-minute period, as well as the time period while the Vault node is down, will be lost. This behavior is expected as there are no activities taking place if the node is down. Lost client activity is acceptable partly because it works in the customer’s favor - if a new client has activity during the lost window, the customer would not be billed for that client.
Q: Do child namespaces create duplicate tokens?
A token created in a parent namespace can be used in a child namespace without adding additional clients.
However, creating a new token across a parent/child namespace boundary could result in a token without an entity and a new client. This is because identity is scoped to a single namespace and tokens cannot be associated with identities that live outside their namespace.