הגדרת אימות ל-Artifact Registry עבור Docker

בדף הזה מוסבר איך להגדיר את Docker כדי לבצע אימות למאגרי Docker ב-Artifact Registry.

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

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

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

    gcloud init

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

  2. (אופציונלי) הגדרת ברירות מחדל לפקודות של ה-CLI של gcloud.
  3. מוודאים שלחשבון שבו אתם משתמשים לאימות יש הרשאה לגשת אל Artifact Registry. מומלץ להשתמש בחשבון שירות ולא בחשבון משתמש.
  4. מתקינים את Docker אם הוא עדיין לא מותקן. ‫Docker כלול ב-Cloud Shell.
  5. כדי לבצע פעולות במאגרי מידע, ל-Docker נדרשת גישה עם הרשאות. ב-Linux או ב-Windows, מוסיפים את המשתמש שמשמש להפעלת פקודות Docker לקבוצת האבטחה של Docker. ב-macOS אין צורך לבצע את השלב הזה כי Docker Desktop פועל במכונה וירטואלית כמשתמש root.

    Linux

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

          sudo usermod -a -G docker ${USER}

    Windows

    קבוצת האבטחה של Docker נקראת docker-users. כדי להוסיף משתמש משורת הפקודה של האדמין, מריצים את הפקודה הבאה:

            net localgroup docker-users DOMAIN\USERNAME /add

    כאשר:

    • ‫DOMAIN הוא הדומיין של Windows.
    • ‫USERNAME הוא שם המשתמש שלכם.

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

בחירה של שיטת אימות

אלה שיטות האימות שזמינות:

כלי עזר לפרטי כניסה ל-CLI של gcloud
הגדרת פרטי הכניסה שלכם ל-Artifact Registry לשימוש ב-Docker ישירות ב-CLI של gcloud. זו שיטת האימות הפשוטה ביותר, אבל היא יכולה להיות איטית יותר מהכלי העצמאי לעזרה בהזנת פרטי הכניסה.
כלי עזר עצמאי של מסמך אימות ל-Docker
האפשרות הזו מיועדת בעיקר להגדרת פרטי הכניסה לשימוש ב-Docker כשאין Google Cloud CLI. הוא מהיר משמעותית מהכלי לעזרה בפרטי הכניסה של ה-CLI של gcloud, והוא משתמש ב-Application Default Credentials‏ (ADC) כדי למצוא באופן אוטומטי את פרטי הכניסה בסביבה שלכם.
טוקן גישה
אפשר ליצור אסימון גישה לטווח קצר לחשבון שירות ואז להשתמש באסימון לאימות באמצעות סיסמה. האסימון תקף רק ל-60 דקות, ולכן הוא אפשרות בטוחה יותר ממפתח של חשבון שירות.
מפתח לחשבון שירות
זוג מפתחות בניהול משתמש שאפשר להשתמש בו כפרטי כניסה לחשבון שירות. מכיוון שהאישורים תקפים לזמן רב, זו האפשרות הכי פחות מאובטחת מבין כל שיטות האימות הזמינות.

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

הגדרות האימות בקובץ ההגדרות של Docker

‫Docker שומר את הגדרות האימות בקובץ התצורה config.json.

  • ‫Linux: ‏ ~/.docker/config.json
  • ב-Windows:‏ %USERPROFILE%\.docker\config.json‎

בקובץ יש קטעים נפרדים לשיטות אימות שונות:

credHelpers
אם משתמשים ב-Docker credential helper לאימות, Artifact Registry מאחסן את ההגדרות של credential helper בקטע credHelpers של הקובץ.
auths
אם משתמשים ב-Docker כדי להיכנס באמצעות טוקן או מפתח של חשבון שירות בתור סיסמה, Docker מאחסן גרסה בקידוד base64 של פרטי הכניסה בקטע auths של הקובץ.
credStore
אם הגדרתם מאגר פרטי כניסה לניהול פרטי הכניסה, ההגדרות של מאגר פרטי הכניסה מופיעות בקטע credStore של הקובץ.

