Image Lifecycle Management

Purpose: For platform engineers, provides retention policies, deprecation process, and base image update cadence.

Overview

Image lifecycle management covers how long images are kept, when they are deprecated, and how base images are updated. Harbor enforces retention rules per project; platform teams define deprecation timelines in release notes.

Retention Policies

Harbor tag retention rules are configured per project. The platform uses these defaults:

Harbor Project	Rule	Retention Period	Rationale
platform-dev	Keep last 10 tags per repo	30 days for untagged	Fast iteration, limited storage
platform-staging	Keep last 5 tags per repo	60 days for untagged	Validation window
platform-production	Keep all semver tags	365 days minimum	Rollback capability, audit trail
customer-apps	Keep last 20 tags per repo	90 days for untagged	Balance between history and storage

Configuring Retention in Harbor

Retention rules are set in each Harbor project under Policy > Tag Retention:

# Example Harbor tag retention policy (applied via Harbor API)
rules:
  - action: retain
    template: latestPushedK     # Keep the K most recently pushed
    params:
      latestPushedK: 10
    scope_selectors:
      repository:
        - kind: doublestar
          decoration: repoMatches
          pattern: "**"
    tag_selectors:
      - kind: doublestar
        decoration: matches
        pattern: "**"

Tagging Strategy

Tag Format	Example	Mutability	Use Case
<semver>-<sha>	1.4.2-a1b2c3d	Immutable	CI artifacts, audit trail
<semver>	1.4.2	Mutable (re-pointed on rebuild)	Human reference, FluxCD ImagePolicy
latest	—	Prohibited	Blocked by Kyverno policy disallow-latest-tag

Deprecation Process

When a platform service image is superseded or end-of-lifed:

1. Announce — Add a deprecation notice to the release notes with the target removal date (minimum 90 days).
2. Label — Apply the OCI annotation org.opencontainers.image.deprecated=true to the image manifest.
3. Block promotion — Update the Harbor project's immutability rule to prevent the deprecated tag from being promoted to production.
4. Remove — After the deprecation window, the image is deleted by the retention policy. A final SBOM snapshot is archived.

Base Image Update Cadence

Base Image	Source	Review Frequency	Trigger
gcr.io/distroless/static-debian12	Google	Weekly (Dependabot)	Digest change
golang	Docker Hub	Weekly (Dependabot)	Minor/patch release
python	Docker Hub	Weekly (Dependabot)	Minor/patch release
alpine	Docker Hub	Weekly (Dependabot)	Patch release

When a base image digest changes, Dependabot opens a PR. CI rebuilds all dependent images and runs the full scan pipeline. If scans pass, the PR is merged and images are promoted through the normal pipeline.

Version Pinning Requirements

All references to images — in Dockerfiles, Helm values, and Kustomize patches — pin by digest or exact semver tag:

# Correct: pinned by digest in Dockerfile
FROM golang:1.22.4@sha256:abc123def456...

# Correct: pinned by semver in HelmRelease values
image:
  repository: harbor.opencenter.example.com/platform-security/kyverno
  tag: "1.12.0-a1b2c3d"

# Incorrect: mutable tag
image:
  tag: "latest"   # Rejected by Kyverno at admission

Further Reading

• Image Catalog — Full list of platform images
• Build System — How images are built and tagged
• Publish & Promote — Promotion between environments