אחסון מודולים של Go ב-Artifact Registry

מגדירים מאגר Go פרטי ב-Artifact Registry, מעלים אליו מודול ומשתמשים במודול כיחס תלות.

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

  1. נכנסים לחשבון Google.

    אם עדיין אין חשבון, יוצרים חשבון חדש.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. Enable the Artifact Registry API.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

  5. התקינו את ה-CLI של Google Cloud.

  6. אם אתם משתמשים בספק זהויות חיצוני (IdP), קודם אתם צריכים להיכנס ל-CLI של gcloud באמצעות המאגר המאוחד לניהול זהויות.

  7. כדי לאתחל את ה-CLI של gcloud, הריצו את הפקודה הבאה: 

    gcloud init

  8. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  9. Verify that billing is enabled for your Google Cloud project.

  10. Enable the Artifact Registry API.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

  11. התקינו את ה-CLI של Google Cloud.

  12. אם אתם משתמשים בספק זהויות חיצוני (IdP), קודם אתם צריכים להיכנס ל-CLI של gcloud באמצעות המאגר המאוחד לניהול זהויות.

  13. כדי לאתחל את ה-CLI של gcloud, הריצו את הפקודה הבאה: 

    gcloud init
  14. מתקינים את Go בגרסה 1.15 ואילך.
  15. מתקינים את התוסף package-go-module gcloud CLI: 
    gcloud components install package-go-module

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

כדי לקבל את ההרשאות שדרושות ליצירה ולניהול של מאגרי מודולים של Go ב-Artifact Registry, צריך לבקש מהאדמין להקצות לכם את התפקיד אדמין של Artifact Registry (roles/artifactregistry.admin) ב-IAM בפרויקט. כדי לקרוא הסבר על מתן תפקידים, ראו איך מנהלים את הגישה ברמת הפרויקט, התיקייה והארגון.

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

יצירת מאגר

כדי ליצור מאגר חדש ולהגדיר אותו:

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

    gcloud artifacts repositories create REPOSITORY \
    --repository-format=go \
    --location=LOCATION \
    --description=DESCRIPTION

    מחליפים את מה שכתוב בשדות הבאים:

    • ‫REPOSITORY הוא שם המאגר. שמות המאגרים צריכים להיות ייחודיים לכל מיקום מאגר בפרויקט.
    • ‫LOCATION הוא המיקום האזורי או המיקום במספר אזורים של המאגר. אפשר להשמיט את הדגל הזה אם מגדירים ברירת מחדל. כדי לראות רשימה של מיקומים נתמכים, מריצים את הפקודה gcloud artifacts locations list.
    • ‫DESCRIPTION הוא תיאור אופציונלי של המאגר. לא לכלול נתונים רגישים, כי תיאורי מאגרים לא מוצפנים.

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

      gcloud artifacts repositories describe --location=LOCATION REPOSITORY

    הפלט אמור להיראות כך:

      Encryption: Google-managed key
  Repository Size: 0.000MB
  createTime: '2022-06-03T20:20:01.644813Z'
  format: GO
  mode: STANDARD_REPOSITORY
  name: projects/my-project/locations/us-west1/repositories/my-repo
  updateTime: '2022-06-03T20:20:01.644813Z'

הגדרת ברירות מחדל לפקודות gcloud

כדי לפשט את הפקודות שלכם, אתם יכולים להגדיר את ערכי ברירת המחדל של הפרויקט, המאגר והמיקום.gcloud CLI אחרי שמגדירים את ברירות המחדל, אין צורך בתגי --project, --location ו---repository.

אריזה והעלאה של מודול Go

התוסף package-go-module gcloud CLI אורז את המודולים של Go, ומאפשר לכם ליצור גרסאות ולהעלות אותם ל-Artifact Registry באמצעות הפקודה gcloud.

יצירת מודול Go

קודם יוצרים מודול Go פשוט להעלאה למאגר.

  1. בספריית הבית, יוצרים ספרייה בשם foo עבור המודול.

    mkdir foo

  2. עוברים לספרייה של המודול ומריצים את הפקודה go mod init כדי ליצור קובץ go.mod בשביל המודול.

      cd foo \
  go mod init example.com/foo

    מחליפים את example.com/foo בנתיב של המודול. מידע נוסף מופיע במאמר בנושא מודולים של Go.

  3. יוצרים קובץ foo.go בספרייה foo עם התוכן הבא:

    
package foo

const HelloWorld = "Hello World!"

אריזה והעלאה של המודול

