הגדרת מיקום הנתונים באמצעות נקודות קצה אזוריות

בדף הזה מוסבר על נקודות קצה (endpoints) גלובליות ואזוריות של שירות Artifact Analysis ואיך משתמשים בהן.

נקודת קצה של שירות היא כתובת URL בסיסית שמציינת את כתובת הרשת של שירות API. ל-Artifact Analysis יש נקודות קצה גלובליות ואזוריות.

• נקודת קצה גלובלית: כברירת מחדל, Artifact Analysis שולח בקשות API לנקודת הקצה הגלובלית, containeranalysis.googleapis.com. נקודות קצה גלובליות לא מבטיחות שהנתונים בזמן ההעברה יישארו במיקום מסוים, ויכולות לאחזר נתונים של Artifact Analysis מכל אזור נתמך. יכול להיות שהנתונים שלכם יעובדו מחוץ לאזור שבו הם מאוחסנים.

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

  containeranalysis.region.rep.googleapis.com.

  כדאי להשתמש בנקודות קצה אזוריות במצבים הבאים:

  • האפליקציה שצריכה לגשת לנתונים שלכם לא נמצאת בקרבה גיאוגרפית לאזור שבו הנתונים מאוחסנים.

  • אתם מאחסנים נתונים בכמה מיקומים ורוצים לשפר את זמן האחזור, המהימנות והזמינות.

  • אתם צריכים לעמוד בדרישות של מדיניות או תקנות בנושא מיקום נתונים, שמחייבות אתכם לעבד את הנתונים באותו מיקום שבו הם מאוחסנים.

אישורים ונתוני אישור המקור של Build מאוחסנים בנקודת הקצה הגלובלית. תוצאות הסריקה לאיתור נקודות חולשה ונתוני ה-SBOM מאוחסנים בנקודות קצה אזוריות ורב-אזוריות.

מיקומים שתומכים בנקודות קצה אזוריות

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

במקרה של מספר אזורים ואזורים מסוימים, Artifact Analysis תומך רק בנקודת הקצה הגלובלית.

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

פקודות של Google Cloud CLI

כשמשתמשים ב-CLI של gcloud, יש שתי דרכים לשלוח בקשות לנקודת הקצה האזורית:

• משתמשים בדגל --location.
• מגדירים את נקודת הקצה האזורית שרוצים להשתמש בה בפקודות של Artifact Analysis.

שימוש בדגל --location

כדי להפנות את הבקשה לנקודת הקצה המתאימה בשירות, אפשר להשתמש בדגל --location עם אחת מהפקודות הבאות:

• gcloud artifacts sbom export
• gcloud artifacts sbom list
• ‫gcloud artifacts sbom load
• gcloud artifacts version describe
• gcloud artifacts vulnerabilities list
• gcloud artifacts vulnerabilities load-vex

כדי שהבקשה תעובד בהצלחה בנקודת קצה אזורית, המיקום שצוין צריך לעמוד בדרישות הבאות:

• המיקום תומך בנקודת קצה אזורית.
• המיקום תואם לאזור שבו מאוחסנים המטא-נתונים של הארטיפקט.

אם לא מציינים את האפשרות --location או מציינים מיקום שלא תומך בנקודת קצה אזורית, הפקודה משתמשת בנקודת הקצה הגלובלית.

לדוגמה, הפקודה הבאה מציגה רשימה של נקודות חולשה באימג' שמאוחסן ב-us-east1:

gcloud artifacts vulnerabilities list --location=us-east1 us-east1-docker.pkg.dev/my-project/my-repo/my-image@sha256:49765698074d6d7baa82f

הגדרת נקודת קצה (endpoint) כברירת מחדל לפקודות

כברירת מחדל, הפקודות ב-CLI של gcloud משתמשות בנקודת הקצה הגלובלית. אתם יכולים להגדיר נקודת קצה אזורית כברירת מחדל לפקודות של Artifact Analysis, כדי שלא תצטרכו לציין את המיקום בפקודות נפרדות.

