Downloads von Artefakten mit Downloadregeln einschränken

Auf dieser Seite wird beschrieben, wie Sie den Download von Artefakten aus Ihren Artifact Registry-Repositories einschränken, indem Sie Downloadregeln erstellen und verwalten.

Mit Downloadregeln können Sie den Download von Artefakten aus Ihren Repositories und Paketen zulassen oder ablehnen. Sie können auch Bedingungen festlegen, damit die Regel auf bestimmte Tags oder Versionen angewendet wird.

Weitere Informationen zur Funktionsweise von Downloadregeln finden Sie im Abschnitt Downloads von Artefakten einschränken der Übersicht „Zugriff steuern und Artefakte schützen“.

Hinweis

  1. Wenn Sie noch keins haben, erstellen Sie ein Standard-Repository im Docker-Format.
  2. Optional: Konfigurieren Sie die Standardeinstellungen für Google Cloud CLI-Befehle.

Erforderliche Rollen

Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen für das Repository zuzuweisen, um die Berechtigungen zu erhalten, die Sie zum Erstellen und Verwalten von Downloadregeln benötigen:

Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

Sie können die erforderlichen Berechtigungen auch über benutzerdefinierte Rollen oder andere vordefinierte Rollen erhalten.

Downloadregeln erstellen

gcloud

Ersetzen Sie folgende Werte, bevor sie einen der Befehlsdaten verwenden:

  • RULE_NAME: der Name der Regel. Der Name muss innerhalb Ihres Repositories eindeutig sein, darf maximal 256 Zeichen lang sein und darf nur alphanumerische Zeichen, Prozentzeichen oder Zeichen aus der Liste [-, ., _, ~, :, @, +, ^] enthalten.
  • ACTION: die Aktion, die auf einen Download angewendet wird, der dieser Regel entspricht. Wählen Sie zwischen ALLOW, mit der die Regel übereinstimmende Downloads zulässt, und DENY, mit der die Regel übereinstimmende Downloads blockiert.
  • PACKAGE: (optional) der Name des Pakets. Wenn angegeben, gilt die Regel nur für das angegebene Paket und nicht für das gesamte Repository.
  • CONDITION: (optional) ein CEL-Ausdruck, der eine Abgleichsregel definiert. Wenn angegeben, wird die Regel nur auf Downloads angewendet, die der angegebenen Bedingung entsprechen. Beispiel: pkg.version.id < '3.0'
  • PROJECT: Ihre Google Cloud Projekt-ID. Wenn die Projekt-ID einen Doppelpunkt (:) enthält, finden Sie weitere Informationen unter Auf Domains beschränkte Projekte.
  • LOCATION: der regionale oder multiregionale Speicherort des Repositories.
  • REPOSITORY: die Repository-ID.

Führen Sie folgenden Befehl aus:

Linux, macOS oder 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"
 Es wird eine neue Regel mit der folgenden Ausgabe erstellt: 
Created rule [RULE_NAME].
Weitere Informationen finden Sie im Hilfeartikel zum Befehl gcloud artifacts rules create.

API

Ersetzen Sie diese Werte in den folgenden Anfragedaten:

  • RULE_NAME: der Name der Regel. Der Name muss innerhalb Ihres Repositories eindeutig sein, darf maximal 256 Zeichen lang sein und darf nur alphanumerische Zeichen, Prozentzeichen oder Zeichen aus der Liste [-, ., _, ~, :, @, +, ^] enthalten.
  • ACTION: die Aktion, die auf einen Download angewendet wird, der dieser Regel entspricht. Wählen Sie zwischen ALLOW, mit der die Regel übereinstimmende Downloads zulässt, und DENY, mit der die Regel übereinstimmende Downloads blockiert.
  • PACKAGE: (optional) der Name des Pakets. Wenn angegeben, gilt die Regel nur für das angegebene Paket und nicht für das gesamte Repository.
  • CONDITION: (optional) ein CEL-Ausdruck, der eine Abgleichsregel definiert. Wenn angegeben, wird die Regel nur auf Downloads angewendet, die der angegebenen Bedingung entsprechen. Beispiel: pkg.version.id < '3.0'
  • PROJECT: Ihre Google Cloud Projekt-ID. Wenn die Projekt-ID einen Doppelpunkt (:) enthält, finden Sie weitere Informationen unter Auf Domains beschränkte Projekte.
  • LOCATION: der regionale oder multiregionale Speicherort des Repositories.
  • REPOSITORY: die Repository-ID.

