כדי להסביר למה צוותי התשתית או האפליקציה שלכם מקבלים החלטות מסוימות לגבי העיצוב, אתם יכולים להשתמש ברשומות של החלטות לגבי הארכיטקטורה (ADR). במסמך הזה מוסבר מתי ואיך להשתמש ב-ADR כשמפתחים ומריצים אפליקציות ב-Google Cloud.
ב-ADR מתועדות האפשרויות העיקריות הזמינות, הדרישות העיקריות שמובילות להחלטה וההחלטות עצמן לגבי התכנון. לרוב, שומרים את מסמכי ה-ADR בקובץ Markdown קרוב לבסיס הקוד שרלוונטי להחלטה. אם מישהו צריך להבין את הרקע של החלטה אדריכלית ספציפית, למשל למה אתם משתמשים באשכול אזורי של Google Kubernetes Engine (GKE), הוא יכול לעיין ב-ADR ואז בקוד שמשויך אליו.
בנוסף, ADR יכול לעזור לכם להפעיל אפליקציות ושירותים אמינים יותר. ה-ADR עוזר להבין את המצב הנוכחי ולפתור בעיות. בנוסף, ה-ADR יוצר אוסף של החלטות הנדסיות שיעזרו בקבלת החלטות ובפריסות עתידיות.
מתי כדאי להשתמש ב-ADR
אתם משתמשים ב-ADR כדי לעקוב אחרי התחומים העיקריים שלדעתכם חשובים לפריסה. ה-ADR עשוי לכלול את הקטגוריות הבאות:
- בחירות ספציפיות של מוצרים, כמו הבחירה בין Pub/Sub לבין Cloud Tasks.
- אפשרויות וקביעות הגדרה ספציפיות של מוצרים, כמו שימוש באשכולות GKE אזוריים עם Multi Cluster Ingress לאפליקציות עם זמינות גבוהה.
- הנחיות כלליות לארכיטקטורה, כמו שיטות מומלצות למניפסטים של Dockerfile.
הנה כמה דוגמאות ספציפיות שיכולות לעורר בכם את הצורך ליצור ADR:
- איך ומדוע מגדירים זמינות גבוהה (HA) למופעים של Cloud SQL?
- מה הגישה שלכם לגבי זמן הפעולה של אשכולות GKE? האם אתם משתמשים באשכולות אזוריים? האם אתם משתמשים בגרסאות קנריות? למה או למה לא?
כשאתם בוחנים את המוצרים שבהם אתם רוצים להשתמש, ה-ADR עוזר לכם להבין כל אחת מההחלטות שלכם. אפשר לחזור ל-ADR כשהצוות מתפתח ולומד עוד על הסטאק, ולקבל או לשנות החלטות נוספות. אם מבצעים שינויים, צריך לכלול את ההחלטה הקודמת ולהסביר למה בוצע שינוי. ההיסטוריה הזו מתעדת את השינויים בארכיטקטורה ככל שהצרכים העסקיים מתפתחים, או כשמתעוררות דרישות טכניות חדשות או כשפתרונות חדשים הופכים לזמינים.
ההנחיות הבאות יעזרו לכם לדעת מתי ליצור מסמכי ADR:
- כשנתקלים באתגר טכני או שיש שאלה טכנית ואין בסיס קיים לקבלת החלטה, כמו פתרון מומלץ, נוהל הפעלה רגיל, תוכנית או בסיס קוד.
- כשאתם או הצוות שלכם מציעים פתרון שלא מתועד במקום כלשהו שנגיש לצוות.
- כשמוצגות שתי אפשרויות הנדסיות או יותר ואתם רוצים לתעד את המחשבות והסיבות שלכם לבחירה.
כשכותבים מסמך ADR, כדאי לחשוב על הקוראים הפוטנציאליים. הקוראים העיקריים הם חברי הצוות שעובדים על הטכנולוגיה שמכוסה על ידי ה-ADR. קבוצות רחבות יותר של קוראים פוטנציאליים של ה-ADR עשויות לכלול צוותים סמוכים שרוצים להבין את ההחלטות שלכם, כמו צוותי ארכיטקטורה ואבטחה.
כדאי גם לקחת בחשבון שהבעלים של האפליקציה עשוי להשתנות או שצוות חדש עשוי להצטרף. מסמך ADR עוזר לתורמים חדשים להבין את הרקע של הבחירות ההנדסיות שנעשו. בנוסף, קל יותר לתכנן שינויים עתידיים באמצעות ADR.
הפורמט של ADR
דוח ADR טיפוסי כולל קבוצה של פרקים. מסמכי ה-ADR צריכים לעזור לכם לתעד את מה שחשוב לכם באפליקציה ובארגון. חלק מה-ADR יכולים להיות באורך של עמוד אחד, בעוד שאחרים דורשים הסבר ארוך יותר.
בדוגמה הבאה של מבנה ADR אפשר לראות איך לעצב ADR כך שיכלול את המידע שחשוב לסביבה שלכם:
- המחברים והצוות
- הקשר והבעיה שרוצים לפתור
- דרישות פונקציונליות ודרישות לא פונקציונליות שאתם רוצים לטפל בהן
- חוויית משתמש הכרחית (CUJ) פוטנציאלית שההחלטה משפיעה עליה
- סקירה כללית של האפשרויות העיקריות
- ההחלטה שלכם והסיבות לבחירה שאושרה
כדי לשמור תיעוד של ההחלטות, כדאי לכלול חותמת זמן לכל החלטה כדי להראות מתי היא התקבלה.
איך פועלות ADR
ה-ADR-ים פועלים בצורה הטובה ביותר כשהמהנדסים, המפתחים או בעלי האפליקציות יכולים לגשת בקלות למידע שהם מכילים. אם יש להם שאלה לגבי הסיבה לכך שמשהו נעשה בצורה מסוימת, הם יכולים לעיין ב-ADR כדי למצוא את התשובה.
כדי להפוך את ה-ADR לנגיש, חלק מהצוותים מאחסנים אותו בוויקי מרכזי שנגיש גם לבעלי העסקים, במקום במאגר בקרת המקורות שלהם. כשמישהו רוצה לשאול שאלה לגבי החלטה הנדסית ספציפית, מסמך ה-ADR מספק את התשובות.
מודעות דינמיות לחיפוש מתאימות במיוחד לתרחישים הבאים:
- הדרכה: חברי צוות חדשים יכולים ללמוד בקלות על הפרויקט, ולעיין ב-ADR אם יש להם שאלות בזמן שהם לומדים בסיס קוד חדש.
- התפתחות הארכיטקטורה: אם יש העברה של חבילת טכנולוגיות בין צוותים, הבעלים החדשים יכולים לבדוק החלטות קודמות כדי להבין את המצב הנוכחי. הצוות יכול גם לבדוק החלטות קודמות אם יש טכנולוגיה חדשה שזמינה לו. ה-ADR יכול לעזור לצוותים להימנע מחזרה על אותם נושאים לדיון, והוא יכול לספק הקשר היסטורי כשצוותים חוזרים לנושאים.
- שיתוף שיטות מומלצות: צוותים יכולים להגיע להסכמה לגבי שיטות מומלצות בכל הארגון כשמסמכי ADR מפרטים למה התקבלו החלטות מסוימות ולמה נדחו חלופות.
מסמך ADR נכתב בדרך כלל בפורמט Markdown כדי לשמור על משקל קל ועל בסיס טקסט. אפשר לכלול קובצי Markdown במאגר של בקרת המקור עם קוד האפליקציה.
מומלץ לשמור את מסמכי ה-ADR קרוב לקוד האפליקציה, באופן אידיאלי באותה מערכת בקרת גרסאות. כשמבצעים שינויים ב-ADR, אפשר לבדוק גרסאות קודמות מניהול המקור לפי הצורך.
אפשר גם להשתמש באמצעי תקשורת אחרים, כמו מסמך Google Docs משותף או ויקי פנימי. יכול להיות שהמיקומים החלופיים האלה יהיו נגישים יותר למשתמשים שלא נכללים בצוות של ה-ADR. אפשרות נוספת היא ליצור את ה-ADR במאגר של מערכת בקרת מקורות, אבל לשקף את ההחלטות המרכזיות בוויקי נגיש יותר.
המאמרים הבאים
- במרכז הארכיטקטורה של Cloud ובGoogle Cloud Well-Architected Framework אפשר למצוא הנחיות ושיטות מומלצות נוספות.
- במאמר תבניות לאפליקציות עמידות שניתנות להרחבה מפורטים תחומים מסוימים שאולי רלוונטיים ל-ADR שלכם.