### NOTE: This is the ~golang part from https://gitlab.com/gitlab-org/gitlab/-/work_items/600850. ## Summary As organizations migrate from Harbor to GitLab Container Registry, a key missing capability is the ability to clean up container images based on **last pull activity**. Harbor supports cleanup policies based on when an image was last pulled, but GitLab's Container Registry currently lacks this functionality. This feature request proposes: 1. **Tracking and exposing `last_pull_timestamp`** (or equivalent field) for container image tags in the registry metadata database and API responses. 2. **Supporting pull-activity-based cleanup policies**, allowing users to define rules such as "delete images not pulled in the last 90 days." ## Problem GitLab's current Container Registry cleanup policy supports: - Tag name matching via regex - Age-based removal (based on `created_date`) - Retaining the N most recent tags It does **not** support: - Cleanup based on last pull/download activity (`last_pull_timestamp`) - Multiple cleanup policies per project This gap is significant for teams migrating from Harbor or other registries that support pull-activity-based cleanup. Without this, organizations must build and maintain custom internal services to handle image cleanup based on pull activity, which adds operational overhead. ## Prior Art within GitLab The **Dependency Proxy** already tracks pull activity via a `read_at` attribute on `dependency_proxy_blob` and `dependency_proxy_manifest` records. This is used for TTL-based cleanup policies (e.g., "delete if not pulled in 90 days"). A similar pattern could be extended to the Container Registry. ## Proposal 1. **Track pull timestamps**: Record the last pull time for each tag/manifest in the Container Registry metadata database (the next-generation metadata database would be the appropriate place for this). 2. **Expose via API**: Add a `last_pulled_at` field to the Container Registry API responses (both REST and GraphQL) for repository tags. 3. **Cleanup policy support**: Extend the cleanup policy configuration to support a `not_pulled_since` or `last_pulled_older_than` parameter, enabling rules like "remove tags not pulled in the last X days." ### API Response Example ```json { "name": "v1.0.0", "path": "group/project:v1.0.0", "location": "registry.gitlab.com/group/project:v1.0.0", "created_at": "2025-01-15T10:00:00Z", "last_pulled_at": "2025-04-20T14:30:00Z" } ``` ### Cleanup Policy Example ```json { "name_regex_delete": ".*", "name_regex_keep": "latest|release-.*", "keep_n": 5, "older_than": "90d", "not_pulled_since": "60d" } ``` ## Use Cases - **Storage optimization**: Automatically remove images that are no longer being used (not pulled) to reduce storage costs. - **Migration from Harbor**: Organizations migrating from Harbor expect feature parity for cleanup policies, including pull-activity-based rules. - **Compliance and lifecycle management**: Ensure only actively used images remain in the registry, supporting software lifecycle policies. ## Additional Context - The next-generation Container Registry metadata database (required for GitLab.com, beta for self-managed) would be the natural place to store pull activity data. - The Dependency Proxy's `read_at` tracking pattern (see [development docs](https://docs.gitlab.com/ee/development/packages/dependency_proxy.html)) provides a proven implementation reference within GitLab. ## Implementation Plan (Go / container-registry) Split into **3 small, independently reviewable MRs**: ### Status - **1. Schema** ✅ **merged** (!2882) — nullable `tags.last_pulled_at timestamptz` on the HASH-partitioned `tags` table. No backfill; nothing reads/writes it yet. - **2. Write path** — 🔜 next (design below; pairing with `@vespian_gl`). - **3. API exposure** — after step 2. Naming settled: **`last_pulled_at`** (matches existing "manifest pulled" terminology). ### Write path (step 2) — async & batched _(supersedes the earlier per-pull "debounce" design)_ Review concluded we must **not** touch the DB on the manifest-pull hot path (read-only, 100s req/s) — not even a debounced read-then-write. Instead, an **asynchronous batched writer**, modeled on the existing `AccessTracker` (URLCache storage middleware): - Manifest GET **enqueues** the pulled `(repository, tag)` via a **non-blocking** call (bounded channel; drops + increments a metric if the buffer is full) — **zero added DB work on the request path**. - A single background goroutine buffers pulls, de-duplicating by tag, and on a **configurable interval** issues **bulk `UPDATE`s** (`last_pulled_at = now()`), one per repository, keyed on the partition column (`top_level_namespace_id`) + `repository_id` + `name` for partition pruning. - **Per-replica** (no leader election): each instance writes the pulls it served; last-writer-wins on a `~now()` timestamp is correct for "last pulled." - **Graceful shutdown** does a final flush so the last window isn't lost. - Gated by `database.enabled` + a new `enabled` flag; flush interval configurable. Net effect: DB write load is capped at ~one bulk statement per active repository per interval, **independent of pull QPS**. ### API exposure (step 3) Add `last_pulled_at` (ISO-8601, nullable) to: - `GET /gitlab/v1/repositories/:path/tags/list/` - `GET /gitlab/v1/repositories/:path/tags/detail/:name/` (consumed by Rails `lib/container_registry/gitlab_api_client.rb`.) ### Out of scope (unchanged) - **Blob/layer pulls** — only manifest pulls count (blobs are deduped across tags). - **Dependency Proxy / CDN pulls** the registry never sees — documented caveat. - **Geo replicas** — only the primary's `last_pulled_at` is authoritative. - **By-digest pulls** — no tag to attribute; skipped. ### Design decisions to confirm (pairing) - Surface the repository ID already resolved on the pull path (avoid a second lookup) vs. resolve it in the background writer. - Timestamp granularity: window-level `now()` (recommended) vs. exact per-pull time. - Bulk shape at high repo fan-out: per-repo `name = ANY(...)` (recommended) vs. a single multi-repo `unnest` UPDATE. ### Rollout 1. Schema on .com (done, gated). 2. Enable write path on .com behind flag; monitor `tags` write load for ≥2 weeks. 3. Enable API exposure. 4. Self-managed release; document write-path load implications in admin docs.