כש-Docker מתחבר למאגר, הוא בודק קודם אם יש כלי עזר לאימות שמשויך למארח. לכן, אם הקובץ config.json כולל הגדרות של Artifact Registry גם בקטע credHelpers וגם בקטע auths, המערכת מתעלמת מההגדרות בקטע auths.

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

הכלי לעזרה בפרטי כניסה של ה-CLI של gcloud מספק גישה מאובטחת לטווח קצר למשאבי הפרויקט. הוא מגדיר את Docker לאימות למארחי Artifact Registry בכל סביבה שבה מותקן Google Cloud CLI. ‫Cloud Shell כולל את Google Cloud CLI וגרסה עדכנית של Docker.

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

כדי לבצע אימות ב-Artifact Registry:

  1. מתחברים ל-CLI של gcloud בתור המשתמש שיריץ את פקודות Docker.

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

    gcloud auth configure-docker HOSTNAME-LIST

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

    לדוגמה, כדי להוסיף את האזורים us-west1 ו-asia-northeast1, מריצים את הפקודה:

    gcloud auth configure-docker us-west1-docker.pkg.dev,asia-northeast1-docker.pkg.dev

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

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

    gcloud artifacts locations list

  2. הפקודה מציגה את הקטע credHelpers של הגדרת Docker הנוכחית ואת ההגדרה המעודכנת אחרי הוספת שמות המארחים שצוינו.

    כדי לאשר את שינויי ההגדרות, מזינים y.

    פרטי הכניסה שלכם נשמרים בספריית הבית של המשתמש.

    • ‫Linux: ‏ $HOME/.docker/config.json
    • ב-Windows:‏ %USERPROFILE%/.docker/config.json‎

  3. ‫Docker דורש שיהיו במערכת PATH כלי עזר לאימות. מוודאים שהפקודה gcloud נמצאת במערכת PATH.

כלי עזר עצמאי לפרטי כניסה

כלי העזר העצמאי של Docker לפרטי כניסה מגדיר את Docker לאימות ב-Artifact Registry במערכת שבה ה-CLI של gcloud לא זמין. הכלי העצמאי, שעשוי להיות מהיר יותר מכלי העזר לפרטי כניסה של gcloud CLI, משתמש ב-Application Default Credentials (ADC) כדי למצוא באופן אוטומטי את פרטי הכניסה בסביבה שלכם. מומלץ להשתמש בשיטת האימות הזו לבנייה אוטומטית באמצעות כלים של צד שלישי או לקוחות Docker עם מספר גדול של מארחי רישום מוגדרים.

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

כדי להשתמש בכלי העזר לפרטי כניסה של Docker:

  1. מתחברים למכונה בתור המשתמש שיריץ את פקודות Docker.

  2. מורידים את כלי העזר העצמאי לפרטי כניסה של Docker מ-GitHub.

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

    VERSION=2.1.29
OS=linux  # or "darwin" for OSX, "windows" for Windows.
ARCH=amd64  # or "386" for 32-bit OSs

curl -fsSL "https://github.com/GoogleCloudPlatform/docker-credential-gcr/releases/download/v${VERSION}/docker-credential-gcr_${OS}_${ARCH}-${VERSION}.tar.gz" \
| tar xz docker-credential-gcr \
&& chmod +x docker-credential-gcr && sudo mv docker-credential-gcr /usr/bin/

  3. מגדירים את Docker כך שישתמש בפרטי הכניסה שלכם ל-Artifact Registry כשמתקשרים עם Artifact Registry (צריך לעשות את זה רק פעם אחת):

    docker-credential-gcr configure-docker --registries=HOSTNAME-LIST

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

    לדוגמה, כדי להוסיף את האזורים us-west1 ו-asia-northeast1, מריצים את הפקודה:

    docker-credential-gcr configure-docker --registries=us-west1-docker.pkg.dev,asia-northeast1-docker.pkg.dev

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

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

    gcloud artifacts locations list

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

    פרטי הכניסה שלכם נשמרים בספריית הבית של המשתמש.

    • ‫Linux: ‏ $HOME/.docker/config.json
    • ב-Windows:‏ %USERPROFILE%/.docker/config.json‎

  4. ‫Docker דורש שיהיו במערכת PATH כלי עזר לאימות. מוודאים שהפקודה docker-credential-gcr נמצאת במערכת PATH.

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

    echo "https://HOSTNAME" | docker-credential-gcr get

    מחליפים את HOSTNAME בשם מארח שהוספתם להגדרה. לדוגמה:

    echo "https://us-west1-docker.pkg.dev" | docker-credential-gcr get

    אם הפקודה מסתיימת ללא שגיאות, פלט ה-JSON שמוחזר כולל אסימון בשדה Secret. לדוגמה:

    {"ServerURL":"https://us-west1-docker.pkg.dev","Username":"_dcgcr_2_0_0_token","Secret":"ya29..."}

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

