ניהול מודולים של Go

בדף הזה מוסבר איך לנהל מודולים של Go באריזה שמאוחסנים ב-Artifact Registry.

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

1. אם מאגר היעד לא קיים, צריך ליצור מאגר חדש. בוחרים באפשרות Go כפורמט המאגר.
2. מוודאים שיש לכם את ההרשאות הנדרשות למאגר.
3. (אופציונלי) הגדרת ברירות מחדל לפקודות gcloud.
4. Install Go 1.15 or later.

5. מתקינים את התוסף package-go-module ל-CLI של gcloud:

   gcloud components install package-go-module

6. מגדירים את Go לאימות באמצעות Artifact Registry.

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

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

• צפייה במודולים: קורא של Artifact Registry (roles/artifactregistry.reader)
• הורדה או התקנה של מודולים: קורא של Artifact Registry (roles/artifactregistry.reader)
• הוספת מודולים למאגר: Artifact Registry Writer (roles/artifactregistry.writer)
• מחיקת מודולים: Artifact Registry Repository Administrator (roles/artifactregistry.repoAdmin)

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

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

העלאת מודול

מצבי מאגר: רגיל

כדי לארוז ולהעלות מודול למאגר, מריצים את הפקודה הבאה:

  gcloud artifacts go upload --project=PROJECT \
      --repository=REPOSITORY \
      --location=LOCATION \
      --module-path=MODULE_PATH \
      --version=VERSION \
      --source=SOURCE_LOCATION

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

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

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

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

העלאה של גרסה חדשה של מודול

מצבי מאגר: רגיל

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

  gcloud artifacts go upload \
      --module-path=MODULE_PATH \
      --version=VERSION \
      --source=SOURCE_LOCATION

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

  gcloud artifacts go upload \
      --module-path=example.com/foo \
      --version=v0.1.1 \
      --source=SOURCE_LOCATION

כדי לסמן מודול כגרסת טרום-הפצה, מוסיפים מקף אחרי VERSION ומצרפים את מזהי טרום-ההפצה של המודול:

  gcloud artifacts go upload \
      --module-path=MODULE_PATH \
      --version=VERSION-PRE_RELEASE_IDENTIFIERS \
      --source=SOURCE_LOCATION

מחליפים את PRE_RELEASE_IDENTIFIERS בתווים אלפאנומריים של ASCII ובמקפים, שמופרדים באמצעות נקודות. לדוגמה, כדי להעלות גרסה של מודול לפני ההשקה עם הנתיב example.com/foo module שמזוהה על ידי alpha.x.12m.5, מריצים את הפקודה הבאה:

  gcloud artifacts go upload \
      --module-path=example.com/foo \
      --version=v1.0.0-alpha.x.12m.5 \
      --source=SOURCE_LOCATION

הערה: מזהים של גרסאות טרום-הפצה חייבים להיות מורכבים מתווים אלפאנומריים של ASCII וממקפים, שמופרדים באמצעות נקודות. אין תמיכה במטא-נתונים. מידע נוסף על ניהול גרסאות זמין במאמר Semantic versioning 2.0.0 ובפוסט הזה בבלוג, שכולל פרטים ספציפיים ל-Go.

העלאה של גרסה ראשית חדשה

מצבי מאגר: רגיל

גרסאות עיקריות לא תואמות לגרסאות קודמות. כדי למנוע ממשתמשים לייבא שינוי שובר, לגרסאות ראשיות אחרי v1 צריכים להיות נתיבי מודולים שונים מאלה של גרסאות קודמות. החל מ-v2, הגרסה הראשית מתווספת לסוף נתיב המודול.

לדוגמה, נתיב המודול של v2.0.0 ב-example.com/foo יהיה example.com/foo/v2.

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

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

  gcloud artifacts go upload --module-path=example.com/foo/v2 --version=v2.0.0

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

מצבי מאגר: רגיל, מרוחק, וירטואלי

