Check for Container Registry usage

Run this tool to determine if there is Container Registry usage within your Google Cloud project, folder, or organization.

Before you begin

  1. Install the Google Cloud CLI.

  2. To initialize the gcloud CLI, run the following command: 

    gcloud init

Required roles

To get the permissions that you need to find Container Registry usage in your Google Cloud project, folder, or organization, ask your administrator to grant you the following IAM roles:

For more information about granting roles, see Manage access.

You might also be able to get the required permissions through custom roles or other predefined roles.

Find Container Registry usage

You can run the tool scoped to a single Google Cloud project, folder, or organization.

project

Run the following command to find any Container Registry usage in your Google Cloud project.

gcloud container images list-gcr-usage \
    --project=PROJECT

Where PROJECT is your Google Cloud project ID. For information on how to find your project ID, see Identifying projects.

The tool returns a list of your host locations for the specified project, and their usage state. The usage states are defined as follows:

  • ACTIVE: Container Registry usage has occurred in the last 30 days. The host location and project are not redirected.
  • INACTIVE: No Container Registry usage has occurred in the last 30 days. The host location and project are not redirected.
  • REDIRECTED: the project has been redirected to Artifact Registry but still has Container Registry Cloud Storage buckets. This project will continue to function after Container Registry is turned down and no further action is required. You can reduce costs by deleting the Container Registry Cloud Storage buckets.
  • REDIRECTION_INCOMPLETE: requests are redirected to Artifact Registry, but data is still being copied from Container Registry.
  • LEGACY: Container Registry usage is unknown. This state is caused by legacy Container Registry projects that store container image metadata files in Cloud Storage buckets. For more information on legacy Container Registry projects, see Container image metadata storage change.

If the tool encounters errors, such as missing permissions to view the Cloud Storage bucket or Container Registry project, then you will see an error message similar to the following:

 repository: us.gcr.io/my-project
      usage: |-
        response: {'status': 401}
        Operation on project 'no-gcr-permission' failed. Caller does not have permission 'storage.objects.list'. To configure permissions, follow instructions at: https://cloud.google.com/container-registry/docs/access-control: None

folder

Run the following command to find any Container Registry usage in your Google Cloud folder.

gcloud container images list-gcr-usage \
    --folder=FOLDER

Where FOLDER is your Google Cloud folder ID. For information on how to list folders in your organization, see List folders.

The tool returns the following lists of usage states:

  • ACTIVE: Container Registry usage has occurred in the last 30 days. The host location and project are not redirected.
  • INACTIVE: No Container Registry usage has occurred in the last 30 days. The host location and project are not redirected.
  • REDIRECTED: the project has been redirected to Artifact Registry but still has Container Registry Cloud Storage buckets. This project will continue to function after Container Registry is turned down and no further action is required. You can reduce costs by deleting the Container Registry Cloud Storage buckets.
  • REDIRECTION_INCOMPLETE: requests are redirected to Artifact Registry, but data is still being copied from Container Registry.
  • LEGACY: Container Registry usage is unknown. This state is caused by legacy Container Registry projects that store container image metadata files in Cloud Storage buckets. For more information on legacy Container Registry projects, see Container image metadata storage change.

If the tool encounters errors, such as missing permissions to view the Cloud Storage bucket or Container Registry project, then you will see an error message similar to the following:

 repository: us.gcr.io/my-project
      usage: |-
        response: {'status': 401}
        Operation on project 'no-gcr-permission' failed. Caller does not have permission 'storage.objects.list'. To configure permissions, follow instructions at: https://cloud.google.com/container-registry/docs/access-control: None

organization

Run the following command to find any Container Registry usage in your Google Cloud organization.

gcloud container images list-gcr-usage \
    --organization=ORGANIZATION

Where ORGANIZATION is your Google Cloud organization ID. For information about how to find your organization ID, see Getting your organization resource ID.

The tool returns the following lists of usage states:

  • ACTIVE: Container Registry usage has occurred in the last 30 days. The host location and project are not redirected.
  • INACTIVE: No Container Registry usage has occurred in the last 30 days. The host location and project are not redirected.
  • REDIRECTED: the project has been redirected to Artifact Registry but still has Container Registry Cloud Storage buckets. This project will continue to function after Container Registry is turned down and no further action is required. You can reduce costs by deleting the Container Registry Cloud Storage buckets.
  • REDIRECTION_INCOMPLETE: requests are redirected to Artifact Registry, but data is still being copied from Container Registry.
  • LEGACY: Container Registry usage is unknown. This state is caused by legacy Container Registry projects that store container image metadata files in Cloud Storage buckets. For more information on legacy Container Registry projects, see Container image metadata storage change.

If the tool encounters errors, such as missing permissions to view the Cloud Storage bucket or Container Registry project, then you will see an error message similar to the following:

 repository: us.gcr.io/my-project
      usage: |-
        response: {'status': 401}
        Operation on project 'no-gcr-permission' failed. Caller does not have permission 'storage.objects.list'. To configure permissions, follow instructions at: https://cloud.google.com/container-registry/docs/access-control: None

Filter results

To control which resource items are listed, pass the --filter=EXPRESSION flag. If the expression evaluates to true for a given item, then that item is listed.

To list all active Container Registry usage in your organization, you can filter by active usage:

gcloud container images list-gcr-usage \
    --organization=ORGANIZATION \
    --filter="usage=ACTIVE"

To find all projects that aren't redirected yet, you can filter by usage!=REDIRECTED:

gcloud container images list-gcr-usage \
    --organization=ORGANIZATION \
    --filter="usage!=REDIRECTED"

For more information on filter expressions, run gcloud topic filters or read the reference documentation.

What's next