دليل Terragrunt السريع

التثبيت

منصة	أمر
macOS (Homebrew)	`brew install terragrunt`
Linux (Binary)	`wget https://github.com/gruntwork-io/terragrunt/releases/download/v0.54.0/terragrunt_linux_amd64 && chmod +x terragrunt_linux_amd64 && sudo mv terragrunt_linux_amd64 /usr/local/bin/terragrunt`
Windows (Chocolatey)	`choco install terragrunt`
Windows (Scoop)	`scoop install terragrunt`
Docker	`docker pull alpine/terragrunt:latest`
Version Manager (tgenv)	`git clone https://github.com/cunymatthieu/tgenv.git ~/.tgenv && tgenv install latest`
From Source (Go 1.21+)	`git clone https://github.com/gruntwork-io/terragrunt.git && cd terragrunt && go install`
Verify Installation	`terragrunt --version`

الأوامر الأساسية

أمر	وصف
`terragrunt init`	قم بتهيئة Terraform مع تكوين الخلفية المُدار تلقائيًا
`terragrunt plan`	قم بإنشاء وعرض خطة التنفيذ للتغييرات البنية التحتية
`terragrunt apply`	قم بتطبيق التغييرات على البنية التحتية (مع طلب التأكيد)
`terragrunt apply -auto-approve`	تطبيق التغييرات دون تأكيد تفاعلي
`terragrunt destroy`	تدمير جميع موارد البنية التحتية المُدارة
`terragrunt destroy -auto-approve`	تدمير الموارد بدون مطالبة تأكيد
`terragrunt validate`	تحقق من صحة بناء جملة تكوين Terragrunt و Terraform
`terragrunt fmt`	قم بتنسيق ملفات تكوين Terraform إلى النمط القانوني
`terragrunt fmt -recursive`	Recursively format all `.tf` files in subdirectories
`terragrunt output`	عرض جميع قيم المخرجات من الحالة
`terragrunt output <name>`	Display specific output value (e.g., `terragrunt output vpc_id`)
`terragrunt output -json`	عرض المخرجات بتنسيق JSON للتحليل
`terragrunt show`	عرض الحالة الحالية أو الخطة المحفوظة بتنسيق يمكن قراءته بواسطة الإنسان
`terragrunt console`	افتح وحدة التحكم التفاعلية لاختبار التعبيرات
`terragrunt refresh`	قم بتحديث ملف الحالة مع الحالة الفعلية للبنية التحتية
`terragrunt state list`	قم بسرد جميع الموارد المتتبعة في ملف الحالة
`terragrunt state show <resource>`	عرض معلومات الحالة التفصيلية للمورد المحدد
`terragrunt workspace list`	قائمة جميع مساحات العمل المتاحة
`terragrunt workspace select <name>`	التبديل إلى مساحة العمل المحددة
`terragrunt workspace new <name>`	إنشاء والتبديل إلى مساحة عمل جديدة

الاستخدام المتقدم

أمر	وصف
`terragrunt run-all plan`	نفذ الخطة عبر جميع الوحدات حسب ترتيب الاعتمادية
`terragrunt run-all apply`	قم بتطبيق التغييرات على جميع الوحدات مع مراعاة التبعيات
`terragrunt run-all destroy`	دمر جميع الوحدات بترتيب التبعية العكسي
`terragrunt run-all init`	قم بتهيئة جميع الوحدات في شجرة الدليل
`terragrunt run-all validate`	تحقق من جميع إعدادات الوحدة
`terragrunt run-all output`	عرض المخرجات من جميع الوحدات
`terragrunt graph-dependencies`	إنشاء وعرض مخطط اعتماديات الوحدة
`terragrunt render-json`	قم بتحويل التكوين النهائي إلى JSON للفحص
`terragrunt hclfmt`	Format `terragrunt.hcl` configuration files
`terragrunt state mv <source> <dest>`	نقل المورد إلى عنوان مختلف في الحالة
`terragrunt state rm <resource>`	قم بإزالة المورد من الحالة دون تدميره
`terragrunt import <address> <id>`	استيراد البنية التحتية الموجودة إلى حالة Terraform
`terragrunt taint <resource>`	علّم المورد للترفيه عند التطبيق التالي
`terragrunt untaint <resource>`	إزالة علامة التلوث من المورد
`terragrunt plan -out=tfplan`	احفظ خطة التنفيذ في ملف للتطبيق لاحقًا
`terragrunt apply tfplan`	تطبيق ملف الخطة المحفوظ مسبقًا
`terragrunt plan --terragrunt-log-level debug`	قم بتشغيل الخطة مع تسجيل تفصيلي للتصحيح
`terragrunt run-all apply --terragrunt-parallelism 3`	قيّد تنفيذ الوحدات المتوازية إلى 3 عمليات متزامنة
`terragrunt apply --terragrunt-source ../local-module`	تجاوز مصدر الوحدة للتطوير/الاختبار المحلي
`terragrunt run-all apply --terragrunt-include-dir vpc`	نفّذ فقط على مجلدات وحدات محددة
`terragrunt run-all apply --terragrunt-exclude-dir legacy`	استبعاد دلائل محددة من التنفيذ
`terragrunt apply --terragrunt-include-external-dependencies`	قم بتضمين التبعيات الخارجية في التنفيذ
`terragrunt init -reconfigure`	إعادة تكوين backend، مع تجاهل التكوين الحالي
`terragrunt init -upgrade`	قم بترقية إضافات المزود إلى أحدث الإصدارات المسموح بها
`terragrunt state pull > terraform.tfstate`	قم بتنزيل وحفظ الحالة البعيدة محليًا

