הגדרת אימות למאגרי חבילות Python ב-Artifact Registry

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

לא צריך להגדיר אימות ל-Cloud Build או לסביבות זמן ריצה של Google Cloud, כמו Google Kubernetes Engine ו-Cloud Run, אבל צריך לוודא שמוגדרות ההרשאות הנדרשות.

ב-Artifact Registry יש תמיכה בשיטות האימות הבאות למאגרי חבילות Python:

• אסימוני גישה: אפשר להשתמש באסימוני גישה באוטומציה, בצינורות עיבוד נתונים של CI/CD, בבניית קונטיינרים או בסביבות שבהן אי אפשר להתקין את ספריית מחזיק המפתחות.
• ספריית מחזיקי מפתחות של Python (מומלץ לפיתוח מקומי): אפשר להשתמש באפשרות הזו בתחנות עבודה של מפתחים כדי לטפל באופן אוטומטי ברענון של פרטי הכניסה.
• אימות באמצעות סיסמה: משתמשים באפשרות הזו כשהאפליקציה לא תומכת ב-Application Default Credentials, אבל כן תומכת באימות באמצעות שם משתמש וסיסמה.

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

1. אם מאגר היעד לא קיים, יוצרים מאגר חדש של חבילות Python.
2. מוודאים ש-Python 3 מותקן. הוראות ההתקנה מופיעות בGoogle Cloud הדרכה להגדרת Python.
3. מוודאים שלחשבון המשתמש או לחשבון השירות שבהם אתם משתמשים יש את ההרשאות הנדרשות לגישה למאגר.

4. התקינו את ה-CLI של Google Cloud. אחר כך, מאתחלים את ה-CLI של Google Cloud באמצעות הפקודה הבאה:

   gcloud init

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

5. (אופציונלי) הגדרת ברירות מחדל לפקודות של ה-CLI של gcloud.

יצירת טוקנים לאימות

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

אפשר ליצור טוקן גישה מסוג oauth2 באמצעות Google Cloud או טוקן מסוג oauth2l מחוץ ל- Google Cloud.

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

יצירת טוקן באמצעות gcloud

כדי ליצור אסימון גישה של oauth2 באמצעות Google Cloud, מריצים את הפקודה הבאה:

export ACCESS_TOKEN="oauth2accesstoken:$(gcloud auth print-access-token)"

עכשיו אפשר להפנות אל ACCESS_TOKEN כששולחים בקשות מחבילת Python אל Artifact Registry.

יצירת טוקן בלי להשתמש ב-gcloud

כדי ליצור אסימון גישה באמצעות ה-CLI של oauth2l בלבד:

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

   go install github.com/google/oauth2l@latest
   

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

   export ACCESS_TOKEN="oauth2l fetch --scope cloud-platform"
   

   ‫Google Cloud יוצר אסימון גיבוב SHA256 ומאחסן אותו במשתנה ACCESS_TOKEN. עכשיו אפשר להפנות אל ACCESS_TOKEN כששולחים בקשות מחבילת Python אל Artifact Registry.

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

אחרי הייצוא של ACCESS_TOKEN, אפשר להעביר אותו אל pip כדי להתקין חבילות:

pip install PACKAGE --index-url https://$ACCESS_TOKEN@LOCATION-python.pkg.dev/PROJECT/REPOSITORY/simple/

אימות באמצעות מחזיק מפתחות

ספריית מחזיקי המפתחות של Python מספקת לאפליקציות דרך לגשת לקצה העורפי של מחזיקי המפתחות, כלומר למאגרי פרטי כניסה של מערכת ההפעלה ושל צד שלישי. ב-Artifact Registry יש את הקצה העורפי של אוסף המפתחות keyrings.google-artifactregistry-auth, שמטפל באימות מול מאגרי Artifact Registry.

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

סדר החיפוש של פרטי הכניסה

כשמשתמשים בעורף של מחזיק מפתחות Artifact Registry, פרטי הכניסה לא מאוחסנים בפרויקט Python. במקום זאת, Artifact Registry מחפש פרטי כניסה בסדר הבא:

1. Application Default Credentials‏ (ADC), אסטרטגיה שמחפשת פרטי כניסה בסדר הבא:

   1. פרטי הכניסה מוגדרים במשתנה הסביבה GOOGLE_APPLICATION_CREDENTIALS.

   2. פרטי הכניסה שחשבון השירות שמוגדר כברירת מחדל ב-Compute Engine,‏ Google Kubernetes Engine,‏ Cloud Run,‏ App Engine או בפונקציות של Cloud Run מספק.

2. פרטי כניסה שסופקו על ידי Google Cloud CLI, כולל פרטי כניסה של משתמשים מהפקודה gcloud auth application-default login.

