שיטות מומלצות לשימוש חוזר במודולים

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

המדריך הזה אינו מבוא ל-Terraform. למידע על שימוש ב-Terraform עם Google Cloud, אפשר לעיין במאמר תחילת העבודה עם Terraform.

הפעלת ממשקי ה-API הנחוצים במודולים

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

אם המודול מאפשר להפעיל את ממשק ה-API, חייבת להיות אפשרות להשבית את הפעלת ה-API על ידי חשיפת משתנה enable_apis שמוגדר כברירת מחדל לערך true.

אם המודול מאפשר להפעיל את ממשק ה-API, חייבת להיות אפשרות להגדיר את המאפיין disable_services_on_destroy עם הערך false, כי המאפיין הזה עלול לגרום לבעיות בעבודה עם מספר מופעים של המודול.

למשל:

module "project-services" {
  source  = "terraform-google-modules/project-factory/google//modules/project_services"
  version = "~> 12.0"

  project_id  = var.project_id
  enable_apis = var.enable_apis

  activate_apis = [
    "compute.googleapis.com",
    "pubsub.googleapis.com",
  ]
  disable_services_on_destroy = false
}

הכללת קובץ בעלים

לכל המודולים המשותפים, צריך לכלול קובץ OWNERS (או CODEOWNERS ב-GitHub), כדי לתעד מי אחראי על המודול. הבעלים צריכים לאשר כל בקשת משיכה (pull request) כדי שהיא תמוזג.

פרסום גרסאות מתויגות

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

חשוב לוודא שהמודולים המשותפים פועלים לפי SemVer בגרסה 2.0.0 כשגרסאות חדשות יתויגו או יתווספו לגרסה.

כשמוסיפים הפניה למודול, צריך להשתמש באילוץ על מספר הגרסה כדי להיצמד לגרסה הראשית. לדוגמה:

module "gke" {
  source  = "terraform-google-modules/kubernetes-engine/google"
  version = "~> 20.0"
}

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

במודולים משותפים אסור להגדיר ספקים או קצוות עורפיים. במקום זאת, צריך להגדיר ספקים וקצוות עורפיים במודולים ברמה הבסיסית (root).

במודולים משותפים, צריך להגדיר את הגרסאות המינימליות הנדרשות למודולים של ספקים בבלוק required_providers, באופן הבא:

terraform {
  required_providers {
    google = {
      source  = "hashicorp/google"
      version = ">= 4.0.0"
    }
  }
}

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

חשיפת תוויות באמצעות משתנה

כדי לאפשר גמישות בהוספת משאבים דרך הממשק של המודול, מומלץ לספק את המשתנה labels עם מיפוי ריק כברירת מחדל, כמו בדוגמה הבאה:

variable "labels" {
  description = "A map of labels to apply to contained resources."
  default     = {}
  type        = "map"
}

חשיפת משתני הפלט של כל המשאבים

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

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

שימוש בתתי-מודולים בקוד ללוגיקה מורכבת

אתם יכולים להשתמש בתתי-מודולים בקוד כדי לחלק מודולים מורכבים של Terraform ליחידות קטנות יותר ולמנוע כפילויות של משאבים נפוצים.
המודולים בקוד צריכים להיות בתוך modules/$modulename.
יש להתייחס למודולים בתור קטעי קוד פרטיים, שלא נועדו לשימוש במודולים חיצוניים, אלא אם כן צוין אחרת במפורש במסמכים של המודול המשותף.
ב-Terraform אין מעקב אחרי משאבים שעברו ארגון מחדש של הקוד (Refactoring). אם אתם מתחילים עם כמה משאבים במודול של הרמה העליונה ולאחר מכן מעבירים אותם לתתי-מודולים, Terraform תנסה ליצור מחדש את כל המשאבים שעברו ארגון מחדש של הקוד. כדי למנוע את ההתנהגות הזו, יש להשתמש בבלוקים של moved כשמארגנים את הקוד מחדש.
משתני פלט שמוגדרים על ידי מודולים פנימיים לא נחשפים באופן אוטומטי. כדי לשתף משתני פלט ממודולים פנימיים, צריך לייצא אותם מחדש.

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