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

בדף הזה מוסבר איך להגביל את ההורדות של פריטי מידע שנוצרו מהמאגרים של 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: מחרוזת שמייצגת את שם החבילה של פריט המידע שנוצר בתהליך הפיתוח (Artifact). אפשר להשתמש בהם עם קבוצת כללים שמוגדרת ברמת המאגר.
  • ‫pkg.version.id: מחרוזת שמייצגת את גרסת פריט המידע שנוצר בתהליך הפיתוח (Artifact).
  • ‫pkg.version.tag: מחרוזת שמייצגת את התג של פריט המידע שנוצר. צריך להשתמש רק במאגר Docker.
  • ‫pkg.version.annotations: מפה של מחרוזות מפתח/ערך שמייצגות הערות שהמשתמש הגדיר בגרסת פריט המידע שנוצר במאגר רגיל.

אתם יכולים להשתמש באופרטורים לוגיים ובפונקציות מובנות עם 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']
      'quarantined' in pkg.version.annotations && pkg.version.annotations['quarantined'] == 'true' #Artifact version has annotation 'quarantined' set to 'true'
    

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

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