Configuring access control

This page describes granting permissions to Artifact Registry repositories.

Before you begin

  1. Enable Artifact Registry, including enabling the API and installing the Google Cloud CLI.
  2. Create the repositories for your packages, if you want to apply repository-specific permissions.

Overview

Artifact Registry is fully integrated with Google Cloud services for implementing a CI/CD pipeline, with default permissions to minimize setup effort. You can also integrate Artifact Registry with third-party CI/CD tools and configure the permissions and authentication required to access repositories.

If you use Container Analysis to work with container metadata, such as vulnerabilities found images, see the Container Analysis documentation for information about granting access to view or manage metadata.

Google Cloud integration

By default, the following permissions apply to Google Cloud CI/CD services in the same project as Artifact Registry:

If all your services are in the same Google Cloud project and the default permissions meet your needs, you do not need to configure permissions.

You must configure Artifact Registry permissions for these services if:

  • You want to use these services to access Artifact Registry in another project. In the project with Artifact Registry, grant the service account for each service the required role.
  • You are using a GKE version that does not have built-in support for pulling images from Artifact Registry. See the GKE section for configuration instructions.
  • You want the default service account to have read and write access to repositories. See the following information for details:
  • You are using a custom service account for your runtime environments instead of the default service account. In the project with Artifact Registry, grant your service account the required role.

Third-party integration

For third-party clients, you must configure both permissions and authentication.

  1. Create a service account to act on behalf of your application, or choose an existing service account that use for your CI/CD automation.
  2. Grant the appropriate Artifact Registry role to the service account to provide repository access.
  3. Configure your third-party client to authenticate with Artifact Registry.

Roles and permissions

Grant an Identity and Access Management (IAM) permission by granting a role that includes the permission. Use the Artifact Registry roles to control access to your repositories. You can grant permissions at the project or repository level.

Although you can use the basic roles Owner, Editor, and Viewer to grant access to repositories, using the Artifact Registry roles enables you to apply the security principle of least privilege, so that users and service accounts only have the permissions that are required.

Artifact Registry permissions

The table below lists the Artifact Registry IAM roles and the permissions that they include:

Role Description Permissions
roles/artifactregistry.reader Artifact Registry Reader

