מקור: https://github.com/antonbabenko/terraform-best-practices/tree/master/examples/small-terraform

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

Source: https://github.com/antonbabenko/terraform-best-practices/tree/master/examples/medium-terraform

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 a different version of the off-the-shelf infrastructure module (alb) sourced from Terraform Registry

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

מבני קוד של Terraform

Terragrunt code structures

Source:

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 a different version of the off-the-shelf infrastructure module (alb) sourced from

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

שאלות הקשורות למבנה של קוד 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 כבר בשימוש.

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

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

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

תיעוד

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

is a framework for managing and maintaining multi-language pre-commit hooks. It is written in Python and is a powerful tool to do something automatically on a developer's machine before code is committed to a git repository. Normally, it is used to run linters and format code (see ).

התוכנה pre-commit היא מסגרת בה אפשר לנהל ולתחזק hooks לשפות רבות. היא נכתבה בפייטון והיא כלי רב עוצמה לביצוע פעולות אוטומטיות במחשב של המפתח לפני שהקוד נכנס לgit. בדר״כ היא משומשת להרצת linters ועיצוב קוד. (ראו )

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

בדקו את מאגר למען היכרות עם הכלי וראו איך הוא כבר משומש במקומות אחרים כגון

terraform-docs

הכלי הוא כלי ליצירת תיעוד ממודולי Terraform בתבניות פלט שונות. את/ה יכול להריץ את זה ידנית (בלי pre-commit-hooks), או להריץ את זה עם על מנת לקבל תיעוד מעודכן באופן אוטומטי.

@todo: Document module versions, release, GH actions

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

הוא פרויטק חדש למדי (כמו רוב הכלים בחלל ה DevOps) שהחל ב2014.

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

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

הספר התחיל במדריד בשנת 2018, זמין בחינם בכתובת .

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

ספונסרים

Please if you want to become a sponsor.

תרגומים

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

תרומות

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

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

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

משאב

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

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

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

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

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

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

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

קומפוזיציה

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

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

מקור מידע

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

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

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

מצב מרוחק

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

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

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

למה כלכך קשה?

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

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

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

• Terragrunt - כלי אורקסטרציה

• tflint - סורק קוד

• tfenv - מנהל גרסאות

• Atlantis - אוטומציית Pull Request

• pre-commit-terraform - אוסף של git hooks עבור Terraform לשימוש עם פלטפורמת pre-commit framework

• Infracost - הערכת עלויות בענן עבור Terraform, עובד עם Terragrunt, Atlantis ו pre-commit-terraform.

מה הפתרונות עם 'גיהנום התלויות' עם מודלים?

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

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

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

התוכן כאן - https://github.com/antonbabenko/terraform-best-practices-workshop

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

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

https://raw.githubusercontent.com/antonbabenko/terraform-best-practices/master/snippets/locals.tf

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.

variable "website" {
  type    = map(string)
  default = {}
}

resource "aws_s3_bucket" "this" {
  # omitted...

  dynamic "website" {
    for_each = length(keys(var.website)) == 0 ? [] : [var.website]

    content {
      index_document = website.value.index_document
      error_document = lookup(website.value, "error_document", null)
    }
  }
}

website = {
  index_document = "index.html"
}

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

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" {}`

1. שם משאב צריך להיקרא this אם אין שם תיאורי וכללי זמין, לחלופין, אם מודול המשאב יוצר משאב יחיד מסוג זה (לדוגמה, במודול AWS VPC קיים משאב יחיד מסוג aws_nat_gateway ומשאבים מרובים של aws_route_table, לכן ל aws_nat_gateway להיקרא בשם this ו- aws_route_table לכלול שמות תיאוריים יותר - כגון private, public, database).

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.