تعد أداة Terraform قوية (إن لم تكن الأقوى الآن) وواحدة من أكثر الأدوات استعمالاً لتوصيف البنى التحتية المعلوماتية باستعمال الكود (Infrastructure as code). تسمح هذه الأداة للمطورين بالقيام بالكثير من الوظائف ولا تمنعهم من فعل الأشياء بطرق يصعب دعمها أو التواصل معها.

بعض المعلومات في هذا الكتاب قد تبدو وكأنها لا تصنف كأفضل الممارسات. أعلم هذا. ولمساعدة القراء على التفريق بين ما يعد أفضل ممارسة أو ما هو مجرد طريقة أخرى لفعل الأشياء، فإني سأقوم باستعمال التلميحات (hints) في بعض الأحيان وتوفير الأيقونات لتحديد مستوى النضج في كل قسم فرعي يتعلق بأفضل الممارسات.

تم البدء بكتابة هذا الكتاب في مدريد في سنة 2018 وهو متوفر مجاناً على الرابط -

تم التعديل على هذا الكتاب بعد عدة سنين لإضافة أفضل الممارسات المتوفرة لإصدار Terraform 1.0 ، هذا الكتاب يجب أن يحتوي أفضل الممارسات والتوصيات الغير القابلة للجدل ليتم استعمالها من قبل مستخدمي الـ Terraform

الرعاة

الترجمات

اتصل بي إذا كنت تود المساعدة بالترجمة إلى لغات أخرى

المساهمات

أرغب دائمًا في الحصول على تعليقات وتحديثات لهذا الكتاب بينما ينضج المجتمع ويتم تنفيذ الأفكار الجديدة والتحقق منها بمرور الوقت.

المؤلفون

الترخيص

هذا العمل مرخص بموجب ترخيص Apache 2. انظر LICENSE للحصول على التفاصيل الكاملة.

لا يمكن للمؤلفين والمساهمين في هذا المحتوى ضمان صحة المعلومات الموجودة هنا. يرجى التأكد من أنك تفهم أن المعلومات المقدمة هنا يتم توفيرها بحرية ، وأنه لا يوجد أي نوع من الاتفاقية أو العقد بينك وبين أي أشخاص مرتبطين بهذا المحتوى أو المشروع. لا يتحمل المؤلفون والمساهمون ، وبموجب هذا ، أي مسؤولية تجاه أي طرف عن أي خسارة أو ضرر أو اضطراب ناتج عن أخطاء أو سهو في المعلومات الواردة في هذا المحتوى أو المرتبطة به أو المرتبطة به ، سواء كانت هذه الأخطاء أو الإغفالات ناتجة عن إهمال أو حادث أو أي سبب آخر.

حقوق النشر © 2018-2023 Anton Babenko.

يشرح هذا القسم المفاهيم الأساسية المستخدمة في الكتاب

المورد (Resource)

المورد هو aws_vpc، aws_db_instance الخ...، ينتمي المورد إلى موفر معين (provider) ويقبل الوسيطات (arguments) ويولد المخرجات (outputs) وله دورات حياة (lifecycles). يمكن إنشاء مورد واسترجاع معلوماته وتحديثه وحذفه.

وحدة الموارد (Resource module)

وحدة البنية التحتية (Infrastructure module)

وحدة البنية التحتية هي مجموعة وحدات موارد والتي قد لا تتربط منطقياً ولكنها توجد في مشروع أو نظام يخدم نفس الهدف. تعرف هذه الوحدة الـتهيئة (configuration) للموفرين (providers)، والتي تقوم بتمريرها إلى وحدات الموارد والموارد المؤلفة لهذه الوحدة. عادةً ما يقتصر العمل في وحدة بنية تحتية واحدة لكل كيان منفصل (على سبيل المثال ، AWS Region ، Google Project).

التركيب (Composition)

التركيب هو مجموعة من وحدات البنية التحتية والتي يمكن أن تمدد على العديد من المناطق المنفصلة (AWS Regions, AWS Accounts) . يتم استعمال التركيب لوصف كامل البنية التحتية لمؤسسة أو مشروع.

كما يبين الشكل يتألف تركيب البنية التحتية (infrastructure composition) من مجموعة وحدات بنية تحتية (infrastructure module) والتي تتكون من وحدات موارد (resources module) والتي تنجز عدة موارد محددة

مصدر البيانات (Data source)

يوفر مصدر البيانات مورداً قابلاً للقراءة فقط (read-only) ويعتمد على نمط الموفر (provider) الذي نتعامل معه، يتم استعماله من قبل كل من وحدة البنية التحتية ووحدة الموارد.

