Cleanup Policies, Retention, Component Age, Last-Downloaded Rules, Preview, and Storage Reclamation: Concepts, Architecture, and Mental Model

1. The practical problem: repositories grow faster than intuition

Artifact repositories accumulate releases, prereleases, CI snapshots, cached upstream packages, metadata, signatures, checksums, container manifests, and format-specific indexes. Keeping everything forever feels safe until storage pressure, backup duration, search scale, vulnerability exposure, and recovery time become operational problems. Deleting arbitrary files from a blob-store directory feels fast until database metadata points at bytes that no longer exist.

Nexus Repository solves this with retention policy: describe which repository components are eligible to be removed, preview the effect, let Nexus update its own metadata through supported tasks, and reclaim physical storage only through the supported blob-store compaction mechanism. The operator controls policy; Nexus owns repository consistency.

2. The lifecycle: selection → logical deletion → reclamation

flowchart TD
P[Cleanup policy criteria] --> A[Repository attachment]
A --> V[Preview / dry-run evidence]
V --> C[Cleanup service evaluates candidates]
C --> S[Components soft deleted]
S --> O[Unused asset/blob cleanup]
O --> B[Soft-deleted blobs remain allocated]
B --> K[Admin - Compact blob store]
K --> F[Physical space reclaimed]
S -. recovery window before compaction .-> R[Supported recovery / backup path]

The arrows matter. A policy definition alone deletes nothing. Attaching it establishes scope. Preview predicts candidates but is not a guarantee because time and downloads can change. The cleanup service marks matching repository content as deleted in supported metadata. Physical blob bytes may still consume space. Compaction is the destructive boundary that permanently removes eligible soft-deleted blob content and releases capacity.

3. Define the retention objects before using them

4. Criteria are conjunctive: narrower than they first appear

Current Sonatype guidance states that the criteria in one cleanup policy are combined so a component must satisfy every configured condition. If a policy says “component age ≥ 90 days” and “component usage ≥ 30 days,” an 120-day-old component downloaded yesterday is retained because it fails the usage condition. This AND behavior is a safety feature only when operators understand it.

eligible = age_matches
        AND usage_matches
        AND release_type_matches_if_configured
        AND asset_name_matches_if_configured

then apply supported retain-last-N exclusions, if configured

Multiple policies may be attached to the same repository. Overlap increases operational complexity because a component can be selected by more than one policy. Document the intent of each policy so a future operator can explain why an artifact was eligible.

5. “Age” and “last downloaded” answer different questions

Component age asks how long content has existed in this Nexus context. Hosted content uses the upload or update time. Proxy content uses the time Nexus first downloaded it from the remote repository, so a ten-year-old upstream library first cached yesterday is “young” to the proxy cleanup policy.

Component usage asks whether consumers have recently downloaded the component. When no download exists, current documentation falls back to the publication/update timestamp. That makes the criterion usable for never-consumed content, but it also means your interpretation must account for how a format and version record downloads.

6. Format semantics change what a safe policy can express

All formats do not expose the same cleanup dimensions. Current cleanup documentation lists age and usage broadly, but release classification, asset-name matching, and version retention vary by format. For example, Maven treats versions containing -SNAPSHOT as prereleases for this purpose, while npm prerelease classification follows its semantic-version dash convention. Docker cleanup evaluates tagged manifests, which is not the same object model as a Maven component.

Before creating a policy, write down the repository format, type, desired lifecycle, rollback need, and the exact current criteria supported for that format. Do not copy a Maven release policy into Docker, PyPI, Raw, or NuGet and assume the same metadata semantics.

Asset Name Matcher is also database-generation sensitive. Current H2/PostgreSQL deployments use Java regular-expression semantics and Sonatype examples show the asset name with a leading slash. Legacy OrientDB policies used different Lucene-style semantics. Never copy an old OrientDB regex into H2/PostgreSQL without re-previewing it against the exact repository; Chapter 26 covers migration in depth.

7. Retain-last-N is an exclusion, not a substitute for lifecycle policy

In the 3.95 release line, Sonatype expanded “Retain last N versions” across versioned formats that have version semantics. Current documentation still identifies this as a Nexus Repository Pro capability requiring PostgreSQL. It is therefore an optional architecture discussion in this course, not a mandatory Community lab.

