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

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

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

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

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

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

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

2. בשלב הבא צריך להפעיל את החיוב במסוף Cloud כדי להשתמש במשאבים או בממשקי API של Cloud. השלמת הקודלאב הזה לא אמורה לעלות הרבה, אם בכלל. כדי להשבית את המשאבים כדי שלא תחויבו אחרי סיום המדריך, פועלים לפי ההוראות ל'ניקוי' שמופיעות בסוף הקודלאב. משתמשים חדשים ב-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

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

אחת מהצרכים הנפוצים ביותר בתהליך ההצטרפות היא החלפת המשתנים בתבניות במופעים בפועל שמשמשים באפליקציה. לדוגמה, ציון שם האפליקציה. הפקודה הבאה יוצרת מכונות של כל קובצי ה-‎ .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. הגדרת הפעלה אוטומטית של צינור עיבוד נתונים

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

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

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

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

מפתח API

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

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

echo $API_KEY_VALUE

סוד של צינור עיבוד נתונים

הסודות משמשים לאישור מבצע קריאה חוזרת (caller) ולהבטחת שיש לו הרשאות למשימה הספציפית של יעד build בענן. יכול להיות שיש לכם 2 מאגרים שונים ב-GitHub, שצריכה להיות להם גישה רק לצינורות עיבוד נתונים משלהם. בעוד ש-API_KEY מגביל את ממשקי ה-API ש-GitHub יכול להשתמש בהם (במקרה הזה, מתבצעת קריאה ל-Cloud Build API), הסוד מגביל את ה-Job ב-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. יוצרים טריגר Webhook ב-Cloud Build באמצעות המשתנים שנוצרו קודם. המיקום של מאגר האפליקציה נשלף מגוף הבקשה מ-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. כדי לבדוק את הטריגר החדש שנוצר ב-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}"

הגדרת Webhook ב-GitHub

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. בקישור הזה תוכלו לבדוק את הטריגר של Cloud Build במסוף.
2. בדף הזה אפשר לעיין בהיסטוריית הגרסאות של ה-build.