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

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

הגדרת סביבה בקצב אישי

1. נכנסים ל-מסוף Google Cloud ויוצרים פרויקט חדש או משתמשים בפרויקט קיים. אם עדיין אין לכם חשבון Gmail או Google Workspace, אתם צריכים ליצור חשבון.

• שם הפרויקט הוא השם המוצג למשתתפים בפרויקט. זו מחרוזת של תווים שלא נמצאת בשימוש ב-Google APIs, ואפשר לעדכן אותה בכל שלב.
• מזהה הפרויקט חייב להיות ייחודי לכל הפרויקטים ב-Google Cloud, והוא קבוע (אי אפשר לשנות אותו אחרי שהוא מוגדר). מסוף Cloud יוצר באופן אוטומטי מחרוזת ייחודית. בדרך כלל לא צריך לדעת מה היא. ברוב סדנאות ה-Codelab, תצטרכו להפנות למזהה הפרויקט (ובדרך כלל הוא מזוהה כ-PROJECT_ID), אז אם אתם לא אוהבים אותו, תוכלו ליצור מזהה אקראי אחר, או לנסות ליצור מזהה משלכם ולראות אם הוא זמין. אחרי שהפרויקט נוצר, הוא 'קפוא'.
• יש ערך שלישי, מספר פרויקט, שמשמש חלק מממשקי ה-API. מידע נוסף על שלושת הערכים האלה מופיע במאמרי העזרה.

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

הערה: אם אתם משתמשים בחשבון Gmail, אתם יכולים להשאיר את מיקום ברירת המחדל כללא ארגון. אם אתם משתמשים בחשבון Google Workspace, אתם צריכים לבחור מיקום שמתאים לארגון שלכם.

2. בשלב הבא, תצטרכו להפעיל את החיוב במסוף Cloud כדי להשתמש במשאבי Cloud או בממשקי API. העלות של התרגול הזה לא אמורה להיות גבוהה, ואולי לא תהיה עלות בכלל. כדי לכבות את המשאבים ולא לחייב אתכם מעבר למה שמוסבר במדריך הזה, צריך לפעול לפי ההוראות לניקוי שמופיעות בסוף ה-Codelab. משתמשים חדשים ב-Google Cloud זכאים לתוכנית תקופת ניסיון בחינם בשווי 300$.

2. הכנת סביבת העבודה

1. פותחים את Cloud Shell Editor בכתובת ה-URL הבאה

https://ide.cloud.google.com

2. מוודאים ששם הפרויקט מוגדר ב-CLI

gcloud config set project {{project-id}}

export PROJECT_ID=$(gcloud config get-value project)

export PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format='value(projectNumber)')

3. הפעלת ממשקי ה-API

gcloud services enable \

cloudbuild.googleapis.com \

secretmanager.googleapis.com

4. מתן הרשאות ל-CloudDeploy

gcloud projects add-iam-policy-binding --member="serviceAccount:${PROJECT_NUMBER}@cloudbuild.gserviceaccount.com" --role roles/clouddeploy.admin ${PROJECT_ID}

gcloud projects add-iam-policy-binding --member="serviceAccount:${PROJECT_NUMBER}@cloudbuild.gserviceaccount.com" --role roles/container.developer ${PROJECT_ID}

gcloud projects add-iam-policy-binding --member="serviceAccount:${PROJECT_NUMBER}@cloudbuild.gserviceaccount.com" --role roles/iam.serviceAccountUser ${PROJECT_ID}

gcloud projects add-iam-policy-binding --member="serviceAccount:${PROJECT_NUMBER}@cloudbuild.gserviceaccount.com" --role roles/clouddeploy.jobRunner ${PROJECT_ID}

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

git clone https://github.com/GoogleCloudPlatform/software-delivery-workshop.git

6. עוברים לספרייה ומגדירים את סביבת העבודה של ה-IDE לשורש המאגר

cd software-delivery-workshop && rm -rf .git

cd delivery-platform && cloudshell workspace .

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

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

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

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

הגדרת גישה ל-GitHub

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

source ./onboard-env.sh

echo Git Username: $GIT_USERNAME

echo Git Base URL: $GIT_BASE_URL

יצירת מאגר תבניות לאפליקציות