HTTP-Methode und URL:

POST https://artifactregistry.googleapis.com/v1/projects/PROJECT/locations/LOCATION/repositories/REPOSITORY/rules?ruleID=RULE_NAME

JSON-Text anfordern:

{
  "action":"ACTION",
  "packageId":"PACKAGE",
  "condition":
  {
    "expression":"CONDITION"
  }
}

Wenn Sie die Anfrage senden möchten, maximieren Sie eine der folgenden Optionen:

Es wird eine neue Regel mit der folgenden Ausgabe erstellt: 
{
  "name": "projects/PROJECT/locations/LOCATION/repositories/REPOSITORY/rules/RULE_NAME",
  "action": ACTION,
  "operation": "DOWNLOAD"
}
Weitere Informationen finden Sie in der REST-Referenz.

Downloadregeln auflisten

gcloud

Ersetzen Sie folgende Werte, bevor sie einen der Befehlsdaten verwenden:

  • PROJECT: Ihre Google Cloud Projekt-ID. Wenn die Projekt-ID einen Doppelpunkt (:) enthält, finden Sie weitere Informationen unter Auf Domains beschränkte Projekte.
  • LOCATION: der regionale oder multiregionale Speicherort des Repositories.
  • REPOSITORY: Name des Repositorys.

Führen Sie folgenden Befehl aus:

Linux, macOS oder 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
 Eine Liste der Regeln für das angegebene Projekt, den angegebenen Speicherort und das angegebene Repository wird angezeigt, die in etwa so aussieht: 
RULE: my-rule
PACKAGE: example.com/foo
ACTION: DENY
OPERATION: DOWNLOAD
CONDITION: pkg.version.id < '3.0'
Weitere Informationen finden Sie im Hilfeartikel zum Befehl gcloud artifacts rules list.

API

Ersetzen Sie diese Werte in den folgenden Anfragedaten:

  • PROJECT: Ihre Google Cloud Projekt-ID. Wenn die Projekt-ID einen Doppelpunkt (:) enthält, finden Sie weitere Informationen unter Auf Domains beschränkte Projekte.
  • LOCATION: der regionale oder multiregionale Speicherort des Repositories.
  • REPOSITORY: Name des Repositorys.

HTTP-Methode und URL:

GET https://artifactregistry.googleapis.com/v1/projects/PROJECT/locations/LOCATION/repositories/REPOSITORY/rules

Wenn Sie die Anfrage senden möchten, maximieren Sie eine der folgenden Optionen:

Eine Liste der Regeln für das angegebene Projekt, den angegebenen Speicherort und das angegebene Repository wird angezeigt, die in etwa so aussieht: 
{
  "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"
    }
  ]
}
Weitere Informationen finden Sie in der REST-Referenz.

Downloadregeln beschreiben

gcloud

Ersetzen Sie folgende Werte, bevor sie einen der Befehlsdaten verwenden:

  • RULE_NAME: der Name der Regel. Der Name muss innerhalb Ihres Repositories eindeutig sein.
  • PROJECT: Ihre Google Cloud Projekt-ID. Wenn die Projekt-ID einen Doppelpunkt (:) enthält, finden Sie weitere Informationen unter Auf Domains beschränkte Projekte.
  • LOCATION: der regionale oder multiregionale Speicherort des Repositories.
  • REPOSITORY: Name des Repositorys.

Führen Sie folgenden Befehl aus:

Linux, macOS oder 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
 Die Regeldetails sehen in etwa so aus: 
RULE: my-rule
PACKAGE: example.com/foo
ACTION: DENY
OPERATION: DOWNLOAD
CONDITION: pkg.version.id < '3.0'
Weitere Informationen finden Sie im Hilfeartikel zum Befehl gcloud artifacts rules describe.

API

