דחיפה ושליפה של תמונות

בדף הזה מוסבר איך להעביר קובצי אימג' של קונטיינרים באמצעות Docker. בנוסף, הוא מספק מידע על שליפת תמונות באמצעות הכלי crictl אם אתם פותרים בעיות ב-Google Kubernetes Engine.

מידע על פריסה בסביבות זמן ריצה של Google Cloud זמין במאמר פריסה ב- Google Cloud.

הוראות לגבי הצגת תמונות, תיוג שלהן ומחיקה שלהן מופיעות במאמר בנושא ניהול תמונות.

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

1. אם מאגר היעד לא קיים, צריך ליצור מאגר חדש.
2. צריכה להיות לכם לפחות גישת כתיבה למאגר ב-Artifact Registry.
3. כדי לשלוח תמונות באמצעות Docker, צריך להתקין את Docker אם הוא עדיין לא מותקן.
4. כדי לשלוח תמונות באמצעות Podman, צריך להתקין את Podman
5. אם Google Cloud CLI עדיין לא מותקן, צריך להתקין אותו.

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

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

• משיכת תמונות: קורא של Artifact Registry (roles/artifactregistry.reader)
• תיוג ותחיבת תמונות: כתיבה ב-Artifact Registry (roles/artifactregistry.writer)

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

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

אימות למאגר

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

שימוש בכלי עזר לפרטי כניסה

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

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

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

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

בקטע credHelpers מפורטים מארחי Docker שהוגדרו ב-Artifact Registry. שמות המארחים מסתיימים ב--docker.pkg.dev. בדוגמה הבאה מוצגים כמה מארחים שהוגדרו עבור כלי העזר לפרטי הכניסה של ה-CLI של gcloud.

"credHelpers": {
  "asia.gcr.io": "gcloud",
  "eu.gcr.io": "gcloud",
  "gcr.io": "gcloud",
  "marketplace.gcr.io": "gcloud",
  "northamerica-northeast1-docker.pkg.dev": "gcloud",
  "us-central1-docker.pkg.dev": "gcloud",
  "us-east1-docker.pkg.dev": "gcloud",
  "us.gcr.io": "gcloud"
}

אם מארח שרוצים להשתמש בו לא מופיע ברשימה, מריצים שוב את הכלי לעזרה בהזנת פרטי הכניסה כדי להוסיף את המארח. לדוגמה, הפקודה הבאה מוסיפה את us-west1-docker.pkg.dev.

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

  gcloud auth configure-docker us-west1-docker.pkg.dev
  

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

  docker-credential-gcr configure-docker us-west1-docker.pkg.dev
  

שימוש בטוקן גישה

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

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

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

ya29.8QEQIfY_...

