How to size and estimate Vault clients in a new deployment

A practical guide to understanding Vault client counting and sizing so you can deploy Vault Enterprise efficiently and avoid future licensing or scaling surprises.

Author: Roman Zamora Carreras, HashiCorp Solutions Engineer

One of the most common questions in new deployments of Vault Enterprise is: “What exactly counts as a Vault client?”. This is an important question because client counts are the basis for licensing and a key insight into how you size your architecture.

»Why is Vault used?

Modern organizations run workloads across multiple environments (cloud, on-premises, and hybrid) where applications, services, and users constantly need access to sensitive data. Managing this securely and consistently across such a diverse landscape is complex, especially as infrastructure becomes more dynamic, ephemeral, and distributed.

HashiCorp Vault addresses this challenge by acting as a central control plane for secrets management, encryption, and identity-based access. It provides a consistent framework to authenticate workloads, authorize access, and protect sensitive data, regardless of where those workloads run.

Teams use Vault to:

• Securely store and deliver secrets such as API keys, certificates, and credentials through a single trusted interface.

• Issue dynamic, short-lived credentials for databases, cloud platforms, and infrastructure components, reducing the risk associated with static credentials.

• Encrypt and decrypt data without exposing raw keys, allowing developers to integrate data protection directly into their applications.

• Unify authentication and authorization by integrating and leveraging existing identity providers (cloud IAM, Kubernetes, LDAP, OIDC, etc.).

• Apply fine-grained policies and governance, ensuring that access decisions are standard and auditable across the organization.

• Scale across environments with performance replication, namespaces, and API-driven automation, making it suitable for both small teams and global enterprises.
  

Vault evolved into a mature solution, trusted by organizations worldwide to secure everything from developer pipelines to critical production systems. Its flexible architecture, deep ecosystem integrations, large community, and proven scalability make it a cornerstone for modern secrets and identity management.

By using Vault, organizations gain not only stronger security but also operational efficiency: centralizing secrets, enforcing least privilege, and automating the entire lifecycle of secrets. For enterprises, Vault acts as a “control plane for secrets and identity,” sitting between applications, services, and users on one side, and critical infrastructure and data stores on the other.

Understanding this role is important because every unique application, service, or user that interacts with Vault counts as a client, if not configured otherwise. This makes sizing and accounting for Vault clients a critical first step in any new deployment.

»Understanding the Vault client definition

A Vault client is any unique application, service, machine, or human that authenticates to Vault to request a secret, perform an operation, or use Vault’s APIs. This definition is broader than many expect, it’s not just “users,” but anything capable of establishing an authenticated session with Vault, both human and non-human users 

As stated in our documentation:
“ Examples of Vault clients include:

• Human users interacting directly with Vault.

• Applications and microservices.

• Servers and platforms like VMs, Docker containers, or K8s

• Orchestrators like Nomad, Terraform, Ansible, ACME, and other continuous integration / continuous delivery (CI/CD) pipelines.

• Vault agents and proxies that act on behalf of an application or microservice. “

A single workload, architected with multiple components such as VMs, containers, or jobs, can involve multiple Vault clients. Without a clear identity design, this can lead to security risks and uncertainty in how clients are counted. By configuring identities consistently, for example, through entity aliases or centralized auth methods, you ensure that client counting remains accurate, predictable, and aligned with your intended architecture.

For billing and consumption, only unique and active clients during the billing period (monthly in the case of HCP Vault Dedicated and annual in the case of self-managed Vault Enterprise) count towards totals. Each client is counted once within a billing period, regardless of how many times it's been active. In billing terms, when a client authenticates to a cluster, those clients have access to that cluster for the remainder of the billing period, regardless of the number of requests or secrets stored. 

»Why do we care about Vault clients?

Correctly counting and managing Vault clients matters for four main reasons:

1. Licensing accuracy

Vault Enterprise licensing is tied to client counts. Misunderstanding what counts as a client can lead to underestimating license needs, resulting in compliance risks, or overestimating, which can inflate costs unnecessarily.

2. Sizing and performance planning

Every client introduces authentication and secret retrieval requests that consume Vault resources. Knowing your client footprint helps you size Vault appropriately for performance and availability.

3. Future-proofing and scaling

New deployments often start small, but workloads and integrations tend to expand rapidly. A clear picture of clients today helps you anticipate growth and avoid rework or re-architecture later.

4. Segmented policies

Configured policies are attached to a token and to a specific identity, which will be mapped to a specific Vault client. Vault supports many standardized authentication methods by default, each one having its own unique ID to tie an identity to the authentication payload. It is key to have a proper hierarchy/segmentation of Vault clients to avoid misconfigurations and allow auditability.

»Estimating Vault clients in a new deployment