الإعدادات

الهيكل الأساسي لـ terragrunt.hcl

# Include root configuration
include "root" {
  path = find_in_parent_folders()
}

# Configure Terraform source
terraform {
  source = "git::https://github.com/org/terraform-modules.git//vpc?ref=v1.0.0"
}

# Define inputs (variables)
inputs = {
  environment    = "production"
  vpc_cidr       = "10.0.0.0/16"
  instance_type  = "t3.medium"
}

إعداد الحالة البعيدة (الجذر terragrunt.hcl)

# Configure remote state backend
remote_state {
  backend = "s3"
  
  generate = {
    path      = "backend.tf"
    if_exists = "overwrite_terragrunt"
  }
  
  config = {
    bucket         = "my-terraform-state-${get_aws_account_id()}"
    key            = "${path_relative_to_include()}/terraform.tfstate"
    region         = "us-east-1"
    encrypt        = true
    dynamodb_table = "terraform-locks"
  }
}

إعداد التبعيات

# Define dependencies between modules
dependency "vpc" {
  config_path = "../vpc"
  
  # Mock outputs for validation without dependencies applied
  mock_outputs = {
    vpc_id = "vpc-temporary-id"
  }
  
  mock_outputs_allowed_terraform_commands = ["validate", "plan"]
}

# Use dependency outputs
inputs = {
  vpc_id = dependency.vpc.outputs.vpc_id
  subnet_ids = dependency.vpc.outputs.private_subnet_ids
}

توليد إعدادات المزود

# Auto-generate provider configuration
generate "provider" {
  path      = "provider.tf"
  if_exists = "overwrite_terragrunt"
  
  contents = <<EOF
provider "aws" {
  region = "us-east-1"
  
  default_tags {
    tags = {
      Environment = "${local.environment}"
      ManagedBy   = "Terragrunt"
    }
  }
}
EOF
}

المحليات والدوال

# Define local variables
locals {
  environment = "production"
  region      = "us-east-1"
  
  # Parse environment from path
  parsed_path = regex(".*/environments/(?P<env>.*?)/.*", get_terragrunt_dir())
  env_name    = local.parsed_path.env
  
  # Common tags
  common_tags = {
    Environment = local.environment
    ManagedBy   = "Terragrunt"
    Project     = "MyProject"
  }
}

# Use locals in inputs
inputs = merge(
  local.common_tags,
  {
    region = local.region
  }
)

إعدادات الخطافات

# Execute commands before/after Terraform operations
terraform {
  before_hook "before_init" {
    commands = ["init"]
    execute  = ["echo", "Initializing Terraform..."]
  }
  
  after_hook "after_apply" {
    commands     = ["apply"]
    execute      = ["./scripts/notify-slack.sh"]
    run_on_error = false
  }
}

حالات الاستخدام الشائعة

حالة الاستخدام 1: إعداد البنية التحتية متعددة البيئات

# Directory structure:
# └── environments/
#     ├── terragrunt.hcl (root config)
#     ├── dev/
#     │   ├── vpc/terragrunt.hcl
#     │   └── app/terragrunt.hcl
#     └── prod/
#         ├── vpc/terragrunt.hcl
#         └── app/terragrunt.hcl

# Deploy entire dev environment
cd environments/dev
terragrunt run-all apply

# Deploy only VPC in production
cd environments/prod/vpc
terragrunt apply

# Plan all production changes
cd environments/prod
terragrunt run-all plan

حالة الاستخدام 2: إدارة تبعيات الوحدات

# In app/terragrunt.hcl, reference VPC dependency:
# dependency "vpc" {
#   config_path = "../vpc"
# }

# Apply app module (automatically applies VPC first if needed)
cd environments/dev/app
terragrunt apply --terragrunt-include-external-dependencies

# View dependency graph
cd environments/dev
terragrunt graph-dependencies | dot -Tpng > dependencies.png

حالة الاستخدام 3: تطوير الوحدات المحلية

# Override module source to test local changes
cd environments/dev/vpc
terragrunt plan --terragrunt-source ../../../modules/vpc-local

# Apply with local module
terragrunt apply --terragrunt-source ../../../modules/vpc-local

# Reset to remote source
terragrunt plan --terragrunt-source-update

حالة الاستخدام 4: إدارة الحالة والترحيل

# List all resources in state
terragrunt state list

# Move resource to new address
terragrunt state mv aws_instance.old aws_instance.new

