luxolus
/
open-vault
2
0
Fork 0
Code Issues 1 Pull Requests Releases Activity

Manual backport of Client count doc updates (#21685)

This commit is contained in:
Sarah Chavis 2023-07-07 12:40:36 -07:00 committed by GitHub
parent 9d1592cc93
commit c569513e54
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
12 changed files with 752 additions and 587 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

201
website/content/docs/concepts/client-count/counting.mdx Normal file
View File

@ -0,0 +1,201 @@
---
layout: docs
page_title: Client count calculation
description: |-
Technical overview of client count calculations in Vault
---
# Client count calculation
Vault provides usage telemetry for the number of clients based on the number of
unique entity assignments within a Vault cluster over a given billing period:
- Standard entity assignments based on authentication method for active entities.
- Constructed entity assignments for active non-entity tokens, including batch
tokens created by performance standby nodes.
- Certificate entity assignments for ACME connections.
```markdown
CLIENT_COUNT_PER_CLUSTER = UNIQUE_STANDARD_ENTITIES +
UNIQUE_CONSTRUCTED_ENTITIES +
UNIQUE CERTIFICATE_ENTITIES
```
Vault does not aggregate or de-duplicate clients across clusters, but all logs
and precomputed reports are included in DR replication.
<Note heading="Certificate entities currently reported as non-entity clients">
Vault currently rolls certificate entities into the non-entity client count
in the UI and API query requests. For more detailed information on certificate
entities, use the
[internal counter endpoint](/vault/api-docs/system/internal-counters) to query
monthly data for the PKI mount path or export historic data and look for
`client_type=pki-acme`.
</Note>
## How Vault tracks clients
Each time a client authenticates, Vault checks whether the corresponding entity
ID has already been recorded in the client log as active for the current month:
- **If no record exists**, Vault adds an entry for the entity ID.
- If a record exists but the entity was last active **prior to the current month**,
Vault adds a new entry to the client record for the entity ID.
- If a record exists and the entity was last active **within the current month**,
Vault does not add a new entry to the client record for the entity ID.
For example:
- Two non-entity tokens under the same namespace, with the same alias name and
policy assignment receive the same entity assignment and are only counted
**once**.
- Two authentication requests from a single ACME client for the same certificate
identifiers from different mounts receive the same entity assignments and
are counted **once**.
- An application authenticating with AppRole receive the same entity assignment
every time and only counted **once**.
At the **end of each month**, Vault pre-computes reports for each cluster on the
number of active entities, per namespace, for each time period within the
configured retention period. By de-duplicating records from the current month
against records for the previous month, Vault ensures entities that remain
active within every calendar month are only counted once for the year.
The deduplication process has two additional consequences:
1. Detailed reporting lags by 1 month at the start of the billing period.
1. Billing period reports that include the current month must use an
approximation for the number of new clients in the current month.
## How Vault approximates current-month client count
Vault approximates client count for the current month using a
[hyperloglog algorithm](https://en.wikipedia.org/wiki/HyperLogLog) that looks
at the difference between the cardinalities of:
- the number of clients across the **entire** billing period, and
- the number of clients across the billing period **excluding** clients from the current month.
The approximation algorithm uses the
[axiomhq](https://github.com/axiomhq/hyperloglog) library with fourteen
registers and sparse representations (when applicable). The multiset for the
calculation is the total number of clients within a billing period, and the
accuracy estimate for the approximation decreases as the difference between the
number of clients in the current month and the number of clients in the billing
period increases.
### Testing verification for client count approximations
Given `CM` as the number of clients for the current month and `BP` as the number
of clients in the billing period, we found that the approximation becomes
increasingly imprecise as:
- the difference between `BC` and `CM` increases
- the value of `CM` approaches zero.
- the number of months in the billing period increase.
The maximum observed error rate
(`ER = (FOUND_NEW_CLIENTS / EXPECTED_NEW_CLIENTS)`) was 30% for 10,000 clients
or less, with an error rate of 5 &ndash; 10% in the average case.
For the purposes of predictive analysis, the following tables list a random
sample the values we found during testing for `CM`, `BP`, and `ER`.
<Tabs>
<Tab heading="Single-month tests">
| Current month (`CM`) | Billing period (`BP`) | Error rate (`ER`) |
| :-----------------: | :------------------: | :---------------: |
| 7 | 10 | 0% |
| 20 | 600 | 0% |
| 20 | 1000 | 0% |
| 20 | 6000 | 10% |
| 20 | 10000 | 10% |
| 200 | 600 | 0% |
| 200 | 10000 | 7% |
| 400 | 6000 | 5% |
| 2000 | 10000 | 4% |
</Tab>
<Tab heading="Multi-month / multi-segment tests">
| Current month (`CM`) | Billing period (`BP`) | Error rate (`ER`) |
| :-----------------: | :------------------: | :---------------: |
| 20 | 15 | 0% |
| 20 | 100 | 0% |
| 20 | 1000 | 0% |
| 20 | 10000 | 30% |
| 200 | 10000 | 6% |
| 2000 | 10000 | 2% |
</Tab>
</Tabs>
## Resource costs for client computation
In addition to the storage used for storing the pre-computed reports, each
active entity in the client log consumes a few bytes of storage. As a safety
measure against runaway storage growth, Vault limits the number of entity
records to 656,000 per month, but typical storage costs are much less.
On average, 1000 monthly active entities requires 1.5 MiB of storage capacity
over the default 24-month retention period.
@include "content-footer-title.mdx"
<Tabs>
<Tab heading="Related concepts">
<ul>
<li>
<a href="/vault/docs/concepts/client-count/">Clients and entities</a>
</li>
<li>
<a href="/vault/docs/concepts/client-count/faq">Client count FAQ</a>
</li>
</ul>
</Tab>
<Tab heading="Related API docs">
<ul>
<li>
<a href="/vault/api-docs/system/internal-counters#client-count">Client Count API</a>
</li>
<li>
<a href="/vault/api-docs/system/internal-counters">Internal counters API</a>
</li>
</ul>
</Tab>
<Tab heading="Related tutorials">
<ul>
<li>
<a href="/vault/tutorials/monitoring/usage-metrics">
Vault Usage Metrics in Vault UI
</a>
</li>
<li>
<a href="/vault/tutorials/monitoring/usage-metrics">KMIP Client metrics</a>
</li>
</ul>
</Tab>
<Tab heading="Other resources">
<ul>
<li>
<a href="https://github.com/axiomhq/hyperloglog#readme">Accuracy estimates for the axiomhq hyperloglog library</a>
</li>
<li>
Blog post: <a href="https://www.hashicorp.com/blog/onboarding-applications-to-vault-using-terraform-a-practical-guide">
Onboarding Applications to Vault Using Terraform: A Practical Guide
</a>
</li>
</ul>
</Tab>
</Tabs>

315
website/content/docs/concepts/client-count/faq.mdx
View File

@ -1,291 +1,66 @@
---
layout: docs
page_title: FAQ
description: An FAQ page to answer the most commonly asked questions about client count.
description: |-
Answers to the most commonly asked questions about client count in Vault.
---
# Client Count FAQ
~> **Note 1**: Starting in Vault 1.9, Vault changed the non-entity token computation logic to deduplicate non-entity tokens. For non-entity tokens (where there is no entity to which tokens map) Vault uses the contents of the token to generate a unique client identifier, based on the namespace ID and policies. The clientID will prevent the same token from being duplicated in the overall client count. Non-entity token tracking is done on access instead of creation. Since the change was made, Vault 1.10 (via the UI, API, documentation, etc.) refers to these non-entity tokens as non-entity clients, and unique entities as entity clients. To summarize, starting in Vault 1.9, the terms used are: total clients = entity clients + non entity clients. Previously, the terms used were: total clients = unique entities + non-entity tokens.
| Definitions |
| ----------------------- |
| [What is a client?](#what-is-a-client) |
| [What is the difference between an entity client, non-entity client, and certificate client?](#eclient-vs-neclient) |
~> **Note 2**: In March 2022, we deprecated the Vault auditor tool. While you can still use the tool, there are no plans to release new versions of the tool.
| Computing client count |
| ----------------------- |
| [Can I compute clients for Vault versions before v1.6?](#before-1-6) |
| [Can I compute KMIP clients for Vault?](#kmip) |
| [Can I compute changes in clients month to month from the UI for Vault v1.8 &nbsp; v1.10?](#month-to-month) |
| [Do child namespaces create duplication in the client count?](#namespace-dupes) |
| [Does the Nomad-Vault integration affect client counts?](#nomad) |
| [Are batch tokens counted differently than service tokens?](#batch-tokens) |
| [Do custom user filters affect client counts?](#custom-filters) |
| [Does mount migration affect client counts?](#mount-migration) |
This FAQ section contains frequently asked questions about the client count feature.
| Upgrading and migration |
| ----------------------- |
| [How has client count changed across different Vault versions?](#logic-improvements) |
| [How has the usage metric UI changed across different Vault versions?](#ui-improvements) |
| [Are there any known client count issues in the UI/API?](#uiapi-ki) |
| [What happens to client count when I upgrade?](#what-happens-at-upgrade) |
- [Q: What is a client?](#q-what-is-a-client)
- [Q: Where can I learn more about Vault clients?](#q-where-can-i-learn-more-about-vault-clients)
- [Q: What is the difference between a direct entity (entity client) and a non-entity token (non-entity client)?](#q-what-is-the-difference-between-a-direct-entity-entity-client-and-a-non-entity-token-non-entity-client)
- [Q: Which Vault version reflects the most accurate client counts?](#q-which-vault-version-reflects-the-most-accurate-client-counts)
- [Q: For customers using versions of Vault older than Vault 1.6, what’s the best way to compute clients](#q-for-customers-using-versions-of-vault-older-than-1-6-what-s-the-best-way-to-compute-clients)
- [Q: For customers using newer versions than Vault 1.6, what's the best way to compute clients?](#q-for-customers-using-newer-versions-than-vault-1-6-what-s-the-best-way-to-compute-clients)
- [Q: Why do we have two different tools (auditor tool and UI/API) to compute clients? Do we plan to deprecate one in the future?](#q-why-do-we-have-two-different-tools-auditor-tool-and-ui-api-to-compute-clients-do-we-plan-to-deprecate-one-in-the-future)
- [Q: How can I compute KMIP clients for Vault?](#q-how-can-i-compute-kmip-clients-for-vault)
- [Q: Why do the Vault auditor tool and the usage metrics UI show me different results for the total number of clients?](#q-why-do-the-vault-auditor-tool-and-the-usage-metrics-ui-show-me-different-results-for-the-total-number-of-clients)
- [Q: When I upgrade to a version of Vault that's greater than Vault 1.6, will the clients be available for the entire history of the billing period, or only available after the upgrade occurred during the billing period?](#q-when-i-upgrade-to-a-version-of-vault-that-s-greater-vault-1-6-will-the-clients-be-available-for-the-entire-history-of-the-billing-period-or-only-available-after-the-upgrade-occurred-during-the-billing-period)
- [Q: If I upgrade from Vault 1.8 to 1.9+, how will the changes to non-entity token logic and local auth mount made in Vault 1.9 affect the clients created prior to the upgrade?](#q-if-i-upgrade-from-vault-1-8-to-1-9-+-how-will-the-changes-to-non-entity-token-logic-and-local-auth-mount-made-in-vault-1-9-affect-the-clients-created-prior-to-the-upgrade)
- [Q: Post Vault 1.9, will the clientID be viewable via the audit logs when non-entity tokens are used?](#q-post-vault-1-9-will-the-clientid-be-viewable-via-the-audit-logs-when-non-entity-tokens-are-used)
- [Q: Is it possible to view a list of unique client IDs that contributed to the client count aggregate?](#q-is-it-possible-to-view-a-list-of-unique-client-ids-that-contributed-to-the-client-count-aggregate)
- [Q: What happens if audit logs are unreadable for use by the Vault auditor tool?](#q-what-happens-if-audit-logs-are-unreadable-for-use-by-the-vault-auditor-tool)
- [Q: What does the usage metrics UI look like for Vault 1.9?](#q-what-does-the-usage-metrics-ui-look-like-for-vault-1-9)
- [Q: What does the usage metrics look like for Vault 1.10?](#q-what-does-the-usage-metrics-look-like-for-vault-1-10)
- [Q: What does the usage metrics UI look like for Vault 1.11?](#q-what-does-the-usage-metrics-ui-look-like-for-vault-1-11)
- [Q: In older Vault versions including Vault 1.10, how do I compute changes to clients month to month from the UI?](#q-in-older-vault-versions-including-vault-1-10-how-do-i-compute-changes-to-clients-month-to-month-from-the-ui)
- [Q: What if I selected an inaccurate billing period via the UI/API?](#q-what-if-i-selected-an-inaccurate-billing-period-via-the-ui-api)
- [Q: What if I want to skip computation of clients for a period of time during the billing period?](#q-what-if-i-want-to-skip-computation-of-clients-for-a-period-of-time-during-the-billing-period)
- [Q: What are the known client count issues in the auditor tool as well as in the UI/API?](#q-what-are-the-known-client-count-issues-in-the-auditor-tool-as-well-as-in-the-ui-api)
- [Q: What conditions can cause the loss of client data?](#q-what-conditions-can-cause-the-loss-of-client-data)
- [Q: How can I disable the counting of client activity?](#q-how-can-i-disable-the-counting-of-client-activity)
- [Q: If I request data for January 2021 - December 2021, but April’s data does not exist, what will be included in the total client count result?](#q-if-i-request-data-for-january-2021-december-2021-but-april-s-data-does-not-exist-what-will-be-included-in-the-total-client-count-result)
- [Q: How can I configure the activity for log retention?](#q-how-can-i-configure-the-activity-for-log-retention)
- [Q: Do child namespaces create duplicate tokens?](#q-do-child-namespaces-create-duplicate-tokens)
- [Q: How does the Nomad Vault integration affect client counts?](#q-how-does-the-nomad-vault-integration-affect-client-counts)
- [Q: Starting in Vault 1.7, Vault does not allow creating two aliases from the same auth mount under a single entity. What changed and how does this impact client counting?](#q-starting-in-vault-1-7-vault-does-not-allow-creating-two-aliases-from-the-same-auth-mount-under-a-single-entity-what-changed-and-how-does-this-impact-client-counting)
- [Q: How does mount migration impact the client count metric?](#q-how-does-mount-migration-impact-the-client-count-metric)
- [Q: Vault 1.9 added support for providing custom user filters through the userfilter parameter. How does this affect client counts?](#q-vault-1-9-added-support-for-providing-custom-user-filters-through-the-userfilter-parameter-how-does-this-affect-client-counts)
- [Q: Are batch tokens counted differently than service tokens?](#q-are-batch-tokens-counted-differently-than-service-tokens)
| Usage |
| ----------------------- |
| [Can I view the list of unique client IDs that contributed to my client count aggregate?](#view-data) |
| [Is clientID viewable in the audit logs for non-entity tokens?](#clientid-in-logs) |
| [Can I skip client computation for a period of time during the billing period?](#skip-computation) |
| [Are there conditions that will cause me to lose client data?](#lost-data) |
| [What happens if a portion of the data is missing for my billing period?](#missing-data) |
| [Can I disable client counting?](#disable-client-count) |
| [Can I configure Vault to log the client count data?](#log-client-count) |
### Q: What is a client?
| Vault auditor tool |
| ----------------------- |
| [What is the Vault auditor?](##vault-auditor) |
| [Are there any known client count issues in the auditor tool?](#auditor-ki) |
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?](/vault/docs/concepts/client-count#what-is-a-client).
## Definitions ((#definitions))
~> **Note**: For KMIP, a different metric is used to compute clients, as described in the **Vault Usage Metrics** documentation under the [KMIP Client metrics](/vault/tutorials/monitoring/usage-metrics) section.
@include 'faq/client-count/definitions.mdx'
### Q: Where can I learn more about Vault clients?
## Computing client count ((#computing-clients))
Refer to the table below for documentation resources.
@include 'faq/client-count/computing-clients.mdx'
| Resource | Description |
| -------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| [What is a Client?](/vault/docs/concepts/client-count/#what-is-a-client) | Provides a conceptual overview of Vault client |
| [Usage Metrics UI](/vault/tutorials/monitoring/usage-metrics) | Provides an overview of the client count dashboard and how to use it |
| [Client Count API](/vault/api-docs/system/internal-counters#client-count) | Provides information about the client count API endpoints |
| [Vault Auditor Tool](/vault/tutorials/monitoring/usage-metrics#vault-auditor-tool) | Provides a walkthrough on how to use the vault-auditor tool to extract metrics from the server audit device logs |
## Upgrading and migration ((#upgrading))
### Q: What is the difference between a direct entity (entity client) and a non-entity token (non-entity client)?
@include 'faq/client-count/upgrading.mdx'
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](/vault/docs/secrets/identity). The name reported to the identity systems by the different types of authentication methods varies, and each entity is created or verified during authorization.
## Usage ((#usage))
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.
@include 'faq/client-count/usage.mdx'
- Tokens within Vault are the core method for authentication. You can use Tokens to authenticate directly, or use the [auth methods](/vault/docs/concepts/auth) 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?](/vault/docs/concepts/client-count/#what-is-a-client) documentation.
## Vault auditor tool ((#auditor))
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: Which Vault version reflects the most accurate client counts?
Although client counts have been available via the usage metrics UI since Vault 1.6 and the Vault auditor tool was available around the same time, we have since made improvements to the Vault client count computation logic in newer versions of Vault. These changes are reflected only in the usage metrics UI (and the corresponding internal API leveraged by the UI) and not in the auditor tool. The initial version and improvements made after that with their corresponding versions are:
**API/UI**:
- Vault 1.6: Introduction of client counts in the usage metrics UI
- Vault 1.8:
- Eliminated wrapped tokens and control groups from client count, thereby reducing the non-entity token count. Previously, the creation and usage of control groups and wrapping tokens incremented the client count via non-entity tokens, each time a wrapped token and a control group were created.
- Changed the logic of counting of active identity entities on usage instead of at create time, resulting in more accurate client counts
- Vault 1.9:
- Changed the non-entity token computation logic to deduplicate non-entity tokens, reducing the overall client count. Moving forward, non-entity tokens, where there is no entity to map tokens, Vault will use the contents of the token to generate a unique client identifier based on the namespace ID and associated policies. The clientID will prevent duplicating the same token in the overall client count when the token is used again during the billing period.
- Changed the tracking of non-entity tokens to complete on access instead of creation.
- Changed the computation logic to not include root tokens in the client count aggregate.
- Changed the local auth mount computation logic such that local auth mounts count towards clients but not as non-entity tokens. Prior to Vault 1.9, local auth mounts counted towards non-entity tokens. Refer to the [What is a Client?](/vault/docs/concepts/client-count) documentation to learn more.
- Added ability to display clients per namespace (top 10, descending order) in the UI and export data for all namespaces. Prior to Vault 1.9, you could not view view the split of clients per namespace on the UI, nor could you export this data via the UI.
- Added ability to display clients earlier than a month (within ten minutes of enabling the feature) in the UI. Prior to Vault 1.9, after enabling the counting of clients, you had to wait for a month to view the client aggregates in the UI.
- Changed functionality to disallow creating two aliases from the same auth mount under a single entity. For more information, refer to the question [Starting in Vault 1.9, Vault does not allow creating two aliases from the same auth mount under a single entity. What changed and how does this impact client counting?](#q-starting-in-vault-1-9-vault-does-not-allow-creating-two-aliases-from-the-same-auth-mount-under-a-single-entity-what-changed-and-how-does-this-impact-client-counting)
- Vault 1.10:
- Display of clients per auth mount within a namespace in the UI.
- Display of clients month to month for a selected billing period via the API.
- Vault 1.11:
- (Tech preview) New functionality to export the unique clients that contribute to the client count aggregate for the selected billing period - available via a new [activity export API endpoint](/vault/api-docs/system/internal-counters#activity-export).
- Display of clients month over month in the UI.
**Auditor tool**:
- This tool is independent of the Vault binary and the version run by the customer. The tool can be used for versions 1.3-1.5 (tested) and prior versions as early as Vault 1.0. The auditor tool was introduced in Vault 1.6.
- In Vault 1.7, we introduced KMIP clients to this auditor tool
- This tool does not contain any of the updates made to the client count computation logic that the API/UI have had since Vault 1.8
- The tool is deprecated as of March 2022. While you can stil use the auditor tool, there are no plans to release newer versions.
The latest GA version of the Vault binary contains the most updated version of the client count computation logic. However, it’s important to note that even if one upgrades to the latest version and the billing period falls on either side of the upgrade time, the compute logic may be different across the billing period. For more details, refer to the question [If I migrate from Vault 1.8 to 1.9, how will the changes to non-entity token logic and local auth mount made in Vault 1.9 affect the clients created prior to the migration?](#q-if-i-migrate-from-vault-1-8-to-1-9-how-will-the-changes-to-non-entity-token-logic-and-local-auth-mount-made-in-vault-1-9-affect-the-clients-created-prior-to-the-migration).
### Q: For customers using versions of Vault older than 1.6, what’s the best way to compute clients?
The Vault [auditor tool](/vault/tutorials/monitoring/usage-metrics#vault-auditor-tool) was built to compute clients for Vault versions older than Vault 1.6. It has been tested for versions 1.3 to 1.5 but should work for earlier versions, such as Vault 1.0, although not officially tested. To use the Vault [auditor tool](/vault/tutorials/monitoring/usage-metrics#vault-auditor-tool), customers should have audit logs for the billing period for computed client counts. You can also set a specific date range in the [auditor tool](/vault/tutorials/monitoring/usage-metrics#vault-auditor-tool).
The auditor tool is separate from the Vault binary. It does not include the latest updates for the usage metrics UI/API (e.g., it does not contain changes made to the deduplication of non-entity tokens logic). Currently, there are no plans to augment the capabilities of the [auditor tool](/vault/tutorials/monitoring/usage-metrics#vault-auditor-tool).
### Q: For customers using newer versions than Vault 1.6, what’s the best way to compute clients?
The usage metrics UI that leverages the internal client count API is the best way to compute clients for versions greater than or equal to Vault 1.6. It’s important to note that the upgrade should have occurred before the ‘billing period’ started. Otherwise, it’s best to use the [auditor tool](/vault/tutorials/monitoring/usage-metrics#vault-auditor-tool) to compute clients because the usage metrics UI will not reflect all clients for the billing period; it will only reflect active unique clients since the upgrade.
### Q: Why do we have two different tools (auditor tool and UI/API) to compute clients? Do we plan to deprecate one in the future?
Not all customers may be on a version greater than Vault version 1.6 that leverages the client count API to display clients via the UI. The [auditor tool](/vault/tutorials/monitoring/usage-metrics#vault-auditor-tool) is available for customers running older Vault versions to compute client counts. The [auditor tool](/vault/tutorials/monitoring/usage-metrics#vault-auditor-tool) does not contain client count computation logic updates (e.g., non-entity token computation logic made in Vault 1.9). In the future, we will deprecate the [auditor tool](/vault/tutorials/monitoring/usage-metrics#vault-auditor-tool).
### Q: How can I compute KMIP clients for Vault?
As of Vault 1.11.0, KMIP clients are not available via the usage metrics UI or the client count API; they are provided via the [auditor tool](/vault/tutorials/monitoring/usage-metrics#vault-auditor-tool). To learn more, refer to the [Vault Usage Metrics](/vault/tutorials/monitoring/usage-metrics#vault-auditor-tool) documentation.
### Q: Why do the Vault auditor tool and the usage metrics UI show me different results for the total number of clients?
For versions prior to Vault 1.7, the [auditor tool](/vault/tutorials/monitoring/usage-metrics#vault-auditor-tool) and usage metrics UI should typically result in the same number of total unique clients for the billing period, unless there is some discrepancy in the underlying data represented by both or due to some other error. For example:
- If there is a discrepancy between the dates selected in the two tools, then the clients reflected in the results may be different
- If the auditor tool does not leverage audit data for the billing period, the auditor results may be incorrect
- If the Vault upgrade made to a version that computes clients in the usage metrics UI (any version greater than Vault 1.6) happened during the billing period, then the results shown in the usage metrics UI will only reflect the period since the upgrade occurred
However, there is one fine detail to keep in mind: the usage metrics UI only allows selection of billing periods from the start of a month to the end of a month (not mid-month). If the dates represented by the audit logs fed into the auditor tool begin and end mid-month, this may result in a subtle change of client counts between the two tools.
For newer versions of Vault 1.8, the API/UI for client counts was updated to reflect count clients more accurately. These changes were not made in the auditor tool and may cause a difference in the results generated by the two tools. For more information on the specific differences, refer to the question [Which Vault version reflects the most accurate count of clients within Vault?](#q-which-version-of-vault-reflects-the-most-accurate-client-counts).
### Q: When I upgrade to a version of Vault that's greater Vault 1.6, will the clients be available for the entire history of the billing period, or only available after the upgrade occurred during the billing period?
The client counts will only be available after the upgrade occurs. For the complete billing period data, it’s preferable to refer to the [auditor tool](/vault/tutorials/monitoring/usage-metrics#vault-auditor-tool). However, keep in mind that since Vault 1.8, we made improvements to the client count API/UI that may cause mismatched results from the [auditor tool](/vault/tutorials/monitoring/usage-metrics#vault-auditor-tool). For more details, refer to the question [If I migrate from Vault 1.8 to 1.9, how will the changes to non-entity token logic and local auth mount made in Vault 1.9 affect the clients created prior to the migration?](/vault/docs/concepts/client-count/faq#q-if-i-migrate-from-vault-1-8-to-1-9-how-will-the-changes-to-non-entity-token-logic-and-local-auth-mount-made-in-vault-1-9-affect-the-clients-created-prior-to-the-migration).
A workaround is to leverage the results from the UI/API (if on a newer version greater than Vault 1.8) instead of the [auditor tool](/vault/tutorials/monitoring/usage-metrics#vault-auditor-tool), and extrapolate the clients for the available period to the billing period.
### Q: If I upgrade from Vault 1.8 to 1.9+, how will the changes to non-entity token logic and local auth mount made in Vault 1.9 affect the clients created prior to the upgrade?
If you have a non-entity token for a fragment pre-Vault 1.9 version and then use the same token post-Vault 1.9 version, it will be counted again. However, for post-upgrade, the token will have an ID associated with it. From there, the subsequent uses of the token will not be counted again, as the token is tracked with the unique clientID. Hence, only for the period post the upgrade, the new deduplication logic for non-entity tokens are accounted for.
As for the local auth mounts, the tokens issued by the local auth mounts pre-Vault 1.9 version will be non-entity-tokens and counted as clients - 1 for each token. After the upgrade to Vault 1.9, the older tokens will continue to be counted as they were counted before, but the newer tokens issued will be part of entities and counted as far lesser clients (equal to the number of entities). To learn more, refer to the documentation on [What is a Client?](/vault/docs/concepts/client-count#what-is-a-client).
### 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: Is it possible to view a list of unique client IDs that contributed to the client count aggregate?
Yes. This is possible starting with Vault 1.11, with new functionality (tech preview) to export the unique clients that contribute to the client count aggregate for the selected billing period. This is possible via a new [activity export API endpoint](/vault/api-docs/system/internal-counters#activity-export).
### Q: What happens if audit logs are unreadable for use by the Vault auditor tool?
This issue may arise if the logs are too large and cannot be read, or you are running an older version than Vault 1.6. We encourage you to upgrade to a newer version of Vault so you can use the API/UI to compute clients. After the upgrade, even if you have only limited historical data on clients (since the upgrade), that data could be extrapolated for future client prediction. Account teams need to look into this on a case-by-case basis.
### 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:
![Vault Client Count](/img/client-counts.jpg)
### Q: What does the usage metrics look like for Vault 1.10?
In Vault 1.10, the client count dashboard is broken down into tabs, similar to Vault 1.9- the current month and the monthly history. On top of the namespace attribution provided in Vault 1.9 (see [What does the usage metrics UI look like for Vault 1.9?](#q-what-does-the-usage-metrics-ui-look-like-for-vault-1-9) for further information), the UI also contains attribution of clients per auth mount.
![Vault Client Count](/img/vault-usage-metrics-1-10.png)
The Vault 1.10 UI does not include monthly attribution of clients, although the API for Vault 1.10 supports the same.
### Q: What does the usage metrics UI look like for Vault 1.11?
The 1.11 UI includes the ability to view changes to client counts month over month the running client total and new monthly clients. All the namespace and auth mount attribution capabilities from earlier versions are also available.
![Vault Usage Metrics](/img/vault-usage-metrics-1-11.png)
### Q: In older Vault versions including Vault 1.10, how do I compute changes to clients month to month from the UI?
To perform this calculation, you must know the billing period. For the sake of this example, assume your billing period starts on January 1st and ends on December 31st:
1. To compute new active unique clients (clients who are new to Vault) for January, you need to use the UI to set the billing start date to January 1st and end date to January 31st:
-Unique clients for Jan = [Jan1 to Jan31]
1. To compute new active unique clients for February, you need to do the following:
-Unique clients for Jan + Feb = [Jan 1 to Feb 28/29]
-Unique clients for Jan = [Jan1 to Jan31]
-Unique clients for Feb = (Unique clients for Jan + Feb) - (Unique clients for Jan)
1. To compute new active unique clients for March, you need to do the following:
-Unique clients for Jan + Feb + Mar = [Jan 1 to Mar 31]
-Unique clients for Jan + Feb = [Jan1 to Feb 28/29]
-Unique clients for Feb = (Unique clients for Jan + Feb + Mar) - (Unique clients for Jan + feb)
… and so on.
### Q: What if I selected an inaccurate billing period via the UI/API?
If you selected an inaccurate billing period, then the clients reflected in the result will be incorrect. The API/UI considers the start date as a fresh start to re-count unique clients that were counted towards the billing period.
### Q: What if I want to skip computation of clients for a period of time during the billing period?
If you break the billing period, duplicates may likely occur. For instance, assume the start date of your billing period is January 1st and December 31st. You compute clients for period 1 = January 1st to March 31st and then period 2 = May 1st to December 31st (thus skipping the month of April). Clients that were already counted during period 1 may be recounted in period 2. Therefore, the addition of clients for period 1 + period 2 will include duplicates.
### Q: What are the known client count issues in the auditor tool as well as in the UI/API?
Known issues for both tools include the following:
**Auditor tool**:
- New updates to the client count logic (made in the API/UI starting Vault 1.8) are not reflected in the Vault auditor tool. We do not plan to update the auditor tool to be consistent with the API/UI and will eventually deprecate it. Use this tool as a stop-gap until you upgrade to a newer version of Vault
**UI/API**:
- Via the UI/API, the billing period cannot be computed for start and end dates that fall in the middle of a month. For example, if the billing period starts on March 15th and ends on March 14th within the subsequent year, the tool can only compute the billing period assuming March 1 is the start date or April 1 is the start date, but not using the March 15th start date
- As of Vault 1.10, KMIP clients are not provided by the API/CLI. We have plans to add this to a future version
- As of Vault 1.10, the data on the current month tab does not take the billing period into account. This means that it may include clients that have already been previously counted. However, the monthly history tab does take the billing period into account.
### Q: 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: How can I disable the counting of client activity?
You can disable the count of client activity by using the enabled parameter in the client count config. For more information, refer to the documentation on [Update the Client Count Configuration](/vault/api-docs/system/internal-counters#update-the-client-count-configuration). Disabling the feature during the middle of a month will discard any data recorded for that month but does not delete previous months.
### Q: If I request data for January 2021 - December 2021, but April’s data does not exist, what will be included in the total client count result?
In this scenario where you requested data for January 2021 through December 2021, and April's data does not exist because tracking was disabled for that particular month while other months have data, Vault will only return the most recent contiguous set of data, so in this case, data will only be returned for May 2021 through December 2021.
### Q: How can I configure the activity for log retention?
Specify retention months in the client config by following the steps in the documentation on [Update the Client Count Configuration](/vault/api-docs/system/internal-counters#update-the-client-count-configuration).
### 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.
### Q: How does the Nomad Vault integration affect client counts?
The [Nomad Vault integration](/nomad/docs/integrations/vault-integration#token-role-based-integration) uses [token roles](/nomad/docs/integrations/vault-integration#vault-token-role-configuration#vault-token-role-configuration). A single token role creates tokens for many Nomad jobs. If no [explicit identity aliases](/vault/api-docs/auth/token#entity_alias) are provided (which is not currently supported in the integration), this would create a non-entity token for every running instance of a Nomad job.
Prior to Vault 1.9, the Nomad Vault integration caused duplicate clients, resulting in an elevated client count. Post Vault 1.9, with the introduction of the deduplication logic, the number of clients created by the integration is reduced. For more information on improvements made to client count in Vault 1.9, refer to the question [Which version of Vault reflects the most accurate count of clients with Vault?](#q-which-vault-version-reflects-the-most-accurate-client-counts).
### Q: Starting in Vault 1.7, Vault does not allow creating two aliases from the same auth mount under a single entity. What changed and how does this impact client counting?
Prior to 1.9, customers could create more than one alias from the same auth mount under a single entity. However, we made a fix in Vault 1.9 to prevent this from occurring as a remediation for a security issue.
This could potentially impact the number of clients generated for customers. For example, pre Vault 1.9, a customer (using K8s, with many namespaces and services accounts in the cluster) could perform entity management by mapping multiple service accounts under different namespaces under a single entity. By default, each service account will create a unique entity. Post Vault 1.9, they can only map a single K8s cluster to a single K8s auth mount.
To provide further clarity, post Vault 1.9, if there was an auth mount per namespace, the customer could create an alias for a service account in namespace-1 and an alias for a service account in namespace-2 onto the same entity without issues. However, within namespace-1, which has a single auth mount, if they have a service account-1 and service account-2, both accounts cannot be aliased to a single client.
### Q: How does mount migration impact the client count metric?
In Vault 1.10, we made improvements to the [`sys/remount`](/vault/api-docs/system/remount) API endpoint to simplify the complexities of moving data, such as secret engine and authentication method configuration from one mount to another, within a namespace or across namespaces. This can help with restructuring namespaces and mounts for various reasons, including [migrating mounts](/vault/docs/concepts/mount-migration) from root to other namespaces when transitioning to using namespaces for the first time. To learn more, refer to the [Mount Move](/vault/tutorials/enterprise/mount-move) tutorial.
When migrating mounts, any aliases that refer to users on the auth mount could now point to an invalid mount when an auth mount is moved. Pointing to an invalid mount may not be the case for every instance; a remount within a namespace will end in the aliases pointing to a valid mount. Still, a remount across namespaces will always result in the aliases pointing to an invalid mount. In the latter case, the Vault operator should find and remove those aliases from the source namespace, and create equivalent aliases and entities for the new mount in the target namespace. If new entities and aliases aren’t created in the target namespace, Vault will dynamically generate them upon login operations.
When migrating mounts within a namespace, client counts are not impacted.
- For each existing alias on the source mount and its corresponding entity, if the new namespace has an entity corresponding to it, then you can assign a corresponding alias for the mount and the client count will not be impacted. For example, say I am a user `abc` on namespace `ns1/` and namespace `ns2/`, and I have an alias on the source mount in `ns1/`. After the move operation, I just need an alias added to the `abc` entity in `ns2/` for the target mount. This keeps the client counts the same.
- For the example above, say I do not have an entity `abc` in `ns2/`. This will need to be created in order to make an alias associating it with the target mount. This increases the client count by 1.
- Following the above example, let's say after the move operation, the entity `abc` in `ns1/` has no other aliases associated with it, i.e., the alias for the source mount was its only alias. At this point, we can clean up and remove the `abc` entity in `ns1/`. This will decrease the client count by 1, as the old entity may have already been used during the billing period.
### Q: Vault 1.9 added support for providing custom user filters through the userfilter parameter. How does this affect client counts?
Vault 1.9 added support for providing custom user filters through the [userfilter](/vault/api-docs/auth/ldap#userfilter) parameter. This addition changed the way that entity alias gets mapped to an entity. Prior to Vault 1.9, alias names were always based on the [login username](/vault/api-docs/auth/ldap#username-3) (which in turn is based on the value of the [userattr](/vault/api-docs/auth/ldap#userattr)). In Vault 1.9, alias names no longer always map to the login username. Instead, the mapping depends on other config values as well, such as [updomain](/vault/api-docs/auth/ldap#upndomain), [binddn](/vault/api-docs/auth/ldap#binddn), [discoverydn](/vault/api-docs/auth/ldap#discoverdn), and userattr.
Vault 1.10 re-introduces the option to force the alias name to map to the login username with the optional parameter username_as_alias. Users that have the LDAP auth method enabled prior to Vault 1.9 may want to consider setting this to true to revert back to the old behavior. Otherwise, depending on the other aforementioned config values, logins may generate a new and different entity for an existing user that already had an entity associated in Vault. This in turn affects client counts since there may be more than one entity tied to this user. The username_as_alias flag will also be made available in subsequent Vault 1.8.1x and Vault 1.9.x releases to allow for this to be set prior to a Vault 1.10 upgrade.
### Q: Are batch tokens counted differently than service tokens?
Batch token clients are counted like service token clients. They can still be mapped to entities, and if they are not, they are counted by the combinations of their namespaces and the policies assigned to them.
@include 'faq/client-count/tools.mdx'

491
website/content/docs/concepts/client-count/index.mdx
View File

@ -1,323 +1,184 @@
---
layout: docs
page_title: Client Count
description: Counting the number of clients accessing Vault.
page_title: Clients and entities
description: |-
Technical overview covering the concept of clients, entities, and entity IDs
in Vault
---
# What is a Client?
# Clients and entities
Before we dive into understanding the approach used to [count the number of clients](#client-count) accessing Vault, we need to first understand what clients represent.
Clients basically represent anything that has authenticated to Vault to do _something_. **Users** are people who log into the cluster to manage policies, set up dynamic secret rotation, and more. So every user that logs into the Vault is considered a **client**. Whereas every application, service, or any other machine-based system that authenticates to Vault is also considered a **client**.
Anything that connects and authenticates to Vault to accomplish a task is a
**client**. For example, a user logging into a cluster to manage policies or a
machine-based system (application or cloud service) requesting a database token
are both considered clients.
![Vault Client Workflows](https://www.datocms-assets.com/2885/1617325020-valult-client-workflows.png)
There are three main ways clients are assigned an identity:
1. **External Identity Management Platform or SSO:** Active Directory, LDAP, OIDC, JWT, GitHub, Username/password, etc.
2. **Platform or server-based identities:** Kubernetes, AWS, GCP, Azure, PKI, Cloud Foundry, etc.
3. **Self Identity:** AppRole, tokens (without an associated auth path or role)
![Vault Client Types](https://www.datocms-assets.com/2885/1617325030-vault-clients.png)
There can be many different types of clients that authenticate and communicate with Vault using one of the above identities, including:
1. **[Human users](/vault/tutorials/recommended-patterns/pattern-centralized-secrets#human-authentication):** GitHub ID, username/password, LDAP, Active Directory, Kerberos, JWT/ OIDC claims, OKTA
2. **Applications or Microservices:** 2-Factor Authentication methods such as AppRole, or by LDAP, Active Directory, or based on the platform’s identity, such as credentials from AWS, Azure, GCP, AliCloud, OCI, Kubernetes, Cloud Foundry, etc.
3. **[Servers and Platforms](/vault/tutorials/recommended-patterns/pattern-centralized-secrets#machine-programmatic-authentication):** VMs, Containers, Pods (Identified by LDAP, Active Directory service accounts, AWS, Azure, GCP, AliCloud, OCI, Kubernetes, TLS Certs
4. **Orchestrators:** Nomad, Terraform, Ansible, or Continuous Integration Continuous Delivery (CI/CD) Pipelines where each pipeline usually identified by 2FA
5. **[Vault Agents and Vault Proxies](/vault/docs/agent-and-proxy/autoauth):** acting on behalf of a app/microservice, typically identified by App role, Cloud credentials, Kubernetes, TLS Certs
6. **Tokens**: which are not tied to any identities at all. **_These should be used sparingly._**
Hashicorp recommends always associating tokens to an entity alias and token role.
## How do Clients work in Vault?
When anything authenticates to Vault, be it a user, application, machine, etc., it is associated with a unique **entity** within the [Vault identity system](/vault/docs/secrets/identity). The name reported to the identity systems by the different types of authentication methods varies ([list below](#authentication-methods-and-how-they-re-counted-in-vault)), each entity is created or verified during authorization. There are scenarios where tokens can be created outside of the identity system, without an associated entity. In this scenario, these tokens are considered **clients** (for production usage, it should be rare to have any tokens created outside any identity systems).
## But wait, there’s more...
Want to take full advantage of the Vault identity system and how clients are counted? The Vault identity system also has [Entity Aliases](/vault/api-docs/secret/identity/entity-alias) and [Identity Groups](/vault/api-docs/secret/identity/group-alias).
![Vault Identity Entities and Aliases](https://www.datocms-assets.com/2885/1617325026-vault-clients-identity-entity-aliases.png)
### Entity Aliases
Entity Aliases enable users or services to authenticate with more than one method and are associated with the same policy to share resources and count as unique entities.
### Identity Groups
Identity Groups within Vault leverage entities, in that Vault enables teams to create and manage logical groupings of entities. **Identity Groups** that can be based on organizations or teams within companies and can be used to assign policies and metadata, making user management dramatically simpler, especially for automating workflows by using Identity Groups to quickly and easily grant access to secrets and functionality within Vault.
For more on managing access with identity, entities, and more, check out [Identity-based Security and Low-trust Networks](https://www.hashicorp.com/identity-based-security-and-low-trust-networks) and the HashiCorp Learn tutorial [Identity: Entities and Groups | Vault](/vault/tutorials/auth-methods/identity)
## How does Vault avoid counting the same entity twice?
Using the identity system allows for Vault to make sure that entities aren’t counted more than once. Once you determine the identity and authentication method to be used for each, human, application, platform, and CI/CD pipeline, upon authentication for the first time in a billing period, Vault instantiates a unique entity. For example, say you have an application “AppX” that needs to get a secret from Vault using the AppRole method. Since AppX has an associated entity within Vault with associated policies, Vault knows every time that AppX is authenticating and authorizing, so AppX is only counted once.
## Non-entity Tokens
If you choose to use the [Token Auth Method](/vault/docs/auth/token) without an identity, this will create a non-entity token. Starting with Vault 1.9, any number of non-entity tokens having the same namespace and set of policies assigned, count as one client. In earlier versions, every non-entity token counted as a separate client, which could rapidly drive up client count to unrealistic values. If you are using Vault 1.8 or earlier, and need to address this without upgrading, one option is to create a [Token Role](/vault/api-docs/auth/token#create-update-token-role) first, with allowable entity aliases and create your token with the appropriate [role and entity alias name](/vault/api-docs/auth/token#create-token). All tokens issued with the same entity alias name count as one client.
### Differences 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](/vault/docs/secrets/identity). 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](/vault/docs/concepts/auth) 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?](/vault/docs/concepts/client-count/#what-is-a-client) documentation.
## Considerations for Namespaces
Since namespaces represent logical isolations within a single Vault cluster for administrative purposes, consideration must be made on how Vault clients are determined in this context.
1. If a client authenticates to Vault in a parent or root namespaces, it is considered the same client in all child namespaces. This is obvious as it is within the same logical isolation.
2. However if a client authenticates to Vault in two separate namespaces, because of logical isolation they are not considered as the same client. As an example, `/namespaceA/ldap/auth/login/bob` is not related to `/namespaceB/ldap/auth/login/bob`. If the intent is that “Bob” is the same client, authenticate into two namespaces:
1. Move the auth to the parent workspace and any auth to child namespaces would be considered as the same client
2. Place that auth in the root namespace to be considered as 1 client in all namespaces.
See also the guide [Secure Multi-Tenancy with Namespaces | Vault](/vault/tutorials/enterprise/namespaces).
## Authentication Methods and how they’re counted in Vault
Below is a list of supported authentication methods within Vault. You can also set up custom auth methods with secure plugins.
Each authentication method has a unique identifier to determine unique identity, similar to a driver license number, that uniquely determines an identity with a driver’s license.
How does this relate to Vault clients? As outlined above, and as an example, if you chose to identify a microservice by AppRole auth method, then assign a role id for that microservice. A role id is the microservice’s username and identity. You should not have different microservices use the same role id. Different microservices should use different role ids. However if microservices (or multiple VMs, or containers), are exact copies using the same role id, they will all have the same identity. This is the appropriate security posture to mitigate any risk, and an operator can easily approve or deny access to secrets for that one role id, without affecting other services. It is important as you choose an identity for each human, app, service, platform, server and pipeline, that you pay attention to the name below that makes each method unique and be given an identity.
| **Auth method** | **Name reported by auth method** |
| ------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------- |
| **[AliCloud](/vault/docs/auth/alicloud)** | Principal ID |
| **[AppRole](/vault/api-docs/auth/approle#create-update-approle)** | Role ID |
| **[AWS IAM](/vault/docs/auth/aws#iam-auth-method)** | Configurable via iam_alias to one of: Role ID (default), IAM unique ID, Full ARN |
| **[AWS EC2](/vault/docs/auth/aws#ec2-auth-method)** | Configurable via ec2_alias to one of: Role ID (default), EC2 instance ID, AMI ID |
| **[Azure](/vault/api-docs/auth/azure#create-role)** | Subject (from JWT claim) |
| **[Cloud Foundry](/vault/docs/auth/cf)** | App ID |
| **[GitHub](/vault/docs/auth/github)** | User login name associated with token |
| **[Google Cloud](/vault/api-docs/auth/gcp#create-role)** | Configurable via iam_alias to one of: Role ID (default), Service account unique ID |
| **[JWT/OIDC](/vault/api-docs/auth/jwt#create-role)** | Configurable via user_claim to one of the presented claims (no default value) |
| **[Kerberos](/vault/docs/auth/kerberos)** | Username |
| **[Kubernetes](/vault/api-docs/auth/kubernetes#create-role)** | Service account UID |
| **[LDAP](/vault/docs/auth/ldap)** | Username |
| **[OCI](/vault/api-docs/auth/oci#create-role)** | Rolename |
| **[Okta](/vault/api-docs/auth/okta#register-user)** | Username |
| **[RADIUS](/vault/docs/auth/radius)** | Username |
| **[TLS Certificate](/vault/api-docs/auth/cert#create-ca-certificate-role)** | Subject CommonName |
| **[Token](/vault/docs/auth/token)** | entity_alias, if provided (Note: please ensure that entity_alias is always used) |
| **[Username/Password](/vault/api-docs/auth/userpass#create-update-user)** | Username |
## Considerations with CI/CD
**Orchestrators and Continuous Integration Continuous Delivery (CI/CD) Pipelines** such as Nomad, Terraform, Ansible and the like, along with CI/CD tools such as Jenkins, Bamboo, Azure Devops, GitLab and GitHub Ops, and the like, can be used to authenticate to and request secrets from Vault during infrastructure or application/ service deployment. While the discussion below focuses on CI/CD, it is also applicable to orchestrators.
A CI/CD workflow can encompass many pipelines. Let us consider your options:
1. **Master CI/CD identity**: Would the overall CI/CD orchestrator be given a master identity (e.g. app role, token with an entity alias), authenticate to Vault, and receive all secrets for all pipelines and all applications/infrastructure to be deployed?
2. **Pipeline Identity**: Or would every CI/CD pipeline be given an identity (e.g. app role, token with an entity alias), authenticate to Vault once and retrieve all the secrets for each application/ infrastructure to be deployed??
3. **Pipeline and App/ Service/ Infra identity**: Or would every CI/CD pipeline be given an identity (e.g. app role, token with an entity alias), authenticate to Vault once and then give each application/ service/ infrastructure deployed, workflow its own identity, which upon bootstrap, in turn, authenticates to Vault on its own to retrieve a secret?
From a threat model and security assessment perspective, **_option 3_** above, where the pipeline does not have access to any secret, but allows applications, services or infrastructure to get its own secrets upon bootstrapping, is the most secure approach. With **_options 1_** and **_2_**, there is a risk that if someone gets access to your CI/CD workflow **_(option 1)_**, or your pipelines **_(option 2)_**, they would gain access to every or some of the secrets used by your apps and services. Using the [principle of least privilege](/vault/tutorials/recommended-patterns/pattern-centralized-secrets#the-principle-of-least-privilege-polp), where you only want to give access to secrets where necessary, there should be little or no gap between your secrets distribution and when it is accessed. Therefore one should avoid inadvertently giving your orchestrator and CI/CD tool god-like privileges where it potentially can access every secret for every app, service or infrastructure you deploy.
If someone goes wrong in **_option 1_** and you revoke access, all pipelines are affected. If something goes wrong in **_option 2_** and you revoke access to a pipeline, only that pipeline is affected, and you limit your security risk blast radius. If something goes wrong in **_option 3_** you can just revoke an app or service without affecting everything else. Please carefully consider your security options as you manage security in a dynamic world.
From a Vault client perspective, **_option 1_** is one client, the Master CI/CD identity; **_option 2_** is one client for the Master CI/CD identity, and one client for each pipeline; **_option 3_** is one client for the Master CI/CD identity, one client for each pipeline, and one for each app, service deployed.
### Onboarding Clients - Putting it all together
The guide: [“Onboarding Applications to Vault Using Terraform: A Practical Guide“](https://www.hashicorp.com/blog/onboarding-applications-to-vault-using-terraform-a-practical-guide) is an example on how to build an automated HashiCorp Vault onboarding system with Terraform to accommodate Vault client using naming standards, ACL policy templates, namespaces, pre-created application entities, and workflows driven by VCS and CI/CD.
## Client Count
The number of active clients using a Vault cluster is the total of:
- active entities: identity entities that create a token via a login
- active non-entity tokens: clients associated with tokens created via a method
that is not associated with an entity
Prior to Vault 1.6, this metric could only be measured from the audit log, using the
[`vault-auditor`](/vault/tutorials/monitoring/usage-metrics#vault-auditor-tool) tool. Starting with Vault 1.6, the number of clients per month, or for
a contiguous sequence of months, can be measured by Vault itself.
As of Vault 1.9, the total client count should always be measured using Vault itself. The
metrics shown by the Vault UI are the source of truth for this data.
Please refer to [Vault Usage Metrics](/vault/tutorials/monitoring/usage-metrics) for a
step-by-step tutorial and description of how to use the UI.
## Measuring clients
Each time a token is used, Vault checks to see whether it belongs to an identity entity
that has already been active in the current month. New entities are added to a log in Vault storage
periodically. Tokens without entities are tracked separately and added to the "non_entity_tokens" count.
Please see the 'Tracking non-entity tokens' subsection below for a detailed explanation of how such
tokens are tracked by Vault.
At the end of each month, Vault creates precomputed reports listing the number of active entities,
per namespace, in each time period within a configurable retention period. This process deduplicates
entities by ID, so that if an entity is active within every calendar month, it still only counts as
one client for the entire year.
There are no client count metrics available until after the first calendar month finishes.
The client counts sum activity from all nodes in a cluster, including batch tokens created by performance
standby nodes. Performance secondary clusters have their own client population, and their own client metrics;
Vault does not aggregate or deduplicate clients across clusters. However, the logs and precomputed
reports are included in DR replication.
### Costs of measurement
Each active entity in the log consumes a few bytes of storage. Vault limits the number of identity
entities it records per month (to 656,000) as a safety measure to prevent unbounded storage growth. However,
typical storage costs should be much less. 1000 monthly active entities will require about 1.5 MiB of storage
capacity over the default 24-month retention period. A smaller amount of additional storage is used for
precomputed reports for all valid start/end pairs of months.
### Disabling measurement
To avoid this potentially unwanted storage usage, the client count feature can be disabled via the UI or API.
By default, the client count is disabled on open source builds, and enabled on Enterprise binaries. The CLI command
to change its state is:
```shell-session
# To enable
$ vault write sys/internal/counters/config enabled=enable
# To disable
$ vault write sys/internal/counters/config enabled=disable
```
If you disable the client counter, then all complete months and all precomputed reports will remain in storage
until their normal expiration time. This allows queries to be run on older data, even if no new data is being collected.
Vault does not report across a disable/enable cycle of the client count. All subsequent reports will start at the
time that the feature is enabled.
## Understanding non-entity tokens
A token without an entity can be created in any of the following ways:
- A root token creates a token via `auth/token/create`.
- Any other token without an entity creates a child token via `auth/token/create` or a token role.
- An orphan token is created via `auth/token/create-orphan`; such a token does not inherit the entity of its creator.
- A token is created using a token role that specifies `orphan=true`.
- An auth method would normally create an entity, but is not allowed to do so, such as:
- A batch token is created on a performance standby node.
- A service token is created on a performance secondary replica, using a local mount.
The `entity_id` field will be empty, or show as `n/a`, for any token that is classified as a non-entity token:
```shell-session
$ vault token lookup
Key Value
--- -----
entity_id n/a
```
To reduce the number of non-entity tokens in use, consider switching to an authentication method such as
[AppRole](/vault/docs/auth/approle) instead of handing out directly-created tokens. Ensure that entities and
[entity aliases](/vault/api-docs/secret/identity/entity-alias) exist for all login methods used to create batch tokens.
### Tracking non-entity tokens
As of Vault 1.9, non-entity tokens are tracked as unique clients based on the policies the token
has access to and the namespace in which it was created. Non-entity tokens that are assigned
the same set of policies and are created in the same namespace will be tracked as the same client.
Conversely, if two non-entity tokens have a different policy set or are created in different namespaces,
they will be tracked as two separate clients.
Please note that before the release of Vault 1.9, non-entity tokens were each tracked separately. That is
to say, two non-entity tokens would always be counted as two separate clients.
## Auditing clients
As of Vault 1.9, the Vault Audit Log contains a `client_id` field in the request. The `client_id` field
contains an Entity ID for requests that are made with tokens with entities, or a unique client ID for
non-entity tokens.
Consumers of the audit log will be able to distinguish between these two types of client IDs by comparing
the value in the `client_id` with the value of the `entity_id` in the `Auth` section of the response. If
the two values are the same, then the `client_id` is an `entity_id`. If not, then the `client_id` was
generated from the use of a non-entity token.
An empty `client_id` field in a request means that Vault did not track a client for that
request; this can happen if the request is unauthenticated, or made with a root token or wrapped token.
## API and Permissions
Please see [Client Count API](/vault/api-docs/system/internal-counters#client-count) for more details. Note that this API is marked as
"internal" so its behavior or format may change without warning. The UI is the preferred means of interacting with the
client count feature.
For the UI to be able to use the client count feature, it needs `read` permission to the following paths:
- `sys/internal/counters/activity`
- `sys/internal/counters/config`
For the UI to be able to modify the configuration settings, it additionally needs `update` permission to
`sys/internal/counters/config`.
## New Clients For Current Month
The billing period for the activity log API can be specified to include the current month
for the end date. For more information, please refer to the
[the internal counters API docs](/vault/api-docs/system/internal-counters) documentation.
When the end date is the current month, the `new_clients` counts will be an approximation of the
number of new clients for the month, and not an exact value. Note that the `new_clients` counts for the rest
of the months will be accurate.
### Why An Approximation?
The `new_clients` counts for the current month is an approximation to improve API
performance and make the UI usable. To give an exact value for the current month's
new clients, client IDs need to be de-duplicated with the previous months' client IDs,
which is a time and i/o intensive process.
### Approximation Details And Accuracy Testing Results
The `new_clients` approximation is calculated by using a [hyperloglog algorithm](https://en.wikipedia.org/wiki/HyperLogLog)
to approximate the cardinality of the total number of clients within the billing period, and the cardinality
of the total number of clients within the billing period not including the current month. The returned value
is the difference between these two numbers.
The hyperloglog library used for the cardinality estimate is [axiomhq](https://github.com/axiomhq/hyperloglog),
with fourteen registers and the use of sparse representations, when applicable. Some accurate estimates can be found
in this library's [README](https://github.com/axiomhq/hyperloglog#readme). These are accuracy results
for the cardinality of the multiset, which is the total number of clients within a billing period. The accuracy
estimate for the number of new clients can be far lower, depending on the discrepancy between the number of
clients in the current month and the number of clients in the billing period.
If we call the number of clients for the current month C and the number of clients in the billing period B, we
have found that in general, if C << B, the approximation can be imprecise, and the further the difference between
C and B grows, the more imprecise the approximation will be. Furthermore, the closer C is to 0, the more imprecise
the approximation can be. Also, the more months in the billing period, the less accurate the approximation can be.
The maximum observed error rate ((found new clients)/(expected new clients)) with testing for 10,000 clients and under
was 30%, with most cases yielding an error rate of 5-10%.
A table with a few randomly selected values for C and B are listed below for the purposes of predictive analysis.
| Current Month Clients | Total Months' Clients | Accuracy |
| :--- | :----: | ---: |
| 7 | 10 | 100% |
| 20 | 600 | 100% |
| 20 | 1000 | 100% |
| 20 | 6000 | 90% |
| 20 | 10000 | 90% |
| 200 | 600 | 100% |
| 200 | 10000 | 93% |
| 400 | 6000 | 95% |
| 2000 | 10000 | 96% |
Some multi-month (over 2 months) and multi-segment tests are below:
| Current Month Clients | Total Months' Clients | Accuracy |
| :--- | :----: | ---: |
| 20 | 15 | 100% |
| 20 | 100 | 100% |
| 20 | 1000 | 100% |
| 20 | 10000 | 70% |
| 200 | 10000 | 94% |
| 2000 | 10000 | 98% |
While there are many different potential clients, the most common are:
1. **Human users** interacting directly with Vault.
1. **Applications and microservices**.
1. **Servers and platforms** like VMs, Docker containers, or Kubernetes pods.
1. **Orchestrators** like Nomad, Terraform, Ansible, ACME, and other continuous
integration / continuous delivery (CI/CD) pipelines.
1. **Vault agents and proxies** that act on behalf of an application or
microservice.
## Identity and entity assignment
Authorized clients can connect to Vault with a variety of authentication methods.
Authorization source | AuthN method
-------------------------- | ---------------------------------
Externally managed or SSO | Active Directory, LDAP, OIDC, JWT, GitHub, username+password
Platform- or server-based | Kubernetes, AWS, GCP, Azure, Cert, Cloud Foundry
Self | AppRole, tokens with no associated authN path or role
![Vault client types](https://www.datocms-assets.com/2885/1617325030-vault-clients.png)
When a client authenticates, Vault assigns a unique identifier
(**client entity**) in the [Vault identity system](/vault/docs/secrets/identity)
based on the authentication method used or a previously assigned alias.
**Entity aliases** let clients authenticate with multiple methods but still be
associated with a single policy, share resources, and count as the same entity,
regardless of the authentication method used for a particular session.
## Standard entity assignments
@include "authn-names.mdx"
Each authentication method has a unique ID string that corresponds to a client
entity used for telemetry. For example, a microservice authenticating with
AppRole takes the associated role ID as the entity. If you are running at scale
and have multiple copies of the microservices using the same role id, the full
set of instances will share the same identifier.
As a result, it is critical that you configure different clients
(microservices, humans, applications, services, platforms, servers, or pipelines)
in a way that results in distinct clients having unique identifiers. For example,
the role IDs should be different **between** two microservices, MicroserviceA and
MicroServiceB, even if the **specific instances** of MicroServiceA and
MicroServiceB share a common role ID.
## Entity assignment with ACME
Vault treats all ACME connections that authenticate under the same certificate
identifier (domain) as the same **certificate entity** for client count
calculations.
For example:
- Authentication requests from two ACME clients living on different servers that
request the same set of certificate identifiers are assigned to the same
certificate entity.
- Multiple requests for the same certificate identifier from a single ACME
client are assigned to the same certificate entity.
- Two authentication requests from a single ACME client for different
certificate identifiers are assigned to separate certificate entities.
## Entity assignment with namespaces
A namespace represents a isolated, logical space within a single Vault
cluster and is typically used for administrative purposes.
When a client authenticates **within a given namespace**, Vault assigns the same
client entity to activities within any child namespaces because the namespaces
exist within the same larger scope.
When a client authenticates **across namespace boundaries**, Vault treats the
single client as two distinct entities because the client is operating
across different scopes with different policy assignments and resources.
For example:
- Different requests under parent and child namespaces from a single client
authenticated under the **parent** namespace are assigned **the same entity
ID**. All the client activities occur **within** the boundaries of the
namespace referenced in the original authentication request.
- Different requests under parent and child namespaces from a single client
authenticated under the **child** namespace are assigned **different entity
IDs**. Some of the client activities occur **outside** the boundaries of the
namespace referenced in the original authentication request.
- Requests by the same client to two different namespaces, NAMESPACE<sub>A</sub>
and NAMESPACE<sub>B</sub> are assigned **different entity IDs**.
## Entity assignment with non-entity tokens
Vault uses tokens as the core method for authentication. You can use tokens to
authenticate directly, or use token [auth methods](/vault/docs/concepts/auth)
to dynamically generate tokens based on external identities.
When clients authenticate with the [token auth method](/vault/docs/auth/token)
**without** a client identity, the result is a **non-entity token**. For example,
a service might use the token authentication method to create a token for a user
whose explicit identity is unknown.
Ultimately, non-entity tokens trace back to a particular client or purpose so
Vault assigns unique entity IDs to non-entity tokens based on a combination of
the:
- assigned entity alias name (if present),
- associated policies, and
- namespace under which the token was created.
In **rare** cases, tokens may be created outside of the Vault identity system
**without** an associated entity or identity. Vault treats every unaffiliated
token as a unique client for production usage. We strongly discourage the use of
unaffiliated tokens and recommend that you always associate a token with an
entity alias and token role.
<Note title="Behavior change in Vault 1.9+">
As of Vault 1.9, all non-entity tokens with the same namespace and policy
assignments are treated as the same client entity. Prior to Vault 1.9, every
non-entity token was treated as a unique client entity, which drastically
inflated telemetry around client count.
If you are using Vault 1.8 or earlier, and need to address client count
inflation without upgrading, we recommend creating a
[token role](/vault/api-docs/auth/token#create-update-token-role) with
allowable entity aliases and assigning all tokens to an appropriate
[role and entity alias name](/vault/api-docs/auth/token#create-token) before
using them.
</Note>
@include "content-footer-title.mdx"
<Tabs>
<Tab heading="Related concepts">
<ul>
<li>
<a href="/vault/docs/concepts/client-count/counting">Client count calculation</a>
</li>
<li>
<a href="/vault/docs/concepts/client-count/faq">Client count FAQ</a>
</li>
<li>
<a href="/vault/docs/secrets/pki/best-practices/cicd-pipelines">Best practices for CI/CD pipelines</a>
</li>
</ul>
</Tab>
<Tab heading="Related tutorials">
<ul>
<li>
<a href="/vault/tutorials/auth-methods/identity">Identity: Entities and Groups</a>
</li>
<li>
<a href="/vault/tutorials/enterprise/namespaces">Secure Multi-Tenancy with Namespaces</a>
</li>
</ul>
</Tab>
<Tab heading="Other resources">
<ul>
<li>
Article: <a href="https://www.hashicorp.com/identity-based-security-and-low-trust-networks">
Identity-based Security and Low-trust Networks
</a>
</li>
</ul>
</Tab>
</Tabs>

5
website/content/partials/alerts/auditor-deprecated.mdx Normal file
View File

@ -0,0 +1,5 @@
<Warning heading="Vault auditor tool deprecated as of March 2022">
You can still download the Vault auditor, but we no longer actively support
the tool. We strongly encourage <a href="/vault/docs/upgrading">upgrading</a> to
an actively supported version of Vault.
</Warning>

23
website/content/partials/authn-names.mdx Normal file
View File

@ -0,0 +1,23 @@
In addition to custom authentication methods configured with secure plugins,
Vault supports many standardized authentication methods by default.
| AuthN method | Unique ID | Configured with
| ----------------------------------------------------------------------- | -------------------------------------------- | ----------------
| [AliCloud](/vault/docs/auth/alicloud) | Principal ID | Not configurable
| [AppRole](/vault/api-docs/auth/approle#create-update-approle) | Role ID | Not configurable
| [AWS IAM](/vault/docs/auth/aws#iam-auth-method) | Role ID (default), IAM unique ID, Full ARN | `iam_alias`
| [AWS EC2](/vault/docs/auth/aws#ec2-auth-method) | Role ID (default), EC2 instance ID, AMI ID | `ec2_alias`
| [Azure](/vault/api-docs/auth/azure#create-role) | Subject (from JWT claim) | Not configurable
| [Cloud Foundry](/vault/docs/auth/cf) | App ID | Not configurable
| [GitHub](/vault/docs/auth/github) | User login name associated with token | Not configurable
| [Google Cloud](/vault/api-docs/auth/gcp#create-role) | Role ID (default), Service account unique ID | `iam_alias`
| [JWT/OIDC](/vault/api-docs/auth/jwt#create-role) | The presented claims (no default value) | `user_claim`
| [Kerberos](/vault/docs/auth/kerberos) | Username | Not configurable
| [Kubernetes](/vault/api-docs/auth/kubernetes#create-role) | Service account UID | Not configurable
| [LDAP](/vault/docs/auth/ldap) | Username | Not configurable
| [OCI](/vault/api-docs/auth/oci#create-role) | Rolename | Not configurable
| [Okta](/vault/api-docs/auth/okta#register-user) | Username | Not configurable
| [RADIUS](/vault/docs/auth/radius) | Username | Not configurable
| [TLS Certificate](/vault/api-docs/auth/cert#create-ca-certificate-role) | Subject CommonName | Not configurable
| [Token](/vault/docs/auth/token) | `entity_alias` | Not configurable
| [Username/Password](/vault/api-docs/auth/userpass#create-update-user) | Username | Not configurable

7
website/content/partials/content-footer-title.mdx Normal file
View File

@ -0,0 +1,7 @@
<br />
<table style={{borderTop: "1px dashed var(--token-color-vault-foreground)"}}><tbody><tr>
<th style={{textAlign: "left", fontSize: "var(--token-typography-display-300-font-size)"}}>
<br />
Continue reading...
</th>
</tr></tbody></table>

90
website/content/partials/faq/client-count/computing-clients.mdx Normal file
View File

@ -0,0 +1,90 @@
### Can I compute clients for Vault versions before v1.6? ((#before-1-6))
@include 'alerts/auditor-deprecated.mdx'
**Yes**.
Use the [Vault auditor tool](/vault/tutorials/monitoring/usage-metrics#vault-auditor-tool)
to compute and display client count data for Vault v1.3 &ndash; 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? ((#kmip))
**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? ((#month-to-month))
**Yes, for Vault v1.8 &ndash; 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 &nbsp; February | `JAN_FEB` | `FEB = JAN_FEB - JAN`
March | January &nbsp; February | `JAN_MAR` | `MAR = JAN_MAR - JAN_FEB`
April | January &nbsp; February | `JAN_APR` | `APR = JAN_APR - JAN_MAR`
May | January &nbsp; February | `JAN_MAY` | `MAY = JAN_MAY - JAN_APR`
June | January &nbsp; February | `JAN_JUN` | `JUN = JAN_JUN - JAN_MAY`
July | January &nbsp; February | `JAN_JUL` | `JUL = JAN_JUL - JAN_JUN`
August | January &nbsp; February | `JAN_AUG` | `AUG = JAN_AUG - JAN_JUL`
September | January &nbsp; September | `JAN_SEP` | `SEP = JAN_SEP - JAN_AUG`
October | January &nbsp; February | `JAN_OCT` | `OCT = JAN_OCT - JAN_SEP`
November | January &nbsp; February | `JAN_NOV` | `NOV = JAN_NOV - JAN_OCT`
December | January &nbsp; February | `JAN_DEV` | `DEC = JAN_DEC - JAN_NOV`
### Do child namespaces create duplication in the client count? ((#namespace-dupes))
**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](/vault/docs/concepts/client-count) overview for more
details.
### Does the Nomad-Vault integration affect client counts? ((#nomad))
**Maybe**.
[Nomad Vault integration](/nomad/docs/integrations/vault-integration#token-role-based-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? ((#batch-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](/vault/docs/concepts/client-count) overview for more
details.
### Do custom user filters affect client counts? ((#custom-filters))
**Yes**.
Custom [user filters](/vault/api-docs/auth/ldap#userfilter) can change the way
that entity aliases are mapped, which can affect the client count computation.
Consult the [clients and entities](/vault/docs/concepts/client-count) overview
for more information about how Vault determines entity assignments.
### Does mount migration affect client counts? ((#mount-migration))
**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.

28
website/content/partials/faq/client-count/definitions.mdx Normal file
View File

@ -0,0 +1,28 @@
### What is a client? ((#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](/vault/docs/concepts/client-count) overview
for more information on client definitions.
### What is the difference between an entity client, non-entity client, and certificate client? ((#eclient-vs-neclient))
- **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](/vault/docs/concepts/client-count) overview
for more information about how Vault determines entity assignments.

21
website/content/partials/faq/client-count/tools.mdx Normal file
View File

@ -0,0 +1,21 @@
### What is the Vault auditor? ((##vault-auditor))
@include 'alerts/auditor-deprecated.mdx'
The [Vault auditor tool](/vault/tutorials/monitoring/usage-metrics#vault-auditor-tool)
lets customers running Vault v1.3 &ndash; 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? ((#auditor-ki))
**Yes**.
The Vault auditor only includes the computation logic improvements from Vault
v1.6 &ndash; 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.

79
website/content/partials/faq/client-count/upgrading.mdx Normal file
View File

@ -0,0 +1,79 @@
### How has client count changed across different Vault versions? ((#logic-improvements))
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 | Eliminated wrapped tokens and control groups and counts active identity entities at usage instead of create time
| 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? ((#ui-improvements))
| 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? ((#uiapi-ki))
**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? ((#what-happens-at-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 heading="Time your upgrade appropriately">
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.
</Warning>
<Tabs>
<Tab heading="Upgrading from Vault 1.8">
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:
<ul>
<li>
Any <b>non-entity tokens</b> 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.
</li>
<li>
Any <b>local auth mounts</b> 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.
</li>
</ul>
</Tab>
<Tab heading="Upgrading from Vault 1.6">
As of v1.7, Vault forbids users from creating two aliases from the same authN
mount under a single entity. Additionally, Vault 1.9 forbids mapping multiple
service accounts under different namespaces to a single entity.
Each unique combination of authN mount, namespace, and alias, will be counted
as a distinct client.
</Tab>
</Tabs>

71
website/content/partials/faq/client-count/usage.mdx Normal file
View File

@ -0,0 +1,71 @@
### Can I view the list of unique client IDs that contributed to my client count aggregate? ((#view-data))
**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](/vault/api-docs/system/internal-counters#activity-export).
### Is clientID viewable in the audit logs for non-entity tokens? ((#clientid-in-logs))
**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? ((#skip-computation))
**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<sub>1</sub> runs from January 1st to March 31st
- Period<sub>2</sub> 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? ((#lost-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? ((#missing-data))
**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? ((#disable-client-count))
**Yes**.
You can use the Vault API to
[update the client count configuration](/vault/api-docs/system/internal-counters#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? ((#log-client-count))
**Yes**.
You can use the Vault API to
[update the client count configuration](/vault/api-docs/system/internal-counters#update-the-client-count-configuration)
and specify your preferred retention period.

8
website/data/docs-nav-data.json
View File

@ -171,12 +171,16 @@
"path": "concepts/resource-quotas"
},
{
"title": "Client Count",
"title": "Client count",
"routes": [
{
"title": "Overview",
"title": "Clients and entities",
"path": "concepts/client-count"
},
{
"title": "Client count calculation",
"path": "concepts/client-count/counting"
},
{
"title": "FAQ",
"path": "concepts/client-count/faq"