ודאו שאתם משתמשים בגרסה 402.0.0 ואילך של ה-CLI של gcloud.

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

• ‫LOCATION: האזור שבו מאוחסנים המטא-נתונים.

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

‫Linux,‏ macOS או Cloud Shell

הערה: חשוב לוודא שהפעלתם את Google Cloud CLI עם אימות ופרויקט באמצעות אחת מהפקודות הבאות: gcloud init; או gcloud auth login ו- gcloud config set project.

gcloud config set api_endpoint_overrides/containeranalysis https://containeranalysis.LOCATION.rep.googleapis.com

‏Windows (PowerShell)

הערה: חשוב לוודא שהפעלתם את Google Cloud CLI עם אימות ופרויקט באמצעות אחת מהפקודות הבאות: gcloud init; או gcloud auth login ו- gcloud config set project.

gcloud config set api_endpoint_overrides/containeranalysis https://containeranalysis.LOCATION.rep.googleapis.com

Windows‏ (cmd.exe)

הערה: חשוב לוודא שהפעלתם את Google Cloud CLI עם אימות ופרויקט באמצעות אחת מהפקודות הבאות: gcloud init; או gcloud auth login ו- gcloud config set project.

gcloud config set api_endpoint_overrides/containeranalysis https://containeranalysis.LOCATION.rep.googleapis.com

שימוש בנקודת קצה אזורית לשיטות API

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

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

• ‫LOCATION: האזור שבו מאוחסנים המטא-נתונים.
• ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .

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

GET https://containeranalysis.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/occurrences

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

‫Curl (Linux,‏ macOS או Cloud Shell)

הערה: הפקודה הבאה מבוססת על ההנחה שנכנסתם ל-CLI של gcloud באמצעות חשבון המשתמש שלכם, על ידי הרצת gcloud init או gcloud auth login, או באמצעות Cloud Shell שמחבר אתכם אוטומטית ל-CLI של gcloud. כדי לבדוק איזה חשבון פעיל, אפשר להריץ את הפקודה gcloud auth list.

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

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://containeranalysis.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/occurrences"

‎PowerShell (Windows)

הערה: הפקודה הבאה מבוססת על ההנחה שנכנסתם ל-CLI של gcloud באמצעות חשבון המשתמש שלכם, על ידי הרצת gcloud init או gcloud auth login. כדי לבדוק איזה חשבון פעיל, אפשר להריץ את הפקודה gcloud auth list.

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

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://containeranalysis.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/occurrences" | Select-Object -Expand Content

אתם אמורים לקבל תגובת JSON שדומה לזו:

occurrences: [
  {
    name: "projects/my-project/locations/us-east1/occurrences/030b7805-eca4-4739-9a43-ec65ed98c61f"
    resource_uri: "https://us-east1-docker.pkg.dev/my-project/my-repo/my-image@sha256:b487c4da45ce363eef69d9c066fa26f6666e4f3c9c414d98d1e27bfcc949e544"
    note_name: "projects/goog-vulnz/locations/us-east1/notes/CVE-2018-1272"
    kind: VULNERABILITY
    ...
  }

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

מזהה המופע לפני המעבר נראה כמו בדוגמה הבאה:

name: "projects/my-project/occurrences/030b7805-eca4-4739-9a43-ec65ed98c61f"

אותו מופע שמאוחסן ב-us-east1 נראה כך:

name: "projects/my-project/locations/us-east1/occurrences/030b7805-eca4-4739-9a43-ec65ed98c61f"

הגבלת השימוש בנקודת קצה ל-API גלובלית

כדי לאכוף את השימוש בנקודות קצה אזוריות, אפשר להשתמש באילוץ constraints/gcp.restrictEndpointUsage של מדיניות הארגון כדי לחסום בקשות לנקודת קצה ל-API גלובלית. מידע נוסף מופיע במאמר בנושא הגבלת השימוש בנקודות קצה.

המאמרים הבאים

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