Red Hat OpenShift Container Platform

Automatically pruning images

To reclaim storage in the OpenShift image registry in Red Hat OpenShift Container Platform and define image retention period, you can configure the automatic image pruner.

You set the schedule, suspension, and retention options on the pruning custom resource (CR).

Prerequisites

You have access to an Red Hat OpenShift Container Platform cluster using an account with cluster administrator permissions.
Install the oc CLI.

The behavior of the Image Registry Operator for managing the pruner is independent to the managementState specified on the ClusterOperator object of the Image Registry Operator. If the Image Registry Operator is not in the Managed state, the image pruner can still be configured and managed by the Pruning Custom Resource.

However, the managementState of the Image Registry Operator alters the behavior of the deployed image pruner job:

Managed: the --prune-registry flag for the image pruner is set to true.
Removed: the --prune-registry flag for the image pruner is set to false, meaning it only prunes image metadata in etcd.

Procedure

Verify that the object named imagepruners.imageregistry.operator.openshift.io/cluster contains the following spec and status fields:
```
spec:
  schedule: 0 0 * * *
  suspend: false
  keepTagRevisions: 3
  keepYoungerThanDuration: 60m
  keepYoungerThan: 3600000000000
  resources: {}
  affinity: {}
  nodeSelector: {}
  tolerations: []
  successfulJobsHistoryLimit: 3
  failedJobsHistoryLimit: 3
status:
  observedGeneration: 2
  conditions:
  - type: Available
    status: "True"
    lastTransitionTime: 2019-10-09T03:13:45
    reason: Ready
    message: "Periodic image pruner has been created."
  - type: Scheduled
    status: "True"
    lastTransitionTime: 2019-10-09T03:13:45
    reason: Scheduled
    message: "Image pruner job has been scheduled."
  - type: Failed
    staus: "False"
    lastTransitionTime: 2019-10-09T03:13:45
    reason: Succeeded
    message: "Most recent image pruning job succeeded."
```
where:
spec.schedule

CronJob formatted schedule. This is an optional field, default is daily at midnight.

spec.suspend

If set to true, the CronJob running pruning is suspended. This is an optional field, default is false. The initial value on new clusters is false.

spec.keepTagRevisions

The number of revisions per tag to keep. This is an optional field, default is 3. The initial value is 3.

spec.keepYoungerThanDuration

Retain images younger than this duration. This is an optional field. If a value is not specified, either keepYoungerThan or the default value 60m (60 minutes) is used.

spec.keepYoungerThan

Deprecated. The same as keepYoungerThanDuration, but the duration is specified as an integer in nanoseconds. This is an optional field. When keepYoungerThanDuration is set, this field is ignored.

spec.resources

Standard pod resource requests and limits. This is an optional field.

spec.affinity

Standard pod affinity. This is an optional field.

nodeSelector

Standard pod node selector. This is an optional field.

spec.tolerations

Standard pod tolerations. This is an optional field.

spec.successfulJobsHistoryLimit

The maximum number of successful jobs to retain. Must be greater than or equal to 1 to ensure metrics are reported. This is an optional field, default is 3. The initial value is 3.

spec.failedJobsHistoryLimit

The maximum number of failed jobs to retain. Must be greater than or equal 1 to ensure metrics are reported. This is an optional field, default is 3. The initial value is 3.

status.observedGeneration

The generation observed by the Operator.

status.conditions
The standard condition objects with the following types:
Available: Indicates if the pruning job has been created. Reasons can be Ready or Error.

Scheduled: Indicates if the next pruning job has been scheduled. Reasons can be Scheduled, Suspended, or Error.

Failed: Indicates if the most recent pruning job failed.

Image prune conditions

Review the prerequisites, dependency checks, and soft-delete conditions required before removing registry images to safely prune image layers without breaking active pod deployments.

Red Hat OpenShift Container Platform supports two methodologies for pruning images:

Pruning by age and tag
Pruning by size limit

These methodologies are mutually exclusive. You must choose whether to prune by age and tag, or by size limit. Regardless of the method that you choose, the image pruner checks to ensure that images in use are not removed.

An image is only pruned if it meets the primary condition and is not actively referenced by a system component.

Image pruning by age and tag

Pruning an image by age and tag is the default pruning strategy. It identifies images for removal by using the --keep-younger-than and --keep-tag-revisions flags. To prune an image by age and tag, the image must be older than the --keep-younger-than threshold, not one of the most recent tag revisions, and cannot be in use by an active workload.

For an image to be pruned by age and tag, all of the following conditions must be met:

The image is managed by Red Hat OpenShift Container Platform or has the openshift.io/image.managed annotation.
The image is older than the time specified by the --keep-younger-than flag.
The image is not one of the most recent images for its tag, as specified by the --keep-tag-revisions flag.
The image is not currently referenced by any of the following active or recent API objects:
- Pods or image streams created more recently than the --keep-younger-than duration.
- Running or pending pods
- Deployments, replication controllers, replica sets, or stateful sets.
- Builds, build configurations, jobs, or cronjobs.
  
  An image is only removed if it is old, not a recent tag revision, and is confirmed to have no active references by system components.

Image pruning by size limit

Pruning an image by size limit uses the --prune-over-size-limit flag. This method is used to bring a project back under its defined image storage limit.

The --prune-over-size-limit flag cannot be combined with the --keep-tag-revisions flag nor the --keep-younger-than flags. Doing so returns information that this operation is not allowed.

For an image to be pruned using this method, all of the following conditions must be true:

The image is part of a project that is currently exceeding its smallest defined size limit.
The image is selected by the pruner as a candidate for deletion to reduce the total size.
The image is not currently referenced by any of the following active API objects:
- Pods that are in a running or pending state.
- Deployments, replication controllers, replica sets, or stateful sets.
- Builds, build configurations, jobs, or cronjobs.
  
  With this method, the primary trigger is the project’s size, but the safety check to ensure that the image is not actively in use is still performed.

Image pruning limitations

Review image layer removal rules and external registry limitations before running prune operations to predict layer deletion and avoid unpruned image streams.

Pruning images from external registries is unsupported.
When an image is pruned, all references to the image are removed from all image streams that contain the image in status.tags.
Image layers that are no longer referenced by any images are removed.