בשיעור ה-Lab הזה מופיעות תבניות לדוגמה של אפליקציות, כדי להראות לכם איך אפשר לשלב תבניות בסיס משלכם. בשלב הזה יוצרים עותק משלכם של הקבצים האלה במאגר שנקרא mcd-app-templates בחשבון GitHub.

1. העתקת התבנית לספריית העבודה

cp -R $BASE_DIR/resources/repos/app-templates $WORK_DIR

cd $WORK_DIR/app-templates

2. יצירת מאגר מרוחק ריק בחשבון GitHub

$BASE_DIR/scripts/git/gh.sh create mcd-app-templates

3. דחיפה של מאגר התבניות למאגר מרוחק

git init && git symbolic-ref HEAD refs/heads/main && git add . && git commit -m "initial commit"

git remote add origin $GIT_BASE_URL/mcd-app-templates

git push origin main

4. ניקוי ספריית העבודה

cd $BASE_DIR

rm -rf $WORK_DIR/app-templates

יצירת מאגר של הגדרות בסיסיות משותפות

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

בשלב הזה יוצרים את מאגר התצורה המשותף שנקרא mcd-shared_kustomize מהדוגמאות שסופקו

1. העתקת התבנית לספריית העבודה

cp -R $BASE_DIR/resources/repos/shared-kustomize $WORK_DIR

cd $WORK_DIR/shared-kustomize

2. יצירת מאגר מרוחק ריק בחשבון GitHub

$BASE_DIR/scripts/git/gh.sh create mcd-shared_kustomize

3. דחיפה של מאגר התבניות למאגר מרוחק

git init && git symbolic-ref HEAD refs/heads/main && git add . && git commit -m "initial commit"

git remote add origin $GIT_BASE_URL/mcd-shared_kustomize

git push origin main

4. ניקוי ספריית העבודה

cd $BASE_DIR

rm -rf $WORK_DIR/shared-kustomize

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

4. יצירת מופע חדש של אפליקציה

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

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

הגדרת שם לאפליקציה החדשה

export APP_NAME=my-app

אחזור מאגר התבניות של Golang

cd $WORK_DIR/

git clone -b main $GIT_BASE_URL/mcd-app-templates app-templates

rm -rf app-templates/.git

cd app-templates/golang

החלפת ערכים זמניים לשמירת מקום (placeholder)

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

for template in $(find . -name '*.tmpl'); do envsubst < ${template} > ${template%.*}; done

יצירת מאגר חדש ואחסון הקבצים המעודכנים

1. יצירת מאגר מרוחק ריק בחשבון GitHub

$BASE_DIR/scripts/git/gh.sh create ${APP_NAME}

2. דחיפה של מאגר התבניות למאגר מרוחק

git init && git symbolic-ref HEAD refs/heads/main && git add . && git commit -m "initial commit"

git remote add origin $GIT_BASE_URL/${APP_NAME}

git push origin main

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

5. הגדרת ביצוע אוטומטי של צינור עיבוד נתונים

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

בשלב הזה מגדירים את GitHub כך שיקרא ל-Google Cloud Build ויבצע את הצינור בכל פעם שמשתמשים מבצעים קומיט או מתייגים קוד במאגר שלהם.

הפעלת גישה מאובטחת

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

מפתח API

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

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

echo $API_KEY_VALUE

סוד הפייפליין

הסודות משמשים לאישור של מבצע הקריאה ולוודא שיש לו זכויות לעבודה הספציפית של יעד ה-Cloud Build. יכול להיות שיש לכם 2 מאגרים שונים ב-GitHub שצריכה להיות להם גישה רק לצינורות משלהם. מפתח ה-API מגביל את השימוש בממשקי API מסוימים על ידי GitHub (במקרה הזה, מתבצעת קריאה ל-Cloud Build API), והסוד מגביל את העבודה שאפשר לבצע ב-Cloud Build API על ידי הלקוח.

1. הגדרת השם, המיקום והערך של הסוד

SECRET_NAME=${APP_NAME}-webhook-trigger-cd-secret

SECRET_PATH=projects/${PROJECT_NUMBER}/secrets/${SECRET_NAME}/versions/1

SECRET_VALUE=$(sed "s/[^a-zA-Z0-9]//g" <<< $(openssl rand -base64 15))

2. יצירת הסוד

printf ${SECRET_VALUE} | gcloud secrets create ${SECRET_NAME} --data-file=-

3. מתן הרשאה ל-Cloud Build לקרוא את הסוד

