Loading…

حول منسق HCL / Terraform عبر الإنترنت

كل من Terraform و Packer وأدوات HashiCorp الأخرى تتحدث HCL2—وكلها تبدو أفضل عندما يتم تنسيقها بشكل متناسق. يرسل منسق HCL هذا التكوين الخاص بك إلى خلفية آمنة تطبق قواعد نمط terraform fmt على المسافات البادئة والتباعد والتخطيط، ثم يعيد HCL2 طبيعيًا مع ترك الدلالات دون تغيير.

الميزات الرئيسية

  • تنسيق واعٍ لـ HCL2 للكتل والسمات والقوائم/الخرائط ووثائق الوراثة بنمط Terraform
  • مسافات بادئة وتباعد متناسق حول = والفوارز والأقواس والكتل المتداخلة
  • يحافظ على التعليقات والأسطر الفارغة المقصودة حيثما أمكن لتحسين قابلية القراءة
  • يعمل مع ملفات .tf و .hcl و .tfvars القائمة على HCL وملفات Packer .pkr.hcl
  • ناتج ثابت: تشغيل المنسق مرة أخرى يعطي نفس النتيجة
  • مساحة سطحية دنيا: إجراء "تنسيق" واحد، بدون أزرار نمط للجدال حولها
  • نسخ أو تنزيل النتيجة المنسقة من المحرر بنقرة واحدة
  • معالجة مدعومة بالخادم عبر نقطة نهاية مؤمنة — رائع للإصلاحات السريعة؛ يُفضل استخدام CLI المحلي للكود شديد الحساسية

🔧 كيفية استخدام منسق HCL for hcl-formatter

1

1. الصق أو أسقط الكود الخاص بك

افتح ملف HCL/Terraform الخاص بك (.tf، .tfvars القائم على HCL، .hcl، .pkr.hcl، إلخ) والصق المحتويات في المحرر، أو أسقط الملف إذا كان متصفحك يدعم ذلك.

2

2. انقر على "تنسيق"

انقر على زر التنسيق. يتم إرسال التكوين الخاص بك إلى خلفية آمنة تطبق قواعد terraform fmt للنصوص، المسافات البادئة، والتباعد، ثم تعيد HCL2 المنسق.

3

3. راجع، انسخ أو حمّل

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

المواصفات الفنية

نموذج التنفيذ

المنسق مدعوم بخادم ومصمم لمحاكاة تطبيع تخطيط نمط terraform fmt لـ HCL2.

الجانبالتفاصيل
الوضعمدعوم بالخادم (بدون WASM في المتصفح)
النطاقالمسافات البيضاء، المسافة البادئة، التباعد، التخطيط الأساسي
إعادة الترتيبلا يوجد إعادة ترتيب دلالي للموارد أو الكتل
الخياراتلا شيء — إجراء تنسيق واحد لإخراج متوقع
الحدودحوالي 1-2 ميجابايت للإدخال، ~25 ثانية مهلة للخادم (قابلة للتعديل)
الاحتفاظمعالجة مؤقتة — يتم التخلص من الإدخال بعد التنسيق
كما هو الحال مع أي أداة عبر الإنترنت، تجنب لصق الأسرار الإنتاجية. استخدم terraform fmt أو packer fmt محليًا للكود الحساس.

تغطية اللغة

يفهم تركيبات HCL2 الشائعة المستخدمة عبر Terraform وأدوات HashiCorp الأخرى.

التركيبأمثلةملاحظات
الكتلresource, variable, output, module, locals, job, taskيتم الحفاظ على هيكل الكتل المتداخلة
السماتname = "web", count = 2يتم توحيد التباعد حول = وبين السمات
المجموعات[1, 2, 3], { key = value }تخطيط موحد للقوائم والخرائط/الكائنات
وثائق الوراثة<<-EOF ... EOFتم الحفاظ على العلامات؛ تم تطبيع المسافات البادئة حيثما أمكن
التعليقاتتعليقات بنمط # و //تم الاحتفاظ بها حيثما أمكن للحفاظ على النية والتوثيق

قبل/بعد مصغر

مثال صغير لتنظيف المسافات البادئة والتباعد في مورد Terraform.