טוקן גישה

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

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

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

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

  3. יצירת אסימון גישה לחשבון השירות ואימות:

    כדי להתחזות לחשבון שירות, לקבל אסימון בשבילו ואז לבצע אימות בתור חשבון השירות, אתם צריכים את ההרשאות שכלולות בתפקיד 'יצירת אסימונים בחשבון שירות' (roles/iam.serviceAccountTokenCreator).

    ‫ מריצים את הפקודה הבאה ומחליפים את ACCOUNT בכתובת האימייל בחשבון השירות ואת LOCATION במיקום האזורי או הרב-אזורי של המאגר. ‫

    Linux

    gcloud auth print-access-token \
    --impersonate-service-account ACCOUNT | docker login \
    -u oauth2accesstoken \
    --password-stdin https://LOCATION-docker.pkg.dev

    Windows

    gcloud auth print-access-token --impersonate-service-account ACCOUNT | docker login -u oauth2accesstoken --password-stdin https://LOCATION-docker.pkg.dev

האימות של Docker ב-Artifact Registry בוצע.

מפתח לחשבון השירות

כל מי שיש לו גישה למפתח פרטי תקף של חשבון שירות יוכל לגשת למשאבים דרך חשבון השירות. חשוב לדעת שמחזור החיים של הגישה של המפתח לחשבון השירות (ולכן גם לנתונים שלחשבון השירות יש גישה אליהם) לא תלוי במחזור החיים של המשתמש שהוריד את המפתח.

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

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

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

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

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

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

  2. אפשר גם לקודד Base64 את כל התוכן של קובץ המפתח.

    Linux

    base64 FILE-NAME > NEW-FILE-NAME

    macOS

    base64 -i FILE-NAME -o NEW-FILE-NAME

    Windows

    Base64.exe -e FILE-NAME > NEW-FILE-NAME

    כאשר FILE-NAME הוא שם הקובץ המקורי של המפתח ו-NEW-FILE-NAME הוא קובץ המפתח בקידוד Base64.

  3. מוודאים שההרשאות מוגדרות בצורה נכונה לחשבון השירות. אם אתם משתמשים בחשבון השירות של Compute Engine, אתם צריכים להגדיר בצורה נכונה גם את ההרשאות וגם את היקפי הגישה.

  4. משתמשים במפתח של חשבון השירות כדי להגדיר שילוב עם Docker:

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

    ‫Linux / macOS

    cat KEY-FILE | docker login -u KEY-TYPE --password-stdin \
https://LOCATION-docker.pkg.dev

    Windows

    Get-Content KEY-FILE |
docker login -u KEY-TYPE --password-stdin https://LOCATION-docker.pkg.dev

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

    • ‫KEY-TYPE הוא אחד מהבאים:
      • ‫_json_key אם אתם משתמשים במפתח של חשבון השירות בפורמט JSON כמו שהוא סופק כשנוצר הקובץ.
      • ‫_json_key_base64 אם קידדתם את כל התוכן של הקובץ בקידוד Base64.
    • ‫KEY-FILE הוא השם של קובץ המפתח של חשבון השירות בפורמט JSON.
    • ‫LOCATION הוא המיקום האזורי או הרב-אזורי של המאגר שבו התמונה מאוחסנת.

האימות של Docker ב-Artifact Registry בוצע.