docker login -u oauth2accesstoken -p "ya29.8QEQIfY_..." `
https://LOCATION-docker.pkg.dev

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

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

במפתח של חשבון שירות משתמשים כמספר סיסמה עם הפקודה docker login.

לדוגמה, הפקודה הבאה משתמשת במפתח חשבון השירות בקידוד base64 בקובץ key.json כדי לבצע אימות ל-us-west1-docker.pkg.dev.

Linux

cat key.json | docker login -u _json_key_base64 --password-stdin \
https://us-west1-docker.pkg.dev

Windows

docker login -u _json_key_base64 --password-stdin https://us-west1-docker.pkg.dev < key.json

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

העלאת תמונה באמצעות Docker

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

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

אם במאגר Docker של Artifact Registry מופעלת האפשרות tag immutability, תג חייב תמיד להפנות לאותו גיבוי תמונה במאגר. אי אפשר להשתמש בתג בגרסה אחרת של אותה תמונה שמעלים למאגר. מידע נוסף על תקצירי קובצי אימג' של קונטיינר, תגים ואי-שינוי של תגים זמין במאמר גרסאות של קובצי אימג' של קונטיינר.

ההגבלות הבאות חלות על תמונות גדולות:

זמן העלאה

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

גודל התמונה

הגודל המקסימלי של ארטיפקט הוא 5TB.‫

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

תיוג התמונה המקומית

1. מוודאים שהאימות שלכם מול המאגר הושלם.

2. קובעים את שם התמונה. הפורמט של שם תמונה מלא הוא:

   LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE
   

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

   • ‫LOCATION הוא המיקום האזורי או המיקום במספר אזורים של המאגר שבו התמונה מאוחסנת.
   • ‫PROJECT-ID הוא מזהה הפרויקט במסוף. Google Cloud אם מזהה הפרויקט מכיל נקודתיים (:), כדאי לעיין במאמר בנושא פרויקטים בהיקף הדומיין.
   • ‫REPOSITORY הוא שם המאגר שבו מאוחסן האימג'.
   • ‫IMAGE הוא שם התמונה. הוא יכול להיות שונה מהשם המקומי של התמונה.

   לדוגמה, תמונה עם המאפיינים הבאים:

   • מיקום המאגר: us-west1
   • שם המאגר: my-repo
   • מזהה הפרויקט: my-project
   • שם התמונה המקומית: my-image
   • שם תמונת היעד: test-image

   בדוגמה הזו, שם התמונה הוא:

   ‫

   us-west1-docker.pkg.dev/my-project/my-repo/test-image
   

   הערה: השם של התמונה שתאחסנו במאגר יכול להיות שונה משם התמונה במכונה המקומית.

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

3. מתייגים את התמונה המקומית בשם המאגר.

   docker tag SOURCE-IMAGE LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE:TAG
   

   מחליפים את SOURCE-IMAGE בשם של האימג' המקומי או במזהה האימג' ואת TAG בתג. אם לא מציינים תג, Docker מחיל את התג latest שמוגדר כברירת מחדל.

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

   gcloud artifacts repositories describe REPOSITORY \
       --project=PROJECT-ID \
       --location=LOCATION
   

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

   docker tag my-image us-west1-docker.pkg.dev/my-project/my-repo/test-image
   

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

   docker tag SOURCE-IMAGE LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE:TAG
   

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

   docker tag my-image us-west1-docker.pkg.dev/my-project/my-repo/test-image:staging
   

העברה בדחיפה של התמונה המתויגת אל Artifact Registry

הערה: ‏ Artifact Registry לא תומך בהעלאות מקוטעות של Docker. חלק מהכלים לקובצי אימג' של קונטיינרים תומכים בהעלאה של קובצי אימג' גדולים של קונטיינרים באמצעות העלאות מחולקות או העלאה מונוליטית אחת. כשמעבירים בדחיפה קובצי אימג' של קונטיינרים אל Artifact Registry, צריך להשתמש בהעלאות מונוליטיות.

1. מוודאים שהאימות שלכם מול המאגר הושלם.

   אם השתמשתם ב-gcloud auth configure-docker או ב-docker-credential-gcr configure-docker כדי להגדיר את לקוח Docker, ודאו ששם המארח של היעד מופיע בקובץ ההגדרות של Docker.

2. מעלים את קובץ האימג' עם התג באמצעות הפקודה:

   docker push LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE
   

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

   docker push LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE:TAG
   

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

אחרי שדוחפים את התמונה, אפשר:

• כדי לראות את התמונה, נכנסים לGoogle Cloud מסוף.

• מריצים את הפקודה gcloud כדי לראות את התגים של האימג' ואת ה-digest שנוצר אוטומטית:

  gcloud artifacts docker images list \
  LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE [--include-tags]
  

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

   IMAGE                                                 DIGEST         CREATE_TIME          UPDATE_TIME
    us-west1-docker.pkg.dev/my-project/my-repo/my-image  sha256:85f...  2019-04-10T15:08:45  2019-04-10T15:08:45
    us-west1-docker.pkg.dev/my-project/my-repo/my-image  sha256:238...  2019-04-10T17:23:53  2019-04-10T17:23:53
    us-west1-docker.pkg.dev/my-project/my-repo/my-image  sha256:85f...  2019-04-10T15:08:46  2019-04-10T15:08:46
  

העלאת תמונה באמצעות Podman

אפשר להעביר בדחיפה קובץ אימג' של קונטיינר מ-Podman אל Artifact Registry.

1. מריצים את הפקודה הבאה כדי ליצור את קובץ האימג' באמצעות Podman:

    podman build -t IMAGE:latest .
   

2. מתייגים את תמונת Podman המקומית עבור Artifact Registry.

   משתמשים בנתיב המלא של Artifact Registry לתג. הפורמט זהה לפורמט של Docker: LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY_NAME/IMAGE:TAG

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

    podman tag IMAGE-NAME LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY_NAME/PODMAN-IMAGE:TAG 
   

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

   ‫

    gcloud auth configure-docker LOCATION-docker.pkg.dev
   

   הערה: כברירת מחדל, Podman מחפש פרטי כניסה ב-~/.config/containers/auth.json ועובר ל-~/.docker/config.json אם קובץ ברירת המחדל של Podman לא קיים או לא מכיל את פרטי הכניסה הנדרשים. אם נתקלים בבעיות, מעתיקים את הקטע auths מ-~/.docker/config.json אל ~/.config/containers/auth.json, או משתמשים בפקודה podman login.

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

    gcloud auth print-access-token | podman login -u oauth2accesstoken --password-stdin LOCATION-docker.pkg.dev
   

4. מעבירים בדחיפה את התמונה המתויגת אל Artifact Registry:

    podman push LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY_NAME/IMAGE:TAG
   

   חשוב לוודא שהתג זהה לתג שבו השתמשתם כדי לתייג את תמונת Podman המקומית.

שליפת תמונות באמצעות Docker

מצבי מאגר: standard, remote, virtual

1. מוודאים שהאימות שלכם מול המאגר הושלם.

   אם השתמשתם ב-gcloud auth configure-docker או ב-docker-credential-gcr configure-docker כדי להגדיר את לקוח Docker, ודאו ששם המארח של היעד מופיע בקובץ ההגדרות של Docker.

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

   docker pull LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE:TAG
   

   או

   docker pull LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE@IMAGE-DIGEST
   

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

   • ‫LOCATION הוא המיקום האזורי או המיקום במספר אזורים של המאגר שבו התמונה מאוחסנת.
   • ‫PROJECT הוא מזהה הפרויקט במסוף. Google Cloud אם מזהה הפרויקט מכיל נקודתיים (:), כדאי לעיין במאמר בנושא פרויקטים בהיקף הדומיין.
   • ‫PROJECT הוא מזהה הפרויקט במסוף. Google Cloud
   • ‫REPOSITORY הוא שם המאגר שבו מאוחסן האימג'.
   • ‫IMAGE הוא שם קובץ האימג' במאגר.
   • ‫TAG הוא התג של גרסת התמונה שרוצים למשוך.
   • ‫IMAGE-DIGEST הוא ערך הגיבוב sha256 של תוכן התמונה. לכל גרסה של תמונה יש תקציר תמונה ייחודי. ב Google Cloud מסוף, לוחצים על התמונה הספציפית כדי לראות את המטא-נתונים שלה. התקציר מופיע כתקציר תמונה.

   לדוגמה, תמונה עם המאפיינים הבאים:

   • מיקום המאגר: us-west1
   • שם המאגר: my-repo
   • מזהה הפרויקט: my-project
   • שם התמונה: test-image
   • תג: staging

   הפקודה למשיכת התמונה היא:

   docker pull us-west1-docker.pkg.dev/my-project/my-repo/test-image:staging
   

מערכת Docker מורידה את התמונה שצוינה.

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

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

לדוגמה, נניח שיש מאגר וירטואלי עם הגדרות העדיפות הבאות למאגרי upstream:

• ‫main-repo: העדיפות מוגדרת ל-100
• secondary-repo1: העדיפות מוגדרת ל-80.
• secondary-repo2: העדיפות מוגדרת ל-80.
• test-repo: העדיפות מוגדרת ל-20.

ל-main-repo יש את ערך העדיפות הגבוה ביותר, ולכן המאגר הווירטואלי תמיד מחפש בו קודם.

העדיפות של secondary-repo1 ושל secondary-repo2 מוגדרת כ80. אם התמונה המבוקשת לא זמינה ב-main-repo, מערכת Artifact Registry מחפשת אותה במאגרים האלה. מכיוון שלשניהם יש את אותו ערך עדיפות, אם הגרסה זמינה בשני המאגרים, Artifact Registry יכול לבחור להציג תמונה מכל אחד מהם.

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

שליפת תמונות באמצעות crictl

‫crictl הוא כלי שורת פקודה שימושי למפתחים של סביבת זמן ריצה של CRI, שמאפשר להם לנפות באגים בסביבת זמן הריצה בלי להגדיר רכיבי Kubernetes. אם הצמתים של Google Kubernetes Engine משתמשים בזמן ריצה של containerd, אפשר למשוך תמונות מ-Artifact Registry באמצעות crictl.

מכיוון ש-crictl הוא בעיקר כלי לפתרון בעיות, חלק מהפקודות של Docker, כמו שליחה או תיוג של תמונות, לא זמינות.

כדי לשלוף תמונה מ-Artifact Registry:

1. נכנסים לדף VM Instances במסוף Google Cloud .

   כניסה לדף VM Instances

2. מתחברים ל-SSH לצומת שבו רוצים לפתור בעיות.

3. מקבלים טוקן גישה לאימות מול המאגר.

   curl -s "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/token" -H "Metadata-Flavor: Google"

4. שולפים את התמונה באמצעות crictl pull --creds והערך access_token

   crictl pull --creds "oauth2accesstoken:ACCESS_TOKEN" LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE:TAG

   או

   crictl pull --creds "oauth2accesstoken:ACCESS_TOKEN" LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE@IMAGE-DIGEST

   הפלט אמור להיראות כך:

   Image is up to date for sha256:0f25067aa9c180176967b4b50ed49eed096d43fa8c17be9a5fa9bff05933bee5

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

• איך מנהלים תגים ומוחקים תמונות
• אם אתם רוצים להריץ קונטיינרים ב-Compute Engine, כדאי לקרוא על קונטיינרים ב-Compute Engine.
• שימוש ב-crictl כדי לנפות באגים בצמתי Kubernetes
• crictl: איך לשלוף אימג'ים ממאגרי Artifact Registry פרטיים
• crictl מידע נוסף על הגדרת מאגרי תמונות