Once you understand what a Vault client is, the next challenge is figuring out how many clients you have in your environment. In a new deployment, this step can feel abstract at first. But taking a methodical approach now will save time, reduce surprises, and help align compliance, performance, and architecture decisions from day one.

Because there’s no historical Vault telemetry yet, you’ll need to map out your anticipated clients based on your current and near-term infrastructure plans. Have a good understanding of what is currently running in your environment and involve the necessary stakeholders who plan to adopt Vault, potentially creating an inventory attached to the selected architecture for your Vault cluster. Here is a generic approach to relate to a maximum of environments:

»1. Applications, services, and Kubernetes workloads

Each discrete application instance that authenticates to Vault is a client.

In a VM-based environment, this typically means one client per VM or service process, depending on how the application authenticates and horizontally scales.

In containerized environments that provide identity to workloads (like Kubernetes, Nomad etc.), the Service Account is the true source of identity for Vault clients. Each unique Service Account that authenticates to Vault is counted as a client. While pod-level authentication is common, if multiple pods share the same Service Account, they are all represented by a single client in Vault.

How you integrate Vault with Kubernetes also affects client counting:

• Vault Secrets Operator (VSO): Typically runs at the namespace level, which can significantly reduce the number of clients (but it could be configured with more granularity). VSO is the recommended pattern for new deployments.

• Sidecar (Vault Agent injector): Still widely used, but each pod generally authenticates independently. This can increase client counts unless Service Accounts are consolidated, which is not necessarily Kubernetes best practice

• CSI driver: Similar to the Vault Agent injector, where client counts map closely to the number of Service Accounts in use.

Because these methods differ in how they handle authentication, your choice of integration strategy directly influences how many Vault clients you need to plan for.

Microservice architectures tend to increase the client footprint, since each service may authenticate separately, even if it is part of the same application stack. One approach we very often see with our customers is to group logically different VMs, applications, nodes, pods, or services that require access to the same pool of secrets under a single Service Account, AppRole, or another auth method.

This approach has both benefits and drawbacks: it reduces billing because fewer unique identities are counted as Vault clients, but it also decreases segmentation and traceability. If credentials are compromised, the potential impact is greater and the workload required to investigate or contain the incident is higher, since the attack surface is broader. Having said that, service account re-use is quite common. This blog is a good read to better understand the differences between the different Kubernetes secrets consumption models.

Ultimately, it’s about deciding how to balance investment against the level of security granularity you require. 

»2. Automation and CI/CD systems

A typical use case for Vault is CI/CD pipelines retrieving secrets to perform any securitized action. Several methods of authentication allow you to be granular and set identity at different levels (project, pipeline, run, etc.)
JWT authentication, especially used in pipelines, can add extra granularity and allow customers to segment further than per runner. With GitHub Actions, GitLab CI, or Jenkins, the JWT authentication method allows you to configure granularity using the user_claim.

If you are looking at giving each job/project running an isolated environment and isolated credentials, you will have to count a Vault Client for each job/project. On the other hand, if your user_claim is configured purely at an organization or project level, you will have a client per organization or project, respectively. We invite you to take this into account in your calculation efforts when an architecture is decided. Again, ultimately, it’s about deciding how to balance investment against the level of security granularity you require.

More information on JWT and how to select bound claims is found in our documentation. This topic can also be discussed with the HashiCorp teams for more details, as it is slightly out of scope for this blog.

»3. Human users

Vault is mainly conceived for application-type secrets, although a group of admin or developers are required to access for proper configuration. Human auth methods include CLI logins, UI access, or integrations via SSO/LDAP.

Humans usually represent a small fraction of client counts compared to machines, but they’re important to include for compliance and capacity planning.

It is standard to see at least 3 Vault clients for admins, depending on the size of your footprint and the number of employees managing your cluster.

»Taking into account specific use cases on your roadmap

It’s important to recognize that your Vault client count is not static. It will increase significantly as you adopt new use cases and expand usage across teams and systems. Each time you bring a new workflow into Vault, you inevitably introduce additional applications, services, or human users that need to authenticate, all of which increase the client count.

For example, an organization may start with Vault for CI/CD secrets, then later extend it to Kubernetes workloads, LDAP/database credential rotation, or encryption as a service. Each of these milestones represents a moment where the number of Vault clients can grow rapidly.

Planning only for the “here and now” has limited value. To size accurately, you need to look at your adoption roadmap and forecast how future use cases will translate into new clients. Even rough estimates, such as expected service accounts, runner jobs, or user groups, can help you avoid under-sizing and prepare your infrastructure and licensing for growth.

»Avoiding common pitfalls

Even with a solid definition of Vault clients and a careful sizing exercise, teams often run into challenges when rolling out Vault Enterprise for the first time. These pitfalls can create compliance gaps, performance issues, or rework later in the deployment. Here are some of the most common ones, and how to avoid them.

