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

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

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

ספונסרים

תרגומים

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

תרומות

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

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

מחברים

רישיון

This work is licensed under Apache 2 License. See LICENSE for full details.

The authors and contributors to this content cannot guarantee the validity of the information found here. Please make sure that you understand that the information provided here is being provided freely, and that no kind of agreement or contract is created between you and any persons associated with this content or project. The authors and contributors do not assume and hereby disclaim any liability to any party for any loss, damage, or disruption caused by errors or omissions in the information contained in, associated with, or linked from this content, whether such errors or omissions result from negligence, accident, or any other cause.

Copyright © 2018-2023 Anton Babenko.

מבני קוד של Terraform

Terragrunt code structures

עמוד זה מתאר מושגים מרכזיים המשמשים בתוך הספר.

משאב

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

מודולים של משאבים

מודול משאב הוא אוסף של משאבים מחוברים אשר יחד מבצעים את הפעולה המשותפת (לדוגמה, המודול AWS VPC Terrasform יוצר VPC, רשתות משנה, שער NAT וכדומה). הדבר תלוי בקונפיגורצית הספק, שניתן להגדירה בתוכה, או במבנים ברמה גבוהה יותר (למשל, במודל תשתית).

מודולים של תשתיות

מודול תשתית הוא אוסף של מודלי משאבים, שניתן לחבר באופן לא לוגי, אך במצב הנוכחי/בפרוייקט/בהגדרה משרתת את אותה המטרה. היא מגדירה את הקונפיגורציה עבור הספקים, המועברים למודולי המשאבים ולמשאבים עצמם. בדרך כלל, היא מוגבלת לעבודה בישות אחת לכל מפריד לוגי (לדוגמה, AWS Region, Google Project).

קומפוזיציה

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

הרכב מורכב ממודולי תשתית, הכוללים מודולי משאבים, אשר מיישמים משאבים בודדים.

מקור מידע

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

מקור מידע terraform_remote_state משמש כדבק עבור מודולים ורכיבים ברמה גבוהה יותר.

מקור המידע http הופך בקשת get HTTP לכתובת ה- URL הנתונה, ומיצא מידע אודות התגובה, אשר שימושית לעתים קרובות לקבלת מידע מנקודות קצה שבהן ספק Terraform אינו קיים.

מצב מרוחק

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

ספק, מקצה משאבים, וכו׳

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

למה כלכך קשה?

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

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

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

תיעוד

ייצור תיעוד באופן אוטומטי

עם קופניגורציית Terraform pre-commit יכול להיות משומש לעיצוב, ובדיקת תקינות הקוד וגם למען יצירת תיעוד.

terraform-docs

@todo: Document module versions, release, GH actions

קישוריים חיצוניים

This example contains code as an example of structuring Terraform configurations for a medium-size infrastructure which uses:

• 2 AWS accounts

• 2 separate environments (prod and stage which share nothing). Each environment lives in a separate AWS account

• Each environment uses the same version of an internal module modules/network since it is sourced from a local directory.

מהם הכלים שעליכם להיות מודעים אליהם ולשקול להשתמש בהם

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

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

השתמש ב locals כדי לציין תלות מפורשת בין משאבים

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

Terraform 0.12 - ארגומנטים נדרשים לעומת אופציונליים

1. Required argument index_document must be set, if var.website is not an empty map.

2. Optional argument error_document can be omitted.

יש גם סדנה לאנשים שרוצים לתרגל חלק מהדברים המתוארים במדריך.

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

כיצד עלי לבנות את קונפיגורצית הTerraform שלי?

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

• מהי מורכבות הפרוייקט?

  • מספר המשאבים

  • מספר ה Terraform providers (ראה הערה אודות ״ספקים לוגיים״)

• באיזו תדירות התשתית שלך משתנה?

  • מ פעם בחודש/שבוע/יום

  • עד ברציפות (בכל פעם שיש גרסה/קוד חדש)

• מאתחלי שינוי קוד? האם לאפשר לשרת ה CI לעדכן את ה repoistory כאשר גרסה חדשה נבנת?

  • רק מפתחים יכולים לדחוף ל repoistory התשתיות

  • כולם יכולים להציע שינוי לכל דבר על-ידי פתיחת PR (כולל משימות אוטומטיות בשרת ה- CI)

• באיזו פלטפורמת פריסה או שירות פריסה אתה משתמש?

  • AWS CodeDeploy, Kubernetes, או OpenShift דורשים גישה קצת שונה

• איך סביבות קשורות אחת לשניה?

  • על פי סביבת עבודה, אזור פריסה, פרוייקט

תחילת העבודה עם בניית Terraform configurations

