petrasrec / gcr-cleaner

Delete untagged image refs in Google Container Registry or Artifact Registry

GCR Cleaner

GCR Cleaner deletes stale images in Google Cloud Container Registry or Google Cloud Artifact Registry. This can help reduce costs and keep your container images list in order.

GCR Cleaner is designed to be deployed as a Cloud Run service and invoked periodically via Cloud Scheduler.

+-------------------+    +-------------+    +-------+
|  Cloud Scheduler  | -> |  Cloud Run  | -> |  GCR  |
+-------------------+    +-------------+    +-------+

This is not an official Google product.

Setup

1. Install the Cloud SDK for your operating system. Alternatively, you can run these commands from Cloud Shell, which has the SDK and other popular tools pre-installed.

2. Export your project ID as an environment variable. The rest of this setup assumes this environment variable is set.

   export PROJECT_ID="my-project"

   Note this is your project ID, not the project number or name.

3. Enable the Google APIs - this only needs to be done once per project:

   gcloud services enable --project "${PROJECT_ID}" \
     appengine.googleapis.com \
     cloudscheduler.googleapis.com \
     run.googleapis.com

   This operation can take a few minutes, especially for recently-created projects.

4. Create a service account which will be assigned to the Cloud Run service:

   gcloud iam service-accounts create "gcr-cleaner" \
     --project "${PROJECT_ID}" \
     --display-name "gcr-cleaner"

5. Deploy the gcr-cleaner container on Cloud Run running as the service account just created:

   gcloud --quiet run deploy "gcr-cleaner" \
     --async \
     --project ${PROJECT_ID} \
     --platform "managed" \
     --service-account "gcr-cleaner@${PROJECT_ID}.iam.gserviceaccount.com" \
     --image "us-docker.pkg.dev/gcr-cleaner/gcr-cleaner/gcr-cleaner" \
     --region "us-central1" \
     --timeout "60s"

6. Grant the service account access to delete references.

   • For Container Registry:

     gsutil acl ch -u gcr-cleaner@${PROJECT_ID}.iam.gserviceaccount.com:W gs://artifacts.${PROJECT_ID}.appspot.com

     To cleanup refs in other GCP projects, replace PROJECT_ID with the target project ID. For example, if the Cloud Run service was running in "project-a" and you wanted to grant it permission to cleanup refs in "gcr.io/project-b/image", you would need to grant the Cloud Run service account in project-a permission on artifacts.projects-b.appspot.com.

     To clean up Container Registry images hosted in specific regions, update the bucket name to include the region:

     gs://eu.artifacts.${PROJECT_ID}.appspot.com
     

     If you plan on using the recursive functionality, you must also grant the service account "Browser" permissions:

     gcloud projects add-iam-policy-binding "${PROJECT_ID}" \
       --member "serviceAccount:gcr-cleaner@${PROJECT_ID}.iam.gserviceaccount.com" \
       --role "roles/browser"

   • For Artifact Registry:

     gcloud artifacts repositories add-iam-policy-binding "${REPO_NAME}" \
         --project "${PROJECT_ID}" \
         --location "${LOCATION}" \
         --member "serviceAccount:gcr-cleaner@${PROJECT_ID}.iam.gserviceaccount.com" \
         --role "roles/artifactregistry.repoAdmin"

     Where "REPO_NAME" is the name of the Artifact Registry repository and "LOCATION" is the geographic location.

7. Create a service account with permission to invoke the Cloud Run service:

   gcloud iam service-accounts create "gcr-cleaner-invoker" \
     --project "${PROJECT_ID}" \
     --display-name "gcr-cleaner-invoker"

   gcloud run services add-iam-policy-binding "gcr-cleaner" \
     --project "${PROJECT_ID}" \
     --platform "managed" \
     --region "us-central1" \
     --member "serviceAccount:gcr-cleaner-invoker@${PROJECT_ID}.iam.gserviceaccount.com" \
     --role "roles/run.invoker"

8. Create a Cloud Scheduler HTTP job to invoke the function every week:

   gcloud app create \
     --project "${PROJECT_ID}" \
     --region "us-central" \
     --quiet

   # Replace this with the full name of the repository for which you
   # want to cleanup old references, for example:
   export REPO="gcr.io/${PROJECT_ID}/my-image"
   export REPO="us-docker-pkg.dev/${PROJECT_ID}/my-repo/my-image"

   # Capture the URL of the Cloud Run service:
   export SERVICE_URL=$(gcloud run services describe gcr-cleaner --project "${PROJECT_ID}" --platform "managed" --region "us-central1" --format 'value(status.url)')

   gcloud scheduler jobs create http "gcrclean-myimage" \
     --project ${PROJECT_ID} \
     --description "Cleanup ${REPO}" \
     --uri "${SERVICE_URL}/http" \
     --message-body "{\"repos\":[\"${REPO}\"]}" \
     --oidc-service-account-email "gcr-cleaner-invoker@${PROJECT_ID}.iam.gserviceaccount.com" \
     --schedule "0 8 * * 2" \
     --time-zone="US/Eastern"

   You can create specify multiple repositories in the list to clean more than one repository.

