הגבלת הורדות של ארטיפקטים באמצעות כללי הורדה

בדף הזה מוסבר איך להגביל את ההורדות של ארטיפקטים ממאגרי Artifact Registry באמצעות יצירה וניהול של כללי הורדה.

כללי הורדה מאפשרים לכם לאשר או לדחות הורדות של ארטיפקטים מהמאגרים ומהחבילות שלכם. אפשר גם להגדיר תנאים כך שהכלל יחול על תגים או גרסאות ספציפיים.

לפרטים על אופן הפעולה של כללי ההורדה, אפשר לעיין בקטע הגבלת ההורדה של ארטיפקטים במאמר 'סקירה כללית על בקרת גישה והגנה על ארטיפקטים'.

לפני שמתחילים

  1. אם עדיין אין לכם מאגר, צרו מאגר סטנדרטי בפורמט Docker.
  2. (אופציונלי) הגדרת ערכי ברירת מחדל לפקודות של Google Cloud CLI.

התפקידים הנדרשים

כדי לקבל את ההרשאות שדרושות ליצירה ולניהול של כללי הורדה, צריך לבקש מהאדמין להקצות לכם את תפקידי ה-IAM הבאים במאגר:

להסבר על מתן תפקידים, ראו איך מנהלים את הגישה ברמת הפרויקט, התיקייה והארגון.

יכול להיות שאפשר לקבל את ההרשאות הנדרשות גם באמצעות תפקידים בהתאמה אישית או תפקידים מוגדרים מראש.

יצירת כללי הורדה

gcloud

לפני השימוש בנתוני הפקודה הבאים, צריך להחליף את הנתונים הבאים:

  • RULE_NAME: שם הכלל. השם צריך להיות ייחודי במאגר, לא יכול להיות ארוך מ-256 תווים, והוא יכול לכלול תווים אלפאנומריים, תווים בקידוד אחוזים או תווים מהרשימה [-, ., _, ~, :, @, +, ^].
  • ACTION: הפעולה שחלה על הורדה שתואמת לכלל הזה. בוחרים בין ALLOW, שבו הכלל מאפשר לבצע הורדות תואמות, לבין DENY, שבו הכלל חוסם הורדות תואמות.
  • PACKAGE: (אופציונלי) שם החבילה. אם מציינים חבילה, הכלל חל רק על החבילה שצוינה ולא על כל המאגר.
  • CONDITION: (אופציונלי) ביטוי CEL שמגדיר כלל התאמה. אם מציינים תנאי, הכלל חל רק על הורדות שתואמות לתנאי שצוין. לדוגמה, pkg.version.id < '3.0'.
  • PROJECT: מזהה הפרויקט ב- Google Cloud. אם מזהה הפרויקט מכיל נקודתיים (:), אפשר לעיין במאמר בנושא פרויקטים בהיקף הדומיין.
  • LOCATION: המיקום האזורי או הרב-אזורי של המאגר.
  • REPOSITORY: מזהה המאגר.

מריצים את הפקודה הבאה:

‫Linux,‏ macOS או 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.

API

לפני שמשתמשים בנתוני הבקשה, צריך להחליף את הנתונים הבאים:

  • RULE_NAME: שם הכלל. השם צריך להיות ייחודי במאגר, לא יכול להיות ארוך מ-256 תווים, והוא יכול לכלול תווים אלפאנומריים, תווים בקידוד אחוזים או תווים מהרשימה [-, ., _, ~, :, @, +, ^].
  • ACTION: הפעולה שחלה על הורדה שתואמת לכלל הזה. בוחרים בין ALLOW, שבו הכלל מאפשר לבצע הורדות תואמות, לבין DENY, שבו הכלל חוסם הורדות תואמות.
  • PACKAGE: (אופציונלי) שם החבילה. אם מציינים חבילה, הכלל חל רק על החבילה שצוינה ולא על כל המאגר.
  • CONDITION: (אופציונלי) ביטוי CEL שמגדיר כלל התאמה. אם מציינים תנאי, הכלל חל רק על הורדות שתואמות לתנאי שצוין. לדוגמה, pkg.version.id < '3.0'.
  • PROJECT: מזהה הפרויקט ב- Google Cloud. אם מזהה הפרויקט מכיל נקודתיים (:), אפשר לעיין במאמר בנושא פרויקטים בהיקף הדומיין.
  • LOCATION: המיקום האזורי או הרב-אזורי של המאגר.
  • REPOSITORY: מזהה המאגר.

