Terraform State Locking: ليه مهندسَين بيشتغلوا سوا ممكن يدمّروا بنيتك التحتية

المستوى: متوسط — مناسب لو انت بتستخدم Terraform مع فريق وعندك backend على S3، وعايز تفهم قفل الحالة صح.

Terraform State Locking: ليه مهندسَين بيشتغلوا سوا ممكن يدمّروا بنيتك التحتية

لو مهندسَين في فريقك شغّلوا terraform apply في نفس اللحظة، ملف الحالة ممكن يتكتب نُصّه من الأول ونُصّه من التاني. النتيجة: موارد اتبنت مرتين، أو موارد موجودة فعلًا واختفت من الحالة فـ Terraform حاول يبنيها تاني. قفل الحالة بيمنع ده بسطر واحد في الإعداد. المقال ده هيوريك السطر، وليه بيشتغل، وإمتى تسيبه.

المشكلة باختصار

Terraform بيحتفظ بملف اسمه terraform.tfstate فيه خريطة بين اللي كتبته في الكود واللي اتبنى فعلًا في السحابة. الملف ده هو مصدر الحقيقة. لو اتنين كتبوا فيه في نفس الوقت، بيحصل اللي بيتسمى lost update: تعديل واحد بيدهس التاني، والحالة تبقى ناقصة أو متضاربة. المشكلة دي مش نظرية؛ بتحصل بالظبط لما الفريق يكبر وكل واحد بيـ apply من اللابتوب بتاعه أو من الـ CI في نفس الوقت.

مثال بسيط الأول: الكرّاسة والقلم الواحد

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

دلوقتي شيل القلم. الاتنين يكتبوا مع بعض على نفس السطر. سطر فوق سطر، وكلام ناقص. ده بالظبط اللي بيحصل لملف الحالة من غير قفل. القفل هو القلم الواحد: مهما كان عدد اللي عايزين يكتبوا، واحد بس بيمسك القلم في اللحظة، والباقي في الطابور.

يعني إيه "القفل" علميًا، وليه بيتكسر من غيره

عمليات الكتابة في Terraform (زي apply وplan بتحديث) بتاخد قفلًا على الحالة قبل ما تبدأ، وبتسيبه بعد ما تخلّص. القفل ده لازم يكون مركزيًا، يعني كل اللي بيشتغلوا على نفس الحالة يشوفوه. لو الحالة مخزّنة محليًا على جهازك، مفيش طريقة زميلك يعرف إنك ماسك القفل. عشان كده الفريق بيحط الحالة في remote backend زي S3، والقفل بيتدار هناك.

الافتراض هنا: انت عندك backend على S3 وفريق أكتر من واحد بيعمل apply. لو ده مش وضعك، القفل مش أولوية (هنرجع لدي في قسم "متى لا تحتاجه").

الحل: قفل الحالة على S3 بسطر واحد

قبل Terraform 1.10 كنت محتاج جدول DynamoDB منفصل عشان القفل. من الإصدار 1.10 بقى فيه قفل أصلي على S3 نفسها من غير أي خدمة زيادة، بتفعّله بخيار واحد اسمه use_lockfile. Terraform بيعمل ملف صغير اسمه <key>.tflock جوه نفس الـ bucket، ويستخدم conditional write (هيدر If-None-Match) عشان يضمن إن الملف يتكتب بس لو مش موجود — ودي عملية ذرّية بتحسم مين مسك القفل الأول.

terraform {
  backend "s3" {
    bucket       = "mycompany-tfstate"
    key          = "prod/network/terraform.tfstate"
    region       = "eu-central-1"
    encrypt      = true
    use_lockfile = true   # قفل S3 الأصلي — Terraform 1.10 وأحدث
  }
}

بعد ما تضيف السطر، فعّل الإعداد الجديد:

terraform init -reconfigure

لو لسه على إصدار أقدم من 1.10، الطريقة القديمة بـ DynamoDB لسه شغّالة: تضيف dynamodb_table = "tf-locks" بدل use_lockfile. لكن من 1.11 الحقل ده اتعمله deprecated ولصالح القفل الأصلي.

