Distributed Caching Strategy
Relevant source files
The following files were used as context for generating this wiki page:
The Distributed Caching Strategy in Harbor Next is designed to improve system performance and reduce database load by providing a transparent caching layer for high-frequency resource access. It primarily targets resources such as projects, project metadata, repositories, artifacts, and manifests, leveraging Redis as the distributed backend to ensure consistency across multiple service instances.
This strategy employs a "cache-aside" pattern where application logic first attempts to retrieve data from the cache before falling back to the primary database. It includes robust mechanisms for cache invalidation, key normalization, and automated management through centralized resource managers.
Sources: src/pkg/cached/manager.go:23-34, src/pkg/factory.go:48-55
Core Architecture and Resource Management
The caching system is built around a standard Manager interface that provides a unified way to interact with cached resources. This interface allows administrators to view metrics and manage the lifecycle of cached data.
Cache Manager Interface
The Manager interface defines the behavior for all resource-specific cache implementations. It provides methods for checking resource types, counting cached items, deleting specific keys, and flushing all entries for a resource type.
This diagram illustrates the interface hierarchy used for resource caching.
Sources: src/pkg/cached/manager.go:37-51
Key Normalization
To prevent collisions and ensure predictable lookups, the system uses an ObjectKey structure. This utility formats keys into a colon-separated namespace string, supporting various value types including integers and strings.
| Feature | Description |
|---|---|
| Namespace | The root prefix for the resource (e.g., artifact, project) |
| Formatting | Transforms pairs of keys and values into namespace:key:value format |
| Type Support | Specifically handles int, int16, int32, int64, and string |
Sources: src/pkg/cached/manager.go:54-94
Resource-Specific Implementations
Harbor Next implements specialized managers for different resource types to handle their unique metadata and invalidation requirements.
Project and Metadata Caching
The Project Manager uses Redis to store project details. It supports lookups by both id and name. When a project is deleted, the manager automatically triggers a cleanUp routine to remove both ID-based and Name-based indices from Redis.
This sequence shows the typical cache-aside flow for retrieving project information.
Sources: src/pkg/cached/project/redis/manager.go:88-124
Metadata Invalidation
Project metadata caching is more complex due to the potentially large number of attributes. When metadata is updated, the system performs a Scan operation with a prefix lookup to find all keys associated with a specific project ID and invalidates them to ensure data consistency.
Sources: src/pkg/cached/project_metadata/redis/manager.go:85-110
Global Initialization and Configuration
The caching layer is initialized globally through a factory pattern. The init function checks system configuration to determine if caching should be enabled for various resource managers.
Manager Initialization
| Manager | Resource Type | Implementation |
|---|---|---|
ArtifactMgr | artifact | cached/artifact/redis |
ProjectMgr | project | cached/project/redis |
ProjectMetaMgr | project_metadata | cached/project_metadata/redis |
RepositoryMgr | repository | cached/repository/redis |
ManifestMgr | manifest | cached/manifest/redis |
Sources: src/pkg/factory.go:34-45
System Configuration
Caching behavior is governed by environment variables and internal configuration. Users can enable or disable the cache globally and set the expiration duration.
CACHE_ENABLED: Boolean flag to activate the distributed cache.CACHE_EXPIRE_HOURS: Duration in hours before cached items are considered stale.
Sources: api/v2.0/swagger.yaml:2634-2639, src/pkg/cached/project/redis/manager.go:56
Monitoring and Metrics
The caching strategy integrates with Harbor's exporter to provide visibility into the health and efficiency of the cache. The ProjectCollector uses internal cache functions to store and retrieve project overview information, such as total counts and quota usage, to avoid expensive SQL aggregations on every Prometheus scrape.
Sources: src/pkg/exporter/project_collector.go:133-155
Conclusion
The Distributed Caching Strategy provides a robust framework for managing ephemeral data across the Harbor Next ecosystem. By abstracting Redis operations behind resource-specific managers and providing automated invalidation during CRUD operations, the system maintains high performance without sacrificing data integrity. This layered approach allows the project to scale horizontally while keeping database latency low for critical paths like artifact retrieval and metadata lookups.