gcrane-gc

List untagged images

$ gcrane gc [repository]

$ gcrane gc [repository] [[-r|--recursive]]

$ gcrane gc [[-h|--help]]

gcrane gc <repository> [flags...]

<repository>
    The full path to the container repository to clean up. Example: gcr.io/my-project/my-app.

-r, --recursive
    Recursively delete untagged images from all repositories underneath the specified <repository>.

--dry-run
    Do not delete any images; instead, print a list of what would be deleted if the command were run without this flag.
Highly recommended for safe operation.

--grace string
    The minimum age of untagged images to consider for deletion. Images newer than this period will be kept.
Examples: '1h' (1 hour), '24h' (24 hours), '7d' (7 days).
Default: '7d'

--keep-last int
    The number of most recent untagged images to keep, even if they are older than the grace period.

--allow-tags
    Allows the deletion of images that *do* have tags.
WARNING: Use with extreme caution as this can lead to unintended deletion of active images.

--keep-tags strings
    A comma-separated list of tags to explicitly keep, even if they would otherwise be deleted (e.g., 'latest,stable').
Useful when combined with --allow-tags.

--insecure
    Allow connecting to registries over HTTP.
Not recommended for production environments.

--platform string
    Filter images by their platform (e.g., 'linux/amd64'). Only images matching this platform will be considered for deletion.

--platform-os string
    Filter images by operating system (e.g., 'linux').

--platform-arch string
    Filter images by architecture (e.g., 'amd64').

--verbose
    Print more detailed output during execution, showing each image considered.

The gcrane-gc command, part of the gcrane utility (from the go-containerregistry project), is designed to help manage storage costs and optimize repository cleanliness within container registries like Google Container Registry (GCR) or Artifact Registry.

It identifies and deletes untagged image manifests and their associated layers that are older than a specified grace period. This is crucial for environments where many temporary or older images accumulate without being explicitly tagged, leading to unnecessary storage consumption and potential cost increases.

While primarily focused on untagged images, it offers options for more aggressive cleanup, including the deletion of tagged images, though this should be used with extreme caution. The command emphasizes safety through its --dry-run option, allowing users to preview deletions before executing them permanently.

gcrane-gc performs destructive operations. Once images are deleted, they cannot be recovered.

The --allow-tags flag is particularly dangerous as it enables the deletion of actively tagged images, which can break deployments or lead to data loss. Always use --dry-run first to understand the impact of your command before actual execution, especially when using aggressive options.

Ensure the authenticated user or service account has the necessary permissions (e.g., storage.objects.delete for GCR/Artifact Registry) to perform deletions in the specified repository.

To successfully run gcrane gc, the identity executing the command must have permissions to list and delete objects within the target container repository. For Google Container Registry or Artifact Registry, this typically means having roles like Storage Object Admin or custom roles with permissions such as storage.objects.list and storage.objects.delete.

A safe and recommended workflow for using gcrane gc is:
1. Run with --dry-run to see what will be deleted:
gcrane gc --dry-run gcr.io/my-project/my-app
2. Review the output carefully to ensure only desired images are targeted.
3. If satisfied, run the command without --dry-run to perform the actual deletions:
gcrane gc gcr.io/my-project/my-app

The gcrane utility is part of the go-containerregistry project, an open-source Go library and set of command-line tools developed by Google. It provides a lightweight, robust, and programmatic way to interact with OCI-compliant container registries. The gc (garbage collection) subcommand was introduced to address the common operational need for managing untagged and old image layers, helping users maintain clean and cost-effective container image repositories without relying solely on cloud provider-specific garbage collection policies or complex scripting.

gcrane(1), crane(1), gcloud container images delete(1), docker rmi(1), skopeo delete(1)