1. Underestimating future integrations

Vault adoption may grow quickly in large organizations: starting with CI/CD secrets, then expanding to Kubernetes, databases, PKI, or encryption. Planning only for day one leads to undersizing. Include roadmap use cases in your sizing estimate, even if you do not have precise numbers yet.

2. Properly understand the difference between client types 

Different types of clients for different usages. Properly read the documentation to understand your client count meter. Do not hesitate to share your concerns with the HashiCorp team. 

3. Misalignment between teams

Security, ops, and dev teams (potentially managed as silos) can have different understandings of a Vault Client, creating gaps. Involve cross-functional stakeholders in the sizing exercise.

4. Mounting auth methods in the wrong place

While mounting auth methods separately in each namespace is interesting for security purposes, it can cause the same client to be counted multiple times across namespaces. Mount common auth methods at the parent namespace and delegate access via policies. This ensures one client is counted once, even if it accesses multiple namespaces.

»Best practices and resourceful tips for accurate and scalable client management

Beyond avoiding pitfalls, there are practices that can make client management in Vault Enterprise more accurate, efficient, and secure. Here are some of the most impactful:

1. Use entity aliases for unified identities

Vault entities let you consolidate multiple auth methods (e.g., Okta + GitHub) under one identity. Without aliases, a single person or service could be counted multiple times. Define a clear alias strategy early to keep counts clean and aligned with licensing. 

2. Properly configure your auth mount

Each authentication method has its own way to count unique identities. For example, Kubernetes workloads look for the Service Account UID configured by default. Some authentication methods allow you to configure the type of Unique ID used. Take into account that this brings security concerns that depend on your Kube configuration. This is a wider conversation on which you can be assisted by the HashiCorp team.   

3. Pre-create entities and entity aliases
Related to the first tip, entities can either be implicitly created by Vault when users/services successfully authenticate into Vault, or they can be explicitly pre-created via Vault API/Terraform provider, etc.

It's recommended to pre-create entities and entity aliases explicitly to ensure a predictable and accurate client count. 

4. Use IaC for a standard pipeline for onboarding

Automating onboarding through infrastructure as code reduces human error, enforces best practices, and provides clear visibility into how clients are registered and managed. Implementing an onboarding pipeline, ideally wrapped into a Terraform module managed by the operations team, helps standardize how new applications, services, and teams are integrated with Vault. This ensures consistent identity configuration, policy application, and secret lifecycle management across environments.

5. Constant monitoring of your client count

Audit logs include a field called clientID that records the active or computed entity ID of the associated token. Vault’s API provides an extensive set of metrics that can be used to gain visibility into client counting. The UI/CLI leverages the same API endpoints and provides a summary of clients in a human-readable format.

Check this tutorial to get more information on client usage monitoring. Remember, observability means control and predictability.

»What Vault client metrics can I monitor?

As stated before, Vault exposes several types of telemetry metrics that provide valuable insight into the health, activity, and identity usage of your deployment. These metrics, together with lease count quotas applied to auth methods, can help you monitor client behavior, validate your sizing assumptions, and ensure compliance with licensing.

Vault telemetry includes three main metric types:

• Counter metrics – Increment whenever an event occurs. Counters are cumulative and reset at the end of the reporting interval.

• Gauge metrics – Represent current values or states, such as the number of active connections or entities.

• Summary metrics – Capture observational data, often used to measure the duration or latency of discrete events.
  

When Vault metrics are enabled, several authentication and identity metrics are emitted. These provide detailed visibility into active entities and client activity across namespaces:

• vault.identity.entity.active.monthly – Number of distinct entities (per namespace) that created a token in the past month.

• vault.identity.entity.active.partial_month – Number of distinct entities (per namespace) that created a token during the current month.

• vault.identity.entity.active.reporting_period – Number of distinct entities (per namespace) that created a token within the configured reporting period.

• vault.identity.entity.alias.count – Number of identity entity aliases (per auth method mount) currently stored in Vault.

• vault.identity.entity.count – Number of identity entities (per namespace) currently stored in Vault.

• vault.identity.entity.creation – Number of identity entities created per namespace.

• vault.identity.num_entities – Total number of identity entities currently stored in Vault.

»Next steps

Getting Vault client sizing right in a new deployment sets the foundation for a secure, scalable, and cost-effective rollout of Vault Enterprise. By understanding what counts as a client, planning for both current and future use cases, and applying best practices, you can avoid common mistakes and grow with confidence.

To continue your journey:

• Deepen your knowledge with official Vault Enterprise documentation and the client counting guide.

• See it in action by reviewing customer stories and deployment architectures.

• Engage with experts: HashiCorp Solutions Engineers and partners can provide tailored workshops to align sizing with your roadmap.