# قبل
resource "aws_s3_bucket" "b"{bucket="demo"
  tags={Name="demo"}}

# بعد
resource "aws_s3_bucket" "b" {
  bucket = "demo"

  tags = {
    Name = "demo"
  }
}
تحويل التخطيط فقط: تبقى المعرفات والتعبيرات والمراجع دون تغيير.

الأخطاء والحالات الحدية

إذا فشل التنسيق أو أظهر خطأ، فعادة ما يكون ذلك بسبب مشاكل في تحليل إدخال HCL2.

العَرَضالسبب المحتملما يجب فحصه
لا يوجد مخرجات / خطأ في التحليلقوس أو قوس معقوف أو قوس هلالي غير مغلقعد أزواج { }، [ ]، ( ) المطابقة وأغلق جميع الكتل
مشاكل في وثائق الوراثةمحدد مفقود أو غير متطابقتأكد من ظهور علامات مثل EOF تمامًا وفي سطرها الخاص
أنماط مختلطةعلامات تبويب/مسافات أو أحرف شاردةطبيع المسافات البادئة، أزل أحرف التحكم الشاردة
ارتباك في ملفات .tfvarsJSON مقابل بناء جملة HCLاستخدم منسق JSON أو terraform fmt لملفات *.tfvars.json

بدائل سطر الأوامر

لتدفقات عمل البنية التحتية ككود اليومية، استخدم المنظمات الرسمية محليًا وفي CI، واحتفظ بهذه الأداة عبر الإنترنت للتنظيفات السريعة المؤقتة.

macOS / Linux

Terraform: تنسيق في المكان

terraform fmt

يعيد كتابة ملفات .tf وملفات .tfvars القائمة على HCL في الدليل الحالي.

Terraform: فحص متكرر لـ CI (بدون كتابة)

terraform fmt -check -recursive

يخرج برمز غير صفري إذا احتاج أي ملف إلى تنسيق - مثالي لـ CI وخطافات ما قبل الالتزام.

Packer: تنسيق القالب

packer fmt path/to/template.pkr.hcl

يُنسق ملف Packer HCL المحدد في مكانه.

ويندوز (PowerShell)

تنسيق جميع ملفات Terraform بشكل متكرر

Get-ChildItem -Recurse -Filter *.tf | ForEach-Object { terraform fmt $_.FullName }

تشغيل terraform fmt على كل ملف .tf تم العثور عليه تحت المجلد الحالي.

فحص التنسيق بأسلوب CI

terraform fmt -check -recursive

استخدم في خطوط أنابيب البناء للفشل عندما يكون التنسيق قديمًا.

إجراءات GitHub

فشل البناء إذا كان التنسيق مطلوبًا

steps:
  - uses: hashicorp/setup-terraform@v3
  - run: terraform fmt -check -recursive

إيقاف سير العمل عندما لا يكون أي ملف Terraform منسقًا بشكل صحيح.

التنسيق التلقائي في طلبات السحب (اختياري)

steps:
  - run: terraform fmt -recursive
  - run: git diff --quiet || (git config user.name "bot" && git config user.email "bot@example" && git commit -am "chore: terraform fmt" && git push)

يطبق terraform fmt ويدفع commit للتنسيق فقط إلى الفرع.

بالنسبة لرمز البنية التحتية المنظم أو السري، يُفضل استخدام أدوات CLI المحلية وتطبيق `terraform fmt -check -recursive` في CI بدلاً من إرسال الملفات إلى منسقات عبر الإنترنت.

التطبيقات العملية

نظافة طلبات السحب والمراجعات

توحيد المسافات البيضاء والمسافات البادئة حتى يتمكن المراجعون من التركيز على تغييرات البنية التحتية الفعلية.

  • تشغيل التنسيق قبل فتح طلب سحب
  • تقليل التعليقات المتعلقة بالأسلوب الدقيق في مراجعات Terraform
  • الحفاظ على اختلافات git صغيرة وذات معنى

تطوير وحدات Terraform

الحفاظ على اتساق الوحدات عبر الفرق والمستودعات والسجلات.

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

حراسة CI