# Import existing AWS resource
terragrunt import aws_instance.web i-1234567890abcdef0

# Remove resource from state (keeps actual resource)
terragrunt state rm aws_instance.temporary

# Pull remote state for inspection
terragrunt state pull > backup.tfstate

حالة الاستخدام 5: التصحيح واستكشاف الأخطاء

# Enable debug logging
export TERRAGRUNT_LOG_LEVEL=debug
terragrunt plan

# Run with trace-level logging
terragrunt apply --terragrunt-log-level trace 2>&1 | tee debug.log

# Validate all configurations
terragrunt run-all validate

# Check formatting issues
terragrunt hclfmt --terragrunt-check

# Test configuration rendering
terragrunt render-json | jq '.'

أفضل الممارسات

استخدم مبدأ DRY: احتفظ بإعداد الخلفية في الجذرterragrunt.hclوقم بتضمينه في الوحدات الفرعية باستخدامincludeكتل لتجنب التكرار
قم بإصدار وحداتك: قم دائمًا بتثبيت مصادر الوحدات على إصدارات أو علامات محددة (مثل?ref=v1.0.0) لضمان نشر قابل للتكرار
نفذ إدارة التبعيات: استخدمdependencyكتل لتحديد العلاقات بين الوحدات بشكل صريح بدلاً من الاعتماد على ترتيب التنفيذ اليدوي
استفد من المحليات والدوال: استخدم الدوال المدمجة في Terragrunt مثلfind_in_parent_folders(), get_aws_account_id(), and path_relative_to_include() for dynamic configuration
Use mock outputs: Define mock_outputs in dependency blocks to enable validation and planning without requiring all dependencies to be applied first
Organize by environment: Structure directories by environment (dev/staging/prod) with shared configuration at the root level for consistency
Enable state locking: Always configure DynamoDB tables for state locking when using S3 backend to prevent concurrent modification conflicts
Use run-all carefully: Test with run-all plan before run-all apply and consider using --terragrunt-parallelism to control concurrent executions
Generate provider configs: Use generate blocks to create provider configurations dynamically, ensuring consistency across modules
Implement hooks for automation: Use before_hook and after_hook to automate tasks like validation, notifications, or compliance checks

Troubleshooting

مشكلة	حل
Error: “No Terraform configuration files”	Ensure `terraform.source` is correctly specified in `terragrunt.hcl` and the source path exists. Run `terragrunt init` to download modules.
Backend initialization fails	Check AWS credentials and permissions. Verify S3 bucket and DynamoDB table exist or set `skip_bucket_creation = false` in remote_state config.
Dependency outputs not found	Ensure dependency module is applied first. Use `mock_outputs` for planning without dependencies. Check `config_path` points to correct directory.
”Working directory already exists” error	Clear Terragrunt cache: `rm -rf .terragrunt-cache` then run `terragrunt init` again. Or use `--terragrunt-source-update` flag.
Module source not updating	Force source update with `terragrunt init --terragrunt-source-update` or delete `.terragrunt-cache` directory to clear cached modules.
State lock acquisition timeout	عملية أخرى تحتفظ بالقفل. انتظر الإكمال أو قم بإطلاق القفل يدويًا في جدول DynamoDB. تحقق من العمليات المتعطلة.
”Module not found” with relative paths	Use `find_in_parent_folders()` to locate root config. Ensure relative paths account for Terragrunt’s working directory structure.
Run-all commands fail partially	Check individual module errors with `--terragrunt-log-level debug`. Verify dependencies are correctly defined. Use `--terragrunt-ignore-dependency-errors` cautiously.
Permission denied errors on AWS	Verify IAM role/user has required permissions. Check if `role_arn` in provider config is correct. Ensure MFA token is valid if required.
Circular dependency detected	Review `dependency` blocks to identify circular references. Restructure modules to break the cycle. Use `terragrunt graph-dependencies` to visualize.
Variables not being passed correctly	Check `inputs` block syntax in `terragrunt.hcl`. Verify variable names match module definitions. Use `terragrunt render-json` to inspect final config.
Performance issues with many modules	Adjust `--terragrunt-parallelism` to optimize concurrent executions. Consider splitting into smaller module groups. Use `--terragrunt-include-dir` for selective runs.

Quick Reference: Terragrunt vs Terraform Commands

أمر Terragrunt	Terraform مكافئ	الفرق الرئيسي
`terragrunt init`	`terraform init`	Auto-configures backend from `terragrunt.hcl`
`terragrunt plan`	`terraform plan`	يتضمن مدخلات واعتمادات يديرها Terragrunt
`terragrunt apply`	`terraform apply`	يعالج التبعيات ويولد التكوينات
`terragrunt run-all apply`	I apologize, but there is no text provided to translate. Could you please share the specific English text you would like me to translate to Arabic?	يُنفّذ عبر وحدات متعددة مع ترتيب الاعتمادية
`terragrunt output`	`terraform output`	يمكن تجميع المخرجات من وحدات متعددة