Ersetzen Sie diese Werte in den folgenden Anfragedaten:

  • RULE_NAME: der Name der Regel. Der Name muss innerhalb Ihres Repositories eindeutig sein.
  • PROJECT: Ihre Google Cloud Projekt-ID. Wenn die Projekt-ID einen Doppelpunkt (:) enthält, finden Sie weitere Informationen unter Auf Domains beschränkte Projekte.
  • LOCATION: der regionale oder multiregionale Speicherort des Repositories.
  • REPOSITORY: Name des Repositorys.

HTTP-Methode und URL:

GET https://artifactregistry.googleapis.com/v1/projects/PROJECT/locations/LOCATION/repositories/REPOSITORY/rules/RULE_NAME

Wenn Sie die Anfrage senden möchten, maximieren Sie eine der folgenden Optionen:

Die Regeldetails sehen in etwa so aus: 
{
  "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"
    }
  ]
}
Weitere Informationen finden Sie in der REST-Referenz.

Downloadregeln aktualisieren

gcloud

Entfernen Sie alle Variablen, die nicht aktualisiert werden sollen.

Ersetzen Sie folgende Werte, bevor sie einen der Befehlsdaten verwenden:

  • RULE_NAME: der Name der Regel. Der Name muss innerhalb Ihres Repositories eindeutig sein.
  • ACTION: die Aktion, die auf einen Download angewendet wird, der dieser Regel entspricht. Wählen Sie einen Wert zwischen ALLOW und DENY aus.
  • PACKAGE: der Name des Pakets. Wenn keine Angabe gemacht wird, gilt die Regel für das gesamte Repository.
  • CONDITION: Ein CEL-Ausdruck, der eine Abgleichsregel definiert. Wenn angegeben, wird die Regel nur auf Downloads angewendet, die der angegebenen Bedingung entsprechen. Beispiel: pkg.version.id < '3.0'
  • PROJECT: Ihre Google Cloud Projekt-ID. Wenn die Projekt-ID einen Doppelpunkt (:) enthält, finden Sie weitere Informationen unter Auf Domains beschränkte Projekte.
  • LOCATION: der regionale oder multiregionale Speicherort des Repositories.
  • REPOSITORY: Name des Repositorys.

Führen Sie folgenden Befehl aus:

Linux, macOS oder 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"
 Die aktualisierten Regeldetails sehen in etwa so aus: 
Updated rule [RULE_NAME].
action: ACTION
condition:
  expression: CONDITION
name: projects/PROJECT/locationsLOCATION/repositories/REPOSITORY/rules/RULE_NAME
operation: DOWNLOAD
Weitere Informationen finden Sie im Hilfeartikel zum Befehl gcloud artifacts rules update.

API

Entfernen Sie alle Variablen, die nicht aktualisiert werden sollen.

Ersetzen Sie diese Werte in den folgenden Anfragedaten:

  • RULE_NAME: der Name der Regel. Der Name muss innerhalb Ihres Repositories eindeutig sein.
  • ACTION: die Aktion, die auf einen Download angewendet wird, der dieser Regel entspricht. Wählen Sie einen Wert zwischen ALLOW und DENY aus.
  • PACKAGE: der Name des Pakets. Wenn keine Angabe gemacht wird, gilt die Regel für das gesamte Repository.
  • CONDITION: Ein CEL-Ausdruck, der eine Abgleichsregel definiert. Wenn angegeben, wird die Regel nur auf Downloads angewendet, die der angegebenen Bedingung entsprechen. Beispiel: pkg.version.id < '3.0'
  • PROJECT: Ihre Google Cloud Projekt-ID. Wenn die Projekt-ID einen Doppelpunkt (:) enthält, finden Sie weitere Informationen unter Auf Domains beschränkte Projekte.
  • LOCATION: der regionale oder multiregionale Speicherort des Repositories.
  • REPOSITORY: Name des Repositorys.

HTTP-Methode und URL:

PATCH https://artifactregistry.googleapis.com/v1/projects/PROJECT/locations/LOCATION/repositories/REPOSITORY/rules/RULE_NAME

JSON-Text anfordern:

