Skip to main content

GCP Container Registry

GCP Container Registry integration allows your product to access container repositories, fetch container images, tags, and metadata stored in Google Container Registry (GCR). This integration is essential for vulnerability scanning, image inventory, and compliance analysis across workloads running in Google Cloud.

GCP Container Registry (GCR) is gradually being replaced by Artifact Registry, but many organizations still use GCR for hosting container images.

Credentials Needed​

To integrate with GCP Container Registry, you need a Google Cloud Service Account with permissions to read container images from GCR buckets.

Required credentials:

  • Service Account JSON Key File (contains: project_id, client_email, private_key, etc.)

This key enables secure authentication with GCP APIs and GCR resources.

Permissions Needed​

To fetch image metadata, tags, and repositories from Google Container Registry, the Service Account must have read-only access to both Storage (GCS) and Container Registry APIs.

Required Roles

RolePurpose
Storage Object Viewer (roles/storage.objectViewer)Grants read access to container image storage buckets (artifacts.<region>.gcr.io, gcr.io, etc.)
Viewer (roles/viewer)General read-only access to project resources
Artifact Registry Reader (roles/artifactregistry.reader) (optional)For hybrid environments using both GCR and Artifact Registry

Key Permissions These Roles Include

  • storage.objects.list
  • storage.objects.get
  • resourcemanager.projects.get
  • artifactregistry.repositories.list (optional)
  • artifactregistry.dockerimages.list (optional)

Creating Users / Service Account in GCP​

Step 1: Create a Service Account

  1. Go to GCP Console → IAM & Admin → Service Accounts
  2. Click + CREATE SERVICE ACCOUNT
  3. Enter a name (e.g., gcr-integration-sa)
  4. Click Create and Continue

Step 2: Assign Roles

  1. Under Grant this service account access to project, click + Add Another Role
  2. Assign the following roles:
    • Storage Object Viewer
    • Viewer
    • (Optional) Artifact Registry Reader
  3. Click Continue → Done

Step 3: Create and Download JSON Key

  1. Open the created Service Account
  2. Go to Keys → Add Key → Create new key
  3. Choose JSON format and download the key file
  4. Save it securely (e.g., gcp-gcr-key.json)

Test Connectivity​

You can verify GCR connectivity using the gcloud CLI:

# Authenticate using the service account key
gcloud auth activate-service-account --key-file=gcp-gcr-key.json

# Verify authentication
gcloud auth list

# Set the project
gcloud config set project <PROJECT_ID>

# List images in GCR
gcloud container images list

# List image tags
gcloud container images list-tags gcr.io/<PROJECT_ID>/<IMAGE_NAME> --limit=5

If these commands successfully return repository and image tag data, your credentials and permissions are correctly configured.

Save the Results in the Platform and Create Connection​

  1. In your platform's integration setup, securely upload or reference the Service Account JSON Key.
  2. Store securely:
    • project_id
    • client_email
    • private_key
  3. Create a connector labeled GCP Container Registry Integration.
  4. Test the connection by listing repositories and image tags for a project.

Best Practices​

  • Use dedicated Service Accounts for each integration to maintain isolation.
  • Apply the principle of least privilege — only assign Storage Object Viewer and Viewer roles.
  • Store JSON keys in Google Secret Manager or your platform's encrypted vault.
  • Rotate Service Account keys periodically or use Workload Identity Federation to eliminate static keys.
  • For new environments, prefer Artifact Registry over GCR for better security and management.
  • Enable Cloud Audit Logs for storage.googleapis.com to monitor image access activity.
  • Implement multi-project scanning support by allowing your integration to read from multiple GCP projects via IAM role bindings.