يعتبر مصدر البيانات terraform_remote_stateأداة لربط الوحدات عالية المستوى والتراكيب المختلفة مع بعضها

ملف الحالة المخرن عن بعد (Remote state)

الموفر (Provider, provisioner)

يوجد توصيف مجزي لمفهوم الموفر في وثائق Terraform الرسمية، ولا يوجد لازمة لتكرارها هنا، وبرأي أن ليس لها علاقة بكتابة وحدات Terraform جيدة.

أين الصعوبة؟

حتى نتمكن من الوصول إلى بيانات فإننا نستعمل مخرجات الوحدات (outputs) بالإضافة إلى مصادر البيانات (data sources)

وأخيراً يمكننا تمثيل المفاهيم المشروحة سابقاً بهذا الشكل

الأسئلة المتعلقة ببنية كود Terraform هي الأكثر شيوعًا في المجتمع. في الكثير من الأحيان فكر الجميع في أفضل بنية كود ممكن الحصول عليها للمشروع.

كيف يجب هيكلة مشروع Terraform؟

هذا نوع من الأسئلة التي يمكن الإجابة عليها بالعديد من الطرق ومن الصعب جداً تقديم نصيحة تنفع لجميع الحالات، لذلك لنبدأ بفهم ما نتعامل معه.

• ما هو مدى تعقيد مشروعك؟

  • عدد الموارد المرتبطة ببعضها

  • عدد الموفرين (انظر الملاحظة أدناه عن "logical providers")

• كم مرة تحتاج إلى تغيير في البنية التحتية؟

  • من مرة في الشهر/الأسبوع/اليوم؟

  • إلى تغيير مستمر (عند كل commit جديدة)

• مصادر تغيير الكود، هل تسمح لمخدم CI بتعديل repository عند بناء artifact جديدة؟

  • يسمح فقط للمطورين بإضافة تغييرات إلى repository الخاصة بالبنية التحتية

  • يسمح لأي أحد باقتراح تغيير من خلال فتح PR (متضمناً المهام الأتوماتيكية التي يقوم بها مخدم CI)

• ما هي المنصة أو الخدمة التي تستعملها لعملية deployment؟

  • AWS CodeDeploy, Kubernetes, OpenShift (يحتاج كل حل إلى معاملة مختلفة)

• كيف يتم فرز البيئات المختلفة؟

  • من خلال بيئة العمل(environment)، المنطقة (region)، المشروع (project)

مقدمة إلى هيكلة مشروع Terraform

عند بداية التعامل مع Terraform أو عندما تريد أن تكتب مثالاً فإن وضع كل الكود في ملف main.tf تعتبر فكرة جيدة، ولكن في كل الحالات الأخرى يجب تقسيم الكود منطقياً إلى ملفات مختلفة كالتالي:

• ملف main.tf, والذي يستدعي الوحدات المختلفة (modules), والوسطاء المحلية (locals)، ومصادر البيانات (data) لتوليد كافة الموارد (resources)

• ملف variables.tf، الذي يحتوي على تعريف للوسطاء (variables) المراد استعمالها فيmain.tf

• ملفoutputs.tf، الذي يعرف خرج الموارد المولدة من قبلmain.tf

• ملفversions.tf ، الذي يحتوي متطلبات الإصدار الخاصة بـ Terraform و الموفرين

كيف يجب أن نفكر عند هيكلة مشروع Terraform

التوصيات العامة لهيكلة الكود

• إنه من الأسهل والأسرع التعامل مع عدد قليل من الموارد

  • إن كل من تعليمتي terraform planوterraform apply تقوم باستدعاء cloud API للتحقق من حالة الموارد

  • إذا كانت كل بنيتك التحتية في تركيب واحد ستأخذ هذه التعليمات وقتاً طويلاً للتنفيذ

• مدى الضرر يكون أصغر في حال تعريف موارد قليلة

  • عزل الموارد غير المرتبطة ببعضها في تراكيب مختلفة يقلل الخطر في حال حدوث مشكلة ما

• استعمل ملف الحالة المخرن عن بعد

  • حاسبك الشخصي لا يمثل عكس لحقيقة البنية التحتية

  • إدارة tfstate في git أمر كارثي

  • لاحقاً عند توسع البنية في اتجاهات عدة (عدد الموارد وعدد dependencies)، سيكون استعمال هذا الملف أسهل للتحكم بهذه البنية