9. (Optional) Run the scheduled job now:

   gcloud scheduler jobs run "gcrclean-myimage" \
     --project "${PROJECT_ID}"

   Note: for initial job deployments, you must wait a few minutes before invoking.

Payload & Parameters

The payload is expected to be JSON with the following fields:

• repos - List of the full names of the repositories to clean (e.g. ["gcr.io/project/repo"]. This field is required.

• grace - Relative duration in which to ignore references. This value is specified as a time duration value like "5s" or "3h". If set, refs newer than the duration will not be deleted. If unspecified, the default is no grace period (all untagged image refs are deleted).

• keep - If an integer is provided, it will always keep that minimum number of images. Note that it will not consider images inside the grace duration.

• tag_filter_any - If specified, any image with at least one tag that matches this given regular expression will be deleted. The image will be deleted even if it has other tags that do not match the given regular expression. The regular expressions are parsed according to the Go regexp package.

• tag_filter_all - If specified, any image where all tags match this given regular expression will be deleted. The image will not be delete if it has other tags that do not match the given regular expression. The regular expressions are parsed according to the Go regexp package.

• dry_run - If set to true, will not delete anything and outputs what would have been deleted.

• recursive - If set to true, will recursively search all child repositories.

  NOTE! On Container Registry, you must grant additional permissions to the service account in order to query the registry. The most minimal permissions are roles/browser.

  NOTE! On Artifact Registry, you must grant additional permissions to the service account in order to query the registry. The most minimal permissions are roles/storage.objectViewer.

  WARNING! If the authenticated principal has access to many Container Registry or Artifact Registry repos, this will be very slow! This is because the Docker v2 API does not support server-side filtering, meaning GCR Cleaner must download a manifest of all repositories to which you have access and then do client-side filtering. The most granular filter is at the host layer, meaning GCR Cleaner will perform a list operation on gcr.io (for Container Registry) or us-docker.pkg.dev (for Artifact Registry), parse the response and do client-side filtering to match against the provided patterns, then start deleting. To re-iterate, this operation is not segmented by project - if the authenticated principal has access to 10,000 repos, the client will need to filter through 10,000 repos. The easiest way to mitigate this is to practice the Principle of Least Privilege and create a dedicated service account that has granular permissions on a subset of repositories.

• tag_filter (Deprecated) - This option is deprecated and only exists to maintain backwards compatibility with some existing broken behavior. You should not use it. If specified, any image where the first tag matches this given regular expression will be deleted. The image will not be deleted if other tags match the regular expression. The regular expressions are parsed according to the Go regexp package.

• allow_tagged (Deprecated) - This option is deprecated and has no effect. By default, GCR Cleaner will not delete tagged images. To delete tagged images, specify tag_filter_any or tag_filter_all. Specifying either of these will enable deletion by tag.

Running locally

In addition to the server, you can also run GCR Cleaner locally for one-off tasks using cmd/gcr-cleaner-cli:

docker run -it us-docker.pkg.dev/gcr-cleaner/gcr-cleaner/gcr-cleaner-cli

Logging

By default, logs are produced at the info level. More logs are available at the debug level. To set the log level, set GCRCLEANER_LOG=debug.

I just want the container!

You can build the container yourself using the included Dockerfile. Alternatively, you can source a pre-built container from Artifact Registry or Container Registry. All of the following URLs provide an equivalent image:

gcr.io/gcr-cleaner/gcr-cleaner
asia-docker.pkg.dev/gcr-cleaner/gcr-cleaner/gcr-cleaner
europe-docker.pkg.dev/gcr-cleaner/gcr-cleaner/gcr-cleaner
us-docker.pkg.dev/gcr-cleaner/gcr-cleaner/gcr-cleaner

What about using Terraform!

📦 You can deploy the stack using the community-supported Terraform module gcr-cleaner:

FAQ

Does it work with Cloud Pub/Sub?
Yes! Just change the endpoint from /http to /pubsub!

What was your inspiration?
GCR Cleaner is largely inspired by ahmetb's gcrgc.sh, but it is written in Go and is designed to be run as a service.

License

This library is licensed under Apache 2.0. Full license text is available in LICENSE.