gcloud secrets add-iam-policy-binding ${SECRET_NAME} \

--member=serviceAccount:service-${PROJECT_NUMBER}@gcp-sa-cloudbuild.iam.gserviceaccount.com \

--role='roles/secretmanager.secretAccessor'

יצירת טריגר של Cloud Build

הטריגר של Cloud Build הוא ההגדרה שתבצע בפועל את תהליכי ה-CICD.

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

4. הגדרת השם של הטריגר והמיקום של קובץ התצורה

export TRIGGER_NAME=${APP_NAME}-clouddeploy-webhook-trigger

export BUILD_YAML_PATH=$WORK_DIR/app-templates/golang/build/cloudbuild-cd.yaml

5. הגדרת המיקום של מאגר התצורה הבסיסית המשותפת.

export KUSTOMIZE_REPO=${GIT_BASE_URL}/mcd-shared_kustomize

6. הוגדר משתנה בסקריפט onboard-env.sh שמגדיר את מאגר התגים של הפרויקט. בודקים את הערך באמצעות הפקודה שבהמשך.

echo $IMAGE_REPO

7. יוצרים טריגר מסוג CloudBuild Webhook באמצעות המשתנים שנוצרו קודם. המיקום של מאגר האפליקציות נשלף מגוף הבקשה מ-GitHub. ערך שמופיע מתחת לנתיב בגוף הבקשה שבו הוא נמצאgcloud alpha builds triggers create webhook \

    `--name=${TRIGGER_NAME} \`
   
    `--substitutions='_APP_NAME='${APP_NAME}',_APP_REPO=$(body.repository.git_url),_CONFIG_REPO='${GIT_BASE_URL}'/'${CLUSTER_CONFIG_REPO}',_DEFAULT_IMAGE_REPO='${IMAGE_REPO}',_KUSTOMIZE_REPO='${GIT_BASE_URL}'/'${SHARED_KUSTOMIZE_REPO}',_REF=$(body.ref)' \`
   
    `--inline-config=$BUILD_YAML_PATH \`
   
    `--secret=${SECRET_PATH}`
   

8. כדי לבדוק את הטריגר לפיתוח גרסת Build החדש שנוצר ב-Cloud Build במסוף, עוברים לקישור הזה.
9. מגדירים משתנה לכתובת ה-URL של נקודת הקצה, שבה GitHub ישתמש בשלב הבא

WEBHOOK_URL="https://cloudbuild.googleapis.com/v1/projects/${PROJECT_ID}/triggers/${TRIGGER_NAME}:webhook?key=${API_KEY_VALUE}&secret=${SECRET_VALUE}"

הגדרת GitHub Webhook

1. הגדרת ה-webhook ב-GitHub

$BASE_DIR/scripts/git/gh.sh create_webhook ${APP_NAME} $WEBHOOK_URL

2. עוברים אל מאגר האפליקציות ובודקים את ה-webhook החדש שהוגדר

REPO_URL=${GIT_BASE_URL}/${APP_NAME}/settings/hooks

echo $REPO_URL

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

6. אוטומציה של כל שלבי ההצטרפות

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

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

יצירת אפליקציה חדשה

1. מוודאים שאתם נמצאים בספרייה הנכונה

cd $BASE_DIR

2. יצירת אפליקציה חדשה

export APP_NAME=demo-app

./app.sh create ${APP_NAME}

כל השלבים מבוצעים באופן אוטומטי.

בדיקת המאגר ב-GitHub

בשלב הזה תוכלו לבדוק את המאגר החדש ב-GitHub

1. מריצים את הפקודה הבאה כדי לאחזר את כתובת ה-URL של מאגר GitHub

echo ${GIT_BASE_URL}/demo-app

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

echo ${GIT_BASE_URL}/demo-app/blob/main/k8s/prod/deployment.yaml#L24

4. צריך לבדוק את ה-webhook שהוגדר בכתובת ה-URL שבהמשך

echo ${GIT_BASE_URL}/demo-app/settings/hooks

בדיקת הטריגר של CloudBuild

הטריגר הוגדר אוטומטית על ידי הסקריפט

1. כדי לבדוק את טריגר לפיתוח גרסת Build ב-Cloud במסוף, עוברים לקישור הזה.
2. אפשר לעיין בהיסטוריית הבנייה בדף הזה