قواعد التسمية

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

يجب ألا يكون هناك سبب لعدم اتباع هذه القواعد على الأقل :)

كن حذراً أن الموارد الحقيقية التي يتم تعريفها في Terraform غالباً ما يكون لها قيود على الأسماء المسموح بها. بعض الموارد كمثال لا تقبل الخطوط (dashes)، أو يجب أن يكون بعضها Camel-cased، القواعد في هذا الكتاب تشير إلى الأسماء المستخدمة في Terraform.

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

2. يجب تسمية المورد باسمthisإذا لم يكن هناك اسم وصفي وعام متاح، أو إذا كانت وحدة الموارد تنشئ موردًا واحدًا من هذا النوع (كمثال في AWS VPC module يوجد فقط مورد وحيد من النوعaws_nat_gateway وعدة موارد من النوع aws_route_table لذلك يجب تسمية المورد من نوعaws_nat_gateway باسم thisويجب أن نستعمل أسماء وصفية اكثر من أجل موارد النوع aws_route_table مثلprivate, public, database)

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

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

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

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

7. عند استعمال شروط للوسيطان count / for_eachففضل استعمال القيم المنطقية عوضاً عنlengthأو أي تعابير أخرى

أمثلة كود لأسماء المصادر

استعمال count / for_eachفي الكود

main.tf

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
}

main.tf

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

  # ... remaining arguments omitted
}

وضعية tagsفي الكود

main.tf

resource "aws_nat_gateway" "this" {
  count = 2

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

  tags = {
    Name = "..."
  }

  depends_on = [aws_internet_gateway.this]

  lifecycle {
    create_before_destroy = true
  }
}   

main.tf

resource "aws_nat_gateway" "this" {
  count = 2

  tags = "..."

  depends_on = [aws_internet_gateway.this]

  lifecycle {
    create_before_destroy = true
  }

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

استعمال الشروط في countفي الكود

outputs.tf

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}هو الصفة المخرجة

   4. انظر الأمثلة.
3. إذا كان الخرج يعيد قيمة مع استعمال interpolation functions وعدة موارد فيجب على {name} و{type} أن تكون معممة قدر الإمكان (this يجب حذفها)انظر الأمثلة
4. إذا كانت قيمة الخرج عبارة عن list فإنه يجب أن نستعمل اسم جمع انظر الأمثلة
5. دائماً قم بإضافة قسمdescription إلى كل المخرجات حتى لو كنت تظن أنه واضح

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

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

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

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

outputs.tf

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من الخرج:

outputs.tf

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 فإنه يجب أن نستعمل اسم جمع :

outputs.tf

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