The useful mental model is: first establish why content would otherwise be old/inactive enough to remove, then preserve a floor of recent versions. “Keep the newest five” without age or usage context can retain five abandoned builds forever; “delete anything older than 30 days” without a version floor can remove the only rollback version after a quiet month. Production retention often needs both lifecycle criteria and explicit release protection.

8. Preview is evidence, not permission to stop thinking

Current Nexus provides cleanup-policy preview before execution. The standard preview has a one-minute timeout to limit performance impact. PostgreSQL deployments can generate a CSV report; Nexus One UI also exposes preview results. Preview is a snapshot: publication, downloads, and concurrent repository activity can change the candidate set between preview and cleanup.

9. The tasks form a chain of different responsibilities

Current Sonatype documentation describes system cleanup tasks that Nexus creates automatically. The cleanup service evaluates repositories using attached policies and soft deletes matched components. Format-specific unused-asset cleanup tasks remove orphaned assets that are no longer required. Physical space is recovered only when the relevant blob store is compacted.

The distinction matters operationally. If the repository no longer shows a component but disk usage has not fallen, that can be expected—not proof that cleanup failed. If compaction runs before you validate the logical deletion set, your recovery window becomes much smaller. Schedule compaction off peak and only after the retention decision is accepted.

10. Read-only inspection before any policy change

Begin with evidence, not a delete button. In a disposable instance, record Nexus version/edition, database, repository format/type, blob-store assignment, current task schedules, and a component inventory. Use UI browsing and documented APIs that your edition supports. Do not query internal tables or inspect individual blob files to reverse-engineer repository state.

# POSIX/Bash — read-only examples against a disposable lab
BASE='http://127.0.0.1:8081'
REPO='cleanup-lab-raw'

curl -fsS "$BASE/service/rest/v1/status"
curl -fsS "$BASE/service/rest/v1/repositories" | python -m json.tool
curl -fsS "$BASE/service/rest/v1/search/assets?repository=$REPO"   -u 'cleanup-reader:password-FAKE_DO_NOT_USE' | python -m json.tool

# Capacity evidence only. Do not delete or edit blob-store files directly.
df -h .

If your Community edition does not expose a documented automation endpoint needed by an example, use the UI and record screenshots/notes rather than substituting an undocumented endpoint.

11. State boundaries: what cleanup changes and what it does not

12. Common wrong mental models

• “Free disk space is the cleanup criterion.” Storage pressure motivates policy, but lifecycle intent selects content.
• “Last downloaded means last used by every consumer.” It means the timestamp Nexus recorded for supported request behavior, subject to format/version caveats.
• “Preview guarantees the run.” It is point-in-time evidence, not a lock.
• “Deleted in Browse means bytes are gone.” Soft deletion and blob compaction are distinct stages.
• “I can remove old blob files with rm.” Direct filesystem deletion can corrupt the database/blob relationship.
• “Retention is backup.” Cleanup reduces retained content; backup preserves recoverable state. They solve opposite problems.

13. Why this matters in DevOps

CI/CD increases artifact velocity. A production repository therefore needs an explicit retention contract: development builds expire aggressively, releases align with rollback/support windows, proxy caches retain enough working-set history for resilience, and storage reclamation happens after verified logical cleanup. The policy should be reviewable by developers, release engineering, operations, and security because each group depends on different evidence.

14. Knowledge check

15. Summary and next step

Retention is a controlled sequence: define lifecycle intent, express format-aware criteria, scope the policy, preview candidates, execute supported logical deletion, verify repository state, and only then reclaim blob storage. Lesson 2 turns that model into a disposable Community-compatible workflow, using a deterministic live cleanup plus an age/usage simulation rather than forging Nexus timestamps.

Official references and version notes

• Sonatype: Cleanup Policies — current criteria, preview, system cleanup tasks, soft deletion, compact-blob-store reclamation, and format matrix.
• Sonatype: Nexus Repository 3.95.x Release Notes — 3.95 cleanup enhancements and current known issues.
• Sonatype: Tasks — current task types including Admin - Compact blob store.
• Sonatype: Keeping Disk Usage Low — supported cleanup/reclamation guidance and the separation between deletion and freed disk space.
• Sonatype: Nexus Repository Professional Features — current Pro-only Retain Select Versions boundary.