OC-ADM-PRUNE-IMAGES(1)

📦
version 4.22.0 · 2 versions
, in nixpkgs unstable

💅 oc adm prune images — the glow-up your registry deserves

hey bestie, welcome to the oc adm prune images page — it lives in the oc manual (OpenShift CLI user manuals, if we're being official about it), and honestly? it's giving spring cleaning for your image registry. let's get into it 🧹✨

✨ NAME ✨

oc adm prune images — literally removes unreferenced images. that's the whole vibe. 🗑️💖

🌸 SYNOPSIS 🌸

oc adm prune images [OPTIONS]

🦋 DESCRIPTION 🦋

okay so here's the tea: this command removes image stream tags, images, and image layers — by age or by usage. no cap.

it yanks historical image stream tags, unused images, and unreferenced image layers out of the integrated registry. by default, all images are considered candidates (everybody's invited to the prune party 🎉). but if you want it to only consider images that were directly pushed to the registry, you pass --all=false — that narrows the guest list.

by default, the prune operation does a dry run — it changes absolutely nothing in the internal registry. it's the "add to cart but don't checkout" of registry maintenance 🙈. you need a --confirm flag for changes to actually be effective. and heads up: that flag requires a valid route to the integrated container image registry. if you're running this outside of the cluster network, you gotta provide that route using --registry-url.

also, permission check 👑: only a user with the cluster role system:image-pruner or higher who is logged-in will be able to actually delete the images. main character energy only, sorry.

if the registry is secured with a certificate signed by a self-signed root certificate authority other than the one present in the current user's config, you may need to specify it using the --certificate-authority flag. 💅

insecure connection is allowed in the following cases unless certificate-authority is specified:

  • --force-insecure is given
  • the provided registry-url is prefixed with http://
  • the registry url is a private or link-local address
  • the user's config allows for insecure connection (the user logged in to the cluster with --insecure-skip-tls-verify or allowed for insecure connection)

🎀 OPTIONS 🎀

  • --all=true — include images that were imported from external registries as candidates for pruning. if pruned, all the mirrored objects associated with them will also be removed from the integrated registry. so like, they're a package deal 🫶
  • --certificate-authority="" — the path to a certificate authority bundle to use when communicating with the managed container image registries. defaults to the certificate authority data from the current user's config file. it cannot be used together with --force-insecure. pick a lane, bestie 😤
  • --confirm=false — if true, specify that image pruning should proceed. defaults to false, which means it displays what would be deleted but doesn't actually delete anything. requires a valid route to the integrated container image registry (see --registry-url). this is the "yes queen, do it" flag 👑
  • --force-insecure=false — if true, allow an insecure connection to the container image registry that is hosted via HTTP or has an invalid HTTPS certificate. whenever possible, use --certificate-authority instead of this dangerous option. i said what i said 💀
  • --ignore-invalid-refs=false — if true, the pruning process will ignore all errors while parsing image references. this means the pruning process will ignore the intended connection between the object and the referenced image. as a result, an image may be incorrectly deleted as unused. yeah… that's the risk, fr fr 😬
  • --keep-tag-revisions=3 — specify the number of image revisions for a tag in an image stream that will be preserved. three is the default, and three is sacred ✨
  • --keep-younger-than=0 — specify the minimum age of an image and its referrers for it to be considered a candidate for pruning. 0 means nobody gets a grace period 🍓
  • --num-workers=5 — specify the number of parallel workers to use when running prune operations. five little worker bees 🐝
  • --prune-over-size-limit=false — specify if images which are exceeding LimitRanges (see 'openshift.io/Image'), specified in the same namespace, should be considered for pruning. this flag cannot be combined with --keep-younger-than nor --keep-tag-revisions. it's an exclusive situation 💅
  • --prune-registry=true — if false, the prune operation will clean up image API objects, but none of the associated content in the registry is removed. note: if only image API objects are cleaned up through use of this flag, the only means for subsequently cleaning up registry data corresponding to those image API objects is to employ the 'hard prune' administrative task. so like, remember where you left that mess 🧚
  • --registry-url="" — the address to use when contacting the registry, instead of using the default value. this is useful if you can't resolve or reach the registry (e.g.; the default is a cluster-internal URL) but you do have an alternative route that works. particular transport protocol can be enforced using '<scheme>://' prefix. very handy, very iconic 🌈

💜 OPTIONS INHERITED FROM PARENT COMMANDS 💜

these are the family traits, bestie — inherited from the parent command:

  • --as="" — username to impersonate for the operation. user could be a regular user or a service account in a namespace. be someone else for a bit, why not 🎭
  • --as-group=[] — group to impersonate for the operation, this flag can be repeated to specify multiple groups.
  • --as-uid="" — UID to impersonate for the operation.
  • --as-user-extra=[] — user extras to impersonate for the operation, this flag can be repeated to specify multiple values for the same key.
  • --cache-dir="/homeless-shelter/.kube/cache" — default cache directory. yes that's the literal default path, no i'm not joking 🏠
  • --client-certificate="" — path to a client certificate file for TLS
  • --client-key="" — path to a client key file for TLS
  • --cluster="" — the name of the kubeconfig cluster to use
  • --context="" — the name of the kubeconfig context to use
  • --disable-compression=false — if true, opt-out of response compression for all requests to the server
  • --insecure-skip-tls-verify=false — if true, the server's certificate will not be checked for validity. this will make your HTTPS connections insecure 😭
  • --kubeconfig="" — path to the kubeconfig file to use for CLI requests.
  • --kuberc="" — path to the kuberc file to use for preferences. this can be disabled by exporting KUBECTL_KUBERC=false feature gate or turning off the feature KUBERC=off.
  • --match-server-version=false — require server version to match client version
  • -n, --namespace="" — if present, the namespace scope for this CLI request
  • --profile="none" — name of profile to capture. one of (none|cpu|heap|goroutine|threadcreate|block|mutex)
  • --profile-output="profile.pprof" — name of the file to write the profile to
  • --request-timeout="0" — the length of time to wait before giving up on a single server request. non-zero values should contain a corresponding time unit (e.g. 1s, 2m, 3h). a value of zero means don't timeout requests. zero = no clock, no stress ⏰
  • -s, --server="" — the address and port of the Kubernetes API server
  • --tls-server-name="" — server name to use for server certificate validation. if it is not provided, the hostname used to contact the server is used
  • --token="" — bearer token for authentication to the API server
  • --user="" — the name of the kubeconfig user to use
  • --warnings-as-errors=false — treat warnings received from the server as errors and exit with a non-zero exit code. no warning erasure here, we listen 🫡

🔥 EXAMPLE 🔥

# See what the prune command would delete if only images and their referrers were more than an hour old
# and obsoleted by 3 newer revisions under the same tag were considered
oc adm prune images --keep-tag-revisions=3 --keep-younger-than=60m

# To actually perform the prune operation, the confirm flag must be appended
oc adm prune images --keep-tag-revisions=3 --keep-younger-than=60m --confirm

# See what the prune command would delete if we are interested in removing images
# exceeding currently set limit ranges ('openshift.io/Image')
oc adm prune images --prune-over-size-limit

# To actually perform the prune operation, the confirm flag must be appended
oc adm prune images --prune-over-size-limit --confirm

# Force the insecure HTTP protocol with the particular registry host name
oc adm prune images --registry-url=http://registry.example.org --confirm

# Force a secure connection with a custom certificate authority to the particular registry host name
oc adm prune images --registry-url=registry.example.org --certificate-authority=/path/to/custom/ca.crt --confirm
⚠️ notice how every "actually delete stuff" example has --confirm on it? that's not a coincidence, bestie. dry run is the default for a reason. do your vibe check before you commit 💀

⭐ SEE ALSO ⭐

oc-adm-prune(1)

🦋 HISTORY 🦋

June 2016, ported from the Kubernetes man-doc generator. vintage! an elder icon 🎀

and that's the page, bestie 🫶 — brought to you by Openshift (OpenShift CLI User Manuals), dated June 2016, original header OC ADM PRUNE(1) and all. go forth and prune responsibly, mwah 💖✨🌷

📦 where this page comes from