המשתנה GOOGLE_APPLICATION_CREDENTIALS מציין במפורש את החשבון לאימות, וכך קל יותר לפתור בעיות. אם לא משתמשים במשתנה, צריך לוודא שלכל חשבון ש-ADC עשוי להשתמש בו יש את ההרשאות הנדרשות. לדוגמה, לחשבון השירות שמוגדר כברירת מחדל למכונות וירטואליות ב-Compute Engine, לצמתים ב-Google Kubernetes Engine ולעדכונים ב-Cloud Run יש גישת קריאה בלבד למאגרים. אם אתם מתכוונים להעלות נתונים מהסביבות האלה באמצעות חשבון השירות שמוגדר כברירת מחדל, אתם צריכים לשנות את ההרשאות.

הגדרת אוסף מפתחות

כדי להגדיר אימות באמצעות קצה העורף של מחזיק המפתחות של Artifact Registry:

1. מתקינים את ספריית אוסף המפתחות.

   pip install keyring
   

2. מתקינים את הבק אנד של Artifact Registry.

   pip install keyrings.google-artifactregistry-auth
   

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

   keyring --list-backends
   

   הרשימה צריכה לכלול

   • ChainerBackend(priority:10)
   • GooglePythonAuth(priority: 9)

4. מריצים את הפקודה הבאה כדי להדפיס את הגדרות המאגר ולהוסיף אותן לפרויקט ב-Python.

   gcloud artifacts print-settings python --project=PROJECT \
       --repository=REPOSITORY \
       --location=LOCATION
   

   מחליפים את הערכים הבאים:

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

5. מוסיפים את ההגדרות הבאות לקובץ .pypirc. מיקום ברירת המחדל הוא:

   • ב-Linux וב-macOS: ‏ $HOME/.pypirc
   • ב-Windows:‏ %USERPROFILE%\.pypirc‎

   [distutils]
   index-servers =
       PYTHON-REPO-ID
   
   [PYTHON-REPO-ID]
   repository = https://LOCATION-python.pkg.dev/PROJECT/REPOSITORY/
   

   מחליפים את הערכים הבאים:

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

6. מוסיפים את המאגר לקובץ התצורה של pip. מיקום הקובץ תלוי בשאלה אם רוצים לעדכן את הקובץ לכל משתמש או את הקובץ שספציפי לסביבה וירטואלית שבה משתמשים.

   עבור הקובץ שמשויך למשתמש במערכת ההפעלה:

   • ‫Unix: ‏ $HOME/.config/pip/pip.conf או $HOME/.pip/pip.conf
   • macOS: ‏ /Library/Application Support/pip/pip.conf או $HOME/.config/pip/pip.conf
   • ב-Windows: ‏ %APPDATA%\pip\pip.ini או %USERPROFILE%\pip\pip.ini

   בסביבות וירטואליות:

   • ב-Unix וב-macOS: ‏ $VIRTUAL_ENV/pip.conf
   • ב-Windows:‏ %VIRTUAL_ENV%\pip.ini‎

   כדי להגדיר את pip כך שיחפש רק במאגר שלכם, משתמשים בהגדרה index-url ומוודאים שלא מוגדרים עוד אינדקסים של חבילות עם ההגדרה extra-index-url.

   [global]
   index-url = https://LOCATION-python.pkg.dev/PROJECT/REPOSITORY/simple/
   

   המחרוזת /simple/ בסוף הנתיב של המאגר מציינת שהמאגר מטמיע את Python Simple Repository API.

עכשיו סביבת Python מוגדרת לאימות באמצעות Artifact Registry.

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

אחרי הגדרת מחזיק המפתחות, אפשר להשתמש בו עם פרטי הכניסה של המשתמש ב-CLI של gcloud. צריך להיכנס ל-Google Cloud CLI לפני שמתחברים למאגר חבילות Python.

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

gcloud auth login

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

אחרי שמגדירים אוסף מפתחות, אפשר להגדיר חשבון שירות לאימות.

1. יוצרים חשבון שירות או בוחרים חשבון שירות קיים שמשמש לאוטומציה.
2. מקצים לחשבון השירות את התפקיד הספציפי ב-Artifact Registry כדי לתת גישה למאגר.

3. כדי לבצע אימות באמצעות חשבון השירות, אפשר להשתמש באחת מהאפשרויות הבאות:

   • Application Default Credentials (מומלץ)

     מקצים את המיקום של קובץ המפתח של חשבון השירות למשתנה GOOGLE_APPLICATION_CREDENTIALS כדי שעוזר האישורים של Artifact Registry יוכל לקבל את המפתח כשמתחברים למאגרים.

     export GOOGLE_APPLICATION_CREDENTIALS=KEY-FILE
     

   • פרטי כניסה ל-CLI של gcloud

     לפני שמתחברים למאגר, צריך להיכנס לחשבון השירות. אל תשתמשו באפשרות הזו אם אתם מתחברים למאגרים ממכונות וירטואליות של Compute Engine, כי Artifact Registry מוצא את פרטי הכניסה לחשבון השירות של המכונה הווירטואלית לפני פרטי הכניסה ב-CLI של gcloud.

     gcloud auth activate-service-account --key-file=KEY-FILE
     

   מחליפים את KEY-FILE בנתיב של קובץ המפתח של חשבון השירות.