אורזים את המודול ומעלים אותו למאגר:

  gcloud artifacts go upload --project=PROJECT \
      --repository=REPOSITORY \
      --location=LOCATION \
      --module-path=example.com/foo \
      --version=VERSION \
      --source=SOURCE_LOCATION

מחליפים את מה שכתוב בשדות הבאים:

  • ‫PROJECT עם Google Cloud מזהה הפרויקט.
  • REPOSITORY בשם המאגר שבו מאוחסנת החבילה.
  • ‫LOCATION עם המיקום האזורי או המיקום במספר אזורים של המאגר.
  • ‫example.com/foo עם נתיב המודול. מידע נוסף מופיע בחומר העזר בנושא מודולים של Go.
  • ‫VERSION עם הגרסה הסמנטית של המודול בפורמט vX.Y.Z, כאשר X היא הגרסה הראשית, Y היא הגרסה המשנית ו-Z היא גרסת התיקון.
  • ‫SOURCE_LOCATION מחליפים בנתיב לספריית הבסיס של מודול Go. אם לא מציינים את הדגל --source, ברירת המחדל היא הספרייה הנוכחית.

המודול מועלה ל-Artifact Registry.

מידע נוסף על יצירת מודולים של Go זמין בהדרכה הזו.

מודולים של רשימות

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

  gcloud artifacts packages list

הפלט אמור להיראות כך:

  Listing items under project my-project, location us-west1, repository my-repo.

  PACKAGE                   CREATE_TIME          UPDATE_TIME
  example.com/foo           2022-06-03T20:43:39  2022-06-20T20:37:40

הצגת פרטי גרסת המודול

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

  gcloud artifacts versions list --package=MODULE_PATH

הפלט אמור להיראות כך:

  Listing items under project my-project, location us-west1, repository my-repo, package example.com/foo.

  VERSION  DESCRIPTION  CREATE_TIME          UPDATE_TIME
  v0.1.0                2022-06-03T20:43:39  2022-06-03T20:43:39
  v0.1.1                2022-06-20T20:37:40  2022-06-20T20:37:40

הורדת מודולים

כדי לייבא מודולים שמאוחסנים ב-Artifact Registry, צריך להנחות את Go לחפש יחסי תלות מ-Artifact Registry ולעקוף את מסד הנתונים של סכומי הביקורת.

