אימות Docker ב-Artifact Registry

הגדרת אימות 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

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

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

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

credHelpers
אם משתמשים בכלי העזר לפרטי כניסה של Docker לצורך אימות, Artifact Registry מאחסן את ההגדרות של כלי העזר לפרטי כניסה בקטע 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. מכיוון שכלי העזר הזה תלוי ב-CLI של gcloud, הוא יכול להיות איטי משמעותית מכלי העזר העצמאי. ב-builds אוטומטיים עם כלים של צד שלישי או לקוחות Docker עם מספר גדול של מארחי מרשם מוגדרים, השתמשו במקום זאת בכלי העזר העצמאי לפרטי כניסה.

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

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

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

    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

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

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

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

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

  4. כדי להשתמש ב-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 במאגר של סביבת ביניים.
  • חשוב לפעול לפי השיטות המומלצות לניהול פרטי כניסה.

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

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

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

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

  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 הושלם.