أساسيات Terraform

بنية HCL وأول الموارد

18 دقيقة الدرس 2 من 30

بنية HCL وأول الموارد

يعتمد Terraform كلياً على لغة HashiCorp للإعداد (HCL) — لغة تصريحية وسهلة القراءة، مُصمَّمة خصيصاً للبنية التحتية. قبل أن تكتب أي كود بنية تحتية ذي معنى، عليك استيعاب ثلاثة مفاهيم أساسية في HCL: الكتل (Blocks)، والوسيطات (Arguments)، والتعبيرات (Expressions). بمجرد فهم هذه المفاهيم، ستحتاج أيضاً إلى إتقان الأوامر الأربعة التي تشكّل سير عمل Terraform الجوهري: init، وplan، وapply، وdestroy. كل إجراء تتخذه في Terraform بالإنتاج هو تنويع على هذه الأساسيات.

الكتل والوسيطات والتعبيرات

كل شيء في ملف HCL هو كتلة (Block). تمتلك الكتلة نوعاً، وصفراً أو أكثر من التسميات، وجسماً محاطاً بقوسين معقوفين. داخل الجسم، تُسند قيماً إلى وسيطات (Arguments) مُسمّاة. يمكن أن تكون هذه القيم سلاسل نصية حرفية، أو أعداداً، أو قيماً منطقية، أو قوائم، أو خرائط، أو تعبيرات (Expressions) كاملة — مراجع لقيم أخرى، أو استدعاءات دوال، أو منطق شرطي.

# تشريح كتلة HCL:
#
#   block_type  "label_one"  "label_two"  {
#     argument_name = expression
#   }
#
# أمثلة ملموسة:

# كتلة "resource" بتسميتين: نوع المورد + الاسم المحلي
resource "aws_s3_bucket" "app_artifacts" {
  bucket = "mycompany-app-artifacts-${var.environment}"
  tags = {
    Team        = "platform"
    Environment = var.environment
    ManagedBy   = "terraform"
  }
}

# كتلة "variable" بتسمية واحدة: اسم المتغير
variable "environment" {
  type        = string
  description = "Deployment environment (dev, staging, prod)"
  default     = "dev"

  validation {
    condition     = contains(["dev", "staging", "prod"], var.environment)
    error_message = "environment must be dev, staging, or prod."
  }
}

# كتلة "locals" (بدون تسميات) لتجميع القيم المحسوبة
locals {
  bucket_name  = "mycompany-app-artifacts-${var.environment}"
  common_tags  = {
    ManagedBy   = "terraform"
    Environment = var.environment
  }
}

أنواع الكتل الأساسية التي ستستخدمها يومياً: terraform (قيود الإصدار وإعداد الـ backend)، وprovider (إعداد واجهة API السحابية)، وresource (الإعلان عن كائن بنية تحتية حقيقي)، وdata (قراءة بنية تحتية موجودة)، وvariable (قبول مُدخلات)، وoutput (كشف القيم)، وlocals (الحسابات الوسيطة)، وmodule (استدعاء وحدات قابلة لإعادة الاستخدام).

التعبيرات بالتفصيل

تعبيرات HCL أكثر قوة مما تبدو عليه. يمكنك الإشارة إلى أي سمة مورد، واستدعاء الدوال المدمجة، واستخدام الشرطية، والتكرار بتعبيرات for — كل ذلك داخل قيمة وسيطة.

# الإدراج في السلسلة النصية — ادمج أي تعبير داخل "${ }"
resource "aws_iam_role" "lambda_exec" {
  name = "lambda-exec-${var.environment}-${local.service_name}"

  # Heredoc للسلاسل متعددة الأسطر (شائع لسياسات JSON)
  assume_role_policy = <<-EOF
    {
      "Version": "2012-10-17",
      "Statement": [{
        "Action": "sts:AssumeRole",
        "Effect": "Allow",
        "Principal": { "Service": "lambda.amazonaws.com" }
      }]
    }
  EOF
}