• تمرن على بنية وطرق تسمية متسقة

  • مثل الكود العادي، فإن كود Terraform يجب أن يكون مقروءاً، الاتساق سيساعد عندما تريد التحقق من تعديلات تمت إضافتها من 6 أشهر ماضية

  • من الممكن أن تنقل موارد لم يتم تعريفها سابقاً إلى ملف Terraform State، لكن وجود كود غير متسق سيصعب الأمر

• قم ببناء وحدة (modules) بسيطة قدر الإمكان

• لا تقم باستعمال قيم ثابتة (hardcoded) إذا كنت تستطيع تمريرها كمتحول أو الحصول عليها من مصدر بيانات

• استعمل مصادر البيانات و terraform_remote_state كغراء بين وحدات البنية التحتية في التركيب

في هذا المشروع قمنا بفرز المشروعات بحسب تعقيدها من البنى الصغيرة إلى الكبيرة جداً، لا يعتبر هذا التجميع ملزماً، لذا ابحث عن طرق أخرى أيضاً.

تنسيق وحدات وتركيبات البنى التحتية

وجود بنية تحتية صغيرة يعني وجود عدد صغير من الاعتماديات (dependencies) والموارد، كلما كبر المشروع فإن أهمية ربط البنى المختلفة وتمرير المتحولات في التركيب تصبح واضحة اكثر.

يوجد على الأقل 5 أدوات تنسيقات مستقلة التي يمكن للمطور أن يستعملها:

1. يكفي للمطور أن يستعمل Terraform

2. استعمال أداة Terragrunt، وهي أداة orchestration تستعمل لتنسيق كل البنية التحتية والاعتماديات، تعمل هذه الأداة مع مختلف الوحدات (modules) والتراكيب (compositions) لذلك تخفف من تكرار الكود (إعادة اختراع العجلة)

3. استعمال scripts خاصة بالشركة (In-house scripts)، تم استعمالها كبداية لعمليات التنسيق قبل صدور Terragrunt

4. استعمال أداة Ansible أو أي أداة أتمتة (Autoamtion tools) . يتم استعمالها في حال تم تبني Terraform بعد استعمال Ansible، أو في حال استعمال Ansible UI.

في هذا الكتاب نقوم فقط بعرض الحلين الأولين (Terraform only and Terragrunt.)

القواعد العامة

1. استعمل _ (underscore) بدلاً من - (dash) في كل مكان (أسماء الموراد، أسماء مصادر البيانات، أسماء المتحولات، أسماء المخرجات الخ..)

2. فضل استعمال الأحرف الصغيرة (lowercase) والأرقام فقط (حتى لو كان نظام UTF-8 مدعوماً)

أسماء الموراد ومصادر البيانات

1. لا تكرر نوع المورد في اسم المورد (ليس جزئيًا أو كليًا):

   resource "aws_route_table" "public" {}

   resource "aws_route_table" "public_route_table" {}

   resource "aws_route_table" "public_aws_route_table" {}

3. استخدم دائمًا الأسماء المفردة للتسمية.

4. استعمل - (dash) داخل قيم الوسيطات وفي الأماكن التي ستتعرض فيها القيمة للبشر (على سبيل المثال ، اسم DNS لخادم افتراضي RDS).

5. استعمل الوسيطان count / for_each داخل المورد أو داخل مصدر البيانات كأول وسيط وقم بإضافة سطر فارغ بعده

6. استعمل الوسيطtags إذا كان مدعوماً من قبل المورد كأخر وسيط متبوع بالوسيطاتdepends_on, lifecycleإذا احتجت إليها، كل منها مفصول عن الأخر بسطر فارغ.

7. عند استعمال شروط للوسيطان count / 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للمتحولات كما هو محدد في قسم "Argument Reference" للمورد الذي تعمل معه.

2. عملية التحقق (Validation) من المتحولات محدود نوعًا ما (على سبيل المثال ، لا يمكن الوصول إلى متحولات أخرى أو إجراء عمليات بحث). خطط وفقًا لذلك لأنه في كثير من الحالات تكون هذه الميزة غير مجدية.

3. استخدم صيغة الجمع في اسم متحول عند يكون نمطهlistأوmap.

4. قم بترتيب الأقسام في المتحول كالتالي:descriptionثمtypeثمdefaultوأخيراًvalidation

5. دائماً قم بإضافة قسمdescription إلى كل المتحولات حتى لو كنت تظن أنه واضح (ستحتاجه في المستقبل)

6. فضل استعمال الأنواع البسيطة (number, string, list(...), map(...), any) على الأنواع الأخرى مثلobject،إلا إذا كنت تحتاج قيود صارمة على كل key

7. استعمل الأنماط المحددة مثلmap(string) في حال كانت كل العناصر الموجودة داخلها من نفس النمط أو كان يمكن تحويلها إلى هذا النمط (مثلاً النمطnumberممكن تحويله إلى النمطstring)