ה-method של ה-HTTP וכתובת ה-URL:

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

תוכן בקשת JSON:

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

כדי לשלוח את הבקשה צריך להרחיב אחת מהאפשרויות הבאות:

נוצר כלל חדש עם הפלט הבא:
{
  "name": "projects/PROJECT/locations/LOCATION/repositories/REPOSITORY/rules/RULE_NAME",
  "action": ACTION,
  "operation": "DOWNLOAD"
}
מידע נוסף זמין במאמר בנושא REST.

הצגת כללי הורדה

gcloud

לפני השימוש בנתוני הפקודה הבאים, צריך להחליף את הנתונים הבאים:

מריצים את הפקודה הבאה:

‫Linux,‏ macOS או 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.

API

לפני שמשתמשים בנתוני הבקשה, צריך להחליף את הנתונים הבאים:

ה-method של ה-HTTP וכתובת ה-URL:

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

כדי לשלוח את הבקשה צריך להרחיב אחת מהאפשרויות הבאות:

תוצג רשימה של כללים לפרויקט, למיקום ולמאגר שצוינו, בדומה לדוגמה הבאה:
{
  "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"
    }
  ]
}
מידע נוסף זמין במאמר בנושא REST.

תיאור כללי ההורדה

gcloud

לפני השימוש בנתוני הפקודה הבאים, צריך להחליף את הנתונים הבאים:

  • RULE_NAME: שם הכלל. השם צריך להיות ייחודי במאגר.
  • PROJECT: מזהה הפרויקט ב- Google Cloud. אם מזהה הפרויקט מכיל נקודתיים (:), אפשר לעיין במאמר בנושא פרויקטים בהיקף הדומיין.
  • LOCATION: המיקום האזורי או הרב-אזורי של המאגר.
  • REPOSITORY: שם המאגר.

מריצים את הפקודה הבאה:

‫Linux,‏ macOS או 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.

API

לפני שמשתמשים בנתוני הבקשה, צריך להחליף את הנתונים הבאים:

  • RULE_NAME: שם הכלל. השם צריך להיות ייחודי במאגר.
  • PROJECT: מזהה הפרויקט ב- Google Cloud. אם מזהה הפרויקט מכיל נקודתיים (:), אפשר לעיין במאמר בנושא פרויקטים בהיקף הדומיין.
  • LOCATION: המיקום האזורי או הרב-אזורי של המאגר.
  • REPOSITORY: שם המאגר.

ה-method של ה-HTTP וכתובת ה-URL:

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

כדי לשלוח את הבקשה צריך להרחיב אחת מהאפשרויות הבאות:

פרטי הכלל מוצגים באופן הבא:
{
  "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"
    }
  ]
}
מידע נוסף זמין במאמר בנושא REST.

עדכון כללי ההורדה

gcloud

מסירים את המשתנים שלא רוצים לעדכן.

לפני השימוש בנתוני הפקודה הבאים, צריך להחליף את הנתונים הבאים:

  • RULE_NAME: שם הכלל. השם צריך להיות ייחודי במאגר.
  • ACTION: הפעולה שחלה על הורדה שתואמת לכלל הזה. בוחרים בין ALLOW לבין DENY.
  • PACKAGE: השם של החבילה. אם לא תציינו מאגר, הכלל יחול על כל המאגר.
  • CONDITION: ביטוי CEL שמגדיר כלל התאמה. אם מציינים תנאי, הכלל חל רק על הורדות שתואמות לתנאי שצוין. לדוגמה, pkg.version.id < '3.0'.
  • PROJECT: מזהה הפרויקט ב- Google Cloud. אם מזהה הפרויקט מכיל נקודתיים (:), אפשר לעיין במאמר בנושא פרויקטים בהיקף הדומיין.
  • LOCATION: המיקום האזורי או הרב-אזורי של המאגר.
  • REPOSITORY: שם המאגר.

מריצים את הפקודה הבאה:

‫Linux,‏ macOS או 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.

API

מסירים את המשתנים שלא רוצים לעדכן.

