Container image deprecation policy¶
This document describes how we manage the lifecycle of container images published by the DevOps
Division. It applies primarily to the base image collection published from the
uis/devops/platform/base-images
GitLab group, which is the current authoritative source of base images and part of the Unified
DevOps Platform. The same policy also continues to
apply to images published from the legacy
uis/devops/infra/dockerimages
registry for the duration of its deprecation. See the containers
explanation for background
on why we currently run the two side by side.
Our goal is to ensure that all available images are secure, actively maintained, and aligned with our current best practices, while providing users with clear communication and sufficient time to migrate when older images are retired.
Image lifecycle stages¶
Each image goes through the following stages:
| Stage | Description | Duration |
|---|---|---|
| Active | The image is actively maintained, receives updates, and is recommended for general use. | Ongoing |
| Deprecated | The image remains available but is no longer maintained or included in our nightly and weekly build pipelines. It does not receive routine security or dependency updates. Users are strongly encouraged to migrate to a supported version. | 3 months |
| Removed | The image is untagged and removed from the registry. | Permanent |
Deprecation triggers¶
An image may be deprecated when one or more of the following conditions are met:
- The base image or dependencies reach end-of-life.
- Known vulnerabilities cannot be patched.
- A newer major or minor version replaces it.
- The image shows low usage or is no longer relevant.
Deprecation announcement¶
When an image is marked as deprecated, we will:
- Post to the UIS DevOps General Microsoft Teams channel.
- Add the image to a
DEPRECATED_IMAGES.mdfile in the repository that publishes it, to track its status. Each publishing repository maintains its own file. For example, the individual base image projects underuis/devops/platform/base-imageseach track their own deprecations, as does the legacydockerimagesregistry.
Grace period¶
Deprecated images remain available in the registry for 90 days from the deprecation date, unless removal is required sooner for security or legal reasons.
During the grace period:
- No new builds or patches will be published.
- Users are encouraged to migrate to the recommended version.
- A warning may appear in logs or at container startup to notify users of deprecation.
Image removal¶
After the grace period expires:
- The deprecated image tags will be removed from the registry.
- This will cause the garbage collection process to delete the image manifests and layers in approximately 24 hours time.
- The
DEPRECATED_IMAGES.mdfile in the publishing repository will be updated to reflect the change.
Emergency removals¶
In the event of a critical security vulnerability, licensing issue, or other urgent matter, images may be removed immediately and without prior notice. Where feasible, an announcement will be published to the UIS DevOps General Microsoft Teams channel to explain the reason for removal.