بعد أن نقل الفريق حالة OpenTofu إلى خلفية مشتركة مقفلة، كما شرحنا في ملف الحالة State في OpenTofu، جاء الطلب التالي الذي يأتي لكل فريق في وقت ما: نريد بيئة اختبار Staging تشبه الإنتاج، نجرب فيها التغيير قبل أن يصل إلى العملاء. والحل الأسرع، وهو ما فعله الفريق فعلاً، أن تنسخ مجلد الإنتاج إلى مجلد جديد، وتغير الأسماء وعدد السيرفرات، وتطبق. وبعد شهرين توقف أحد سيرفرات الإنتاج بعد إعادة تشغيل Docker ولم يعد وحده، فأضاف أحد الزملاء سياسة إعادة التشغيل restart = "unless-stopped" في ملف الإنتاج وطبق، ولم يتذكر أحد أن يضيفها في ملف الاختبار. وبعد شهر آخر جرب فريق الاختبار سيناريو إعادة تشغيل السيرفر في بيئة الاختبار، فنجح الاختبار بطريقة مختلفة تماماً عما يحدث في الإنتاج، لأن البيئتين لم تعودا نسختين من الشيء نفسه.
وهذه هي المشكلة التي جاءت الوحدات Modules لتحلها: أن تكتب شكل الخدمة مرة واحدة، ثم تستدعيه من كل بيئة بقيمها، فإذا أصلحت شيئاً في الوحدة وصل الإصلاح إلى كل البيئات في الخطة التالية. ولكن الوحدات تأتي معها أسئلة جديدة: كيف تقسم المجلدات، وكيف تنقل الموارد الموجودة إلى داخل الوحدة دون أن تحذفها، وكيف تصدر نسخة جديدة من الوحدة دون أن تفاجئ كل البيئات في يوم واحد، وكيف تختبرها قبل أن يستخدمها أحد. وفي هذا المقال نشغل كل ذلك فعلاً على مختبر يعمل على جهازك، كما في المقالات السابقة من أول بنية مع OpenTofu، ونقرأ كل ما تطبعه الأداة، بما في ذلك إعادة هيكلة حذفت كل سيرفرات الإنتاج في المختبر. وسوف نناقش في هذا المقال ما يلي:
- لماذا ينسخ الفريق المجلد، وما الذي يختلف بين النسختين بعد شهرين.
- ما هي الوحدة، والفرق بين الوحدة الجذرية Root Module والوحدة الفرعية Child Module، ومدخلاتها ومخرجاتها.
- بناء وحدة لسيرفرات الويب بمدخلات تتحقق من نفسها، ووحدة Reverse Proxy تقرأ مخرجات الأولى.
- تنظيم المجلدات: بيئة في مجلد، وحالة لكل بيئة، ولماذا لا نستخدم مساحات العمل Workspaces لفصل البيئات.
- مشكلة حقيقية: نقل الموارد إلى الوحدة حذف السيرفرات، وكيف تمنعه كتل
moved. countمعfor_each، واستبدال ال Reverse Proxy دون انقطاع بقياس حقيقي.- إصدارات الوحدات من Git، ومشكلتان ظهرتا عند التحديث، واختبار الوحدة بالأمر
tofu test.
لماذا ينسخ الفريق المجلد؟ Copy-Paste Environments
لنبدأ من حيث بدأ الفريق، فعندنا مجلدان، envs/staging وenvs/prod، وفي كل منهما ملف main.tf فيه شبكة خاصة، وال Image، وسيرفرات ويب من ال Image nginx:1.29.3-alpine، والاختلاف المقصود بينهما في الأسماء وفي العدد: سيرفر واحد في الاختبار، وثلاثة في الإنتاج. وشغلنا OpenTofu 1.13.2 من ال Image الصغيرة نفسها التي بنيناها في المقالات السابقة، مع مزود kreuzwerker/docker بالإصدار 4.6.0، وطبقنا الاثنين، ثم قارنا الملفين بالأمر diff:
1c1
< # Flat version: everything for this environment in one file (the original)
---
> # Flat version: everything for this environment in one file (copied from staging)
3c3
< name = "wr-iac-staging"
---
> name = "wr-iac-prod"
12,13c12,13
< count = 1
< name = "wr-iac-staging-web-${count.index + 1}"
---
> count = 3
< name = "wr-iac-prod-web-${count.index + 1}"
14a15
> restart = "unless-stopped"
21c22
< value = "staging"
---
> value = "prod"في المخرج أعلاه لاحظ أن كل الفروق متوقعة ما عدا واحداً، وهو السطر 14a15، أي أن ملف الإنتاج فيه سطر إضافي بعد السطر 14 لا يوجد في ملف الاختبار، وهو سياسة إعادة التشغيل. وهذا السطر هو الإصلاح الذي أضافه الزميل، وهو الفرق الذي لم يقصده أحد. والمشكلة أن هذا الفرق يضيع بين الفروق المقصودة، فعندما يكون عندك عشرة فروق بين بيئتين، تسعة منها أسماء وأعداد، فلن ينتبه أحد للعاشر. ومع الوقت تصبح المقارنة نفسها مستحيلة، لأن كل بيئة تأخذ إصلاحات في أوقات مختلفة، ويصبح سؤال «هل الاختبار يشبه الإنتاج؟» سؤالاً لا يستطيع أحد أن يجيب عنه دون أن يقرأ الملفين سطراً بسطر.
وقد تقول إن المراجعة في طلب الدمج يجب أن تكتشف ذلك، ولكن طلب الدمج الذي أضاف السطر كان يغير ملف الإنتاج فقط، فلم يكن أمام المراجع ملف الاختبار أصلاً، ولا يوجد شيء في الأداة يقول إن هذين الملفين يجب أن يبقيا متطابقين. وهذا يشبه تماماً ما يحدث في كود التطبيقات عندما تنسخ دالة إلى مكانين بدلاً من أن تستدعيها، والحل هو نفسه: أن تكتب الشيء مرة واحدة، وأن تجعل الاختلاف الوحيد بين البيئتين في القيم التي تمررها له.
ما هي الوحدة Module في OpenTofu؟
الوحدة في OpenTofu هي ببساطة مجلد فيه ملفات .tf، وهذا يعني أنك كنت تستخدم الوحدات من أول يوم دون أن تعرف، فالمجلد الذي تشغل فيه tofu plan هو الوحدة الجذرية Root Module، كما في وثائق الوحدات. وعندما تكتب في هذا المجلد كتلة module تشير إلى مجلد آخر، يصبح المجلد الآخر وحدة فرعية Child Module، وتقرأ الأداة ملفاته وتضيف موارده إلى الخطة نفسها والحالة نفسها، ولكن تحت عنوان يبدأ باسم الوحدة، مثل module.web.docker_container.this[0].
وأقرب تشبيه للوحدة هو الدالة في البرمجة: المتغيرات variable هي المعاملات التي تأخذها الدالة، والمخرجات output هي ما ترجعه، والموارد داخلها هي جسم الدالة الذي لا يراه من يستدعيها. والقاعدة المهمة هنا أن الوحدة لا ترى شيئاً من خارجها إلا ما تمرره لها، فلا تستطيع أن تقرأ مورداً في الوحدة الجذرية مباشرة، ولا تستطيع الوحدة الجذرية أن تقرأ مورداً داخل الوحدة إلا عبر مخرجاتها. وهذا الحد هو بالضبط ما يجعل الوحدة قابلة لإعادة الاستخدام، لأنها لا تعتمد على أي شيء لم تعلنه في مدخلاتها.
والمصادر التي تأتي منها الوحدة كثيرة، فقد تكون مجلداً محلياً بمسار يبدأ بـ ./ أو ../، أو مستودع Git بإصدار محدد، أو سجل وحدات Registry مثل سجل OpenTofu العام، أو أرشيفاً على HTTP، كما في وثائق مصادر الوحدات. وسوف نبدأ بالمسار المحلي لأنه الأبسط، ثم ننتقل إلى Git عندما نتحدث عن الإصدارات.
بناء وحدة لسيرفرات الويب: Inputs مع Validation
أنشأنا مجلداً اسمه modules/web، ونقلنا إليه الموارد الثلاثة التي كانت في ملف البيئة، مع تحويل كل ما يختلف بين البيئات إلى متغير. وهذا ملف المتغيرات، وهو أهم ملف في الوحدة لأنه العقد بينها وبين من يستخدمها:
variable "env" {
description = "Environment name, used in every resource name"
type = string
validation {
condition = can(regex("^[a-z][a-z0-9-]{1,15}$", var.env))
error_message = "env must be lowercase letters, digits or '-', 2 to 16 characters."
}
}
variable "replicas" {
description = "How many web containers"
type = number
default = 1
validation {
condition = var.replicas >= 1 && var.replicas <= 10
error_message = "replicas must be between 1 and 10."
}
}
variable "image" {
description = "Web image with a pinned tag"
type = string
validation {
condition = can(regex(":[0-9][^:]*$", var.image))
error_message = "image must have a pinned version tag such as nginx:1.29.3-alpine, not latest or no tag."
}
}
variable "restart" {
description = "Docker restart policy"
type = string
default = "unless-stopped"
}في الإعداد أعلاه لاحظ التالي:
- كل متغير له نوع
typeووصفdescription، والوصف ليس للزينة، فهو أول ما يقرؤه زميلك عندما يستخدم الوحدة بعد سنة، ويظهر في أدوات توليد الوثائق. - كتل
validationهي قواعد تتحقق منها الأداة قبل أن تبدأ أي خطة، كما في وثائق المتغيرات. فالوحدة لا تقبل عدداً من السيرفرات أقل من 1 أو أكثر من 10، ولا تقبل Image بلا رقم إصدار. والفكرة هنا أن تضع القواعد التي تعلمها الفريق من أخطائه داخل الوحدة نفسها، فلا يحتاج كل مراجع أن يتذكرها. - المتغير
restartله قيمة افتراضية هي الإصلاح الذي أضافه الزميل في الإنتاج، فأصبح الإصلاح جزءاً من الوحدة، وكل بيئة تأخذه دون أن تطلبه، وإذا احتاجت بيئة قيمة أخرى مررتها صراحة. - لا يوجد متغير للشبكة ولا لل Image ID، لأن الوحدة تنشئهما بنفسها، فالقاعدة أن تجعل المدخلات ما يختلف فعلاً بين البيئات، وليس كل خاصية في كل مورد، وإلا أصبحت الوحدة نسخة من المزود بأسماء أخرى.
أما ملف الموارد فهو الموارد نفسها التي كانت في ملف البيئة، مع الأسماء من المتغيرات، واسم this لكل مورد لأن الوحدة فيها مورد واحد من كل نوع:
resource "docker_network" "this" {
name = "wr-iac-${var.env}"
}
resource "docker_image" "this" {
name = var.image
keep_locally = true
}
resource "docker_container" "this" {
count = var.replicas
name = "wr-iac-${var.env}-web-${count.index + 1}"
image = docker_image.this.image_id
restart = var.restart
networks_advanced {
name = docker_network.this.name
}
labels {
label = "env"
value = var.env
}
}ثم المخرجات، وهي ما تعطيه الوحدة لمن يستدعيها، وهنا نحتاج اثنين: اسم الشبكة، وأسماء السيرفرات، لأن الوحدة التالية سوف تحتاجهما:
output "network_name" {
description = "Network the web containers are on"
value = docker_network.this.name
}
output "container_names" {
description = "Names of the web containers (also their DNS names on the network)"
value = docker_container.this[*].name
}والمخرجات مثل المدخلات جزء من العقد، فكل مخرج تضيفه سوف يعتمد عليه أحد يوماً، وإذا حذفته أو غيرت شكله، مثل أن يصبح خريطة بدلاً من قائمة، توقفت خطة كل بيئة تقرؤه. لذلك لا تقم بإخراج المورد كله، مثل value = docker_container.this، لمجرد أنه أسهل، وإنما أخرج القيم التي يحتاجها غيرك بالاسم، وإذا كان المخرج سراً، مثل كلمة مرور تولدها الوحدة، فعلمه sensitive = true حتى لا يطبع في مخرج الخطة الذي يراه كل من يفتح صفحة الخط.
ولاحظ ملف versions.tf في الوحدة، فهو يختلف عن ملف البيئة في شيء مهم:
terraform {
required_version = "~> 1.13"
required_providers {
docker = {
source = "kreuzwerker/docker"
version = ">= 4.6.0, < 5.0.0"
}
}
}الوحدة تحدد مدى من الإصدارات وليس رقماً واحداً، والسبب أن الوحدة تستخدم في بيئات كثيرة، وكل بيئة تثبت رقمها الكامل في ملفها وفي ملف القفل، فإذا ثبتت الوحدة رقماً واحداً فلن تستطيع أي بيئة أن تحدث المزود قبل أن تصدر نسخة جديدة من الوحدة. لذلك القاعدة المعتادة: الوحدة تقول «أعمل مع هذا المدى»، والبيئة تقول «أستخدم هذا الرقم بالضبط»، وكتلة provider نفسها لا توضع في الوحدة، وإنما في البيئة، كما في وثائق المزودات داخل الوحدات، لأن البيئة هي التي تعرف أين يتصل المزود وبأي مفتاح.
ماذا لو مرر أحد قيمة خاطئة؟ Validation Errors
جربنا أن نستدعي الوحدة من بيئة الاختبار بقيمتين خاطئتين: صفر سيرفرات، وال Image nginx:latest:
Error: Invalid value for variable
on main.tf line 5, in module "web":
5: replicas = 0
├────────────────
│ var.replicas is 0
replicas must be between 1 and 10.
This was checked by the validation rule at
../../modules/web/variables.tf:14,3-13.
Error: Invalid value for variable
on main.tf line 6, in module "web":
6: image = "nginx:latest"
├────────────────
│ var.image is "nginx:latest"
image must have a pinned version tag such as nginx:1.29.3-alpine, not latest
or no tag.
This was checked by the validation rule at
../../modules/web/variables.tf:23,3-13.في المخرج أعلاه لاحظ أن الأداة طبعت الخطأين معاً ولم تتوقف عند الأول، وأن كل خطأ يشير إلى مكانين: السطر الذي مرر القيمة في البيئة، والسطر الذي فيه القاعدة داخل الوحدة، فالشخص الذي أخطأ يعرف ماذا يصلح، والشخص الذي يريد أن يعرف لماذا هذه القاعدة يعرف أين يقرأ. ولاحظ أن رسالة الخطأ هي التي كتبناها نحن في error_message، لذلك اكتبها كما تكتب رسالة لزميل، واذكر فيها مثالاً صحيحاً، فالرسالة «invalid image» لا تساعد أحداً.
وحدة ثانية تقرأ مخرجات الأولى: Module Composition
سيرفرات الويب تحتاج إلى شيء أمامها يوزع الطلبات عليها، فكتبنا وحدة ثانية اسمها modules/proxy تنشئ Reverse Proxy من nginx، وتبني ملف إعداده من قائمة السيرفرات. والقالب Template الذي يبني الإعداد صغير:
upstream web {
%{ for u in upstreams ~}
server ${u}:80;
%{ endfor ~}
}
server {
listen 80;
location / {
proxy_pass http://web;
add_header X-Upstream $upstream_addr;
}
}والدالة templatefile تقرأ هذا الملف وتضع فيه قائمة السيرفرات، كما في وثائق الدالة templatefile، والسطر add_header X-Upstream يضيف إلى كل رد ترويسة فيها عنوان السيرفر الذي خدم الطلب، حتى نتحقق من التوزيع. ثم أصبح ملف بيئة الإنتاج كله استدعاء للوحدتين:
module "web" {
source = "../../modules/web"
env = "prod"
replicas = 3
image = "nginx:1.29.3-alpine"
}
module "proxy" {
source = "../../modules/proxy"
env = "prod"
network = module.web.network_name
upstreams = module.web.container_names
}
output "proxy" {
value = module.proxy.name
}في الإعداد أعلاه لاحظ أن الوحدتين لا تعرفان بعضهما، فوحدة ال Proxy لا تعرف أن هناك وحدة اسمها web، وإنما تأخذ شبكة وقائمة أسماء، والذي يربطهما هو ملف البيئة، عندما يمرر module.web.container_names إلى upstreams. وهذا الربط هو نفسه الاعتمادية التي رأيناها في المقال الأول بين السيرفر وسجل DNS، فالأداة تعرف أن ال Proxy يجب أن ينشأ بعد السيرفرات، وأن زيادة السيرفرات تعني تغيير إعداد ال Proxy. وهذا ما تسميه الوثائق تركيب الوحدات Module Composition، وتنصح في صفحة تركيب الوحدات بأن تبقى الوحدات مسطحة بهذا الشكل، أي أن تستدعيها البيئة كلها مباشرة وتمرر المخرجات بينها، بدلاً من أن تستدعي وحدة وحدة أخرى بداخلها، والسبب أن العلاقات تبقى ظاهرة في ملف واحد تقرؤه.
وعندما شغلنا tofu init في البيئة ظهر سطر جديد لم يكن في المشاريع السابقة:
Initializing the backend...
Initializing modules...
- proxy in ../../modules/proxy
- web in ../../modules/webالأداة تجهز الوحدات قبل المزودات، والوحدات المحلية لا تنسخ، وإنما تقرأ من مكانها مباشرة، لذلك أي تعديل في modules/web يظهر في خطة كل بيئة دون أن تشغل init من جديد، وهذا مريح أثناء التطوير، وخطير في الإنتاج كما سوف نرى في قسم الإصدارات.
تنظيم المجلدات Project Layout: بيئة في مجلد
هذا هو الشكل الذي وصل إليه المشروع، وهو الشكل الذي تستخدمه أغلب الفرق الصغيرة والمتوسطة:
infra/
├── modules/
│ ├── web/ # network + image + web containers
│ │ ├── main.tf
│ │ ├── variables.tf
│ │ ├── outputs.tf
│ │ ├── versions.tf # provider range, no provider block
│ │ └── tests/web.tftest.hcl
│ └── proxy/ # nginx in front of the web containers
│ ├── main.tf
│ ├── nginx.conf.tftpl
│ └── ...
└── envs/
├── staging/ # one root module = one state
│ ├── main.tf # calls the modules with staging values
│ ├── versions.tf # exact provider version + provider block
│ └── .terraform.lock.hcl
└── prod/
└── ...
والقاعدة الأهم في هذا الشكل أن كل مجلد تحت envs/ وحدة جذرية مستقلة لها حالتها الخاصة، فإذا كنت تستخدم خلفية مشتركة فلكل بيئة مسار مختلف، مثل shop/staging/terraform.tfstate وshop/prod/terraform.tfstate كما ذكرنا في مقال الحالة. وفائدة هذا الفصل كبيرة: الخطة في الاختبار لا تستطيع أن تلمس مورداً في الإنتاج، لأن الإنتاج غير موجود في حالتها أصلاً، وتستطيع أن تعطي مفتاح الاختبار لكل المطورين وتبقي مفتاح الإنتاج عند خط CI/CD وحده، وخطأ في تطبيق الاختبار لا يقفل حالة الإنتاج.
وقد يتساءل البعض: لماذا لا نستخدم مساحات العمل Workspaces في OpenTofu، فهي تعطي حالة لكل اسم من المجلد نفسه بالأمر tofu workspace new staging؟ والإجابة أن مساحات العمل تشترك في الكود نفسه والخلفية نفسها والمفاتيح نفسها، والفرق الوحيد بينها هو اسم المساحة، فلا تستطيع أن تعطي بيئة إصداراً مختلفاً من الوحدة لتجربه قبل الأخرى، ولا تستطيع أن تفصل الصلاحيات، والأخطر أن البيئة التي تطبق عليها تحددها حالة في جهازك لا تظهر في الكود، فيكفي أن ينسى أحد أن يبدل المساحة ليطبق تغيير الاختبار على الإنتاج. وتقول وثائق مساحات العمل نفسها إنها لا تناسب فصل البيئات التي تحتاج إلى صلاحيات منفصلة، لذلك المجلد لكل بيئة هو الخيار الأوضح، والتكرار الوحيد فيه هو ملف صغير يستدعي الوحدات، وهذا تكرار مقصود لأنه يحمل الفرق بين البيئات.
عندما تحتاج بيئة شيئاً من مشروع آخر: Remote State أم Data Source؟
بعد فترة يكبر المشروع، فيقرر الفريق أن الشبكات وسجلات DNS المشتركة يجب أن تكون في مشروع خاص بها، يديره شخصان فقط، لأن خطأ فيه يوقف كل الخدمات، بينما تبقى خدمات الويب في مشروع آخر يغيره الجميع كل يوم. وهنا يظهر سؤال: كيف يعرف مشروع الويب اسم الشبكة التي أنشأها مشروع الشبكات؟ والطريقة التي يجدها الجميع أولاً هي مصدر البيانات terraform_remote_state، فهو يقرأ مخرجات مشروع آخر من حالته مباشرة. وهذه الطريقة تعمل، ولكن فيها مشكلة لا تظهر في الوثائق المختصرة: لكي تقرأ مخرجات الحالة يجب أن تقرأ الحالة كلها، أي أن مشروع الويب يحتاج إلى صلاحية قراءة حالة الشبكات بكل ما فيها، ومنها الأسرار كما رأينا في مقال الحالة، وإذا كانت الحالة مشفرة فهو يحتاج إلى مفتاح التشفير أيضاً. أي أنك فصلت المشروعين لتفصل الصلاحيات، ثم أعدت دمج الصلاحيات من الباب الخلفي.
والبديل الأنظف أن يسأل مشروع الويب المزود نفسه عن الشيء الذي يحتاجه، بمصدر بيانات Data Source من المزود، مثل data "docker_network" باسم الشبكة، أو مصدر البيانات الذي يقرأ سجلات DNS أو الشبكات الافتراضية عند مزودك السحابي. وبهذا يحتاج مشروع الويب إلى صلاحية قراءة الشبكة فقط، ولا يعرف شيئاً عن حالة المشروع الآخر ولا عن الأداة التي أنشأتها، فإذا نقل فريق الشبكات مشروعه يوماً إلى أداة أخرى أو إلى حالة أخرى، لم يتغير شيء عند فريق الويب. والقاعدة التي نستخدمها: داخل المشروع الواحد مرر المخرجات بين الوحدات كما فعلنا مع web وproxy، وبين المشاريع اسأل المزود بمصدر بيانات، واترك terraform_remote_state للحالات التي لا يوجد فيها مصدر بيانات للشيء الذي تحتاجه.
ولاحظ أن العنوان الكامل لكل مورد داخل الوحدة، مثل module.web.docker_container.this[0]، هو ما يظهر في الخطة وفي الحالة وفي أوامر مثل tofu state show وtofu import، فإذا استوردت مورداً إلى وحدة كتبت عنوانه كاملاً بهذا الشكل. وإذا احتاجت وحدة أن تنتظر وحدة أخرى لا تقرأ منها أي قيمة، فتستطيع أن تكتب depends_on = [module.web] في استدعائها، ولكن استخدمها قليلاً، لأنها تجعل كل موارد الوحدة تنتظر كل موارد الأخرى، وتجعل الأداة تعتبر كثيراً من القيم مجهولة حتى التطبيق، فتظهر في الخطة (known after apply) في أماكن لم تكن تتوقعها. والأفضل دائماً أن تمرر قيمة حقيقية بين الوحدتين، فالاعتمادية تأتي من القيمة وحدها كما رأيت.
مشكلة حقيقية: إعادة الهيكلة حذفت الإنتاج Refactoring
الآن جاء وقت نقل البيئات الموجودة إلى الوحدات، وهنا وقعنا في الخطأ الذي يقع فيه أغلب الفرق في أول مرة. فقد استبدلنا ملف الإنتاج القديم باستدعاء الوحدتين كما في القسم السابق، وشغلنا tofu init، ثم طلبنا الخطة:
# docker_container.web[0] will be destroyed
# (because docker_container.web is not in configuration)
# docker_container.web[1] will be destroyed
# (because docker_container.web is not in configuration)
# docker_container.web[2] will be destroyed
# (because docker_container.web is not in configuration)
# docker_image.web will be destroyed
# (because docker_image.web is not in configuration)
# docker_network.app will be destroyed
# (because docker_network.app is not in configuration)
# module.proxy.docker_container.proxy will be created
# module.web.docker_container.this[0] will be created
# module.web.docker_container.this[1] will be created
# module.web.docker_container.this[2] will be created
# module.web.docker_image.this will be created
# module.web.docker_network.this will be created
Plan: 6 to add, 0 to change, 5 to destroy.الخطة تريد أن تحذف كل شيء وتنشئه من جديد. والسبب واضح عندما تتذكر ما في الحالة: الحالة تعرف مورداً عنوانه docker_container.web[0]، والكود لم يعد فيه هذا العنوان، وإنما فيه عنوان جديد هو module.web.docker_container.this[0]، والأداة لا تعرف أنهما الشيء نفسه، فهي ترى مورداً اختفى من الكود فتحذفه، ومورداً جديداً ظهر فتنشئه. والعبارة because docker_container.web is not in configuration تقول لك ذلك صراحة. ولكي نرى ماذا يحدث لمن لا يقرأ الخطة، طبقناها على بيئة الإنتاج في المختبر:
docker_container.web[2]: Destroying... [id=875757c9896673d0a2c22c66e739ff4ae5aa75b6b34e0dc361112d5a02bda6b7]
docker_container.web[1]: Destroying... [id=af06e59f54c54f8432ec9e30bbe5f6f406d3e0cd5eb47d974562717d76d03873]
docker_container.web[0]: Destroying... [id=79940aafd770680ec3f21d608af1cf81dd8100a0f78a58a9cf6e0b63b3cdfbcc]
module.web.docker_network.this: Creating...
module.web.docker_image.this: Creating...
docker_container.web[2]: Destruction complete after 2s
docker_container.web[1]: Destruction complete after 2s
docker_container.web[0]: Destruction complete after 2s
docker_network.app: Destroying... [id=5556810b1f0e4dab329741246d925e86fdbc5575863a4a5cf492f80ea232341f]
docker_image.web: Destroying... [id=sha256:b3c656d55d7ad751196f21b7fd2e8d4da9cb430e32f646adcf92441b72f82b14nginx:1.29.3-alpine]
docker_image.web: Destruction complete after 0s
module.web.docker_image.this: Creation complete after 4s [id=sha256:b3c656d55d7ad751196f21b7fd2e8d4da9cb430e32f646adcf92441b72f82b14nginx:1.29.3-alpine]
docker_network.app: Destruction complete after 3s
Error: Unable to create network: Error response from daemon: network with name wr-iac-prod already exists
with module.web.docker_network.this,في المخرج أعلاه لاحظ التالي:
- الأداة حذفت السيرفرات الثلاثة في الثواني الأولى، لأنها لا تعتمد على شيء جديد، فبدأت بها مباشرة وبالتوازي.
- في الوقت نفسه حاولت أن تنشئ الشبكة الجديدة، والشبكة القديمة ما زالت موجودة بالاسم نفسه
wr-iac-prod، فرفض Docker، وتوقف التطبيق بخطأ. - النتيجة أن الإنتاج بلا سيرفرات ويب، والشبكة القديمة حذفت، والجديدة لم تنشأ، أي أسوأ حالة ممكنة: لا القديم ولا الجديد.
وعندما أعدنا التطبيق مرة ثانية نجح، لأن الاسم أصبح متاحاً، فأنشأ الشبكة ثم السيرفرات الثلاثة في 6 ثوان ثم ال Proxy، وتحققنا من أن ال Proxy يرد ويوزع على السيرفرات:
HTTP/1.1 200 OK
X-Upstream: 172.22.0.4:80ولكن الإنتاج كان متوقفاً بين التطبيقين، وعلى مزود سحابي حقيقي يكون الأمر أسوأ بكثير: السيرفرات الجديدة لها عناوين جديدة، وما كان على أقراص القديمة ضاع، وإذا كان من بين الموارد قاعدة بيانات فقد حذفتها. والدرس هنا أن الخطة قالت كل شيء قبل التطبيق، فالسطر 5 to destroy في خطة «إعادة تنظيم فقط» يجب أن يوقفك، فإعادة الهيكلة الصحيحة خطتها لا تحذف شيئاً.
![مقارنة بين نقل الموارد إلى الوحدة بطريقتين: على اليسار دون moved، الحالة تعرف docker_container.web[0] والكود فيه module.web.docker_container.this[0]، فالخطة 6 to add و5 to destroy، والتطبيق حذف السيرفرات الثلاثة وفشل في إنشاء الشبكة لأن الاسم wr-iac-prod موجود، وعلى اليمين مع moved، الخطة تقول has moved to وتعدل restart في مكانه، والنتيجة 1 to add و1 to change و0 to destroy مع بقاء معرف ال Container نفسه 150d2002](https://arabroot.io/content/images/2026/11/tofu-modules-02-refactor.webp)
كتل moved: انقل العنوان ولا تحذف المورد
الحل أن تخبر الأداة أن العنوان القديم أصبح عنواناً جديداً، وهذا ما تفعله كتلة moved، كما في وثائق إعادة الهيكلة. وقد طبقناها على بيئة الاختبار بالطريقة الصحيحة، فأضفنا إلى ملفها بعد استدعاء الوحدتين ثلاث كتل، واحدة لكل مورد:
# The resources already exist: tell OpenTofu their new address instead of destroying them
moved {
from = docker_network.app
to = module.web.docker_network.this
}
moved {
from = docker_image.web
to = module.web.docker_image.this
}
moved {
from = docker_container.web
to = module.web.docker_container.this
}ولاحظ أن الكتلة الثالثة تنقل المورد كله بكل نسخه [0] و[1] وغيرها، فلا تحتاج كتلة لكل رقم. ثم طلبنا الخطة:
~ update in-place (current -> planned)
# module.proxy.docker_container.proxy will be created
+ restart = "unless-stopped"
# module.web.docker_container.this[0] will be updated in-place
# (moved from docker_container.web[0])
~ resource "docker_container" "this" {
~ restart = "no" -> "unless-stopped"
# (45 unchanged attributes hidden)
# (2 unchanged blocks hidden)
# docker_image.web has moved to module.web.docker_image.this
# (3 unchanged attributes hidden)
# docker_network.app has moved to module.web.docker_network.this
# (9 unchanged attributes hidden)
# (1 unchanged block hidden)
Plan: 1 to add, 1 to change, 0 to destroy.في المخرج أعلاه لاحظ التالي، وهو من أجمل ما ستراه في خطة:
- الشبكة وال Image تقول
has moved to، أي أن الأداة سوف تغير عنوانهما في الحالة فقط دون أن تلمس Docker. - السيرفر نفسه انتقل أيضاً
(moved from docker_container.web[0])، ولكن معه تعديل في مكانه:restart = "no" -> "unless-stopped". وهذا هو الفرق الذي نسيه الفريق بين البيئتين، ظهر وحده في الخطة، لأن الوحدة فيها القيمة الافتراضية الصحيحة، فأصبحت بيئة الاختبار تشبه الإنتاج من أول تطبيق. - السطر الأخير
0 to destroy، وهذا هو المعيار الذي تحكم به على أي إعادة هيكلة.
وبعد التطبيق بقي معرف السيرفر كما هو 150d200231e3…، فالأداة عدلت السياسة في السيرفر نفسه ولم تستبدله، وأنشأت ال Proxy، ثم أصبحت الحالة كما يلي:
module.proxy.docker_container.proxy
module.web.docker_container.this[0]
module.web.docker_image.this
module.web.docker_network.thisومتى تحذف كتل moved؟ بعد أن تطبق كل نسخة من المشروع الخطة التي فيها الانتقال، فإذا كان المشروع وحدة يستخدمها غيرك فاتركها مدة طويلة، لأن من يحدث من إصدار قديم يحتاجها ليصل إلى العنوان الجديد، أما في مجلد بيئة تطبقه أنت فقط فتستطيع حذفها بعد أن تخرج الخطة No changes. وتوجد أيضاً كتلة removed لعكس الحالة: أن تخرج مورداً من الحالة دون أن تحذفه من المزود، وهي مفيدة عندما تنقل مورداً من مشروع إلى مشروع آخر يستورده.
ماذا لو تغيرت القائمة؟ count مع for_each
الوحدة تستخدم count للسيرفرات، وهذا مناسب لأن السيرفرات متطابقة ولا يهم أيها يحذف عند التقليل. ولكن كثيراً من الموارد ليست متطابقة، مثل مواقع أو نطاقات أو مستخدمين لكل منها اسم، وهنا يظهر الفرق بين الطريقتين. ولكي نراه بوضوح كتبنا مشروعاً صغيراً فيه مورد بسيط من نوع terraform_data لكل موقع من قائمة فيها ثلاثة مواقع، مرة بـ count ومرة بـ for_each:
variable "sites" {
type = list(string)
default = ["shop", "blog", "docs"]
}
# count: each instance is known by its position in the list
resource "terraform_data" "by_count" {
count = length(var.sites)
input = var.sites[count.index]
}
# for_each: each instance is known by its key
resource "terraform_data" "by_key" {
for_each = toset(var.sites)
input = each.key
}ثم طبقنا، وطلبنا الخطة بعد حذف الموقع الأول shop من القائمة:
# terraform_data.by_count[0] will be updated in-place
~ input = "shop" -> "blog"
# terraform_data.by_count[1] will be updated in-place
~ input = "blog" -> "docs"
# terraform_data.by_count[2] will be destroyed
# (because index [2] is out of range for count)
- input = "docs" -> null
# terraform_data.by_key["shop"] will be destroyed
# (because key ["shop"] is not in for_each map)
- input = "shop" -> null
Plan: 0 to add, 2 to change, 2 to destroy.في المخرج أعلاه لاحظ أن count يعرف كل نسخة برقمها في القائمة، فلما حذفنا الأول انزاح كل شيء: النسخة رقم 0 التي كانت shop أصبحت blog، ورقم 1 الذي كان blog أصبح docs، ورقم 2 حذف. أي أن حذف موقع واحد غير الموقعين الآخرين وحذف ثالثاً لم نطلب حذفه. ومع مورد حقيقي يستبدل عند تغيير خصائصه، مثل سيرفر أو قاعدة بيانات، فهذا يعني استبدال كل ما بعد العنصر المحذوف. أما for_each فيعرف كل نسخة بمفتاحها ["shop"]، فحذف shop فقط ولم يلمس الباقي. والقاعدة كما في وثائق for_each: استخدم count للنسخ المتطابقة التي يهمك عددها فقط، واستخدم for_each لكل شيء له اسم أو هوية. وإذا أردت أن تحول مورداً موجوداً من count إلى for_each فكتلة moved نفسها تفعل ذلك، من terraform_data.by_count[0] إلى terraform_data.by_key["shop"]، واحدة لكل نسخة.

زيادة السيرفرات دون انقطاع: create_before_destroy
عادت بيئة الإنتاج إلى العمل بالوحدتين، ثم طلبنا خطة لرفع السيرفرات من ثلاثة إلى أربعة، ونتوقع إضافة سيرفر واحد فقط:
# module.proxy.docker_container.proxy must be replaced
# (16 unchanged attributes hidden)
- upload { # forces replacement
+ upload { # forces replacement
# module.web.docker_container.this[3] will be created
Plan: 2 to add, 0 to change, 1 to destroy.ال Proxy سوف يستبدل، لأن ملف إعداده الذي نرفعه بالكتلة upload تغير بإضافة السيرفر الرابع، والمزود يعتبر أي تغيير في الملفات المرفوعة سبباً للاستبدال. والاستبدال الافتراضي يحذف القديم ثم ينشئ الجديد، وبما أن ال Proxy هو الباب الوحيد للموقع، فهذا يعني انقطاعاً. ولكي نقيسه شغلنا Container صغيراً يرسل طلباً إلى ال Proxy كل ربع ثانية ويطبع رمز الرد، ثم طبقنا:
module.proxy.docker_container.proxy: Destroying... [id=739693f79a1bdee9362fd0c246ab04cc09a4169f600937d01054038c674056f0]
module.proxy.docker_container.proxy: Destruction complete after 1s
module.web.docker_container.this[3]: Creating...
module.web.docker_container.this[3]: Creation complete after 3s [id=e6c2cdbd5ff49520c588c82c51d014c745ccbf3a8f410a219a31ed1b419a33c2]
module.proxy.docker_container.proxy: Creating...
module.proxy.docker_container.proxy: Creation complete after 3s [id=609afb2f4a6a28bb5ca27740e60c6bfdc529d8dca270c144e4403783fcb529fa]والمسبار سجل هذه الردود في وقت التطبيق، والرمز 000 يعني أن الطلب لم يحصل على أي رد:
01:37:15 000
01:37:16 000
01:37:18 000
01:37:19 000
01:37:20 000
01:37:21 000ست ثوان والموقع لا يرد، وهي الوقت بين حذف ال Proxy القديم وانتهاء إنشاء الجديد، والأداة لم تنشئ الجديد إلا بعد أن انتهت من السيرفر الرابع لأن إعداده يحتاج اسمه. والحل الذي يخطر أولاً هو create_before_destroy في كتلة lifecycle، أي أن تنشئ الأداة الجديد قبل أن تحذف القديم، كما في وثائق lifecycle. ولكن هذا وحده لا يكفي هنا، لأن اسم ال Container ثابت، وDocker لا يقبل اسمين متطابقين، فسوف يفشل إنشاء الجديد والقديم ما زال موجوداً، وهي المشكلة نفسها التي رأيناها مع الشبكة. لذلك غيرنا وحدة ال Proxy في ثلاثة أشياء معاً:
locals {
config = templatefile("${path.module}/nginx.conf.tftpl", { upstreams = var.upstreams })
}
resource "docker_container" "proxy" {
# A new name for every new config, so the new proxy can start before the old one stops
name = "wr-iac-${var.env}-proxy-${substr(sha256(local.config), 0, 8)}"
image = "nginx:1.29.3-alpine"
restart = "unless-stopped"
networks_advanced {
name = var.network
aliases = ["proxy"] # clients use this name, not the container name
}
upload {
file = "/etc/nginx/conf.d/default.conf"
content = local.config
}
healthcheck {
test = ["CMD", "wget", "-q", "-O", "/dev/null", "http://127.0.0.1/"]
interval = "2s"
retries = 3
}
wait = true # apply waits until the healthcheck passes
lifecycle {
create_before_destroy = true
}
}في الإعداد أعلاه لاحظ التالي:
- اسم ال Container ينتهي بأول ثمانية حروف من هاش ملف الإعداد، فكل إعداد جديد يعطي اسماً جديداً، وبالتالي يستطيع ال Proxy الجديد أن يعمل بجانب القديم.
- العملاء لا يستخدمون اسم ال Container، وإنما الاسم البديل Alias
proxyعلى الشبكة، وهو اسم يحمله القديم والجديد معاً في لحظة الانتقال، فيوزع Docker الطلبات بينهما. وعلى سيرفر حقيقي يقوم مقام هذا الاسم موزع الضغط Load Balancer أو سجل DNS. - الخيار
wait = trueمع فحص الصحة Healthcheck يجعل الأداة تنتظر حتى يرد ال Proxy الجديد فعلاً قبل أن تعتبر إنشاءه انتهى، وبدونه قد تحذف القديم وما زال الجديد يقرأ إعداده.
ثم طبقنا الانتقال إلى الوحدة الجديدة مرة واحدة، وشغلنا المسبار على الاسم proxy، وطلبنا هذه المرة تقليل السيرفرات من أربعة إلى ثلاثة:
module.proxy.docker_container.proxy: Creating...
module.proxy.docker_container.proxy: Creation complete after 6s [id=89051206399f52d1811c2f177dc0611ad988d6a9531cb46ec6dfa94cd9127c82]
module.proxy.docker_container.proxy (deposed object 41e80aca): Destroying... [id=58e811c1278a0e175c2a82ca424d4c7daa08286e8768bb3ea62afdf8040790f4]
module.proxy.docker_container.proxy: Destruction complete after 1s
module.web.docker_container.this[3]: Destroying... [id=e6c2cdbd5ff49520c588c82c51d014c745ccbf3a8f410a219a31ed1b419a33c2]
module.web.docker_container.this[3]: Destruction complete after 1s
Apply complete! Resources: 1 added, 0 changed, 2 destroyed.والمسبار سجل 109 ردود كلها 200، ولا يوجد رد واحد فاشل. وفي المخرج أعلاه لاحظ الترتيب: ال Proxy الجديد أنشئ أولاً وانتظرت الأداة 6 ثوان حتى نجح فحص صحته، ثم حذف القديم، والعبارة deposed object هي اسم الأداة للنسخة القديمة التي بقيت مؤقتاً بعد إنشاء البديل. ثم حذف السيرفر الرابع في النهاية، لأن ال Proxy الجديد لا يرسل إليه شيئاً، فالأداة رتبت الحذف بحيث لا يصل طلب إلى سيرفر محذوف. ولاحظ أن هذا الإصلاح كتب مرة واحدة في الوحدة، فأصبحت بيئة الاختبار والإنتاج تستبدلان ال Proxy دون انقطاع من الخطة التالية، وهذه بالضبط فائدة الوحدة.

إصدارات الوحدات Module Versions من Git
حتى الآن تقرأ البيئتان الوحدة من مجلد محلي، وهذا يعني أن أي تعديل في modules/web يصل إلى الاختبار والإنتاج في الخطة التالية لكل منهما، وهذا مقبول ما دام الفريق صغيراً والمستودع واحداً، ولكنه يصبح مشكلة عندما تريد أن تجرب تغييراً في الوحدة على الاختبار أسبوعاً قبل أن يصل إلى الإنتاج، أو عندما تستخدم الوحدة فرق أخرى في مستودعاتها. والحل أن تضع الوحدة في مستودع Git خاص بها، وتصدر نسخها بوسوم Tags، وتثبت كل بيئة النسخة التي تستخدمها، تماماً كما تثبت إصدار المزود. ووضعنا الوحدة في مستودع وسمنا فيه النسخة v1.0.0، وأنشأنا بيئة ثالثة envs/dev تقرؤها منه:
module "web" {
# A pinned release of the module from its own repository
source = "git::file:///work/repos/modules.git//web?ref=v1.0.0"
env = "dev"
replicas = 1
image = "nginx:1.29.3-alpine"
}في العنوان أعلاه لاحظ ثلاثة أجزاء: git:: يقول للأداة أن تستخدم Git، والجزء بعد // هو المجلد داخل المستودع، والقيمة ?ref=v1.0.0 هي الوسم، كما في وثائق مصادر الوحدات. واستخدمنا file:// في المختبر لأن المستودع على الجهاز، أما في عملك فيكون العنوان مثل git::https://git.example.com/infra/modules.git//web?ref=v1.0.0 على سيرفر Gitea مثل الذي شرحناه في تثبيت Gitea. ثم شغلنا tofu init:
Initializing the backend...
Initializing modules...
Downloading git::file:///work/repos/modules.git?ref=v1.0.0 for web...
Error: Failed to download module
on main.tf line 1:
1: module "web" {
Could not download module "web" (main.tf:1) source code from
"git::file:///work/repos/modules.git?ref=v1.0.0": error downloading
'file:///work/repos/modules.git?ref=v1.0.0': git must be available and on the
PATHوهذه مشكلة حقيقية سوف تراها في أول خط CI/CD تبنيه: OpenTofu لا يحمل Git بداخله، وإنما يشغل البرنامج git الموجود على الجهاز ليسحب الوحدة، وال Image الصغيرة التي بنيناها من alpine:3.22 لا يوجد فيها Git. والحل أن تضيفه إلى ال Image التي تشغل الأداة، ومعه عميل SSH إذا كانت الوحدات خلف SSH:
# Same tofu image, plus git: OpenTofu calls the git program to fetch git:: module sources
FROM ghcr.io/opentofu/opentofu:1.13.2-minimal AS tofu
FROM alpine:3.22
RUN apk add --no-cache git openssh-client
COPY --from=tofu /usr/local/bin/tofu /usr/local/bin/tofu
ENTRYPOINT ["/usr/local/bin/tofu"]وبعد بناء ال Image الجديدة، وفيها Git بالإصدار 2.49.1، نجح init:
Initializing modules...
Downloading git::file:///work/repos/modules.git?ref=v1.0.0 for web...
- web in .terraform/modules/web/web
Initializing provider plugins...
- Finding kreuzwerker/docker versions matching ">= 4.6.0, 4.6.0, < 5.0.0"...
- Installing kreuzwerker/docker v4.6.0...في المخرج أعلاه لاحظ التالي:
- الوحدة نسخت هذه المرة إلى
.terraform/modules/web، بخلاف الوحدات المحلية، فالبيئة تعمل بالنسخة التي سحبتها حتى تطلب غيرها، ولا يصلها أي تعديل في المستودع. - سطر البحث عن المزود يجمع القيدين معاً:
>= 4.6.0, < 5.0.0من الوحدة، و4.6.0من البيئة، والأداة تختار إصداراً يحقق كل القيود معاً، فإذا تعارضت، كأن تطلب الوحدة 5 والبيئة 4، توقفinitبخطأ، وهذا هو سبب أن الوحدة تكتب مدى وليس رقماً.
والأداة تحفظ مصدر كل وحدة سحبتها في ملف modules.json داخل .terraform/modules:
{"Modules":[{"Key":"","Source":"","Dir":"."},{"Key":"web","Source":"git::file:///work/repos/modules.git//web?ref=v1.0.0","Dir":".terraform/modules/web/web"}]}تحديث الوحدة إلى نسخة جديدة: Module Source has changed
بعد ذلك أضاف أحد الزملاء إلى الوحدة وسماً جديداً على كل Container يقول إنه من إنشاء الوحدة، وأصدر النسخة v1.1.0. فغيرنا الرقم في بيئة dev وطلبنا الخطة مباشرة:
Error: Module source has changed
on main.tf line 3, in module "web":
3: source = "git::file:///work/repos/modules.git//web?ref=v1.1.0"
The source address was changed from
"git::file:///work/repos/modules.git//web?ref=v1.0.0" to
"git::file:///work/repos/modules.git//web?ref=v1.1.0" since this module was
installed. Run "tofu init" to install all modules required by this
configuration.الأداة رفضت أن تخطط بنسخة لم تسحبها، وطلبت tofu init، وهذه حماية مفيدة، لأنها تمنع أن تخطط بنسخة وأنت تظن أنك تخطط بأخرى. وفي خط CI/CD لا تظهر هذه الرسالة لأن الخط يشغل init في كل مرة، أما على جهازك فسوف تراها كلما سحبت فرعاً غير فيه أحد رقم وحدة. وبعد init كانت الخطة كما يلي:
# module.web.docker_container.this[0] must be replaced
# (16 unchanged attributes hidden)
+ labels { # forces replacement
+ label = "managed-by"
# (1 unchanged block hidden)
Plan: 1 to add, 0 to change, 1 to destroy.وهذه هي المفاجأة الثانية: الزميل أضاف وسماً فقط، وهو تغيير يبدو بريئاً، ولكن مزود Docker يعتبر الوسوم Labels جزءاً لا يتغير من ال Container، فكل سيرفر في كل بيئة سوف يستبدل عندما تحدث الوحدة. وهذا هو سبب الإصدارات أصلاً: أن تحدث الاختبار أولاً، وترى الخطة، وتقرر هل الاستبدال مقبول ومتى، ثم تحدث الإنتاج في وقت تختاره. ولو كانت البيئات تقرأ الوحدة من مجلد محلي، لظهر الاستبدال في خطة الإنتاج في اليوم نفسه، في طلب دمج لا علاقة له بالوحدة أصلاً. لذلك عامل كل نسخة من الوحدة كما تعامل إصدار مكتبة: رقم إصدار دلالي Semantic Versioning، وملاحظات إصدار تذكر أي تغيير يستبدل الموارد، وتحديث بطلب دمج تظهر فيه الخطة.

اختبار الوحدة قبل أن يستخدمها أحد: tofu test
الوحدة الآن كود يستخدمه آخرون، والكود الذي يستخدمه آخرون يحتاج إلى اختبارات، وOpenTofu يأتي بأمر اختبار خاص اسمه tofu test، كما في وثائق الأمر test. والاختبار ملف ينتهي بـ .tftest.hcl فيه قيم للمتغيرات، وكتل run تشغل خطة أو تطبيقاً ثم تتحقق من النتيجة بكتل assert. وكتبنا ثلاثة اختبارات للوحدة، كلها بخطة فقط، فلا تنشئ أي Container:
# tofu test: plans the module with sample inputs and checks the result, no real containers
variables {
env = "ci"
replicas = 2
image = "nginx:1.29.3-alpine"
}
run "names_follow_env" {
command = plan
assert {
condition = docker_container.this[1].name == "wr-iac-ci-web-2"
error_message = "container names must be wr-iac-<env>-web-<n>"
}
assert {
condition = docker_network.this.name == "wr-iac-ci"
error_message = "network name must be wr-iac-<env>"
}
}
run "rejects_latest" {
command = plan
variables {
image = "nginx:latest"
}
expect_failures = [var.image]
}
run "rejects_zero_replicas" {
command = plan
variables {
replicas = 0
}
expect_failures = [var.replicas]
}في الإعداد أعلاه لاحظ أن الاختبار الأول يتحقق من قاعدة التسمية، لأن أسماء السيرفرات هي ما تقرؤه وحدة ال Proxy، فإذا تغيرت توقف التوزيع، وأن الاختبارين الآخرين يتحققان من أن قواعد التحقق ترفض القيم الخاطئة فعلاً، والكتلة expect_failures تعني أن الاختبار ينجح فقط إذا فشل التحقق من هذا المتغير. ثم شغلنا الاختبار من مجلد الوحدة:
tests/web.tftest.hcl... pass
run "names_follow_env"... pass
run "rejects_latest"... pass
run "rejects_zero_replicas"... pass
Success! 3 passed, 0 failed.ثم جربنا ما يحدث لو غير أحد قاعدة التسمية، فجعلنا الأرقام تبدأ من صفر بحذف + 1 من اسم ال Container، وهو تغيير قد يبدو تنظيفاً للكود:
tests/web.tftest.hcl... fail
run "names_follow_env"... fail
Error: Test assertion failed
on tests/web.tftest.hcl line 12, in run "names_follow_env":
12: condition = docker_container.this[1].name == "wr-iac-ci-web-2"
├────────────────
│ docker_container.this[1].name is "wr-iac-ci-web-1"
├────────────────
│ Diff:
│ "wr-iac-ci-web-1" -> "wr-iac-ci-web-2"
container names must be wr-iac-<env>-web-<n>
run "rejects_latest"... pass
run "rejects_zero_replicas"... pass
Failure! 2 passed, 1 failed.الاختبار فشل، وطبع القيمة الفعلية والقيمة المتوقعة، ولو وصل هذا التغيير إلى البيئات لاستبدل كل سيرفر فيها لأن اسمه تغير. ومكان هذا الأمر الطبيعي هو خط CI/CD للمستودع الذي فيه الوحدات، فلا تصدر نسخة جديدة إلا إذا نجحت اختباراتها، وهذا ما سوف نضيفه في المقال التالي.
متى لا تكتب وحدة؟ Over-abstraction
بعد أن يرى الفريق فائدة الوحدات تأتي المرحلة الثانية، وهي أن يصبح كل شيء وحدة، وهذه مشكلة أيضاً. فالوحدة التي تلف مورداً واحداً وتمرر كل خصائصه كمتغيرات لا تضيف شيئاً، وإنما تضيف طبقة بين القارئ والمورد، فمن يريد أن يعرف ماذا يحدث عليه أن يفتح ملفين بدلاً من ملف. والوحدات المتداخلة ثلاث طبقات تجعل الخطة مليئة بعناوين طويلة مثل module.app.module.web.module.net.docker_network.this، وتجعل أي إعادة هيكلة تحتاج إلى عشرات كتل moved. والقاعدة التي نستخدمها: اكتب وحدة عندما يتكرر الشيء نفسه في مكانين على الأقل، أو عندما تريد أن تفرض قاعدة، مثل منع latest أو فرض سياسة إعادة التشغيل، وأبق الوحدات طبقة واحدة تستدعيها البيئة، ولا تقم بكتابة وحدة لشيء لا تعرف بعد كيف سوف يتغير، فالتجريد الخاطئ أصعب في الإصلاح من التكرار.
وتذكر أيضاً أن الوحدة الجيدة تصف خدمة من وجهة نظر من يستخدمها، وليس من وجهة نظر المزود، فالمدخلات env وreplicas وimage هي أسئلة يعرف إجابتها أي مطور في الفريق، أما مدخل مثل network_driver_opts فهو تفصيل للمزود، فإذا احتاجه أحد يوماً أضفه حينها.
أخطاء شائعة Common Mistakes
- نسخ مجلد البيئة بدلاً من وحدة: الفروق المقصودة تخفي الفرق غير المقصود، والإصلاح يصل إلى بيئة واحدة.
- نقل الموارد إلى وحدة دون
moved: الخطة تحذف كل شيء وتنشئه، ورأيت أن التطبيق قد يتوقف في المنتصف بلا قديم ولا جديد. - قبول خطة إعادة هيكلة فيها
destroy: إعادة الهيكلة الصحيحة0 to destroy. countلموارد لها أسماء: حذف عنصر من أول القائمة يغير كل ما بعده، فاستخدمfor_each.- كتلة
providerداخل الوحدة: تمنع البيئات من أن تحدد أين يتصل المزود، وتمنع حذف الوحدة بأمان. - رقم مزود واحد في الوحدة: يمنع البيئات من التحديث، فاكتب مدى في الوحدة ورقماً كاملاً في البيئة.
- وحدات من فرع وليس من وسم:
?ref=mainيجعل كلinitيسحب شيئاً مختلفاً، فثبت وسماً أو هاش Commit. - نسيان Git في Image الخط:
git must be available and on the PATHفي أول تشغيل. - مساحات العمل لفصل الاختبار عن الإنتاج: الكود والمفاتيح مشتركة، والبيئة تحددها حالة في جهازك لا يراها المراجع.
- وحدة لكل مورد، ووحدات داخل وحدات: طبقات تخفي ما يحدث ولا تضيف قاعدة.
قائمة التحقق Checklist
| قبل أن تعتبر الوحدات جاهزة | كيف تتحقق |
|---|---|
| لكل بيئة مجلد وحالة مستقلة | مسار مختلف لكل بيئة في الخلفية، ومفتاح الإنتاج عند الخط فقط |
| كل متغير له نوع ووصف | لا يوجد variable بلا type وdescription |
| قواعد الفريق داخل الوحدة | validation لما تعلمتموه، مثل منع latest |
لا يوجد provider داخل الوحدة | الوحدة فيها required_providers بمدى فقط |
| إعادة الهيكلة بلا حذف | كتل moved، والخطة 0 to destroy |
الموارد ذات الأسماء بـ for_each | حذف عنصر من القائمة لا يلمس غيره في الخطة |
| الاستبدال لا يقطع الخدمة | create_before_destroy مع اسم متغير وفحص صحة، ومسبار يسجل الردود أثناء التطبيق |
| البيئات تثبت نسخة الوحدة | ?ref=v1.1.0 وليس فرعاً، وتحديث الإنتاج بعد الاختبار |
| الوحدة لها اختبارات | tofu test ينجح قبل أي وسم جديد |
الخلاصة Summary
وصلنا لنهاية الموضوع، وأهم ما فيه:
- نسخ مجلد البيئة يبدأ سريعاً، ثم يصبح الفرق غير المقصود بين البيئات مخفياً بين الفروق المقصودة، كما حدث مع سياسة إعادة التشغيل.
- الوحدة مجلد فيه موارد، مدخلاتها المتغيرات ومخرجاتها
output، والبيئة تربط الوحدات بتمرير المخرجات بينها، وقواعدvalidationتضع ما تعلمه الفريق داخل الوحدة. - كل بيئة مجلد ووحدة جذرية وحالة مستقلة، ومساحات العمل لا تناسب فصل الاختبار عن الإنتاج.
- نقل الموارد إلى وحدة دون
movedحذف سيرفرات الإنتاج في المختبر وتوقف في المنتصف، ومعmovedانتقلت بلا حذف وظهر الفرق المنسي وحده في الخطة. for_eachللموارد ذات الأسماء، وcreate_before_destroyمع اسم متغير وفحص صحة حول ست ثوان من الانقطاع إلى صفر.- الوحدات من Git بوسوم، وال Image التي تشغل الأداة تحتاج Git، وتغيير الوسم يحتاج
init، وتحديث صغير في الوحدة قد يستبدل كل السيرفرات، لذلك يصل إلى بيئة واحدة أولاً. tofu testيكتشف تغيير قاعدة التسمية قبل أن يستبدل سيرفرات أي بيئة.
وفي المقال التالي في المرحلة بإذن الله نشغل كل هذا من خط CI/CD: خطة في كل طلب دمج يقرؤها المراجع، وتطبيق بعد الدمج لا يملك مفاتيحه إلا الخط. والمقالات المرتبطة بهذا المقال:
دليلملف الحالة State في OpenTofu: الحفظ والقفل والحمايةأين تحفظ حالة OpenTofu حتى يراها كل الفريق، وكيف تتأكد أن القفل يعمل فعلاً، وكيف تشفرها لأنها تحمل كلمات المرور بنص واضح.
دليلأول بنية مع OpenTofu: سيرفرات مع سجلات DNS من ملف واحدمختبر يعمل على جهازك ينشئ السيرفرات وسجل DNS الذي يشير إليها من ملف واحد، ويقرأ معك كل سطر في مخرج init وplan وapply.
دليلمصطلحات البنية كشيفرة IaC التي تحتاجها قبل أي أداةما معنى أن تكتب بنيتك في ملفات داخل Git، ولماذا يفشل السكربت العادي عند تشغيله مرة ثانية، وما الذي تحفظه الأداة في ملف الحالة.
دليلGitea: خادم Git خاص لفريقك على سيرفرككيف تثبت Gitea على سيرفرك حتى يبقى كود فريقك عندك بتجربة تشبه GitHub، مع النسخ الاحتياطي والتحديث.سجل التحديثات Changelog
- نوفمبر 2026: كتابة المقال وتنفيذ المختبر بـ OpenTofu 1.13.2 داخل Image بنيناها من 1.13.2-minimal على alpine:3.22، ثم Image ثانية فيها Git 2.49.1 لمصادر git::، مع مزود kreuzwerker/docker 4.6.0 وال Image nginx:1.29.3-alpine والمسبار curlimages/curl:8.11.1، على Docker Engine 29.8.0.