# التعبير الشرطي: condition ? true_val : false_val
resource "aws_instance" "web" {
  instance_type = var.environment == "prod" ? "t3.medium" : "t3.micro"
  ami           = data.aws_ami.amazon_linux_2023.id

  # تعبير for لبناء قائمة من خريطة
  security_groups = [for sg in var.security_group_ids : sg if sg != ""]
}

# استدعاءات الدوال — يمتلك Terraform أكثر من 100 دالة مدمجة
locals {
  region_short = substr(var.aws_region, 0, 6)               # "us-eas"
  encoded      = base64encode(file("${path.module}/certs/ca.pem"))
  merged_tags  = merge(local.common_tags, { Role = "web" })
}

المراجع تتبع دائماً النمط type.name.attribute. مرجع مورد مثل aws_s3_bucket.app_artifacts.arn يُخبر Terraform بالبحث عن سمة arn لمورد aws_s3_bucket المُسمّى app_artifacts. هذا المرجع يُشفّر أيضاً تبعية ضمنية: لن ينشئ Terraform أي شيء يُشير إلى هذا الـ bucket حتى يتواجد الـ bucket نفسه. فهم هذا هو أساس الترتيب الصحيح للموارد.

سير العمل الجوهري: init، plan، apply، destroy

عمليات Terraform دائماً حتمية ويمكن التنبؤ بها عند اتباع سير العمل الرباعي. هذه ليست مجرد اقتراح — في الإنتاج، يجب ألا تشغّل apply أبداً دون مراجعة plan أولاً.

الأوامر الأربعة لسير عمل Terraform الجوهري. راجع دائماً ناتج plan قبل apply؛ لا تتخطَّ هذه الخطوة أبداً في الإنتاج.

إليك شرحاً تطبيقياً كاملاً. أنشئ مجلداً، واكتب مورداً أول، وشغّل الأوامر الأربعة:

# 1. إنشاء مشروع بسيط
mkdir tf-demo && cd tf-demo

# main.tf — يُعلن عن provider + حاوية S3 واحدة
cat > main.tf <<'EOF'
terraform {
  required_version = ">= 1.7"
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.0"
    }
  }
}

provider "aws" {
  region = "us-east-1"
}

resource "aws_s3_bucket" "demo" {
  bucket = "tf-demo-hcl-syntax-2025"

  tags = {
    Name      = "tf-demo"
    ManagedBy = "terraform"
  }
}

output "bucket_arn" {
  value       = aws_s3_bucket.demo.arn
  description = "ARN of the demo bucket"
}
EOF

# 2. Init — يُحمّل موفّر AWS (~20 MB)، يُهيئ .terraform/
terraform init

# 3. Plan — يُظهر بالضبط ما سيحدث. راجعه بعناية.
#    +  = إنشاء   ~  = تحديث في المكان   -  = حذف   -/+ = استبدال
terraform plan

# 4. Apply — يُنفّذ الخطة. يتطلب تأكيداً يدوياً ("yes")
terraform apply

# تخطّي التأكيد في CI (فقط بعد مراجعة الخطة وحفظها):
terraform plan -out=tfplan
terraform apply tfplan        # يُطبّق الخطة المحفوظة بالضبط، بدون موجه

# 5. Destroy — يُزيل كل ما يُديره Terraform في هذا workspace
#    لا تُشغّل هذا على الإنتاج أبداً دون مراجعة مفصّلة
terraform destroy

ما الذي يفعله `init` فعلياً