8. استعمل النمط anyلتعطيل التحقق من النوع بدءاً من عمق معين أو عندما يجب دعم أنواع متعددة

9. القيمة {} هي عبارة عن map في بعض الأحيان وobject في أحيان أخرى. استعمل ()tomap لجعلها من النمط map دائماً.

أسماء المخرجات

اجعل المخرجات متسقة ومفهومة خارج سياقها ( عندما يتم استعمال وحدة من قبل مستخدم يجب على المخرجات أن تكون واضح ما هو نمط وما صفات القيمة التي ترجعها)

1. يجب على اسم الخرج أن يصف القيمة التي يرجعها وأن تكون أقل حرية مما تريد عادة.

2. الشكل الجيد لاسم الخرج يكون كالتالي {attribute}_{type}_{name} حيث:

   1. إن {name} هو اسم المورد أو اسم مصدر البيانات بدون اسم الموفر. كمثال للمورد aws_subnet يكون الاسم هوsubnetوللموردaws_vpc يكون vpc

   2. إن {type}هو نمط الخرج الئي نتعامل معه

   3. إن{attribute}هو الصفة المخرجة
5. دائماً قم بإضافة قسمdescription إلى كل المخرجات حتى لو كنت تظن أنه واضح

6. تجنب وضع وسيط sensitiveإلا إذا كنت تملك تحكم كامل باستعمال هذا الخرج في كل الأماكن في كل الوحدات

7. فضل استعمال ()try (متوفرة منذ الإصدار 0.13) على استعمال element(concat(...))(التي كانت تستعمل قبل 0.13)

أمثلة كود لأسماء المخرجات

تعيد على الأكثر Security group ID وحيد

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)
  

إذا كانت قيمة الخرج عبارة عن list فإنه يجب أن نستعمل اسم جمع :

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

التوثيق

التوثيق مولداً تلقائياً

مع ملفات Terraform يمكننا استعمال pre-commitلتنسيق الكود والتحقق منه بالإضافة إلى تعديل التوثيق

أداة terraform-docs

@todo: Document module versions, release, GH actions

الموراد

بنى الكود في Terraform

بنى الكود في Terragrunt

استعمل locals لتحديد الاعتماديات الصريحة بين الموارد

من الطرق المساعدة لإخبار Terraform أنه يجب حذف بعض الموارد حتى عندما لا يوجد اعتمادية مباشرة عليها

إصدار Terraform 0.12 - الوسيطات الإجبارية والاختيارية

1. الوسيط index_documentهو وسيط إجباري يجب تحديده، إذا كانتvar.websiteليستmapفارغة

2. الوسيط error_documentهو وسيط اختياري من الممكن عدم ذكره

يحتوي هذا المثال على كود لهيكلة كود Terraform لبنية تحتية صغيرة، حيث لا وجود لاعتمادات خارجية

يحتوي هذا المثال على كود لهيكلة كود Terraform لبنية تحتية متوسطة والتي تستعمل:

• حسابين AWS

• بيئتين مختلفتين (prod and stage لا وجود لشيء مشترك بينهما). كل بيئة موجودة في حساب AWS مختلف

• كل بيئة تستعمل الإصدار نفسه للوحدات الداخلية modules/network مصدره المجلد المحلي

يوجد أيضاً ورشة عمل للناس التي تريد أن تتمرن على الأشياء التي تعلمناها في هذا المرجع

يحتوي هذا المثال على كود لهيكلة كود Terraform لبنية تحتية كبيرة والتي تستعمل:

• حسابين AWS

• منطقتين

• بيئتين مختلفتين (prod and stage لا وجود لشيء مشترك بينهما). كل بيئة موجودة في حساب AWS مختلف وتوزع الموارد على المنطقتين

• كل بيئة تستعمل الإصدار نفسه للوحدات الداخلية modules/network مصدره المجلد المحلي

بث مباشر من قبل مؤلف هذه الكتاب. مراجعات، مقابلات، Q&A، جلسات تكويد وكل شيء عن الأداة

أخبار مختلفة عن عالم الأداة (مشاريع جديدة، إعلانات، نقاشات) ترسل إليك من قبل مؤلف الكتاب.

ما هي الأدوات التي يجب معرفتها واستخدامها؟

يجب تحديد إصدار الوحدة التي نتعامل معها. يجب تعريف الموفرات خارج الوحدات وفقط في التراكيب، يجب أيضاً تحديد إصدار الموفرات وإصدار Terraform أالذي نتعامل معه.