לפני שמשתמשים בנתוני הבקשה, צריך להחליף את הנתונים הבאים:

  • RULE_NAME: שם הכלל. השם צריך להיות ייחודי במאגר.
  • ACTION: הפעולה שחלה על הורדה שתואמת לכלל הזה. בוחרים בין ALLOW לבין DENY.
  • PACKAGE: השם של החבילה. אם לא תציינו מאגר, הכלל יחול על כל המאגר.
  • CONDITION: ביטוי CEL שמגדיר כלל התאמה. אם מציינים תנאי, הכלל חל רק על הורדות שתואמות לתנאי שצוין. לדוגמה, pkg.version.id < '3.0'.
  • PROJECT: מזהה הפרויקט ב- Google Cloud. אם מזהה הפרויקט מכיל נקודתיים (:), אפשר לעיין במאמר בנושא פרויקטים בהיקף הדומיין.
  • LOCATION: המיקום האזורי או הרב-אזורי של המאגר.
  • REPOSITORY: שם המאגר.

ה-method של ה-HTTP וכתובת ה-URL:

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

תוכן בקשת JSON:

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

כדי לשלוח את הבקשה צריך להרחיב אחת מהאפשרויות הבאות:

פרטי הכלל המעודכנים מוצגים באופן הבא:
{
  "name": "projects/PROJECT/locations/LOCATION/repositories/REPOSITORY/rules/RULE_NAME",
  "action": ACTION,
  "operation": "DOWNLOAD"
}
מידע נוסף זמין במאמר בנושא REST.

מחיקת כללי הורדה

gcloud

לפני השימוש בנתוני הפקודה הבאים, צריך להחליף את הנתונים הבאים:

  • RULE_NAME: שם הכלל. השם צריך להיות ייחודי במאגר.
  • PROJECT: מזהה הפרויקט ב- Google Cloud. אם מזהה הפרויקט מכיל נקודתיים (:), אפשר לעיין במאמר בנושא פרויקטים בהיקף הדומיין.
  • LOCATION: המיקום האזורי או הרב-אזורי של המאגר.
  • REPOSITORY: שם המאגר.

מריצים את הפקודה הבאה:

‫Linux,‏ macOS או 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
הכלל נמחק ומוצג הפלט הבא:
You are about to delete rule [RULE_NAME]

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

Deleted rule [RULE_NAME].
מידע נוסף זמין בפקודה gcloud artifacts rules delete.

API

לפני שמשתמשים בנתוני הבקשה, צריך להחליף את הנתונים הבאים:

  • RULE_NAME: שם הכלל. השם צריך להיות ייחודי במאגר.
  • PROJECT: מזהה הפרויקט ב- Google Cloud. אם מזהה הפרויקט מכיל נקודתיים (:), אפשר לעיין במאמר בנושא פרויקטים בהיקף הדומיין.
  • LOCATION: המיקום האזורי או הרב-אזורי של המאגר.
  • REPOSITORY: שם המאגר.

ה-method של ה-HTTP וכתובת ה-URL:

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

כדי לשלוח את הבקשה צריך להרחיב אחת מהאפשרויות הבאות:

מידע נוסף זמין במאמר בנושא REST.

שימוש ב-CEL להגדרת תנאים

אפשר להגדיר תנאים לכללי ההורדה באמצעות Common Expression Language ‏ (CEL), שפה בקוד פתוח להערכת ביטויים. ‫Artifact Registry מספק את האובייקט pkg שמכיל את המאפיינים הבאים:

  • pkg.id: מחרוזת שמייצגת את שם החבילה של הארטיפקט. אפשר להשתמש בהם עם כללים שמוגדרים ברמת המאגר.
  • pkg.version.id: מחרוזת שמייצגת את גרסת הארטיפקט.
  • pkg.version.tag: מחרוזת שמייצגת את התג של הארטיפקט. לשימוש רק במאגר Docker.

אפשר להשתמש באופרטורים לוגיים ובפונקציות מובנות עם CEL. בהמשך מפורטות כמה דוגמאות לביטויי CEL שיכולים להיות שימושיים בכללי ההורדה שלכם:

  • המאפיין הזה שימושי לכללים שמוגדרים ברמת המאגר:

      pkg.id == 'myPackage'  #Artifact package matches 'myPackage'
      pkg.id.startsWith('my') #Artifact package must start with 'my'
    
  • שימושי לכללים שמוגדרים לחבילות:

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

כשמוסיפים כללים עם תנאים מבוססי-תגים כמו pkg.version.tag == 'latest' במאגרי Docker, חשוב לשים לב לדברים הבאים:

  • כששולפים לפי תקציר, הלקוח לא מספק תג. תנאים שמשתמשים בתגים יותאמו לתג ריק, ועשויים לגרום להתנהגות לא צפויה.
  • בתמונות של קונטיינרים מרובי-ארכיטקטורה, יכול להיות שתנאים שמשתמשים בתגים לא יפעלו כמצופה, ולכן מומלץ להימנע מהם.