This page describes how to restrict artifact downloads from your Artifact Registry repositories by creating and managing download rules.
Download rules let you allow or deny artifact downloads from your repositories and packages. You can also set conditions so the rule applies to specific tags or versions.
For details on how downloads rules work, see the Restrict artifact downloads section of the Control access and protect artifacts overview.
Before you begin
- If you don't already have one, create a Docker-format standard repository.
- (Optional) Configure defaults for Google Cloud CLI commands.
Required roles
To get the permissions that you need to Create and manage download rules, ask your administrator to grant you the following IAM roles on the repository:
-
Create, update, get, list and delete rules:
Artifact Registry Repository Administrator (
roles/artifactregistry.repoAdmin
) -
Get and list rules:
Artifact Registry Reader (
roles/artifactregistry.reader
)
For more information about granting roles, see Manage access to projects, folders, and organizations.
You might also be able to get the required permissions through custom roles or other predefined roles.
Create download rules
gcloud
Before using any of the command data below, make the following replacements:
RULE_NAME
: the name of the rule. The name must be unique within your repository, have a max length of 256 characters, and consist of alpha-numeric characters, percent-encoded characters, or characters in the list [-
,.
,_
,~
,:
,@
,+
,^
].ACTION
: the action applied to a download that matches this rule. Choose betweenALLOW
, where the rule allows matching downloads to occur, andDENY
, where the rule blocks matching downloads from occurring.PACKAGE
: (optional) the name of the package. If supplied, the rule applies only to the specified package instead of the whole repository.CONDITION
: (optional) a CEL expression that defines a matching rule. If supplied, only applies the rule to downloads that match the specified condition. For example,pkg.version.id < '3.0'
.PROJECT
: your Google Cloud project ID. If your project ID contains a colon (:
), see Domain-scoped projects.LOCATION
: the regional or multi-regional location of the repository.REPOSITORY
: the repository ID.
Execute the following command:
Linux, macOS, or Cloud Shell
gcloud artifacts rules create RULE_NAME \ --action=ACTION \ --project=PROJECT \ --location=LOCATION \ --repository=REPOSITORY \ --package=PACKAGE \ --condition="CONDITION"
Windows (PowerShell)
gcloud artifacts rules create RULE_NAME ` --action=ACTION ` --project=PROJECT ` --location=LOCATION ` --repository=REPOSITORY ` --package=PACKAGE ` --condition="CONDITION"
Windows (cmd.exe)
gcloud artifacts rules create RULE_NAME ^ --action=ACTION ^ --project=PROJECT ^ --location=LOCATION ^ --repository=REPOSITORY ^ --package=PACKAGE ^ --condition="CONDITION"
Created rule [RULE_NAME].
gcloud artifacts rules create
command.
API
Before using any of the request data, make the following replacements:
RULE_NAME
: the name of the rule. The name must be unique within your repository, have a max length of 256 characters, and consist of alpha-numeric characters, percent-encoded characters, or characters in the list [-
,.
,_
,~
,:
,@
,+
,^
].ACTION
: the action applied to a download that matches this rule. Choose betweenALLOW
, where the rule allows matching downloads to occur, andDENY
, where the rule blocks matching downloads from occurring.PACKAGE
: (optional) the name of the package. If supplied, the rule applies only to the specified package instead of the whole repository.CONDITION
: (optional) a CEL expression that defines a matching rule. If supplied, only applies the rule to downloads that match the specified condition. For example,pkg.version.id < '3.0'
.PROJECT
: your Google Cloud project ID. If your project ID contains a colon (:
), see Domain-scoped projects.LOCATION
: the regional or multi-regional location of the repository.REPOSITORY
: the repository ID.
HTTP method and URL:
POST https://artifactregistry.googleapis.com/v1/projects/PROJECT/locations/LOCATION/repositories/REPOSITORY/rules?ruleID=RULE_NAME
Request JSON body:
{ "action":"ACTION", "packageId":"PACKAGE", "condition": { "expression":"CONDITION" } }
To send your request, expand one of these options:
A new rule is created with the following output:{ "name": "projects/PROJECT/locations/LOCATION/repositories/REPOSITORY/rules/RULE_NAME", "action": ACTION, "operation": "DOWNLOAD" }
List download rules
gcloud
Before using any of the command data below, make the following replacements:
PROJECT
: your Google Cloud project ID. If your project ID contains a colon (:
), see Domain-scoped projects.LOCATION
: the regional or multi-regional location of the repository.REPOSITORY
: the name of the repository.
Execute the following command:
Linux, macOS, or Cloud Shell
gcloud artifacts rules list \ --project=PROJECT \ --location=LOCATION \ --repository=REPOSITORY
Windows (PowerShell)
gcloud artifacts rules list ` --project=PROJECT ` --location=LOCATION ` --repository=REPOSITORY
Windows (cmd.exe)
gcloud artifacts rules list ^ --project=PROJECT ^ --location=LOCATION ^ --repository=REPOSITORY
RULE: my-rule PACKAGE: example.com/foo ACTION: DENY OPERATION: DOWNLOAD CONDITION: pkg.version.id < '3.0'
gcloud artifacts rules list
command.
API
Before using any of the request data, make the following replacements:
PROJECT
: your Google Cloud project ID. If your project ID contains a colon (:
), see Domain-scoped projects.LOCATION
: the regional or multi-regional location of the repository.REPOSITORY
: the name of the repository.
HTTP method and URL:
GET https://artifactregistry.googleapis.com/v1/projects/PROJECT/locations/LOCATION/repositories/REPOSITORY/rules
To send your request, expand one of these options:
A list of rules for the specified project, location, and repository is displayed similar to the following:{ "rules": [ { "name": "projects/my-project/locations/us-central1/repositories/my-repo/rules/my-rule", "action": "DENY", "operation": "DOWNLOAD", "condition": { "expression": "pkg.version.id \u003c '3.0'" }, "packageId": "example.com/foo" } ] }
Describe download rules
gcloud
Before using any of the command data below, make the following replacements:
RULE_NAME
: the name of the rule. The name must be unique within your repository.PROJECT
: your Google Cloud project ID. If your project ID contains a colon (:
), see Domain-scoped projects.LOCATION
: the regional or multi-regional location of the repository.REPOSITORY
: the name of the repository.
Execute the following command:
Linux, macOS, or Cloud Shell
gcloud artifacts rules describe RULE_NAME \ --project=PROJECT \ --location=LOCATION \ --repository=REPOSITORY
Windows (PowerShell)
gcloud artifacts rules describe RULE_NAME ` --project=PROJECT ` --location=LOCATION ` --repository=REPOSITORY
Windows (cmd.exe)
gcloud artifacts rules describe RULE_NAME ^ --project=PROJECT ^ --location=LOCATION ^ --repository=REPOSITORY
RULE: my-rule PACKAGE: example.com/foo ACTION: DENY OPERATION: DOWNLOAD CONDITION: pkg.version.id < '3.0'
gcloud artifacts rules describe
command.
API
Before using any of the request data, make the following replacements:
RULE_NAME
: the name of the rule. The name must be unique within your repository.PROJECT
: your Google Cloud project ID. If your project ID contains a colon (:
), see Domain-scoped projects.LOCATION
: the regional or multi-regional location of the repository.REPOSITORY
: the name of the repository.
HTTP method and URL:
GET https://artifactregistry.googleapis.com/v1/projects/PROJECT/locations/LOCATION/repositories/REPOSITORY/rules/RULE_NAME
To send your request, expand one of these options:
Rule details are displayed similar to the following:{ "rules": [ { "name": "projects/my-project/locations/us-central1/repositories/my-repo/rules/my-rule", "action": "DENY", "operation": "DOWNLOAD", "condition": { "expression": "pkg.version.id \u003c '3.0'" }, "packageId": "example.com/foo" } ] }
Update download rules
gcloud
Remove any variables you don't want to update.
Before using any of the command data below, make the following replacements:
RULE_NAME
: the name of the rule. The name must be unique within your repository.ACTION
: the action applied to a download that matches this rule. Choose betweenALLOW
andDENY
.PACKAGE
: the name of the package. If not supplied, the rule applies to the whole repository.CONDITION
: a CEL expression that defines a matching rule. If supplied, only applies the rule to downloads that match the specified condition. For example,pkg.version.id < '3.0'
.PROJECT
: your Google Cloud project ID. If your project ID contains a colon (:
), see Domain-scoped projects.LOCATION
: the regional or multi-regional location of the repository.REPOSITORY
: the name of the repository.
Execute the following command:
Linux, macOS, or Cloud Shell
gcloud artifacts rules update RULE_NAME \ --action=ACTION \ --project=PROJECT \ --location=LOCATION \ --repository=REPOSITORY \ --package=PACKAGE \ --condition="CONDITION"
Windows (PowerShell)
gcloud artifacts rules update RULE_NAME ` --action=ACTION ` --project=PROJECT ` --location=LOCATION ` --repository=REPOSITORY ` --package=PACKAGE ` --condition="CONDITION"
Windows (cmd.exe)
gcloud artifacts rules update RULE_NAME ^ --action=ACTION ^ --project=PROJECT ^ --location=LOCATION ^ --repository=REPOSITORY ^ --package=PACKAGE ^ --condition="CONDITION"
Updated rule [RULE_NAME]. action: ACTION condition: expression: CONDITION name: projects/PROJECT/locationsLOCATION/repositories/REPOSITORY/rules/RULE_NAME operation: DOWNLOAD
gcloud artifacts rules update
command.
API
Remove any variables you don't want to update.
Before using any of the request data, make the following replacements:
RULE_NAME
: the name of the rule. The name must be unique within your repository.ACTION
: the action applied to a download that matches this rule. Choose betweenALLOW
andDENY
.PACKAGE
: the name of the package. If not supplied, the rule applies to the whole repository.CONDITION
: a CEL expression that defines a matching rule. If supplied, only applies the rule to downloads that match the specified condition. For example,pkg.version.id < '3.0'
.PROJECT
: your Google Cloud project ID. If your project ID contains a colon (:
), see Domain-scoped projects.LOCATION
: the regional or multi-regional location of the repository.REPOSITORY
: the name of the repository.
HTTP method and URL:
PATCH https://artifactregistry.googleapis.com/v1/projects/PROJECT/locations/LOCATION/repositories/REPOSITORY/rules/RULE_NAME
Request JSON body:
{ "action":"ACTION", "packageId":"PACKAGE", "condition": { "expression":"CONDITION" } }
To send your request, expand one of these options:
Updated rule details are shown similar to the following:{ "name": "projects/PROJECT/locations/LOCATION/repositories/REPOSITORY/rules/RULE_NAME", "action": ACTION, "operation": "DOWNLOAD" }
Delete download rules
gcloud
Before using any of the command data below, make the following replacements:
RULE_NAME
: the name of the rule. The name must be unique within your repository.PROJECT
: your Google Cloud project ID. If your project ID contains a colon (:
), see Domain-scoped projects.LOCATION
: the regional or multi-regional location of the repository.REPOSITORY
: the name of the repository.
Execute the following command:
Linux, macOS, or Cloud Shell
gcloud artifacts rules describe RULE_NAME \ --project=PROJECT \ --location=LOCATION \ --repository=REPOSITORY
Windows (PowerShell)
gcloud artifacts rules describe RULE_NAME ` --project=PROJECT ` --location=LOCATION ` --repository=REPOSITORY
Windows (cmd.exe)
gcloud artifacts rules describe RULE_NAME ^ --project=PROJECT ^ --location=LOCATION ^ --repository=REPOSITORY
You are about to delete rule [RULE_NAME] Do you want to continue (Y/n)? Y Deleted rule [RULE_NAME].
gcloud artifacts rules delete
command.
API
Before using any of the request data, make the following replacements:
RULE_NAME
: the name of the rule. The name must be unique within your repository.PROJECT
: your Google Cloud project ID. If your project ID contains a colon (:
), see Domain-scoped projects.LOCATION
: the regional or multi-regional location of the repository.REPOSITORY
: the name of the repository.
HTTP method and URL:
DELETE https://artifactregistry.googleapis.com/v1/projects/PROJECT/locations/LOCATION/repositories/REPOSITORY/rules/RULE_NAME
To send your request, expand one of these options:
For more information, see the REST reference.Use CEL to define conditions
You can define conditions for your download rules with
Common Expression Language (CEL), which is an open-source language
for expression evaluation. Artifact Registry provides the pkg
object that
contains the following attributes:
pkg.id
: a string representing the package name of the artifact. Can be used with rules set at the repository level.pkg.version.id
: a string representing the version of the artifact.pkg.version.tag
: a string representing the tag of the artifact. Use only in a Docker repository.
You can use logical operators and built-in functions with CEL. The following are some example CEL expressions that might be useful in your download rules:
Useful for rules set at the repository level:
pkg.id == 'myPackage' #Artifact package matches 'myPackage' pkg.id.startsWith('my') #Artifact package must start with 'my'
Useful for rules set on packages:
pkg.version.id != '1.0.0' #Artifact version is not '1.0.0' pkg.version.id > '1.0.1' || pkg.version.id < '0.0.1' #Artifact version is greater than '1.0.1' or less than '0.0.1' pkg.version.id.startsWith('1.0.') #Artifact version must start with '1.0.' pkg.version.id in ['1.0.0', '1.2.0'] #Artifact version must be a member of the list ['1.0.0', '1.2.0'] pkg.version.tag == 'tag1' #Artifact tag must be 'tag1' pkg.version.tag.startsWith('tag') #Artifact tag must start with 'tag' pkg.version.tag in ['tag1', 'tag2'] #Artifact tag must be a member of the list ['tag1', 'tag2']
When adding rules with tag-based conditions such as pkg.version.tag == 'latest'
in your Docker repositories, be aware of the following:
- When pulling by digest, the client doesn't provide a tag. Conditions using tags will be matched against an empty tag and might result in unexpected behavior.
- For multi-arch container images, conditions using tags might not work as expected and should be avoided.