لما القفل يشتغل فعلًا: ده اللي هتشوفه

شغّل apply من تيرمينالين مع بعض. الأول بيمسك القفل ويكمّل. التاني بيلاقي إن ملف .tflock موجود، فالـ conditional write بيرجّع 412 PreconditionFailed، وTerraform بيوقفك برسالة واضحة:

Error: Error acquiring the state lock

Lock Info:
  ID:        3f8a1c22-9b40-4e11-8b6e-7c0f1d2a55e9
  Path:      prod/network/terraform.tfstate.tflock
  Operation: OperationTypeApply
  Who:       ahmed@laptop
  Created:   2026-07-22 09:14:02.51 +0000 UTC

ده سلوك صح مش خطأ: Terraform حماك من الكتابة المتوازية. تستنّى الأول يخلّص وتعيد المحاولة. أما لو عملية اتقتلت في النص (الـ CI اتقفل مثلًا) وسابت قفل معلّق، بتفكّه يدويًا بالـ ID الظاهر فوق:

terraform force-unlock 3f8a1c22-9b40-4e11-8b6e-7c0f1d2a55e9

خُد بالك: force-unlock سلاح خطير. استخدمه بس لما تكون متأكد 100% إن مفيش عملية شغّالة فعلًا، وإلا هترجع لنفس مشكلة الكتابة المتوازية.

الأرقام والـ trade-offs

التكلفة الحقيقية للقفل صغيرة: عملية PutObject واحدة زيادة لملف JSON حجمه بضع مئات من البايتات، بتضيف زمنًا في حدود عشرات المللي ثانية على كل apply (زمن طلب S3 نموذجي). ده رقم مايتحسّش جنب أي apply حقيقي بياخد ثوانٍ أو دقايق.

• بتكسب: استحالة عمليًا إن اتنين يكتبوا الحالة في نفس اللحظة، يعني صفر حالة متكسّرة بسبب التوازي.
• بتخسر: عمليات الكتابة على نفس الحالة بقت متسلسلة. لو عندك pipeline بيـ apply كتير على نفس الـ state، هيقفوا في طابور. الحل إنك تقسّم الحالة (state لكل مكوّن: شبكة، قاعدة بيانات، تطبيق) فالتزاحم يقل.
• الافتراض: S3 دلوقتي بتدعم الـ conditional writes في كل الأقاليم، فالقفل الأصلي شغّال من غير إعداد إضافي. لكنه يتطلب Terraform 1.10 على الأقل عند كل عضو في الفريق وفي الـ CI.

متى لا تحتاج كل ده

مش كل حالة محتاجة قفل remote:

• لو انت لوحدك وبتشتغل بحالة محلية فقط، Terraform بيقفل محليًا على أي حال، والقفل الموزّع زيادة مالهاش لزمة.
• لو كل مهندس/مكوّن عنده حالة منفصلة تمامًا، التزاحم نادر أصلًا.
• عمليات القراءة البحتة زي terraform output أو show مش بتكتب، فمش محتاجة قفل. تجنّب استخدام -lock=false إلا في قراءة مؤكدة، وممنوع نهائيًا مع apply.

الخطوة التالية

افتح ملف الـ backend بتاعك دلوقتي، أضف use_lockfile = true، وشغّل terraform init -reconfigure. بعدين افتح تيرمينالين وشغّل terraform apply في الاتنين في نفس الوقت على بيئة تجريبية. لو التاني وقف برسالة "Error acquiring the state lock"، يبقى القفل شغّال صح. لو الاتنين كمّلوا، يبقى الإعداد لسه مش متفعّل — راجع إصدار Terraform والـ init.

مصادر

• HashiCorp — S3 Backend (use_lockfile وإعداد القفل)
• HashiCorp — State Locking
• Terraform 1.10.0 Release Notes — إدخال القفل الأصلي على S3
• HashiCorp — Terraform State (ما هو ملف الحالة)