Introduction
As Helm repositories grow in size and complexity, ensuring optimal performance in Artifactory becomes increasingly important. The way repositories are structured—whether small and modular or large and aggregated—can significantly impact indexing, replication, and general responsiveness. This article explores the pros and cons of several common architectures, provides insight into Helm’s evolution, and offers practical recommendations for scaling effectively in Artifactory. It also discusses the possibility of migrating from a Helm legacy repository to an OCI-based Helm repository for improved performance in Helm chart resolution.
Understanding the Context: Helm’s Evolution and Scaling Challenges
Initially, Helm maintained a central chart repository. As usage grew, this central model became difficult to maintain, which led to performance bottlenecks and eventual deprecation. In response, Helm transitioned toward a decentralized model, now anchored around the Artifact Hub. This hub aggregates over 3,000 micro Helm repositories but treats each as an independent source of truth. The key lesson from this shift is clear: decentralization can dramatically reduce scaling issues.
JFrog aligns with this direction and recommends aggregating no more than 20 repositories into a single virtual repository. This best practice helps avoid excessive recalculations and large index files, which can hinder performance as the number of repositories and artifacts increases.
Approach 1: Small Local Repositories Aggregated into a Virtual Repository
Aggregating small local repositories into a single virtual one may seem convenient, but it can introduce complex performance issues. Every time a deployment occurs, it can invalidate the cached index.yaml files, especially when user permissions vary. For each permission permutation, Artifactory may need to recalculate a separate index.yaml file, causing heavy backend load and frequent regeneration of “dirty” indexes.
Over time, as more local repositories are added and more permission sets exist, the computational cost of maintaining and recalculating these index files grows exponentially. This architecture can become a bottleneck, especially for large teams or organizations with layered access controls.
Approach 2: One Large Local Repository
A single large local repository eliminates the permission-based recalculation issue. With only one repository, Artifactory doesn’t need to differentiate indexes based on permissions across multiple sources. However, this method introduces a different challenge—file size.
The index.yaml file grows proportionally with the number of charts stored. With 2,300 charts, it may be just 2.4 MB, but if this scales to millions of charts, the index.yaml could exceed several gigabytes. In extreme cases, a 3 million-chart repository could produce an index file over 3 GB in size. Over time, as the repository continues to grow, the index file may reach 10 GB or more, significantly impacting performance during routine operations like helm repo update or helm install.
This strategy, while simpler in structure, becomes unsustainable in environments where scalability and performance are priorities.
Approach 3: Small Local Repositories (Artifact Hub Approach)
Inspired by Helm’s current architecture, the most scalable approach involves using many small, independent local repositories. Each repository maintains a smaller, manageable index.yaml file, avoiding the need for large-scale aggregation or recalculation.
This decentralized model allows more flexibility and control. Indexes remain small, caching is efficient, and the system avoids the complexity of generating multiple index files based on user permissions. When grouped logically and accessed through appropriately sized virtual repositories, this method scales gracefully while maintaining responsiveness for end users.
Our Recommendation
Following Helm’s current best practices, we recommend adopting the Artifact Hub Approach. Instead of aggregating hundreds of repositories into a single virtual instance, group them logically and ensure each virtual repository maintains a manageable size.
Aim to keep each index.yaml file under a few thousand charts. This makes updates and access faster and more reliable, while also reducing the risk of memory-related performance issues. Although the exact limit for artifacts in a local repository will depend on the system resources available, monitoring and observing latency is key—performance degradation is a clear indicator that a split may be needed.
Additional Considerations:
Index File Generation and Caching
When user-specific permissions apply to a virtual repository, Artifactory may generate separate index.yaml files for each unique permission set. These files are not visible in the UI but are stored in the backend, with a database entry for each.
For example, 100 distinct user permissions could result in 100 separate index.yaml files. These are created on demand when users connect and are cleared when using the “Zap cache” feature on the virtual repository.
To further improve performance, starting from Artifactory version 7.80.0, the index calculation logic has been enhanced to minimize out-of-memory (OOM) issues. It is strongly recommended to configure the “Metadata Retrieval Cache Period (Sec)” to at least 60 seconds. This setting, which defaults to 360 seconds (6 minutes), prevents unnecessary repeated index calculations during that period.
When a user requests an index.yaml from a Helm virtual repository, Artifactory first checks for a cached version that matches the user's permissions. If it doesn’t exist, the system triggers a calculation and waits for the result (up to 6 minutes), then serves the final cached version to the user. This caching system is designed to reduce strain on the instance and ensure smoother client experiences.
Migrating Helm Repositories from Legacy Format to OCI in Artifactory
Artifactory supports both legacy Helm repositories and Helm repositories based on the OCI (Open Container Initiative) standard. While legacy Helm repositories rely on an index.yaml file to maintain metadata about available charts and their versions, this model presents some operational limitations as explained above. The index.yaml must be continuously updated and synchronized, which can lead to performance and storage impacts.
Helm OCI repositories, on the other hand, offer a more robust and scalable alternative by leveraging Artifactory’s native support for OCI registries, making it easier to scale, distribute, and leverage the power of OCI to deliver charts. Charts are treated as OCI artifacts and pushed using standard tagging mechanisms, eliminating the need for an index.yaml. Version management is handled through image tags, and retrieval relies on standard OCI APIs — similar to how Docker images are managed.
Key benefits of using OCI Helm repositories in Artifactory:
- No dependency on index.yaml, reducing metadata-related conflicts or delays.
- Improved scalability and performance, especially in CI/CD pipelines with frequent Helm chart updates.
- Cleaner version control using tags, enabling better automation and traceability.
For teams using a Helm chart repository, migrating to OCI-based Helm repositories is a smart approach to consider, as it ensures compatibility with the latest Helm standards (Helm 3+) and simplifies Helm chart distribution across environments.
To migrate a legacy Helm chart repository to a Helm OCI repository, follow the steps described in this article.