Downloads von Artefakten mit Downloadregeln einschränken

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

Mit Downloadregeln können Sie Artefaktdownloads 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 Artefaktdownloads einschränken in der Übersicht unter „Zugriff steuern und Artefakte schützen“.

Hinweise

  1. Wenn Sie noch keines 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 in Ihrem Repository eindeutig sein, darf maximal 256 Zeichen lang sein und darf nur alphanumerische Zeichen, prozentcodierte Zeichen oder Zeichen aus der Liste [-, ., _, ~, :, @, +, ^] enthalten.
  • ACTION: die Aktion, die auf einen Download angewendet wird, der dieser Regel entspricht. Wählen Sie zwischen ALLOW, wobei die Regel übereinstimmende Downloads zulässt, und DENY, wobei die Regel übereinstimmende Downloads blockiert.
  • PACKAGE: (optional) der Name des Pakets. Falls 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. Falls 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 für das Repository.
  • 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"
Eine neue Regel wird mit der folgenden Ausgabe erstellt:
Created rule [RULE_NAME].
Weitere Informationen finden Sie im gcloud artifacts rules create-Befehl.

API

Ersetzen Sie diese Werte in den folgenden Anfragedaten:

  • RULE_NAME: der Name der Regel. Der Name muss in Ihrem Repository eindeutig sein, darf maximal 256 Zeichen lang sein und darf nur alphanumerische Zeichen, prozentcodierte Zeichen oder Zeichen aus der Liste [-, ., _, ~, :, @, +, ^] enthalten.
  • ACTION: die Aktion, die auf einen Download angewendet wird, der dieser Regel entspricht. Wählen Sie zwischen ALLOW, wobei die Regel übereinstimmende Downloads zulässt, und DENY, wobei die Regel übereinstimmende Downloads blockiert.
  • PACKAGE: (optional) der Name des Pakets. Falls 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. Falls 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 für das Repository.
  • 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:

Mit der folgenden Ausgabe wird eine neue Regel 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 für das Repository.
  • 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 Standort und das angegebene Repository wird angezeigt, ähnlich wie im Folgenden:
RULE: my-rule
PACKAGE: example.com/foo
ACTION: DENY
OPERATION: DOWNLOAD
CONDITION: pkg.version.id < '3.0'
Weitere Informationen finden Sie im gcloud artifacts rules list-Befehl.

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 für das Repository.
  • 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 Standort und das angegebene Repository wird angezeigt, ähnlich wie im Folgenden:
{
  "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 Repositorys 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 für das Repository.
  • 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 werden in etwa so angezeigt:
RULE: my-rule
PACKAGE: example.com/foo
ACTION: DENY
OPERATION: DOWNLOAD
CONDITION: pkg.version.id < '3.0'
Weitere Informationen finden Sie im gcloud artifacts rules describe-Befehl.

API

Ersetzen Sie diese Werte in den folgenden Anfragedaten:

  • RULE_NAME: der Name der Regel. Der Name muss innerhalb Ihres Repositorys 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 für das Repository.
  • 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:

Regeldetails werden in etwa so angezeigt:
{
  "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 Sie nicht aktualisieren möchten.

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

  • RULE_NAME: der Name der Regel. Der Name muss innerhalb Ihres Repositorys eindeutig sein.
  • ACTION: die Aktion, die auf einen Download angewendet wird, der dieser Regel entspricht. Wählen Sie zwischen ALLOW und DENY aus.
  • PACKAGE: der Name des Pakets. Wenn nichts angegeben ist, gilt die Regel für das gesamte Repository.
  • CONDITION: Ein CEL-Ausdruck, der eine Abgleichsregel definiert. Falls 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 für das Repository.
  • 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 werden in etwa so angezeigt:
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 gcloud artifacts rules update-Befehl.

API

Entfernen Sie alle Variablen, die Sie nicht aktualisieren möchten.

Ersetzen Sie diese Werte in den folgenden Anfragedaten:

  • RULE_NAME: der Name der Regel. Der Name muss innerhalb Ihres Repositorys eindeutig sein.
  • ACTION: die Aktion, die auf einen Download angewendet wird, der dieser Regel entspricht. Wählen Sie zwischen ALLOW und DENY aus.
  • PACKAGE: der Name des Pakets. Wenn nichts angegeben ist, gilt die Regel für das gesamte Repository.
  • CONDITION: Ein CEL-Ausdruck, der eine Abgleichsregel definiert. Falls 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 für das Repository.
  • 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:

Aktualisierte Regeldetails werden ähnlich wie unten dargestellt:
{
  "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 Repositorys 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 für das Repository.
  • REPOSITORY: Name des Repositorys.

Führen Sie folgenden Befehl aus:

Linux, macOS oder Cloud Shell

gcloud artifacts rules delete RULE_NAME \
    --project=PROJECT \
    --location=LOCATION \
    --repository=REPOSITORY

Windows (PowerShell)

gcloud artifacts rules delete RULE_NAME `
    --project=PROJECT `
    --location=LOCATION `
    --repository=REPOSITORY

Windows (cmd.exe)

gcloud artifacts rules delete RULE_NAME ^
    --project=PROJECT ^
    --location=LOCATION ^
    --repository=REPOSITORY
Die Regel wird mit der folgenden Ausgabe gelöscht:
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 gcloud artifacts rules delete-Befehl.

API

Ersetzen Sie diese Werte in den folgenden Anfragedaten:

  • RULE_NAME: der Name der Regel. Der Name muss innerhalb Ihres Repositorys 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 für das Repository.
  • 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. CEL ist eine Open-Source-Sprache zur Auswertung von Ausdrücken. Artifact Registry stellt das pkg-Objekt mit den folgenden Attributen bereit:

  • pkg.id: Ein String, der den Paketnamen des Artefakts darstellt. Kann mit Regeln verwendet werden, die auf Repository-Ebene festgelegt sind.
  • 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 auf Repository-Ebene:

      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 werden:

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

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

  • Wenn der Abruf über den Digest erfolgt, stellt der Client kein Tag bereit. Bedingungen mit Tags werden mit einem leeren Tag abgeglichen und können zu unerwartetem Verhalten führen.
  • Bei Container-Images für mehrere Architekturen funktionieren Bedingungen mit Tags möglicherweise nicht wie erwartet und sollten vermieden werden.