Configuring access control

This page describes granting permissions to Artifact Registry repositories.

Before you begin

Enable Artifact Registry, including enabling the API and installing the Cloud SDK.
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:

Cloud Build permissions include permissions to upload and download artifacts.
Compute Engine, supported Google Kubernetes Engine versions, and Cloud Run use the Compute Engine default service account, which has read-only access to storage.

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:
- Compute Engine
- GKE
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.

Create a service account to act on behalf of your application, or choose an existing service account that use for your CI/CD automation.
Grant the appropriate Artifact Registry role to the service account to provide repository access.
Configure your third-party application to authenticate with Artifact Registry.
- Docker
- Java (alpha)
- Node.js (alpha)

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 an Artifact Registry role:

Console

Open the IAM page in the Cloud Console.
Open the IAM page
Click Select a project, choose the project where Artifact Registry is running, and click Open.
Click Add.
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.
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.
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:

Open the Repositories page in the Cloud Console.

Open the Repositories page
Select the appropriate repository.
If the info panel is not displayed, click Show Info Panel in the menu bar.
On the Permissions tab, click Add Member.
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.
Select a role for the member. We recommend giving the member the least amount of privilege needed.
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

Open the Repositories page in the Cloud Console.

Open the Repositories page
Select the appropriate repository.
If the info panel is not displayed, click Show Info Panel in the menu bar.
On the Permissions tab, click Add Member.
In New members field, enter allUsers.
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:

Open the Repositories page in the Cloud Console.

Open the Repositories page
Select the appropriate repository.
If the info panel is not displayed, click Show Info Panel in the menu bar.
On the Permissions tab, expand the appropriate member. If you are making a public repository private, expand the allUsers member.
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:

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.
In the project with the repository, grant permissions so that the service account can access the repository.
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:

GKE is in the same project as Artifact Registry
Nodes are using the default service account, the Compute Engine default service account
You are running a supported version of GKE

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:

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.
If GKE is in a different project than Artifact Registry, grant the required permissions to the service account.
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:

In the project with GKE, find Compute Engine default service account. The account email address has the suffix @developer.gserviceaccount.com.
Download the service account key for the service account.
In the project with the repository, verify that you have granted permissions to the repository.
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.
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.

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.

Docker
Java (alpha)
Node.js (alpha)