{
  "action":"ACTION",
  "packageId":"PACKAGE",
  "condition":
  {
    "expression":"CONDITION"
  }
}

Wenn Sie die Anfrage senden möchten, maximieren Sie eine der folgenden Optionen:

Die aktualisierten Regeldetails sehen in etwa so aus: 
{
  "name": "projects/PROJECT/locations/LOCATION/repositories/REPOSITORY/rules/RULE_NAME",
  "action": ACTION,
  "operation": "DOWNLOAD"
}
Weitere Informationen finden Sie in der REST-Referenz.

Downloadregeln löschen

gcloud

Ersetzen Sie folgende Werte, bevor sie einen der Befehlsdaten verwenden:

  • RULE_NAME: der Name der Regel. Der Name muss innerhalb Ihres Repositories eindeutig sein.
  • PROJECT: Ihre Google Cloud Projekt-ID. Wenn die Projekt-ID einen Doppelpunkt (:) enthält, finden Sie weitere Informationen unter Auf Domains beschränkte Projekte.
  • LOCATION: der regionale oder multiregionale Speicherort des Repositories.
  • REPOSITORY: Name des Repositorys.

Führen Sie folgenden Befehl aus:

Linux, macOS oder 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
 Die Regel wird gelöscht und die folgende Ausgabe wird angezeigt: 
You are about to delete rule [RULE_NAME]

Do you want to continue (Y/n)?  Y

Deleted rule [RULE_NAME].
Weitere Informationen finden Sie im Hilfeartikel zum Befehl gcloud artifacts rules delete.

API

Ersetzen Sie diese Werte in den folgenden Anfragedaten:

  • RULE_NAME: der Name der Regel. Der Name muss innerhalb Ihres Repositories eindeutig sein.
  • PROJECT: Ihre Google Cloud Projekt-ID. Wenn die Projekt-ID einen Doppelpunkt (:) enthält, finden Sie weitere Informationen unter Auf Domains beschränkte Projekte.
  • LOCATION: der regionale oder multiregionale Speicherort des Repositories.
  • REPOSITORY: Name des Repositorys.

HTTP-Methode und URL:

DELETE https://artifactregistry.googleapis.com/v1/projects/PROJECT/locations/LOCATION/repositories/REPOSITORY/rules/RULE_NAME

Wenn Sie die Anfrage senden möchten, maximieren Sie eine der folgenden Optionen:

Weitere Informationen finden Sie in der REST-Referenz.

Bedingungen mit CEL definieren

Sie können Bedingungen für Ihre Downloadregeln mit der Common Expression Language (CEL) definieren, einer Open-Source-Sprache zur Ausdrucksbewertung. Artifact Registry bietet das pkg-Objekt mit den folgenden Attributen:

  • pkg.id: ein String, der den Paketnamen des Artefakts darstellt. Kann mit Regeln auf Repositoryebene verwendet werden.
  • pkg.version.id: Ein String, der die Version des Artefakts darstellt.
  • pkg.version.tag: Ein String, der das Tag des Artefakts darstellt. Nur in einem Docker-Repository verwenden.

Sie können logische Operatoren und integrierte Funktionen mit CEL verwenden. Im Folgenden finden Sie einige Beispiel-CEL-Ausdrücke, die in Ihren Downloadregeln nützlich sein könnten:

  • Nützlich für Regeln, die auf Repositoryebene festgelegt sind:

      pkg.id == 'myPackage'  #Artifact package matches 'myPackage'
  pkg.id.startsWith('my') #Artifact package must start with 'my'

  • Nützlich für Regeln, die für Pakete festgelegt sind:

      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']

Beachten Sie Folgendes, wenn Sie Ihren Docker-Repositories Regeln mit tagbasierten Bedingungen wie pkg.version.tag == 'latest' hinzufügen:

  • Beim Abrufen per Digest gibt der Client kein Tag an. Bedingungen mit Tags werden mit einem leeren Tag abgeglichen und können zu unerwartetem Verhalten führen.
  • Bei Container-Images mit mehreren Architekturen funktionieren Bedingungen mit Tags möglicherweise nicht wie erwartet und sollten vermieden werden.