אחסון של Ruby gems ב-Artifact Registry

אחסון של Ruby gems ב-Artifact Registry

תצוגה מקדימה

השימוש במוצר או בתכונה כפוף לתנאי השימוש במוצרים בגרסת טרום-GA, בחלק "תנאים כלליים לשירות" של התנאים הספציפיים לשירות. השימוש בתכונות ובמוצרים בגרסת טרום-GA הוא "כפי שהם" (As is), ויכול להיות שהתמיכה בהם תהיה מוגבלת. מידע נוסף זמין בקטע תיאור שלבי ההשקה.

במדריך למתחילים הזה מוסבר איך להגדיר מאגר Ruby פרטי של Artifact Registry, ואז להעלות למאגר חבילה שנקראת גם gem.

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

נכנסים לחשבון Google Cloud . אם אתם משתמשים חדשים ב- Google Cloud, צרו חשבון כדי שתוכלו להעריך את הביצועים של המוצרים שלנו בתרחישים מהעולם האמיתי. לקוחות חדשים מקבלים בחינם גם קרדיט בשווי 300$ להרצה, לבדיקה ולפריסה של עומסי העבודה.
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.
Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.
Go to project selector
Verify that billing is enabled for your Google Cloud project.
Enable the Artifact Registry API.
Roles required to enable APIs
To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.
Enable the API
Make sure that you have the following role or roles on the project: Artifact Registry Administrator
Check for the roles
1. In the Google Cloud console, go to the IAM page.

   Go to IAM
2. Select the project.

3. In the Principal column, find all rows that identify you or a group that you're included in. To learn which groups you're included in, contact your administrator.

4. For all rows that specify or include you, check the Role column to see whether the list of roles includes the required roles.
Grant the roles
1. In the Google Cloud console, go to the IAM page.

   Go to IAM
2. Select the project.
3. Click Grant access.

4. In the New principals field, enter your user identifier. This is typically the email address for a Google Account.

5. Click Select a role, then search for the role.
6. To grant additional roles, click Add another role and add each additional role.
7. Click Save.

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.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Artifact Registry API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

Make sure that you have the following role or roles on the project: Artifact Registry Administrator

Check for the roles

1. In the Google Cloud console, go to the IAM page.

   Go to IAM
2. Select the project.

3. In the Principal column, find all rows that identify you or a group that you're included in. To learn which groups you're included in, contact your administrator.

4. For all rows that specify or include you, check the Role column to see whether the list of roles includes the required roles.

Grant the roles

1. In the Google Cloud console, go to the IAM page.

   Go to IAM
2. Select the project.
3. Click Grant access.

4. In the New principals field, enter your user identifier. This is typically the email address for a Google Account.

5. Click Select a role, then search for the role.
6. To grant additional roles, click Add another role and add each additional role.
7. Click Save.

הפעלת Cloud Shell

במדריך למתחילים הזה תשתמשו ב-Cloud Shell, שהיא סביבת מעטפת לניהול משאבים שמתארחים ב-Google Cloud.

ב-Cloud Shell מותקנים מראש Google Cloud CLI ו-Ruby. ה-CLI של gcloud הוא ממשק שורת הפקודה העיקרי ל- Google Cloud.

מפעילים את Cloud Shell:

1. עוברים אל Google Cloud המסוף.

   ‫Google Cloud console

2. בסרגל הכלים של מסוף Google Cloud , לוחצים על Activate Cloud Shell (הפעלת Cloud Shell).

בחלק התחתון של המסוף ייפתח סשן של Cloud Shell בתוך מסגרת. משתמשים בשורת הפקודות הזו כדי להריץ פקודות gcloud.

הגדרת אימות

‫Ruby תומך בשתי שיטות לאימות בקשות למאגר Artifact Registry:

• ממשק ה-CLI של RubyGems: תומך בבקשות push ו-pull. ה-CLI הזה זמין כברירת מחדל עם Ruby. כשאתם מבצעים אימות באמצעות RubyGems, אתם צריכים לבצע אימות בכל פעם שאתם שולחים בקשת push או pull למאגר.

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

  כדי להתקין את Bundler CLI, מזינים את הפקודה gem install bundler.

אימות באמצעות RubyGems CLI

ה-CLI של RubyGems משתמש באסימוני OAuth2 כדי לאמת בקשה. כדי להעביר אסימוני OAuth2 לקריאות למאגרי Artifact Registry, צריך קודם ליצור את האסימון ואז להעביר אותו עם הכתובת של המאגר כששולחים בקשה. משך החיים של האסימונים הוא שעה אחת, ולכן צריך לרענן אותם כל שעה.