מריצים את הפקודה הבאה כדי לבדוק מודול 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 במאמר הגדרת אימות ל-Go.

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

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

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

     go mod init MODULE_PATH
   

   מחליפים את MODULE_PATH בנתיב המודול של המודול שמאוחסן ב-Artifact Registry. מידע נוסף מופיע בחומר העזר בנושא מודולים של Go.

3. כדי לדרוש את הגרסה של המודול שמאוחסנת ב-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

4. כוללים את נתיב המודול כרגיל בקטע import של הקובץ main.go.

   לדוגמה, כדי לייבא מודול עם הנתיב example.com/foo שמאוחסן ב-Artifact Registry, קטע הייבוא יכול להיראות כך:

     
     package main
   
     import (
       foo "example.com/foo"
     )
   
     func main() {
   
       ...
   
     }
   
     
   

5. מריצים את הפקודה go mod tidy כדי להוריד יחסי תלות:

     go mod tidy
   

6. מריצים את המודול כרגיל:

     go run .
   

   המודול שמאוחסן ב-Artifact Registry מורד ומשמש כתלות.

מחיקת מודולי Go ארוזים

מצבי מאגר: רגיל, מרוחק

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

• אחרי שמוחקים חבילה, אי אפשר לבטל את הפעולה.

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

כדי למחוק חבילה:

המסוף

1. פותחים את הדף Repositories במסוף Google Cloud .

   פתיחת הדף Repositories

2. ברשימת המאגרים, לוחצים על המאגר המתאים.

   בדף Packages (חבילות) מופיעה רשימת החבילות במאגר.

3. בוחרים את החבילה שרוצים למחוק.

4. לוחצים על מחיקה.

5. בתיבת הדו-שיח לאישור, לוחצים על מחיקה.

gcloud

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

gcloud artifacts packages delete PACKAGE \
    [--repository=REPOSITORY] [--location=LOCATION] [--async]

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

• ‫PACKAGE הוא שם החבילה במאגר.
• ‫REPOSITORY הוא שם המאגר. אם הגדרתם מאגר ברירת מחדל, תוכלו להשמיט את הדגל הזה כדי להשתמש בברירת המחדל.
• ‫ LOCATION הוא המיקום האזורי או המיקום במספר אזורים של המאגר. ‫ אפשר להשתמש בדגל הזה כדי להציג מאגרי מידע במיקום ספציפי. אם הגדרתם מיקום ברירת מחדל, אתם יכולים להשמיט את הדגל הזה כדי להשתמש בברירת המחדל.

הדגל --async גורם לפקודה לחזור באופן מיידי, בלי להמתין שהפעולה תסתיים.

כדי למחוק גרסאות של חבילה:

המסוף

1. פותחים את הדף Repositories במסוף Google Cloud .

   פתיחת הדף Repositories

2. ברשימת המאגרים, לוחצים על המאגר המתאים.

   בדף Packages (חבילות) מופיעה רשימת החבילות במאגר.

3. לוחצים על חבילה כדי לראות את הגרסאות שלה.

4. בוחרים את הגרסאות שרוצים למחוק.

5. לוחצים על מחיקה.

6. בתיבת הדו-שיח לאישור, לוחצים על מחיקה.

gcloud

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

gcloud artifacts versions delete VERSION \
    --package=PACKAGE \
    [--repository=REPOSITORY] [--location=LOCATION] \
    [--async]

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

• ‫VERSION הוא שם הגרסה שרוצים למחוק.
• ‫PACKAGE הוא שם החבילה במאגר.
• ‫REPOSITORY הוא שם המאגר. אם הגדרתם מאגר ברירת מחדל, תוכלו להשמיט את הדגל הזה כדי להשתמש בברירת המחדל.
• ‫ LOCATION הוא המיקום האזורי או המיקום במספר אזורים של המאגר. ‫ אפשר להשתמש בדגל הזה כדי להציג מאגרי מידע במיקום ספציפי. אם הגדרתם מיקום ברירת מחדל, אתם יכולים להשמיט את הדגל הזה כדי להשתמש בברירת המחדל.

הדגל --async גורם לפקודה לחזור באופן מיידי, בלי להמתין שהפעולה תסתיים.

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

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