ينفّذ terraform init ثلاث مهام: يُحمّل إضافات المزود إلى .terraform/providers/، ويُهيئ الـ backend المُعدّ (محلي بشكل افتراضي — مجرد ملف terraform.tfstate)، ويُثبّت أي مصادر وحدات. يجب إعادة تشغيل init في أي وقت تُغيّر فيه إصدارات المزود، أو تُضيف مزوداً جديداً، أو تُغيّر إعداد الـ backend. ملف .terraform.lock.hcl الذي يُنشئه يُثبّت مجاميع اختبارية دقيقة للمزود — احفظ هذا الملف في Git حتى يستخدم كل عضو في الفريق وكل تشغيل CI إصدارات مزود متطابقة.

احفظ الخطط دائماً في CI. في الـ pipeline، لا تُشغّل أبداً terraform apply -auto-approve على خطة محسوبة حديثاً. النمط الصحيح هو: terraform plan -out=tfplan في مرحلة الخطة، احفظ أثر tfplan، ثم terraform apply tfplan في مرحلة التطبيق (محاطة بخطوة موافقة يدوية). هذا يضمن أن ما راجعته في الخطة هو بالضبط ما سيُطبَّق — لا ظروف تسابق إذا تغيّرت البنية التحتية بين المرحلتين.

قراءة ناتج Plan

ناتج plan هو أهم ناتج في كل Terraform. كل مهندس أول يقرأه كلمة بكلمة قبل الموافقة على apply. يُخبرك سطر الملخص بعدد الإجراءات (Plan: 3 to add, 1 to change, 0 to destroy)، لكن كتلة التفاصيل تُخبرك بما يتغيّر على كل سمة. الرمز ~ (تحديث) على سمة مورد آمن؛ أما -/+ (استبدال) فيعني أن المورد سيُحذف ويُعاد إنشاؤه، مما يُسبّب في الغالب توقفاً عن العمل إذا لم تكن حذراً.

الاستبدالات هي أخطر عملية في Terraform. عندما ترى -/+ resource "aws_db_instance" "main" (forces replacement)، سيحذف Terraform قاعدة البيانات ويُنشئ واحدة جديدة. البيانات القديمة ستختفي ما لم يكن لديك لقطة (snapshot). عدة تغييرات تفرض الاستبدال على الموارد الحيوية: إعادة تسمية نسخة RDS، أو تغيير إصدار المحرك لكلاستر ElastiCache، أو تعديل subnet_ids لكلاستر EKS. قبل تطبيق أي خطة تحتوي على استبدال، تحقق من وجود نسخة احتياطية وإجراء استعادة مُختبَر. في الإنتاج، استخدم lifecycle { prevent_destroy = true } على الموارد ذات الحالة لجعل Terraform يُصدر خطأً بدلاً من استبدالها بصمت.

اتفاقيات تنظيم الملفات

يقوم Terraform بتحميل جميع ملفات *.tf في المجلد كإعداد واحد. الاتفاقية المجتمعية — وما ستراه في كل وحدة مفتوحة المصدر — هي تقسيم الاهتمامات عبر ملفات مُسمّاة: main.tf للموارد، وvariables.tf لإعلانات المُدخلات، وoutputs.tf لإعلانات المُخرجات، وproviders.tf لكتل المزود و terraform، وlocals.tf لكتل القيم المحلية. لا يُفرض هذا من قِبَل الأداة، لكن مخالفة الاتفاقية ستجعل كودك غير مقروء لكل مبرمج Terraform آخر في فريقك.

في الدرس التالي، ستتعمق في المزودين والإصدارات — كيف يعمل الـ registry، وكيف تُثبّت إصدارات المزود وتُرقّيها بأمان، وكيف تُعدّ نسخاً متعددة من المزود (مناطق AWS متعددة، حسابات متعددة) في وحدة جذر واحدة.

بنية HCL وأول الموارد

بنية HCL وأول الموارد

الكتل والوسيطات والتعبيرات

التعبيرات بالتفصيل

سير العمل الجوهري: init، plan، apply، destroy

ما الذي يفعله init فعلياً

قراءة ناتج Plan

اتفاقيات تنظيم الملفات

ما الذي يفعله `init` فعلياً