Over time, API objects created in {product-title} can accumulate in the etcd data store through normal user operations, such as when building and deploying applications.
As an administrator, you can periodically prune older versions of objects from your {product-title} instance that are no longer needed. For example, by pruning images you can delete older images and layers that are no longer in use, but are still taking up disk space.
The CLI groups prune operations under a common parent command.
$ oadm prune <object_type> <options>
This specifies:
-
The
<object_type>
to perform the action on, such asbuilds
,deployments
, orimages
. -
The
<options>
supported to prune that object type.
In order to prune deployments that are no longer required by the system due to age and status, administrators may run the following command:
$ oadm prune deployments [<options>]
Option | Description |
---|---|
|
Indicate that pruning should occur, instead of performing a dry-run. |
|
Prune all deployments whose deployment config no longer exists, status is complete or failed, and replica count is zero. |
|
Per deployment config, keep the last N deployments whose status is complete and
replica count is zero. (default |
|
Per deployment config, keep the last N deployments whose status is failed and
replica count is zero. (default |
|
Do not prune any object that is younger than |
To see what a pruning operation would delete:
$ oadm prune deployments --orphans --keep-complete=5 --keep-failed=1 \ --keep-younger-than=60m
To actually perform the prune operation:
$ oadm prune deployments --orphans --keep-complete=5 --keep-failed=1 \ --keep-younger-than=60m --confirm
In order to prune builds that are no longer required by the system due to age and status, administrators may run the following command:
$ oadm prune builds [<options>]
Option | Description |
---|---|
|
Indicate that pruning should occur, instead of performing a dry-run. |
|
Prune all builds whose build config no longer exists, status is complete, failed, error, or canceled. |
|
Per build config, keep the last N builds whose status is complete. (default
|
|
Per build config, keep the last N builds whose status is failed, error, or
canceled (default |
|
Do not prune any object that is younger than |
To see what a pruning operation would delete:
$ oadm prune builds --orphans --keep-complete=5 --keep-failed=1 \ --keep-younger-than=60m
To actually perform the prune operation:
$ oadm prune builds --orphans --keep-complete=5 --keep-failed=1 \ --keep-younger-than=60m --confirm
In order to prune images that are no longer required by the system due to age, status, or exceed limits, administrators may run the following command:
$ oadm prune images [<options>]
Note
|
Currently, to prune images you must first log in to the CLI as a user with an access token. The user must also have the cluster role system:image-pruner or greater (for example, cluster-admin). |
Option | Description |
---|---|
|
The path to a certificate authority file to use when communicating with the {product-title}-managed registries. Defaults to the certificate authority data from the current user’s config file. |
|
Indicate that pruning should occur, instead of performing a dry-run. |
|
For each image stream, keep up to at most N image revisions per tag. (default
|
|
Do not prune any image that is younger than |
|
Prune each image that exceeds the smallest limit
defined in the same project. This flag cannot be combined with |
{product-title} uses the following logic to determine which images and layers to prune:
Image Prune Conditions
-
Remove any image "managed by {product-title}" (images with the annotation
openshift.io/image.managed
) that was created at least--keep-younger-than
minutes ago and is not currently referenced by:-
any pod created less than
--keep-younger-than
minutes ago. -
any image stream created less than
--keep-younger-than
minutes ago. -
any running pods.
-
any pending pods.
-
any replication controllers.
-
any deployment configurations.
-
any build configurations.
-
any builds.
-
the
--keep-tag-revisions
most recent items instream.status.tags[].items
.
-
-
Remove any image "managed by {product-title}" (images with the annotation
openshift.io/image.managed
) that is exceeding the smallest limit defined in the same project and is not currently referenced by:-
any running pods.
-
any pending pods.
-
any replication controllers.
-
any deployment configurations.
-
any build configurations.
-
any builds.
-
-
There is no support for pruning from external registries.
-
When an image is pruned, all references to the image are removed from all image streams that have a reference to the image in
status.tags
. -
Image layers that are no longer referenced by any images are removed as well.
Note
|
|
To see what a pruning operation would delete:
-
Keeping up to three tag revisions, and keeping resources (images, image streams and pods) younger than sixty minutes:
$ oadm prune images --keep-tag-revisions=3 --keep-younger-than=60m
-
Pruning every image that exceeds defined limits:
$ oadm prune images --prune-over-size-limit
To actually perform the prune operation for the previously mentioned options accordingly:
$ oadm prune images --keep-tag-revisions=3 --keep-younger-than=60m --confirm $ oadm prune images --prune-over-size-limit --confirm
If your images keep accumulating and the prune
command removes just a small
portion of what you expect, ensure that you understand
the conditions that must apply for an image to be
considered a candidate for pruning.
Especially ensure that images you want removed occur at higher positions in each
tag
history than your chosen tag revisions threshold. For example, consider an old
and obsolete image named sha:abz
. By running the following command in
namespace N
, where the image is tagged, you will see the image is tagged three
times in a single image stream named myapp
:
$ image_name="sha:abz" $ oc get is -n N -o go-template='{{range $isi, $is := .items}}{{range $ti, $tag := $is.status.tags}}'\ '{{range $ii, $item := $tag.items}}{{if eq $item.image "'"${image_name}"\ $'"}}{{$is.metadata.name}}:{{$tag.tag}} at position {{$ii}} out of {{len $tag.items}}\n'\ '{{end}}{{end}}{{end}}{{end}}' myapp:v2 at position 4 out of 5 myapp:v2.1 at position 2 out of 2 myapp:v2.1-may-2016 at position 0 out of 1
When default options are used, the image will not ever be pruned because it
occurs at position 0
in a history of myapp:v2.1-may-2016
tag. For an image to
be considered for pruning, the administrator must either:
-
Specify
--keep-tag-revisions=0
with theoadm prune images
command.CautionThis action will effectively remove all the tags from all the namespaces with underlying images, unless they are younger or they are referenced by objects younger than the specified threshold.
-
Delete all the istags where the position is below the revision threshold, which means
myapp:v2.1
andmyapp:v2.1-may-2016
. -
Move the image further in the history, either by running new builds pushing to the same istag, or by tagging other image. Unfortunately, this is not always desirable for old release tags.
Tags having a date or time of a particular image’s build in their names should be avoided, unless the image needs to be preserved for undefined amount of time. Such tags tend to have just one image in its history, which effectively prevents them from ever being pruned. Learn more about istag naming.