הגדרת אימות באמצעות סיסמה עם מפתחות של חשבון שירות

השתמשו בגישה הזו כשאתם צריכים אימות באמצעות שם משתמש וסיסמה.

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

• מומלץ להשתמש בחשבון שירות ייעודי לאינטראקציה עם מאגרי מידע.
• מעניקים את התפקיד ב-Artifact Registry עם ההרשאות המינימליות שנדרשות לחשבון השירות. לדוגמה, הקצו את התפקיד "קריאה ב-Artifact Registry" לחשבון שירות שמוריד פריטי מידע שנוצרו בתהליך פיתוח התוכנה בלבד.
• אם קבוצות בארגון שלכם צריכות רמות גישה שונות למאגרי מידע ספציפיים, כדאי להעניק גישה ברמת מאגר המידע ולא ברמת הפרויקט.
• שיטות מומלצות לניהול פרטי כניסה

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

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

   כדי להגדיר אימות באמצעות Artifact Registry, תצטרכו לדעת איפה נמצא קובץ המפתח של חשבון השירות. בחשבונות קיימים, אפשר לראות את המפתחות וליצור מפתחות חדשים בדף Service Accounts.

   מעבר לדף 'חשבונות שירות'

2. מקצים לחשבון השירות את התפקיד המתאים ב-Artifact Registry כדי לספק גישה למאגר.

3. מריצים את הפקודה הבאה כדי להדפיס את הגדרות המאגר שאותן צריך להוסיף לפרויקט Python.

   gcloud artifacts print-settings python --project=PROJECT \
       --repository=REPOSITORY \
       --location=LOCATION \
       --json-key=KEY-FILE
   

   מחליפים את הערכים הבאים:

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

4. מוסיפים את ההגדרות הבאות לקובץ .pypirc. מיקום ברירת המחדל של קובץ ההגדרות של pip לכל משתמש הוא:

   • ב-Linux וב-macOS: ‏ $HOME/.pypirc
   • ב-Windows:‏ %USERPROFILE%\.pypirc‎

   [distutils]
   index-servers =
       PYTHON-REPO-ID
   
   [PYTHON-REPO-ID]
   repository = https://LOCATION-python.pkg.dev/PROJECT/REPOSITORY/
   username: _json_key_base64
   password: KEY
   

   מחליפים את הערכים הבאים:

   • ‫PYTHON-REPO-ID הוא מזהה של המאגר שאפשר להפנות אליו באמצעות כלים כמו Twine.
   • ‫PROJECT הוא מזהה הפרויקט. אם לא מציינים את הדגל הזה, המערכת משתמשת בפרויקט הנוכחי או בפרויקט ברירת המחדל.
   • ‫REPOSITORY הוא המזהה של המאגר. אם הגדרתם מאגר ברירת מחדל ב-Artifact Registry, המערכת תשתמש בו אם לא תציינו את הדגל הזה בפקודה.
   • ‫LOCATION הוא המיקום האזורי או המיקום במספר אזורים של המאגר.
   • ‫KEY הוא המפתח בקידוד Base64 בקובץ המפתח של חשבון השירות.

5. מוסיפים את המאגר לקובץ התצורה של pip. המיקום של קובץ התצורה של pip תלוי בשאלה אם רוצים לעדכן את הקובץ לכל משתמש או את הקובץ הספציפי לסביבה הווירטואלית שבה משתמשים.

   בקובץ שמשויך למשתמש במערכת ההפעלה:

   • ‫Unix: ‏ $HOME/.config/pip/pip.conf או $HOME/.pip/pip.conf
   • macOS: ‏ /Library/Application Support/pip/pip.conf או $HOME/.config/pip/pip.conf
   • ב-Windows: ‏ %APPDATA%\pip\pip.ini או %USERPROFILE%\pip\pip.ini

   בסביבות וירטואליות:

   • ב-Unix וב-macOS: ‏ $VIRTUAL_ENV/pip.conf
   • ב-Windows:‏ %VIRTUAL_ENV%\pip.ini‎

   מוסיפים את השורה הבאה לקובץ התצורה של pip:

   [global]
   index-url = https://_json_key_base64:KEY@LOCATION-python.pkg.dev/PROJECT/REPOSITORY/simple/
   

   • ‫KEY המפתח הפרטי בקובץ המפתח של חשבון השירות.
   • המחרוזת /simple/ בסוף הנתיב של המאגר מציינת שהמאגר מטמיע את Python Simple Repository API.

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

• הגדרת גישה למאגרי מידע
• מידע נוסף על ניהול מאגרים
• מידע על ניהול חבילות