אימות של בקשות משיכה

אפשר לאמת בקשת משיכה בשורת הפקודה של Google Cloud CLI או על ידי עדכון הקובץ .gemrc.

אימות בקשות משיכה בשורת הפקודה

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

export GEM_TOKEN="oauth2accesstoken:$(gcloud auth print-access-token)"
gem install GEM_NAME --source https://$[e-mail]/PROJECT/REPOSITORY

כדי לבצע אימות לגרסה ספציפית של Gem, מוסיפים את האפשרות -v GEM_VERSION לפקודה gem install.

כאשר:

• ‫GEM_NAME הוא שם ה-Gem שעבורו מוגשת הבקשה.
• ‫LOCATION הוא המיקום האזורי או המיקום במספר אזורים של המאגר.
• ‫PROJECT הוא מזהה הפרויקט שמכיל את המאגר.
• ‫REPOSITORY הוא המזהה של המאגר.

אימות בקובץ .gemrc

כדי להגדיר אימות למקורות בבקשות משיכה, אפשר להוסיף את השורות הבאות לקובץ /.gemrc הגלובלי או הספציפי לפרויקט:

# File: ~/.gemrc

# Use the GEM_TOKEN retrieved from export GEM_TOKEN="oauth2accesstoken:$(gcloud auth print-access-token)"

<...>
:sources:
    - https://[e-mail]/PROJECT/REPO/
<...>

כדי להתקין gem באמצעות המקור או המקורות שמוגדרים בקובץ /.gemrc, מריצים את הפקודה:

gem install GEM_NAME

אימות בקשות Push

אפשר לאמת בקשת push בשורת הפקודה של Google Cloud CLI או לעדכן את קובץ פרטי הכניסה.

אימות בקשות push בשורת הפקודה

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

export GEM_HOST_API_KEY="Bearer $(gcloud auth print-access-token)"
gem push GEM_NAME --host https://LOCATION-ruby.pkg.dev/PROJECT/REPOSITORY

הערה: אחרי שמגדירים את GEM_HOST_API_KEY, לא צריך להעביר את אסימון OAuth2 בכתובת ה-URL של בקשות הפוש.

כאשר:

• ‫GEM_NAME הוא שם ה-Gem שעבורו מוגשת הבקשה.
• ‫LOCATION הוא המיקום האזורי או המיקום במספר אזורים של המאגר.
• ‫PROJECT הוא מזהה הפרויקט שמכיל את המאגר.
• ‫REPOSITORY הוא המזהה של המאגר.

אימות בקשות push בקובץ פרטי כניסה

כלי שורת הפקודה gem משתמש בקובץ ~/.gem/credentials כדי לאחסן מפתחות API לשליחה ולמשיכה של חבילות gem. כדי להגדיר את קובץ פרטי הכניסה לאימות למקורות בבקשות push, מבצעים את הפעולות הבאות:

1. מריצים את הפקודה הבאה כדי ליצור אסימון גישה מסוג OAuth2:

   gcloud auth print-access-token

   האסימון הזה משמש כמפתח ה-API שלכם ב-Artifact Registry.

2. מעדכנים את קובץ פרטי הכניסה:

   1. פותחים את ~/.gem/credentials ומוסיפים שורה למאגר. המפתח הוא כתובת ה-URL של המאגר, והערך הוא Bearer, ואחריו האסימון שלכם:

      :rubygems_api_key: RUBYGEMS_ORG_KEY
      https://LOCATION-ruby.pkg.dev/PROJECT/REPOSITORY: Bearer OAUTH_TOKEN
      

      כאשר:

      • ‫RUBYGEMS_ORG_KEY הוא מפתח ה-API של RubyGems.org.
      • ‫LOCATION הוא המיקום האזורי או המיקום במספר אזורים של המאגר.
      • ‫PROJECT הוא מזהה הפרויקט שמכיל את המאגר.
      • ‫REPOSITORY הוא המזהה של המאגר.
      • ‫OAUTH_TOKEN הוא אסימון הגישה שלכם ל-OAuth2.

   2. דוחפים את האבן. שימו לב שלא צריך להגדיר את GEM_HOST_API_KEY, כי כבר הגדרתם את המפתח בקובץ פרטי הכניסה.

      gem push GEM_NAME --host https://LOCATION-ruby.pkg.dev/PROJECT/REPOSITORY
      

אימות באמצעות Bundler

‫Bundler של Ruby מנהל את יחסי התלות של האפליקציה בכמה gems. כדי להגדיר את Bundler:

1. מוסיפים את הכתובת של המאגר כ-source בקובץ ה-gemfile:

   # Gemfile
   # <...>
   source "https://LOCATION-ruby.pkg.dev/PROJECT/REPOSITORY"
   