View and get artifacts, view repository metadata

  • artifactregistry.repositories.list
  • artifactregistry.repositories.get
  • artifactregistry.repositories.downloadArtifacts
  • artifactregistry.files.list
  • artifactregistry.files.get
  • artifactregistry.packages.list
  • artifactregistry.packages.listTagBindings
  • artifactregistry.repositories.listEffectiveTags
  • artifactregistry.packages.list
  • artifactregistry.tags.list
  • artifactregistry.tags.get
  • artifactregistry.versions.list
  • artifactregistry.versions.get
  • artifactregistry.locations.list
  • artifactregistry.locations.get
  • roles/artifactregistry.writer Artifact Registry Writer

    Read and write artifacts

    All roles/artifactregistry.reader permissions, and:

    • artifactregistry.repositories.uploadArtifacts
    • artifactregistry.tags.create
    • artifactregistry.tags.update
    roles/artifactregistry.repoAdmin Artifact Registry Repository Administrator

    Read, write, and delete artifacts

    All roles/artifactregistry.writer permissions, and:

    • artifactregistry.repositories.deleteArtifacts
    • artifactregistry.packages.delete
    • artifactregistry.projectsettings.update
    • artifactregistry.tags.delete
    • artifactregistry.versions.delete
    roles/artifactregistry.admin Artifact Registry Administrator

    Create and manage repositories and artifacts

    All roles/artifactregistry.repoAdmin permissions, and:

    • artifactregistry.repositories.create
    • artifactregistry.repositories.createTagBinding
    • artifactregistry.repositories.delete
    • artifactregistry.repositories.deleteTagBinding
    • artifactregistry.repositories.getIamPolicy
    • artifactregistry.repositories.setIamPolicy
  • artifactregistry.repositories.update
  • The following table lists the basic roles that existed prior to IAM, and the Artifact Registry IAM roles that they include:

    Role Role Title Includes role
    roles/viewer Viewer roles/artifactregistry.reader
    roles/editor Editor roles/artifactregistry.writer
    roles/owner Owner
    • roles/artifactregistry.repoAdmin
    • roles/artifactregistry.admin

    Granting permissions

    Grant permissions at the project level if the same permissions apply to all repositories in the project. If some accounts require different levels of access, grant roles at the repository level.

    If you are granting roles using the gcloud command, you can specify a single role binding for a member or use a policy file to define multiple bindings.

    The following reference policy template is used for the examples on this page. The reference policy file is named policy.yaml. The template contains example user and service account names. Replace these example users and service accounts as appropriate for your project.

    For details about the policy format, see the IAM policy documentation.

    bindings:
    
    - members:
      - user: user@gmail.com
      role: roles/owner
    
    - members:
      - serviceAccount: repo-readonly@iam.gserviceaccount.com
      - user: user2@gmail.com
      role: roles/artifactregistry.reader
    
    - members:
      - serviceAccount: repo-write@iam.gserviceaccount.com
      role: roles/artifactregistry.writer
    
    - members:
      - serviceAccount: repo-admin@iam.gserviceaccount.com
      role: roles/artifactregistry.repoAdmin
    
    - members:
      - serviceAccount: ar-admin@iam.gserviceaccount.com
      role: roles/artifactregistry.admin
    

    Granting project-wide permissions

    Grant a role at the project level if the same permissions apply to all repositories in the project.

    To add a team member to a project and grant them an Artifact Registry role:

    Console

    1. Open the IAM page in the Cloud console.

      Open the IAM page

    2. Click Select a project, choose the project where Artifact Registry is running, and click Open.

    3. Click Add.

    4. Enter an email address. You can add individuals, service accounts, or Google Groups as members.

    5. Select a role for the member. In accordance with the security principle of least privilege, consider granting the least amount of privilege needed to prevent unwanted access to other resources.

    6. Click Save.

    gcloud

    To grant a role to a single member, run the following command:

    gcloud projects add-iam-policy-binding PROJECT --member=MEMBER --role=ROLE
    

    where

    • PROJECT is the ID of the project where Artifact Registry is running.
    • MEMBER is the member to add the binding for. Use the form user|group|serviceAccount:email or domain:domain.

      Examples: user:test-user@gmail.com, group:admins@example.com, serviceAccount:test123@example.domain.com, or domain:example.domain.com.

    • ROLE is the role that you want to grant.

    For more information, see the add-iam-policy-binding documentation.

    To grant roles using a policy file, run the following command:

    gcloud projects set-iam-policy PROJECT /PATH/TO/policy.yaml

    Where

    • PROJECT is the ID of the project or fully qualified identifier for the project where Artifact Registry is running.
    • /PATH/TO/policy.yaml is the path and file name of the policy file.

    To get the currently configured policy, run the following command:

    gcloud projects get-iam-policy PROJECT

    Where PROJECT is the ID of the project or fully qualified identifier for the project.

    For more information, see the set-iam-policy documentation.

    Granting repository-specific permissions

    Grant repository-level permissions when you want users or service accounts to have different levels of access for each repository in your project.

    Console

    To grant access to a specific repository:

    1. Open the Repositories page in the Cloud console.

      Open the Repositories page

    2. Select the appropriate repository.

    3. If the info panel is not displayed, click Show Info Panel in the menu bar.

    4. On the Permissions tab, click Add Member.

    5. Enter an email address. You can add individuals, service accounts, or Google Groups as members.

    6. Select a role for the member. We recommend giving the member the least amount of privilege needed.

    7. Click Save.

    gcloud

    You can set an IAM set of individual policy bindings or use a policy file.

    To grant a role to a single member, run the following command:

    gcloud artifacts repositories add-iam-policy-binding REPOSITORY \
    --location LOCATION --member=MEMBER --role=ROLE
    

    where

    • REPOSITORY is the ID of the repository.
    • MEMBER is the member to add the binding for. Use the form user|group|serviceAccount:email or domain:domain.

      Examples: user:test-user@gmail.com, group:admins@example.com, serviceAccount:test123@example.domain.com, or domain:example.domain.com.

    • ROLE is the role that you want to grant.

    • LOCATION is the regional or multi-regional location of the repository.

    For example, to add an IAM policy binding for the role roles/artifactregistry.writer for the user write@gmail.com with the repository my-repo in the location --us-central1, run:

    gcloud artifacts repositories add-iam-policy-binding my-repo \
     --location=us-central1 --member=user:write@gmail.com --role=roles/artifactregistry.writer
    

    To grant roles using a policy file, run the following command:

    gcloud artifacts repositories set-iam-policy REPOSITORY /PATH/TO/policy.yaml --location=LOCATION

    Where

    • REPOSITORY is the ID of the repository.
    • /PATH/TO/policy.yaml is the path and file name of the policy file.
    • LOCATION is the regional or multi-regional location of the repository.

    For example, to set the IAM policy for the repository my-repo in the location --us-central1 with the policy defined in policy.yaml, run:

    gcloud artifacts repositories set-iam-policy my-repo policy.yaml --location=us-central1
    

    Terraform

    Use the google_artifact_registry_repository_iam resource to configure an IAM policy. The following example defines a service account with the resource name repo-account and grants it read access to a repository with the resource name my-repo.

    If you are new to using Terraform for Google Cloud, see the Get Started - Google Cloud page on the HashiCorp website.

    provider "google" {
        project = "PROJECT-ID"
    }
    
    resource "google_artifact_registry_repository" "my-repo"     {
      provider = google-beta
    
      location = "LOCATION"
      repository_id = "REPOSITORY"
      description = "DESCRIPTION"
      format = "FORMAT"
    }
    
    resource "google_service_account" "repo-account" {
      provider = google-beta
    
      account_id   = "ACCOUNT-ID"
      display_name = "Repository Service Account"
    }
    
    resource "google_artifact_registry_repository_iam_member" "repo-iam" {
      provider = google-beta
    
      location = google_artifact_registry_repository.my-repo.location
      repository = google_artifact_registry_repository.my-repo.name
      role   = "roles/artifactregistry.reader"
      member = "serviceAccount:${google_service_account.repo-account.email}"
    }
    

    ACCOUNT-ID is the ID of the service account. This is the the part of the service account email field before the @ symbol.

    For additional examples, see the documentation for the google_artifact_registry_repository_iam resource.

    Configuring public access to a repository

    If you have artifacts that you want to make available to anyone on the internet without authentication, store them in a repository that you make public.

    To configure a repository for public read-only access, grant the Artifact Registry Reader role to the member allUsers. We also recommend capping user request quotas so that a single user can't use up your project's overall quota.

    Console

    1. Open the Repositories page in the Cloud console.

      Open the Repositories page

    2. Select the appropriate repository.

    3. If the info panel is not displayed, click Show Info Panel in the menu bar.

    4. On the Permissions tab, click Add Member.

    5. In New members field, enter allUsers.

    6. Select the role Artifact Registry Reader.

    7. Set a per-user limit on Artifact Registry API requests to prevent misuse by unauthenticated users. See Capping usage for instructions.

    gcloud

    1. Run the following command:

      gcloud artifacts repositories add-iam-policy-binding REPOSITORY \
      --location=LOCATION --member=allUsers --role=ROLE
      

      where

      • REPOSITORY is the ID of the repository.
      • MEMBER is the member to add the binding for. Use the form user|group|serviceAccount:email or domain:domain.

        Examples: user:test-user@gmail.com, group:admins@example.com, serviceAccount:test123@example.domain.com, or domain:example.domain.com.

      • ROLE is the role that you want to grant.

      • LOCATION is the regional or multi-regional location of the repository.

      For example, configure the repository my-repo in the location --us-central1 as public, run:

      gcloud artifacts repositories add-iam-policy-binding my-repo \
       --location=us-central1 --member=allUsers --role=roles/artifactregistry.reader
      
    2. Set a per-user limit on Artifact Registry API requests to prevent misuse by unauthenticated users. See Capping usage for instructions.

    Revoking permissions

    To revoke access to a repository, remove the member from the list of authorized members.

    To remove public access from a repository, remove the allUsers member.

    Console

    To revoke permissions:

    1. Open the Repositories page in the Cloud console.

      Open the Repositories page

    2. Select the appropriate repository.

    3. If the info panel is not displayed, click Show Info Panel in the menu bar.

    4. On the Permissions tab, expand the appropriate member. If you are making a public repository private, expand the allUsers member.

    5. Click Remove member to revoke access.

    gcloud

    To revoke a role at the project level, run the following command:

    gcloud projects remove-iam-policy-binding PROJECT --member=MEMBER --role=ROLE
    
    • PROJECT is the project ID.
    • MEMBER is the member to remove the binding for. Use the form user|group|serviceAccount:email or domain:domain.

      Examples: user:test-user@gmail.com, group:admins@example.com, serviceAccount:test123@example.domain.com, or domain:example.domain.com.

    • ROLE is the role that you want to revoke.

    To revoke a role for a repository, run the following command:

    gcloud artifacts repositories remove-iam-policy-binding REPOSITORY --member=MEMBER --role=ROLE
    

    where

    • REPOSITORY is the ID of the repository.
    • MEMBER is the member to remove the binding for. Use the form user|group|serviceAccount:email or domain:domain.

      Examples: user:test-user@gmail.com, group:admins@example.com, serviceAccount:test123@example.domain.com, or domain:example.domain.com.

      To revoke public access to the repository, specify the member allUsers.

    • ROLE is the role that you want to revoke.

    For example, to remove a policy binding for the role roles/artifactregistry.writer for the user write@gmail.com with the repository my-repo in the location --us-central1, run:

    gcloud artifacts repositories remove-policy-binding my-repo \
     --location=us-central1 --member=user:write@gmail.com --role=roles/artifactregistry.writer

    To revoke public access to my-repo in the location --us-central1, run:

    gcloud artifacts repositories remove-policy-binding my-repo \
     --location=us-central1 --member=allUsers --role=roles/artifactregistry.reader
     

    Granting conditional access with tags

    This feature is in Preview.

    Project administrators can create tags for resources across Google Cloud and manage them in Resource Manager. When you attach a tag to a Artifact Registry repository, administrators can use the tag with IAM conditions to grant conditional access to the repository.

    You cannot attach tags to individual artifacts.

    For more information see the following documentation:

    Integrating with Google Cloud services

    For most Google Cloud service accounts, configuring access to a registry only requires granting the appropriate IAM permissions.

    Default permissions for Google Cloud services

    Google Cloud services such as Cloud Build or Google Kubernetes Engine use a default or Google-managed service account to interact with resources within the same project.

    You must configure or modify permissions yourself if:

    • The Google Cloud service is in a different project than Artifact Registry.
    • The default permissions do not meet your needs. For example, the default Compute Engine service account has read-only access to storage in the same project. If you want to push an image from a VM to Artifact Registry, you can modify permissions for the VM service account or use a different account with the required permissions.
    • You are using a user-provided service account to interact with Artifact Registry instead of the default service account.

    The following service accounts typically access Artifact Registry. The email address for the service account includes the Google Cloud project ID or project number of the project where the service is running.

    Service Service account Email address Permissions
    App Engine flexible environment App Engine service account PROJECT-ID@appspot.gserviceaccount.com Editor role, can read and write to repositories
    Compute Engine Compute Engine default service account PROJECT-NUMBER-compute@developer.gserviceaccount.com Editor role, limited to read-only access to repositories
    Cloud Build Cloud Build service account PROJECT-NUMBER@cloudbuild.gserviceaccount.com Default permissions include read and write access to repositories.
    Cloud Run Compute Engine default service account
    The default runtime service account for revisions.
    PROJECT-NUMBER-compute@developer.gserviceaccount.com Editor role, limited to read-only access to repositories
    GKE Compute Engine default service account
    The default service account for nodes.
    PROJECT-NUMBER-compute@developer.gserviceaccount.com Editor role, limited to read-only access to repositories

    Granting access to Compute Engine instances

    VM instances that access repositories must have both Artifact Registry permissions and storage access scope configured.

    While a service account's access level is determined by the IAM roles granted to the service account, access scopes on a VM instance determine the default OAuth scopes for requests made through the gcloud CLI and client libraries on the instance. As a result, access scopes potentially further limit access to API methods when authenticating with application default credentials.

    By default, the default Compute Engine default service account has Editor permission for resources in the same project and the read-only storage access scope. The service account email address has the suffix @developer.gserviceaccount.com.

    While the Editor permissions generally grants write access, the read-only access scope limits the instance service account to downloading artifacts only from any repository in the same project.

    You must configure the access scope of the service account if:

    • The VM service account needs to access a repository in a different project.
    • The VM service account needs to perform actions other than reading artifacts from repositories. This typically applies third-party tools on a VM that need to push images or run Artifact Registry gcloud commands.

    To configure permissions and set the access scope:

    1. In the project with your VM instance, get the name of the Compute Engine default service account. The service account email address has the suffix @developer.gserviceaccount.com.

    2. In the project with the repository, grant permissions so that the service account can access the repository.

    3. Set the access scope with the --scopes option.

      1. Stop the VM instance. See Stopping an instance.

      2. Set the access scope with the following command:

        gcloud compute instances set-service-account INSTANCE --scopes=SCOPE
        

        Replace SCOPE with the appropriate value.

        • For Docker, the following options are supported:

          • storage-ro - Grants read permission only for pulling images.
          • storage-rw - Grants read and write permission for pushing or pulling images.
          • cloud-platform - View and manage data, including metadata, across Google Cloud service.
        • For other formats, you must use the cloud-platform scope.

      3. Restart the VM instance. See Starting a stopped instance.

    Granting access to Google Kubernetes Engine clusters

    GKE clusters and node pools can pull containers without any additional configuration if all the following requirements are met:

    If your GKE environment does not meet these requirements the instructions to grant access depend on whether you are using the Compute Engine default service account or a custom service account as the identity for your nodes.

    Default service account

    The following configuration requirements apply to the Compute Engine default service account:

    1. If GKE is in a different project than Artifact Registry, grant the required permissions to the service account.

    2. To push images, interact with repositories for formats other than containers, or run gcloud commands from your cluster, you must set access scopes for the service account when you create the cluster or node pool.

    3. If you are not using a supported version of GKE, configure imagePullSecrets.

    Custom service account

    If you want to use a custom service account as the identity for a cluster, you must:

    1. Grant the required permissions to the service account from the Google Cloud project where Artifact Registry is running.

    2. By default, creating a cluster or node pool with a custom service account grants the cloud-platform access scope.

      If you use the --scopes flag with the gcloud container clusters create or gcloud container node-pools create command, you must include the appropriate access scopes for use with Artifact Registry.

    Setting access scopes

    To specify access scopes when creating a cluster, run the following command:

    gcloud container clusters create NAME --scopes=SCOPES
    

    To specify access scopes when creating a node pool, run the following command:

    gcloud container node-pools create NAME --scopes=SCOPES
    

    Replace the following values:

    • NAME is the name of the cluster or node pool.
    • SCOPES is a comma-separated list of access scopes to grant.

      • To access Docker repositories, use one of the following scopes:

      • storage-ro - Grants read permission only for pulling images.

      • storage-rw - Grants read and write permission for pushing or pulling images.

      • cloud-platform - View and manage data, including metadata, across Google Cloud service.

      • To access other repositories, you must use the cloud-platform scope.

      For a full list of scopes, see the documentation for gcloud container clusters create or gcloud container node-pools create.

    For more information about scopes you can set when creating a new cluster, refer to the documentation for the command gcloud container clusters create.

    Configuring an imagePullSecret

    To configure an imagePullSecret:

    1. In the project with GKE, find Compute Engine default service account. The account email address has the suffix @developer.gserviceaccount.com.

    2. Download the service account key for the service account.

    3. In the project with the repository, verify that you have granted permissions to the repository.

    4. In the project with your cluster, create an imagePullSecret secret called artifact-registry with the service account key.

      kubectl create secret docker-registry artifact-registry \
      --docker-server=https://LOCATION-docker.pkg.dev \
      --docker-email=SERVICE-ACCOUNT-EMAIL \
      --docker-username=_json_key \
      --docker-password="$(cat KEY-FILE)"
      

      Where

      • LOCATION is the regional or multi-regional location of the repository.
      • SERVICE-ACCOUNT-EMAIL is the email address of the Compute Engine service account.
      • KEY-FILE is the name of your service account key file. For example key.json.
    5. Open your default service account:

      kubectl edit serviceaccount default --namespace default

      Every namespace in your Kubernetes cluster has a default service account called default. This default service account is used to pull your container image.

    6. Add the newly created imagePullSecret secret to your default service account:

      imagePullSecrets:
      - name: artifact-registry
      

      Your service account should now look like this:

      apiVersion: v1
      kind: ServiceAccount
      metadata:
        name: default
        namespace: default
        ...
      secrets:
      - name: default-token-zd84v
      # The secret you created:
      imagePullSecrets:
      - name: artifact-registry
      

    Now, any new pods created in the current default namespace will have the imagePullSecret secret defined.

    Artifact Registry service account

    The Artifact Registry Service Agent is a Google-managed service account that acts on behalf of Artifact Registry when interacting with Google Cloud services. For more information about the account and its permissions, see Artifact Registry service account.

    What's next

    After you have set up permissions, learn more about working with your artifacts.