From 1f9c2bc5e321ef42e3d4198ddc512a207a89810e Mon Sep 17 00:00:00 2001 From: Steven Smith Date: Fri, 15 Aug 2025 13:47:20 -0400 Subject: [PATCH] Update Image prune conditions docs --- applications/pruning-objects.adoc | 5 + modules/pruning-images-conditions.adoc | 63 ++++ modules/pruning-images-job-cronjob.adoc | 172 +++++++++++ modules/pruning-images-manual.adoc | 277 ++---------------- modules/pruning-images-options.adoc | 83 ++++++ modules/pruning-images-running-operation.adoc | 36 +++ modules/pruning-images-secure-insecure.adoc | 29 ++ 7 files changed, 412 insertions(+), 253 deletions(-) create mode 100644 modules/pruning-images-conditions.adoc create mode 100644 modules/pruning-images-job-cronjob.adoc create mode 100644 modules/pruning-images-options.adoc create mode 100644 modules/pruning-images-running-operation.adoc create mode 100644 modules/pruning-images-secure-insecure.adoc diff --git a/applications/pruning-objects.adoc b/applications/pruning-objects.adoc index 48730b4333..5e36a65b4b 100644 --- a/applications/pruning-objects.adoc +++ b/applications/pruning-objects.adoc @@ -38,6 +38,11 @@ include::modules/pruning-images.adoc[leveloffset=+1] //cannot create resource "serviceaccounts". cannot create resource "cronjobs" ifndef::openshift-rosa,openshift-dedicated[] include::modules/pruning-images-manual.adoc[leveloffset=+1] +//include::modules/pruning-images-job-cronjob.adoc[leveloffset=+2] +include::modules/pruning-images-conditions.adoc[leveloffset=+2] +include::modules/pruning-images-running-operation.adoc[leveloffset=+2] +include::modules/pruning-images-secure-insecure.adoc[leveloffset=+2] +include::modules/pruning-images-options.adoc[leveloffset=+2] include::modules/pruning-images-troubleshooting.adoc[leveloffset=+2] [role="_additional-resources"] diff --git a/modules/pruning-images-conditions.adoc b/modules/pruning-images-conditions.adoc new file mode 100644 index 0000000000..f60bce4797 --- /dev/null +++ b/modules/pruning-images-conditions.adoc @@ -0,0 +1,63 @@ +// Module included in the following assemblies: +// +// * applications/pruning-objects.adoc + +:_mod-docs-content-type: REFERENCE +[id="pruning-images-conditions_{context}"] += Image prune conditions + +{product-title} 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. + +[id="pruning-images-age-tag_{context}"] +== Pruning an image 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 {product-title} 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. + +[id="pruning-images-size-limit_{context}"] +== Pruning an image 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. + +[NOTE] +==== +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. \ No newline at end of file diff --git a/modules/pruning-images-job-cronjob.adoc b/modules/pruning-images-job-cronjob.adoc new file mode 100644 index 0000000000..7e89fc5a4f --- /dev/null +++ b/modules/pruning-images-job-cronjob.adoc @@ -0,0 +1,172 @@ +// Module included in the following assemblies: +// +// * applications/pruning-objects.adoc + +:_mod-docs-content-type: PROCEDURE +[id="pruning-images-job-cronjob_{context}"] += Running image pruning as a Job or CronJob + +You can configure image pruning to run on a schedule by creating a `Job` or `CronJob` that invokes the pruning operation on the cluster. +This approach allows administrators to automate pruning at regular intervals without relying on the image pruning custom resource. + + +.Prerequisites + +* To prune images, you must first log in to the CLI as a user with an access token. The user must also have the `system:image-pruner` cluster role or greater (for example, `cluster-admin`). +* Expose the image registry. + +.Procedure + +To manually prune images that are no longer required by the system due to age, status, or exceed limits, use one of the following methods: + +* Run image pruning as a `Job` or `CronJob` on the cluster by creating a YAML file for the `pruner` service account, for example: ++ +[source,terminal] +---- +$ oc create -f .yaml +---- ++ +.Example output ++ +[source,yaml] +---- +kind: List +apiVersion: v1 +items: +- apiVersion: v1 + kind: ServiceAccount + metadata: + name: pruner + namespace: openshift-image-registry +- apiVersion: rbac.authorization.k8s.io/v1 + kind: ClusterRoleBinding + metadata: + name: openshift-image-registry-pruner + roleRef: + apiGroup: rbac.authorization.k8s.io + kind: ClusterRole + name: system:image-pruner + subjects: + - kind: ServiceAccount + name: pruner + namespace: openshift-image-registry +- apiVersion: batch/v1 + kind: CronJob + metadata: + name: image-pruner + namespace: openshift-image-registry + spec: + schedule: "0 0 * * *" + concurrencyPolicy: Forbid + successfulJobsHistoryLimit: 1 + failedJobsHistoryLimit: 3 + jobTemplate: + spec: + template: + spec: + restartPolicy: OnFailure + containers: + - image: "quay.io/openshift/origin-cli:4.1" + resources: + requests: + cpu: 1 + memory: 1Gi + terminationMessagePolicy: FallbackToLogsOnError + command: + - oc + args: + - adm + - prune + - images + - --certificate-authority=/var/run/secrets/kubernetes.io/serviceaccount/service-ca.crt + - --keep-tag-revisions=5 + - --keep-younger-than=96h + - --confirm=true + name: image-pruner + serviceAccountName: pruner +---- + +* Run the `oc adm prune images []` command: ++ +[source,terminal] +---- +$ oc adm prune images [] +---- ++ +Pruning images removes data from the integrated registry unless `--prune-registry=false` is used. ++ +Pruning images with the `--namespace` flag does not remove images, only image streams. Images are non-namespaced resources. Therefore, limiting pruning to a particular namespace makes it impossible to calculate its current usage. ++ +By default, the integrated registry caches metadata of blobs to reduce the number of requests to storage, and to increase the request-processing speed. Pruning does not update the integrated registry cache. Images that still contain pruned layers after pruning will be broken because the pruned layers that have metadata in the cache will not be pushed. Therefore, you must redeploy the registry to clear the cache after pruning: ++ +[source,terminal] +---- +$ oc rollout restart deployment/image-registry -n openshift-image-registry +---- ++ +If the integrated registry uses a Redis cache, you must clean the database manually. ++ +If redeploying the registry after pruning is not an option, then you must permanently disable the cache. ++ +`oc adm prune images` operations require a route for your registry. Registry routes are not created by default. ++ +The *Prune images CLI configuration options* table describes the options you can use with the `oc adm prune images ` command. ++ +.Prune images CLI configuration options +[cols="4,8",options="header"] +|=== + +|Option |Description + +.^|`--all` +|Include images that were not pushed to the registry, but have been mirrored by +pullthrough. This is on by default. To limit the pruning to images that were +pushed to the integrated registry, pass `--all=false`. + +.^|`--certificate-authority` +|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 configuration file. If provided, a secure connection is +initiated. + +.^|`--confirm` +|Indicate that pruning should occur, instead of performing a test-run. This +requires a valid route to the integrated container image registry. If this +command is run outside of the cluster network, the route must be provided +using `--registry-url`. + +.^|`--force-insecure` +|Use caution with this option. Allow an insecure connection to the container +registry that is hosted via HTTP or has an invalid HTTPS certificate. + +.^|`--keep-tag-revisions=` +|For each imagestream, keep up to at most `N` image revisions per tag (default +`3`). + +.^|`--keep-younger-than=` +|Do not prune any image that is younger than `` relative to the +current time. Alternately, do not prune any image that is referenced by any other object that +is younger than `` relative to the current time (default `60m`). + +.^|`--prune-over-size-limit` +|Prune each image that exceeds the smallest limit defined in the same project. +This flag cannot be combined with `--keep-tag-revisions` nor +`--keep-younger-than`. + +.^|`--registry-url` +|The address to use when contacting the registry. The command attempts to use a +cluster-internal URL determined from managed images and image streams. In case +it fails (the registry cannot be resolved or reached), an alternative route that +works needs to be provided using this flag. The registry hostname can be +prefixed by `https://` or `http://`, which enforces particular connection +protocol. + +.^|`--prune-registry` +|In conjunction with the conditions stipulated by the other options, this option +controls whether the data in the registry corresponding to the {product-title} +image API object is pruned. By default, image pruning processes both the image +API objects and corresponding data in the registry. + +This option is useful when you are only concerned with removing etcd content, to reduce the number of image objects but are not concerned with cleaning up registry storage, or if you intend to do that separately by hard pruning the registry during an appropriate maintenance window for the registry. +|=== + diff --git a/modules/pruning-images-manual.adoc b/modules/pruning-images-manual.adoc index fc549aecfb..67b22d22fa 100644 --- a/modules/pruning-images-manual.adoc +++ b/modules/pruning-images-manual.adoc @@ -2,280 +2,51 @@ // // * applications/pruning-objects.adoc -:_mod-docs-content-type: PROCEDURE +:_mod-docs-content-type: CONCEPT [id="pruning-images-manual_{context}"] = Manually pruning images // out of scope for this PR - needs to be split into multiple modules, there shouldn't be multiple procedures in one module -The pruning custom resource enables automatic image pruning for the images from the {product-registry}. However, administrators can manually prune images that are no longer required by the system due to age, status, or exceed limits. There are two methods to manually prune images: +The pruning custom resource enables automatic image pruning for the images from the {product-registry}. Administrators can manually prune images with the `oc adm prune images ` command. For example: -* Running image pruning as a `Job` or `CronJob` on the cluster. -* Running the `oc adm prune images` command. - -.Prerequisites - -* To prune images, you must first log in to the CLI as a user with an access token. The user must also have the `system:image-pruner` cluster role or greater (for example, `cluster-admin`). -* Expose the image registry. - -.Procedure - -To manually prune images that are no longer required by the system due to age, status, or exceed limits, use one of the following methods: - -* Run image pruning as a `Job` or `CronJob` on the cluster by creating a YAML file for the `pruner` service account, for example: -+ [source,terminal] ---- -$ oc create -f .yaml ----- -+ -.Example output -+ -[source,yaml] ----- -kind: List -apiVersion: v1 -items: -- apiVersion: v1 - kind: ServiceAccount - metadata: - name: pruner - namespace: openshift-image-registry -- apiVersion: rbac.authorization.k8s.io/v1 - kind: ClusterRoleBinding - metadata: - name: openshift-image-registry-pruner - roleRef: - apiGroup: rbac.authorization.k8s.io - kind: ClusterRole - name: system:image-pruner - subjects: - - kind: ServiceAccount - name: pruner - namespace: openshift-image-registry -- apiVersion: batch/v1 - kind: CronJob - metadata: - name: image-pruner - namespace: openshift-image-registry - spec: - schedule: "0 0 * * *" - concurrencyPolicy: Forbid - successfulJobsHistoryLimit: 1 - failedJobsHistoryLimit: 3 - jobTemplate: - spec: - template: - spec: - restartPolicy: OnFailure - containers: - - image: "quay.io/openshift/origin-cli:4.1" - resources: - requests: - cpu: 1 - memory: 1Gi - terminationMessagePolicy: FallbackToLogsOnError - command: - - oc - args: - - adm - - prune - - images - - --certificate-authority=/var/run/secrets/kubernetes.io/serviceaccount/service-ca.crt - - --keep-tag-revisions=5 - - --keep-younger-than=96h - - --confirm=true - name: image-pruner - serviceAccountName: pruner +$ oc adm prune images <1> ---- +<1> For more information about available pruning options, see "Manual image pruning command options". -* Run the `oc adm prune images []` command: -+ -[source,terminal] ----- -$ oc adm prune images [] ----- -+ -Pruning images removes data from the integrated registry unless `--prune-registry=false` is used. -+ -Pruning images with the `--namespace` flag does not remove images, only image streams. Images are non-namespaced resources. Therefore, limiting pruning to a particular namespace makes it impossible to calculate its current usage. -+ -By default, the integrated registry caches metadata of blobs to reduce the number of requests to storage, and to increase the request-processing speed. Pruning does not update the integrated registry cache. Images that still contain pruned layers after pruning will be broken because the pruned layers that have metadata in the cache will not be pushed. Therefore, you must redeploy the registry to clear the cache after pruning: +This command removes images that are no longer required by the system. + +Depending on your needs, you can prune images based on their age and tag history, or prune images that cause a project to exceed its defined storage limits. + +[id="considerations-pruning-images_{context}"] +== Considerations when pruning images + +Consider the following information before manually pruning images: + +* Pruning with the `--namespace` flag does not remove images. It only removes image streams, because images are cluster-scoped resources. Limiting pruning to a particular namespace makes it impossible to calculate current usage. + +* By default, the integrated registry caches metadata of blobs to reduce the number of requests to storage, and to increase request-processing speed. Pruning does not update the integrated registry cache. Images that still contain pruned layers after pruning will be broken because the pruned layers that have metadata in the cache will not be pushed. Therefore, you must redeploy the registry to clear the cache after pruning: + [source,terminal] ---- $ oc rollout restart deployment/image-registry -n openshift-image-registry ---- -+ -If the integrated registry uses a Redis cache, you must clean the database manually. -+ -If redeploying the registry after pruning is not an option, then you must permanently disable the cache. -+ -`oc adm prune images` operations require a route for your registry. Registry routes are not created by default. -+ -The *Prune images CLI configuration options* table describes the options you can use with the `oc adm prune images ` command. -+ -.Prune images CLI configuration options -[cols="4,8",options="header"] -|=== -|Option |Description +* If the integrated registry uses a Redis cache, you must clean the database manually. -.^|`--all` -|Include images that were not pushed to the registry, but have been mirrored by -pullthrough. This is on by default. To limit the pruning to images that were -pushed to the integrated registry, pass `--all=false`. +* If redeploying the registry after pruning is not an option, then you must permanently disable the cache. -.^|`--certificate-authority` -|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 configuration file. If provided, a secure connection is -initiated. +* `oc adm prune images` operations require a route for your registry. Registry routes are not created by default. -.^|`--confirm` -|Indicate that pruning should occur, instead of performing a test-run. This -requires a valid route to the integrated container image registry. If this -command is run outside of the cluster network, the route must be provided -using `--registry-url`. -.^|`--force-insecure` -|Use caution with this option. Allow an insecure connection to the container -registry that is hosted via HTTP or has an invalid HTTPS certificate. +[id="additional-pruning-limitations_{context}"] +== Limitations when pruning images -.^|`--keep-tag-revisions=` -|For each imagestream, keep up to at most `N` image revisions per tag (default -`3`). +The following limitations apply when pruning an image: -.^|`--keep-younger-than=` -|Do not prune any image that is younger than `` relative to the -current time. Alternately, do not prune any image that is referenced by any other object that -is younger than `` relative to the current time (default `60m`). +* Pruning images from external registries is unsupported. -.^|`--prune-over-size-limit` -|Prune each image that exceeds the smallest limit defined in the same project. -This flag cannot be combined with `--keep-tag-revisions` nor -`--keep-younger-than`. +* When an image is pruned, all references to the image are removed from all image streams that contain the image in `status.tags`. -.^|`--registry-url` -|The address to use when contacting the registry. The command attempts to use a -cluster-internal URL determined from managed images and image streams. In case -it fails (the registry cannot be resolved or reached), an alternative route that -works needs to be provided using this flag. The registry hostname can be -prefixed by `https://` or `http://`, which enforces particular connection -protocol. - -.^|`--prune-registry` -|In conjunction with the conditions stipulated by the other options, this option -controls whether the data in the registry corresponding to the {product-title} -image API object is pruned. By default, image pruning processes both the image -API objects and corresponding data in the registry. - -This option is useful when you are only concerned with removing etcd content, to reduce the number of image objects but are not concerned with cleaning up registry storage, or if you intend to do that separately by hard pruning the registry during an appropriate maintenance window for the registry. -|=== - -[id="pruning-images-conditions_{context}"] -== Image prune conditions - -You can apply conditions to your manually pruned images. - -* To remove any image managed by {product-title}, or images with the annotation `openshift.io/image.managed`: -** Created at least `--keep-younger-than` minutes ago and are not currently referenced by any: -*** Pods created less than `--keep-younger-than` minutes ago -*** Image streams created less than `--keep-younger-than` minutes ago -*** Running pods -*** Pending pods -*** Replication controllers -*** Deployments -*** Deployment configs -*** Replica sets -*** Build configurations -*** Builds -*** Jobs -*** Cronjobs -*** Stateful sets -*** `--keep-tag-revisions` most recent items in `stream.status.tags[].items` -** That are exceeding the smallest limit defined in the same project and are not currently referenced by any: -*** Running pods -*** Pending pods -*** Replication controllers -*** Deployments -*** Deployment configs -*** Replica sets -*** Build configurations -*** Builds -*** Jobs -*** Cronjobs -*** Stateful sets -* 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. - -[NOTE] -==== -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. -==== - -Separating the removal of {product-title} image API objects and image data from the registry by using `--prune-registry=false`, followed by hard pruning the registry, can narrow timing windows and is safer when compared to trying to prune both through one command. However, timing windows are not completely removed. - -For example, you can still create a pod referencing an image as pruning identifies that image for pruning. You should still keep track of an API object created during the pruning operations that might reference images so that you can mitigate any references to deleted content. - -Re-doing the pruning without the `--prune-registry` option or with `--prune-registry=true` does not lead to pruning the associated storage in the image registry for images previously pruned by `--prune-registry=false`. Any images that were pruned with `--prune-registry=false` can only be deleted from registry storage by hard pruning the registry. - -[id="pruning-images-running-operation_{context}"] -== Running the image prune operation - -.Procedure - -. To see what a pruning operation would delete: - -.. Keeping up to three tag revisions, and keeping resources (images, image streams, and pods) younger than 60 minutes: -+ -[source,terminal] ----- -$ oc adm prune images --keep-tag-revisions=3 --keep-younger-than=60m ----- - -.. Pruning every image that exceeds defined limits: -+ -[source,terminal] ----- -$ oc adm prune images --prune-over-size-limit ----- - -. To perform the prune operation with the options from the previous step: -+ -[source,terminal] ----- -$ oc adm prune images --keep-tag-revisions=3 --keep-younger-than=60m --confirm ----- -+ -[source,terminal] ----- -$ oc adm prune images --prune-over-size-limit --confirm ----- - -[id="pruning-images-secure-insecure_{context}"] -== Using secure or insecure connections - -The secure connection is the preferred and recommended approach. It is done over -HTTPS protocol with a mandatory certificate verification. The `prune` command -always attempts to use it if possible. If it is not possible, in some cases it -can fall-back to insecure connection, which is dangerous. In this case, either -certificate verification is skipped or plain HTTP protocol is used. - -The fall-back to insecure connection is allowed in the following cases unless -`--certificate-authority` is specified: - -. The `prune` command is run with the `--force-insecure` option. -. The provided `registry-url` is prefixed with the `http://` scheme. -. The provided `registry-url` is a local-link address or `localhost`. -. The configuration of the current user allows for an insecure connection. This -can be caused by the user either logging in using `--insecure-skip-tls-verify` -or choosing the insecure connection when prompted. - -[IMPORTANT] -==== -If the registry is secured by a certificate authority different from the one used by {product-title}, it must be specified using the -`--certificate-authority` flag. Otherwise, the `prune` command fails with an error. -==== diff --git a/modules/pruning-images-options.adoc b/modules/pruning-images-options.adoc new file mode 100644 index 0000000000..b57c915830 --- /dev/null +++ b/modules/pruning-images-options.adoc @@ -0,0 +1,83 @@ +// Module included in the following assemblies: +// +// * applications/pruning-objects.adoc + +:_mod-docs-content-type: REFERENCE +[id="pruning-images-options_{context}"] += Image pruning CLI options + +The following table describes the options you can use with the `oc adm prune images ` command. + +.Manual image pruning command options +[cols="4,8",options="header"] +|=== + +|Option |Description + +.^|`--all` +|Include images that were not pushed to the registry, but have been mirrored by +pullthrough. This is on by default. To limit the pruning to images that were +pushed to the integrated registry, pass `--all=false`. + +.^|`--certificate-authority` +|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 configuration file. If provided, a secure connection is +initiated. + +.^|`--confirm` +|Indicate that pruning should occur, instead of performing a test-run. This +requires a valid route to the integrated container image registry. If this +command is run outside of the cluster network, the route must be provided +using `--registry-url`. + +.^|`--force-insecure` +|Use caution with this option. Allow an insecure connection to the container +registry that is hosted via HTTP or has an invalid HTTPS certificate. + +.^|`--keep-tag-revisions=` +|For each imagestream, keep up to at most `N` image revisions per tag (default +`3`). + +.^|`--keep-younger-than=` +|Do not prune any image that is younger than `` relative to the +current time. Alternately, do not prune any image that is referenced by any other object that +is younger than `` relative to the current time (default `60m`). + +.^|`--prune-over-size-limit` +|Prune each image that exceeds the smallest limit defined in the same project. +This flag cannot be combined with `--keep-tag-revisions` nor +`--keep-younger-than`. + +.^|`--registry-url` +|The address to use when contacting the registry. The command attempts to use a +cluster-internal URL determined from managed images and image streams. In case +it fails (the registry cannot be resolved or reached), an alternative route that +works needs to be provided using this flag. The registry hostname can be +prefixed by `https://` or `http://`, which enforces particular connection +protocol. + +.^|`--prune-registry` +|In conjunction with the conditions stipulated by the other options, this option +controls whether the data in the registry corresponding to the {product-title} +image API object is pruned. By default, image pruning processes both the image +API objects and corresponding data in the registry. + +This option is useful when you are only concerned with removing etcd content, to reduce the number of image objects but are not concerned with cleaning up registry storage, or if you intend to do that separately by hard pruning the registry during an appropriate maintenance window for the registry. +|=== + +[id="information-about-prune-registry-flag_{context}"] +== Additional information about the --prune-registry flag + +You can separate the removal of {product-title} image API objects from the removal of image data in the registry by passing in the `--prune-registry=false` flag. For example, the following command prunes only the API objects, leaving the registry storage untouched: + +[source,terminal] +---- +$ oc adm prune images --keep-tag-revisions=3 --keep-younger-than=60m --confirm --prune-registry=false +---- + +Then, you can perform a hard prune of the registry to remove the associated image data. This approach can narrow the timing window for race conditions compared to pruning both in a single command. + +However, timing windows are not completely eliminated. For example, a pod might still be created that references an image while that image is being identified for pruning. You should track any API objects created during pruning to ensure that they do not reference deleted content. + +Re-running the pruning without the `--prune-registry` option, or with `--prune-registry=true`, does not remove the associated registry storage for images previously pruned with `--prune-registry=false`. Those images can only be removed from registry storage by performing a hard prune of the registry. For more information, see "Hard pruning the registry". diff --git a/modules/pruning-images-running-operation.adoc b/modules/pruning-images-running-operation.adoc new file mode 100644 index 0000000000..91d38ed2fb --- /dev/null +++ b/modules/pruning-images-running-operation.adoc @@ -0,0 +1,36 @@ +// Module included in the following assemblies: +// +// * applications/pruning-objects.adoc + +:_mod-docs-content-type: PROCEDURE +[id="pruning-images-running-operation_{context}"] += Running image prune operations + +Use the following procedure to run an image prune operation + +.Prerequisites + +* You must be logged into the CLI with an access token. +* You must have the `system:image-pruner` cluster role or greater (for example, `cluster-admin`). +* The image registry must be exposed. +* You have reviewed the "Considerations when manually pruning images" section of this document. + +.Procedure + +. Optional: To preview which images would be pruned, enter the following command. This command prints a list of the images, image streams, and pods that would be removed. Note that nothing is deleted until you add the `--confirm` flag. ++ +[source,terminal] +---- +$ oc adm prune images <1> +---- +<1> For more information about available pruning options, see "Manual image pruning command options". + + +. Review the output to confirm the list of images, image streams, and pods to be removed. + +. Run the `oc adm prune images` command with the appropriate options for your cluster. Add the `--confirm` flag to confirm deletion. For example: ++ +[source,terminal] +---- +$ oc adm prune images --confirm +---- \ No newline at end of file diff --git a/modules/pruning-images-secure-insecure.adoc b/modules/pruning-images-secure-insecure.adoc new file mode 100644 index 0000000000..fd5fc4b9cd --- /dev/null +++ b/modules/pruning-images-secure-insecure.adoc @@ -0,0 +1,29 @@ +// Module included in the following assemblies: +// +// * applications/pruning-objects.adoc + +:_mod-docs-content-type: REFERENCE +[id="pruning-images-secure-insecure_{context}"] += Using secure or insecure connections + +The secure connection is the preferred and recommended approach. It is done over +HTTPS protocol with a mandatory certificate verification. The `prune` command +always attempts to use it if possible. If it is not possible, in some cases it +can fall-back to insecure connection, which is dangerous. In this case, either +certificate verification is skipped or plain HTTP protocol is used. + +The fall-back to insecure connection is allowed in the following cases unless +`--certificate-authority` is specified: + +. The `prune` command is run with the `--force-insecure` option. +. The provided `registry-url` is prefixed with the `http://` scheme. +. The provided `registry-url` is a local-link address or `localhost`. +. The configuration of the current user allows for an insecure connection. This +can be caused by the user either logging in using `--insecure-skip-tls-verify` +or choosing the insecure connection when prompted. + +[IMPORTANT] +==== +If the registry is secured by a certificate authority different from the one used by {product-title}, it must be specified using the +`--certificate-authority` flag. Otherwise, the `prune` command fails with an error. +==== \ No newline at end of file