הגדרת סביבת Go

  1. מנחים את Go להוריד מודולים מ-Artifact Registry, משרת ה-proxy הציבורי של מודולי Go, ואז מהמקור, לפי הסדר הזה:

      export GOPROXY=https://LOCATION-go.pkg.dev/PROJECT/REPOSITORY,https://proxy.golang.org,direct

    מחליפים את מה שכתוב בשדות הבאים:

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

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

      export GONOSUMDB=MODULE_PATH_REGEX

    מחליפים את MODULE_PATH_REGEX בנתיב המודול או בביטוי רגולרי אם רוצים להחריג כמה מודולים.

    כדי להחריג את המודול example.com/foo מהבדיקה באמצעות מסד הנתונים הציבורי של סכומי הביקורת, מריצים את הפקודה הבאה:

      export GONOSUMDB=example.com/foo

    אם רוצים שכל המודולים עם נתיבי מודולים שמתחילים ב-example.com לא ייבדקו באמצעות מסד הנתונים הציבורי של סכומי הביקורת, מריצים את הפקודה הבאה:

      export GONOSUMDB=example.com/*

אימות ב-Artifact Registry

כשמורידים מודולים של Go שנארזו כדי להשתמש בהם כתלות מ-Artifact Registry, קובץ ה-binary של Go משתמש בפרטי הכניסה בקובץ netrc כדי לבצע אימות מול Artifact Registry. כדי לפשט את תהליך האימות, אפשר להשתמש בכלי העזר לאימות של Go כדי לרענן את האסימונים בקובץ netrc לצורך אימות ב-Artifact Registry.

אפשר להגדיר את המיקום של קובץ netrc באמצעות משתנה הסביבה netrc. אם המשתנה NETRC לא מוגדר, הפקודה go תקרא $HOME/.netrc בפלטפורמות דמויות UNIX או %USERPROFILE%\_netrc ב-Windows.

‫Artifact Registry תומך בשיטות האימות הבאות.

פרטי כניסה לטווח קצר (מומלץ)
משתמשים בכלי Go credential helper של Artifact Registry כדי לעדכן את אסימוני האימות בקובץ netrc.
שימוש במפתח של חשבון שירות

משתמשים באפשרות הזו כשאי אפשר להשתמש בפרטי כניסה בסביבה שלכם לצורך אימות. מוסיפים את מפתח חשבון השירות הלא מוצפן לקובץ netrc.

הוספת כלי העזר לפרטי כניסה של Go אל GONOPROXY

לפני שמשתמשים בכלי העזר לאישורי גישה של Go, צריך להוסיף אותו לרשימה GONOPROXY כדי לחייב את Go להוריד אותו ישירות מ-GitHub. אם יש לכם מודולים אחרים שאתם רוצים להוריד ישירות מהמקור, אתם יכולים להוסיף אותם לרשימה שמופרדת באמצעות פסיקים, כמו בדוגמה הבאה:

  export GONOPROXY=MODULE_PATH1, MODULE_PATH2

כאשר MODULE_PATH1 ו-MODULE_PATH2 הם נתיבי מודולים של מודולים שצריך להוריד מהמקור.

כדי להוסיף את כלי העזר לאישורי גישה של Go לרשימת GONOPROXY ולהפעיל אותו כדי להגדיר את אישורי הגישה:

  1. מוסיפים את כלי העזר לפרטי כניסה של Go אל GONOPROXY

      export GONOPROXY=github.com/GoogleCloudPlatform/artifact-registry-go-tools

  2. מריצים את הפקודה הבאה כדי להוסיף את פרטי הכניסה של Artifact Registry לקובץ netrc באמצעות כלי חבילת המודולים של Go:

      GOPROXY=proxy.golang.org \
      go run github.com/GoogleCloudPlatform/artifact-registry-go-tools/cmd/auth@v0.4.0 \
      add-locations --locations=LOCATION \
      [--json_key=path/to/service/account/key.json]

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

    הכלי לעזרה בהוספת פרטי כניסה של Go מוסיף הגדרות לקובץ netrc לצורך אימות ב-Artifact Registry. אם מעבירים את האפשרות --json_key, המפתח מתווסף לקובץ netrc לצורך אימות סיסמה.

שימוש במודול כתלות

  1. אם אתם משתמשים בפרטי כניסה לטווח קצר כדי לבצע אימות ל-Artifact Registry, תצטרכו לרענן את טוקן ה-OAuth על ידי הפעלת הפקודה הבאה:

      GOPROXY=proxy.golang.org \
  go run github.com/GoogleCloudPlatform/artifact-registry-go-tools/cmd/auth@v0.4.0 refresh

  2. בתיקיית הבית, יוצרים תיקייה בשם bar.

      mkdir bar

  3. עוברים לספרייה של המודול ומריצים את הפקודה go mod init כדי ליצור קובץ go.mod לחבילה.

      cd bar \
  go mod init example.com/bar

    מחליפים את example.com/bar בנתיב המודול. מידע נוסף מופיע בחומר העזר בנושא מודולים של Go.

  4. כדי לדרוש את הגרסה של foo שמאוחסנת ב-Artifact Registry, עורכים את הקובץ go.mod כך שייראה כמו הדוגמה הבאה:

    
module example.com/bar

go 1.19

require example.com/foo v0.1.0

    מחליפים את מה שכתוב בשדות הבאים:

    • ‫example.com/foo הוא נתיב המודול של המודול הנדרש
    • ‫v0.1.0 היא הגרסה שמאוחסנת ב-Artifact Registry

  5. יוצרים קובץ main.go בספרייה bar עם התוכן הבא:

      
  package main

  import (
    "fmt"

    foo "example.com/foo"
  )

  func main() {
    fmt.Println(foo.HelloWorld)
  }

  6. מריצים את הפקודה go mod tidy כדי להוריד את התלויות, כולל חבילת foo:

      go mod tidy

  7. מריצים את מודול הסרגל:

      go run .

    הפלט אמור להיראות כך:

      Hello World!

הסרת המשאבים

כדי לא לצבור חיובים לחשבון Google Cloud על המשאבים שבהם השתמשתם בדף הזה, פועלים לפי השלבים הבאים:

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

  1. כדי למחוק את המאגר:

      gcloud artifacts repositories delete \
      --location=LOCATION \
      --project=PROJECT \
      REPOSITORY

    מחליפים את מה שכתוב בשדות הבאים:

    • ‫LOCATION עם המיקום האזורי או המיקום במספר אזורים של המאגר.
    • ‫PROJECT עם Google Cloud מזהה הפרויקט.
    • REPOSITORY בשם המאגר.

  2. אם רוצים להסיר את הגדרות ברירת המחדל של המאגר והמיקום שהגדרתם עבור ההגדרה הפעילה של gcloud, מריצים את הפקודות הבאות:

      gcloud config unset artifacts/repository
  gcloud config unset artifacts/location

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