2. מאמתים את המאגר באמצעות bundle config:

   export GEM_TOKEN="oauth2accesstoken:$(gcloud auth print-access-token)"
   export HOST="https://LOCATION-ruby.pkg.dev/PROJECT/REPOSITORY"
   bundle config $HOST $GEM_TOKEN
   

כאשר:

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

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

מידע נוסף על הגדרת Bundler זמין במאמר Gemfiles במסמכי התיעוד של bundler.io.

למידע נוסף על שיטות אימות, ראו הגדרת אימות ל-Artifact Registry עבור מאגרי Ruby gem.

יצירת מאגר

יוצרים את המאגר של אבן החן.

1. מריצים את הפקודה הבאה כדי ליצור מאגר חדש של Ruby gem בפרויקט הנוכחי בשם quickstart-ruby-repo במיקום us-west1.

   gcloud artifacts repositories create quickstart-ruby-repo \
       --repository-format=ruby \
       --location=us-west1 \
       --description="Ruby gem repository"
   

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

   gcloud artifacts repositories list
   

3. כדי לפשט את הפקודות של gcloud, מגדירים את מאגר ברירת המחדל ל-quickstart-ruby-repo ואת מיקום ברירת המחדל ל-us-west1. אחרי שמגדירים את הערכים, לא צריך לציין אותם בפקודות gcloud שדורשות מאגר או מיקום.

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

   gcloud config set artifacts/repository quickstart-ruby-repo
   

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

   gcloud config set artifacts/location us-west1
   

   מידע נוסף על הפקודות האלה זמין במאמר בנושא gcloud config set.

הורדת תצורת Gem

כשיוצרים פרויקט Ruby, קובצי ההפצה נשמרים בספריית משנה בפרויקט Ruby.lib כדי לפשט את המדריך למתחילים הזה, תיצרו ספרייה ואז תורידו קובץ gem לספרייה הזו.

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

mkdir ruby-quickstart
mkdir ruby-quickstart/lib
cd ruby-quickstart/lib

בשלב הבא, מורידים את ה-Gem. אתם יכולים להשתמש ב-Gem משלכם או להוריד Gem לדוגמה מהדף Popular Gems באתר rubygems.org. כדי להוריד gem מ-rubygems.org, מריצים את הפקודה הבאה:

gem fetch GEM_NAME

יש לך עכשיו תצורת Gem בשם GEM_NAME בספרייה ruby_quickstart/lib. בקטע הבא תשתמשו ב-RubyGems CLI כדי להעלות את ה-gem למאגר.

דחיפת ה-gem למאגר

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

gem push GEM_NAME --host https://us-west1-ruby.pkg.dev/PROJECT/quickstart-ruby-repo

כאשר:

• ‫GEM_NAME הוא שם ה-gem שרוצים להעלות למאגר.
• ‫PROJECT הוא מזהה הפרויקט. אם לא מציינים את הדגל הזה, המערכת משתמשת בפרויקט הנוכחי או בפרויקט ברירת המחדל.

הצגת אבן החן במאגר

כדי לוודא שהתכונה Gem נוספה, מציגים את רשימת החבילות במאגר ruby-quickstart.

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

gcloud artifacts packages list --repository=ruby-quickstart

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

gcloud artifacts versions list --package=GEM_NAME

התקנה של ה-gem

כדי להתקין את ה-gem שדחפתם למאגר Artifact Registry, מריצים את הפקודה הבאה:

export GEM_TOKEN="oauth2accesstoken:$(gcloud auth print-access-token)"
gem install GEM_NAME --source https://$[e-mail]/PROJECT/quickstart-ruby-repo

כאשר:

• ‫GEM_NAME הוא שם ה-gem שרוצים להתקין במאגר.
• ‫PROJECT הוא מזהה הפרויקט. אם לא מציינים את הדגל הזה, המערכת משתמשת בפרויקט הנוכחי או בפרויקט ברירת המחדל.

פתרון בעיות

מידע נוסף זמין במאמר פתרון בעיות ב-Ruby gems.

הסרת המשאבים

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

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

1. כדי למחוק את מאגר quickstart-ruby-repo, מריצים את הפקודה הבאה:

   gcloud artifacts repositories delete quickstart-ruby-repo
   

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

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

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

• מידע נוסף על הגדרת אימות
• מידע נוסף על ניהול מאגרי מידע
• מידע על ניהול חבילות
• אפשר גם לקרוא את המשאבים שלנו בנושא DevOps ולעיין בתוכנית המחקר שלנו.