הצבת כל הקוד ב main.tf הוא רעיון טוב בתחילת העבודה או בעת כתיבת קוד לדוגמה. בכל המקרים האחרים, יהיה עליכם לפצל לכמה קבצים באופן לוגי:

• main.tf - משתמשים במודולים, הגדרות משתנים מקומיות, ומקורות נתונים כדי ליצור את כל המשאבים

• variables.tf - מכיל הצהרות של משתנים המשמשים ב main.tf

• outputs.tf - מכיל פלט מהמשאבים שנוצרו בmain.tf

• versions.tf - כולל את דרישות הגרסה של Terraform ושאר הספקים.

terraform.tfvars - אין להשתמש מלבד בקומפוזציה

כיצד לחשוב על מבנה הקוד של Terraform?

המלצות נפוצות לעיצוב הקוד

• קל ומהיר יותר לעבוד עם מספר מצומצם של משאבים בכל תיקיית הרצה

  • terraform plan ו terraform apply מבצעים קריאות API  בענן כדי לאמת את מצב המשאבים.

  • אם התשתית כולה רשומה בקובץ (או תיקייה) אחת, זמן הפריסה יתארך גם לשינויים קטנים בשל הצורך באימות

• רדיוס הסכנה (במקרה של פירצות אבטחה) קטן יותר כאשר יש פחות משאבים

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

• התחילו את הפרוייקט במצב של שמירת ה״מצב״ במקום מרוחק

  • הלפטופ שלכם הוא לא מקום לשמור ולאמת את התשתית שלכם

  • ניהול קבצי ״מצב״ בגיט זה סיוט

  • בשלב מאוחר יותר, כאשר התשתית תתחיל להתרחב לכיוונים שונים (מספר התלויות של משאבים) יהיה קל יותר לשלוט על חלוקת המשאבים

• תרגלו מוסכמת מתן שמות ומבנה קוד עקבי

  • בדומה לקוד פרוצדורלי, מולמץ לרשום את הקוד בצורה שבה קודם כל אנשים יבינו את מה שנעשה, עקביות תעזור כאשר יהיה צורך לבצי שינויים בעוד שישה חודשים.

  • ניתן להעביר משאבים בין קבצי מצב, אך ייתכן שיהיה קשה יותר לעשות אם יש מבנה שמות לא עקבי

• שמור על מודולי משאבים פשוטים ככל האפשר

• אל תכתבו ״ערכים קשיחים״ אל תוך המודולים כאשר אפשר להשיג אותם כמשתנה או מתוך מקור נתונים אחר

• השתמשו במקורות נתונים (data resources) וב terraform_remote_state כדבק בין מודולי תשתית מורכבים בקומפוזיציה

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

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

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

יש לפחות 5 קבוצות שונות של פתרונות אורכיסטרציה שבהם מפתחים משתמשים:

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

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

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

4. Ansible או כלי אוטומציה שונים. משומש בדרך כלל כאשר השימוש ב Terraform נעשה אחרי השימוש באנסיבל, או כאשר Ansible UI כבר בשימוש.

ספר זה סוקר את שני הדרכים הראשונות, Terraform only ו Terragrunt.

ראו דוגמאות של מבני קוד עבור Terraform ו Terragrunt בפרק הבא.

קונבנציות כלליות

