Map IAM roles from Container Registry to Artifact Registry

Preview

This feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

Caution: We recommend using the automatic migration tool to map Container Registry roles to Artifact Registry roles instead of using the steps found in this document.

This document shows you how to map Container Registry roles to Artifact Registry roles and apply them to an Artifact Registry repository. You can accomplish the same steps using the automatic migration tool.

Container Registry and Artifact Registry use different Identity and Access Management (IAM) roles to control access to container images stored in the registry.

To help you transition to from Container Registry to Artifact Registry, you can run a Google Cloud CLI command that:

• Identifies allow policies that apply to a Cloud Storage storage bucket that stores images for Container Registry
• Returns a policy with similar Artifact Registry roles so that you can grant your existing Container Registry users access to Artifact Registry repositories.

The command uses the IAM Policy Analyzer to analyze IAM allow policies.

Note: Artifact Registry doesn't support IAM conditions, so if you have set conditional role bindings for Container Registry, you can't use the Policy Analyzer, and will have to use the information in the Role mappings section to determine which Artifact Registry roles to grant to your users.

Before you begin

1. Create an Artifact Registry repository. If you've chosen the manual method to transition, follow the steps to either migrate manually to gcr.io repositories in Artifact Registry or migrate manually to pkg.dev repositories.

   Caution: we recommend that you use the auto-migration tool to transition to gcr.io repositories, not the manual method.

2. Enable the Cloud Asset API.

   Enable the API

   You must enable the API in the project or organization where you want to analyze existing allow policies.

3. Install and initialize gcloud CLI. For an existing installation, update to the latest version with the command:

   gcloud components update
   

Required roles

To get the permissions that you need to analyze allow policies and grant access to Artifact Registry repositories, ask your administrator to grant you the following IAM roles on the project, folder, or organization that you want to analyze for permissions:

• Cloud Asset Viewer (roles/cloudasset.viewer)
• To analyze policies with custom IAM roles: Role Viewer (roles/iam.roleViewer)
• To use the Google Cloud CLI to analyze policies: Service Usage Consumer (roles/serviceusage.serviceUsageConsumer)
• To grant roles on an Artifact Registry repository: Artifact Registry Administrator

For more information about granting roles, see Manage access to projects, folders, and organizations.

These predefined roles contain the permissions required to analyze allow policies and grant access to Artifact Registry repositories. To see the exact permissions that are required, expand the Required permissions section:

Required permissions

The following permissions are required to analyze allow policies and grant access to Artifact Registry repositories:

• cloudasset.assets.analyzeIamPolicy
• cloudasset.assets.searchAllResources
• cloudasset.assets.searchAllIamPolicies
• To analyze policies with custom IAM roles: iam.roles.get
• To use the Google Cloud CLI to analyze policies: serviceusage.services.use
• To grant roles on an Artifact Registry repository: artifactregistry.repositories.setIamPolicy

You might also be able to get these permissions with custom roles or other predefined roles.

Use the mapping tool

The mapping tool checks allow policies for a specified Container Registry hostname, such as gcr.io.

The tool checks for sets of permissions that are in predefined Cloud Storage roles and maps them to Artifact Registry roles. For a comparison of Cloud Storage permissions to Artifact Registry roles, see Role mappings.

To use the role mapping tool:

1. Run the mapping tool:

   gcloud beta artifacts docker upgrade print-iam-policy HOSTNAME \
       --project=PROJECT_ID > POLICY_FILENAME
   

   Replace the following values:

   • HOSTNAME is the Container Registry hostname that you want the tool to analyze:

     • gcr.io
     • asia.gcr.io
     • eu.gcr.io
     • us.gcr.io

   • PROJECT_ID is the ID of the Google Cloud project with the registry host you are analyzing.

   • POLICY_FILE is the filename for the policy, in YAML format, that the tool will return.

   The following example command analyzes the storage bucket for gcr.io in the project my-project for allow policies that are applied directly to the bucket or are inherited from the parent organization ID 101231231231 and its descendants.

   gcloud beta artifacts docker upgrade print-iam-policy gcr.io \
       --project=my-project > gcr-io-policy.yaml
   

   The command returns a policy file in YAML format with Artifact Registry role bindings, based on existing allow policies for the storage bucket. If the parent project for the storage bucket is in an organization, the policy file includes principals who have access granted at the folder or organization level.

   For example, the following sample includes Artifact Registry role bindings for:

   • Cloud Build, Compute Engine, and Container Registry service agents. Service agents act on behalf of Google Cloud services.
   • The user account [e-mail]
   • The user-managed service account [e-mail].

   bindings:
   - members:
     - [e-mail]
     - user:[e-mail]
     role: roles/artifactregistry.repoAdmin
   - members:
     - serviceAccount:[e-mail]
     - serviceAccount:service-1231231231231@@compute-system.iam.gserviceaccount.com
     - serviceAccount:[e-mail]
     role: roles/artifactregistry.reader
   

2. Remove the line for the Container Registry service agent from the policy file since that service account does not require access to your Artifact Registry repositories. The suffix of the service agent email address is containerregistry.iam.gserviceaccount.com.

   In the example policy from the previous step, the line with the Container Registry service agent is:

   - serviceAccount:[e-mail]
   

3. Review the other role bindings to confirm that they are appropriate.

   Artifact Registry has additional predefined roles that you might want to consider for some principals. For example Artifact Registry Create-on-push Repository Administrator allows a principal to create gcr.io repositories in Artifact Registry but does not allow them to create other Artifact Registry repositories.

4. Add role bindings for any principals that are missing from the policy file.

   The following principals might be missing from the returned policy file:

   • Principals with custom roles, and those custom roles don't have the sets of permissions that the tool used to map roles.
   • Principals who were granted access on a parent folder or organization if you don't have permissions to view a parent folder or organization.

5. Apply the policy bindings to your Artifact Registry repositories.

   gcloud artifacts repositories set-iam-policy REPOSITORY FILENAME \
       --project=PROJECT_ID \
       --location=LOCATION
   

   Replace the following values:

   • REPOSITORY is the name of the repository.
   • POLICY_FILENAME is the name of the policy file that you are applying to the repository.
   • PROJECT_ID is the project ID.
   • LOCATION is the regional or multi-regional location of the repository.

   The following example for the project my-project applies the policy in the file gcr-io-policy.yaml to the repository named gcr.io in the us multi-region:

   gcloud artifacts repositories set-iam-policy gcr.io gcr-io-policy.yaml \
       --project=my-project \
       --location=us
   

   If you want to apply role bindings to a higher level resource, edit the existing project, folder, or organization policy with the bindings you want to add.

Role mappings

The following table shows which predefined Artifact Registry roles should be granted to existing Container Registry users depending on the Cloud Storage permissions they have.

Required permissions in the role	Artifact Registry role
storage.objects.get storage.objects.list	Artifact Registry Reader
storage.buckets.get storage.objects.get storage.objects.list storage.objects.create	Artifact Registry Writer
storage.buckets.get storage.objects.get storage.objects.list storage.objects.create storage.objects.delete	Artifact Registry Repository Administrator
storage.buckets.get storage.objects.get storage.objects.list storage.objects.create storage.buckets.create	Artifact Registry Administrator