استخدم فحوصات terraform fmt في CI لمنع انحراف النمط مع مرور الوقت.

  • إضافة `terraform fmt -check -recursive` كخطوة إلزامية في خط الأنابيب
  • منع عمليات الدمج حتى يتم تنسيق جميع ملفات .tf

الإدماج والتوثيق

الأمثلة القابلة للقراءة تساعد أعضاء الفريق الجدد على تعلم كل من Terraform والنمط المنزلي بسرعة.

  • نشر مقاطع منسقة بشكل متسق في ملفات README
  • استخدام أمثلة نظيفة في جلسات تدريب Terraform الداخلية

❓ Frequently Asked Questions

🔒هل تتم معالجة الكود محليًا؟

لا. منسق HCL هذا مدعوم بالخادم: يتم إرسال مدخلاتك إلى نقطة نهاية آمنة للتنسيق ويتم إرجاع HCL الناتج إلى متصفحك. بالنسبة لرمز البنية التحتية شديد الحساسية أو المنظم، يُفضل تشغيل `terraform fmt` (أو `packer fmt`) محليًا.

🛡️هل يمكنني لصق الأسرار هنا؟

نوصي بشدة بعدم لصق أسرار الإنتاج في أي أداة عبر الإنترنت. على الرغم من أن الخدمة مؤمنة ومصممة للمعالجة العابرة، يجب أن تبقى بيانات الاعتماد طويلة الأمد أو عالية الحساسية في الملفات المحلية أو مخازن الأسرار أو خزائن CI فقط — وليس في أدوات المتصفح.

🧩هل يغير التنسيق سلوك التكوين؟

لا. يركز المُنسق على التخطيط: المسافات البيضاء، المسافات البادئة والتباعد. تبقى كتل الموارد، الوسائط، التعبيرات والمراجع كما هي، بافتراض أن HCL الأصلي كان صالحًا.

📄هل يمكنني تنسيق ملفات .tfvars؟

نعم، طالما أن ملف .tfvars يستخدم بناء جملة HCL. يدعم Terraform أيضًا المتغيرات القائمة على JSON عبر `.tfvars.json`؛ تتبع تلك قواعد JSON ويُفضل معالجتها بواسطة مُنسق JSON أو بواسطة `terraform fmt` نفسه.

⚙️كيف يختلف هذا عن `terraform fmt`؟

`terraform fmt` هو المُنسق الرسمي المرفق مع Terraform وهو مثالي للتطوير المحلي وCI. تهدف هذه الأداة الويب إلى التنظيفات السريعة والعرضية عندما لا يكون CLI متاحًا لديك أو تريد ترتيب مقتطف صغير في المتصفح.

🧯لماذا فشل التنسيق؟

معظم حالات الفشل هي أخطاء في التحليل: أقواس أو معقوفات غير مغلقة، وثائق ميراث مشوهة، أو خلط tfvars بنمط JSON مع بناء جملة HCL. أصلح المشكلة الهيكلية (أو استخدم اللهجة/المنسق الصحيح) وحاول مرة أخرى.

Pro Tips

CI Tip

فرض `terraform fmt -check -recursive` في CI لمنع انحراف التنسيق عبر مستودعات البنية التحتية الكبيرة.

Best Practice

تجنب لصق الأسرار أو البيانات المتعلقة بالحالة في الأدوات عبر الإنترنت؛ حافظ على أمثلة التكوين مُنظفة وشغّل منسقات CLI المحلية لشفرة البنية التحتية الحقيقية.

Best Practice

وحّد الأسطر الجديدة الزائدة والمسافات البادئة في محررك حتى تنتج ملفات Terraform فروقات نظيفة ومستقرة عبر المنصات.

Best Practice

أضف خطاف pre-commit يشغل `terraform fmt` حتى تصل طلبات السحب مُنسقة مسبقًا ويمكن للمحادثات المراجعة أن تبقى مركزة على الهندسة والمخاطر.

Additional Resources

Terraform CLI: fmt
Documentation
نظرة عامة على لغة Terraform (HCL2)
Documentation
لغة تكوين HashiCorp (HCL) – GitHub
Documentation
Packer CLI: fmt
Documentation

Other Tools