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 Cloud SDK.
  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 applications, 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 application 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

  • artifactregistry.repositories.list
  • artifactregistry.repositories.get
  • artifactregistry.repositories.downloadArtifacts
  • artifactregistry.files.list
  • artifactregistry.files.get
  • artifactregistry.packages.list
  • artifactregistry.packages.get
  • artifactregistry.tags.list
  • artifactregistry.tags.get
  • artifactregistry.versions.list
  • artifactregistry.versions.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.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.update
  • artifactregistry.repositories.delete
  • artifactregistry.repositories.getIamPolicy
  • artifactregistry.repositories.setIamPolicy

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 a 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. To use alpha features, the users must be members of the Google Group ar-trusted-testers@googlegroups.com.

  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, to access Alpha features, the users must be members of the Google Group ar-trusted-testers@googlegroups.com.

  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

For information about using Terraform to provision repositories and grant repository permissions, see Integrating with Terraform.

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.

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

gcloud

Run the following command:

gcloud artifacts repositories add-iam-policy-binding REPOSITORY \
--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'

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 pubilc 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 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 tool 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 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. 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.

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

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

Setting access scopes

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

gcloud container clusters create CLUSTER-NAME --scopes=SCOPE

Where

CLUSTER-NAME is the name of the cluster. SCOPE is a scope that matches your needs:

  • For Docker repositories, choose one of the following options:

    • 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 repositories, you must use the cloud-platform scope.

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 accoun. 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.

Configuring a custom service account

For clusters that use a custom service account as their identity, you must grant the required permissions to the service account from the Google Cloud project where Artifact Registry is running.

What's next

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