1. השתמש ב- _ (מקף תחתון) במקום - (מקף) בכל מקום (בשמות משאבים, בשמות מקורות נתונים, בשמות משתנים, בפלט וכו').

2. עדיף להשתמש באותיות קטנות ובמספרים (למרות ש- UTF-8 נתמך).

ארגומנטים של משאב ומקורות נתונים

1. אל תחזורו על סוג המשאב בשם המשאב (לא באופן חלקי או מלא):

`resource "aws_route_table" "public" {}`

`resource "aws_route_table" "public_route_table" {}`

`resource "aws_route_table" "public_aws_route_table" {}`

2. השתמשו תמיד בשמות עצם (יחיד) עבור שמות.

3. השתמש ב - בתוך ערכי ארגומנטים ובמקומות שבהם הערך ייחשף לבני אדם (לדוגמה, בתוך שם DNS של RDS).

4. הארגומנטיים count / for_each מומלץ שיבואו כארגומנטים ראשונים בתוך משאבים ויופרדו בשורה חדשה משאר ההגדרות.

5. האגומנט tags מומלץ שיבוא אחרון, מיד אחרי lifecycles ושיפורד בשורה ריקה בין שאר המשאבים

6. בעת שימוש בתנאים ב- argumentcount / for_each עדיף להשתמש בערכים בוליאניים במקום להשתמש length או בביטויים אחרים.

דוגמאות לקוד של משאב

שימוש ב count / for_each

resource "aws_route_table" "public" {
  count = 2

  vpc_id = "vpc-12345678"
  # ... remaining arguments omitted
}

resource "aws_route_table" "private" {
  for_each = toset(["one", "two"])

  vpc_id = "vpc-12345678"
  # ... remaining arguments omitted
}

resource "aws_route_table" "public" {
  vpc_id = "vpc-12345678"
  count  = 2

  # ... remaining arguments omitted
}

מיקום של tags

resource "aws_nat_gateway" "this" {
  count = 2

  allocation_id = "..."
  subnet_id     = "..."

  tags = {
    Name = "..."
  }

  depends_on = [aws_internet_gateway.this]

  lifecycle {
    create_before_destroy = true
  }
}   

resource "aws_nat_gateway" "this" {
  count = 2

  tags = "..."

  depends_on = [aws_internet_gateway.this]

  lifecycle {
    create_before_destroy = true
  }

  allocation_id = "..."
  subnet_id     = "..."
}

תנאים ב count

resource "aws_nat_gateway" "that" {    # Best
  count = var.create_public_subnets ? 1 : 0
}

resource "aws_nat_gateway" "this" {    # Good
  count = length(var.public_subnets) > 0 ? 1 : 0
}

משתנים

1. אל תמציא מחדש את הגלגל במודולי המשאבים: name, description, ו default עבור משתנים, כפי שמוגדר בסעיף "הפניה לארגומנט" עבור המשאב שאיתו אתה עובד.

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

3. השתמשו בצורת שם עצם רבים כאשר סוג המשתנה הוא list(...) או map(...).

4. סדרו את ה keys בבלוק משתנה כך: description , type, default, validation.

5. כללו תמיד תיאור בכל המשתנים גם אם אתם סבורים שזה ברור מאליו (תזדקקו לו בעתיד).

6. העדפו שימוש בסוגים פשוטים (מספר, מחרוזת, רשימה(...), מפה(...), any) על-פני סוג ספציפי כגון אובייקט(), אלא אם כן עליכם לכלול אילוצים מחמירים על כל key.

7. השתמש בסוגים ספציפיים כגון map(map(string)) אם לכל רכיבי המפה יש סוג זהה (לדוגמה מחרוזת) או ניתן להמיר אותה אליה (לדוגמה, מספר ניתן להמרה למחרוזת).

8. השתמשו בסוג any כדי לנטרל את אימות הסוג כאשר יש לתמוך בסוגים מרובים.

9. הערך {} הוא לעתים מפה, אך לעתים אובייקט. השתמשו ב- tomap(...) כדי ליצור מפה כיוון שאין דרך ליצור אובייקט.

פלט

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

1. שם הפלט צריך לתאר את המאפיין שהוא מכיל.

2. מבנה טוב לשם הפלט נראה כך {name}_{type}_{attribute}

   1. {name}הוא שם משאב או מקור נתונים ללא קידומת ספק. {name} של aws_subnet יהיה subnet, בשבילaws_vpc זה vpc.

   2. {type} הוא סוג המשאב

   3. {attribute} הוא תכונה המוחזרת על-ידי הפלט
4. אם הפלט מחזיר ערך עם פונקציות אינטרפולציה ומשאבים מרובים, {name} ו- {type} צריכים להיות כלליים ככל האפשר (יש להשמיט קידומת זו).

5. אם הערך המוחזר הוא רשימה, עליו להיות לו שם עצם רבים.

6. כלול תמיד תיאור עבור כל התוצרים גם אם אתה סבור שזה ברור מאליו.

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

8. העדיפו try() (זמין מאז terraform 0.13) על concat(...13)

דוגמאות קוד output

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

output "security_group_id" {
  description = "The ID of the security group"
  value       = try(aws_security_group.this[0].id, aws_security_group.name_prefix[0].id, "")
}

כאשר יש משאבים מרובים מאותו סוג, יש להשמיט this בשם הפלט:

output "this_security_group_id" {
  description = "The ID of the security group"
  value       = element(concat(coalescelist(aws_security_group.this.*.id, aws_security_group.web.*.id), [""]), 0)
}

השתמש בשם עצם רבים אם הערך המוחזר הוא רשימה

output "rds_cluster_instance_endpoints" {
  description = "A list of all cluster instance endpoints"
  value       = aws_rds_cluster_instance.this.*.endpoint
}

This example contains code as an example of structuring Terraform configurations for a large-size infrastructure which uses:

• 2 AWS accounts

• 2 regions

• 2 separate environments (prod and stage which share nothing). Each environment lives in a separate AWS account and span resources between 2 regions

• Each environment uses the same version of an internal module modules/network since it is sourced from a local directory.