pratique: true

الورشة الأساسية 1 — Terraform : كتلة، خطة، state

المدة

20 دقيقة

الوحدة

1/7

المتطلبات المسبقة

Terraform مثبَّت (terraform version يجيب) والعُدّة مستنسخة في lab-terraform (المشروع 01، الملحق A.1 إلى A.4 أو B.1 إلى B.4)

ستبني

مشروع Terraform مختزلًا إلى جوهره، كتلة واحدة من ثلاثة أسطر، ملفًا bonjour.txt يُنشئه Terraform، وstate ستقرأه

المخرج المطلوب

مخرجات terraform state show local_file.bonjour من الخطوة 9

كيف تقرأ هذه الصفحة. عشر خطوات، أمر واحد في كل مرة. لكل منها : الأمر الذي تكتبه، والمخرجات الدقيقة لجهاز الدورة (Terraform 1.12.2)، وما يجب النظر إليه فيها. اكتب كل أمر بنفسك (لا نسخ ولصق) : بكتابة init وplan وapply وstate ترسخ الكلمات. كتل « لفهم أفضل » اختيارية ؛ افتحها إذا تركت لك خطوة شكًا. أوامر terraform … متطابقة على Windows وLinux وmacOS ؛ وعندما يعتمد أمر على النظام (إنشاء ملف، قراءته، سرد محتوى)، تُعطى النسختان، إحداهما تحت الأخرى. إذا لم يكن Terraform مثبَّتًا أو لم تكن العُدّة مستنسخة، فارجع إلى المشروع 01، قسم باختصار (العُدّة : https://github.com/hrhouma2/aiopsatlas-terraform-labo-fr).

الهدف

جعلك المشروع 01 تنفّذ ثلاثة عشر أمرًا على main.tf من خمسة عشر سطرًا، مع كتلة terraform وكتلة provider وكتلة resource. رأيت الجمل تمرّ، لكن خمسة عشر سطرًا كثيرة أصلًا لمعرفة ما هو ضروري فعلًا. هنا، تنطلق من الصفر بـ ثلاثة أسطر مفيدة : كتلة resource واحدة، بلا شيء حولها. سترى Terraform يرفض العمل بدون init، ثم تجعله يكتب كشفه، وينفّذه، وتقرأ ما دوّنه في سجله. في النهاية، تعرف ما هي الكتلة والخطة وstate لأنك صنعتها بنفسك، واحدة بعد الأخرى.

المفردات في صورة واحدة

استعد المهندس المعماري من الدرس 01. الكتلة resource سطر في مخطط المهندس : « هنا، ملف، بهذا الاسم وهذا المحتوى ». الخطة (الأمر) هي الكشف : ما سيفعله Terraform ليشبه الواقع الرسم. State هو السجل : ما بناه Terraform فعليًا، تحت أي معرّف، وبأي قيم. ثلاثة كائنات، ثلاثة أوامر لرؤيتها : تُقرأ الكتلة في main.tf، والكشف بـ terraform plan، والسجل بـ terraform state show.

أين تكتب

طرفية (PowerShell على Windows ؛ bash أو zsh على Linux وmacOS وWSL 2 أو Git Bash)، مفتوحة في جذر العُدّة lab-terraform، الذي يحتوي على labo.ps1 وlabo.sh. وVS Code لكتابة الملف. تُكتب أوامر terraform … بالطريقة نفسها تمامًا في كل مكان ؛ فقط أوامر إنشاء ملف أو قراءته أو سرده تتغيّر، وتُعطى في النسختين كل مرة.

الخطوة 1 — إنشاء مجلد فارغ

Windows (PowerShell) :

.\labo.ps1 nouveau atelier-1
cd travail\atelier-1

Linux وmacOS وWSL 2 وGit Bash :

./labo.sh nouveau atelier-1
cd travail/atelier-1

Dossier travail/atelier-1 créé (ignoré par Git). Tapez :
  cd travail/atelier-1

ما يطلبه الأمر : أنشئ لي مجلد عمل فارغًا، travail/atelier-1، سيتجاهله Git (على Windows يكتب السكربت travail\atelier-1، بالشرطة المائلة العكسية). (رسالة العُدّة تعني : « أُنشئ المجلد travail/atelier-1 (يتجاهله Git). اكتب : »)

ما يجب النظر إليه : المجلد فارغ. لا شيء مشروع Terraform بعد : main.tf، ثم init، هما ما سيجعلانه كذلك.

الخطوة 2 — كتابة كتلة من ثلاثة أسطر

في VS Code (code . من داخل المجلد)، أنشئ ملفًا main.tf واكتب بالضبط :

resource "local_file" "bonjour" {
  filename = "${path.module}/bonjour.txt"
  content  = "Bonjour Terraform"
}

ما يطلبه الملف : « يا Terraform، أدِر لي ملفًا على القرص (local_file)، أسمّيه bonjour ؛ اسمه bonjour.txt، في هذا المجلد، ويحتوي على Bonjour Terraform. »

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

Windows (PowerShell) :

Get-ChildItem
Get-Content .\main.tf

Linux وmacOS وWSL 2 وGit Bash :

ls -la
cat main.tf

مدخل واحد، main.tf، وأسطر الملف الأربعة. إذا رأيت main.tf.txt، فأعد تسميته.

الخطوة 3 — طلب خطة مبكرًا جدًا

terraform plan

Error: Inconsistent dependency lock file

The following dependency selections recorded in the lock file are
inconsistent with the current configuration:
  - provider registry.terraform.io/hashicorp/local: required by this configuration but no version is selected

To make the initial dependency selections that will initialize the dependency
lock file, run:
  terraform init

ما يطلبه الأمر : « قل لي ماذا ستفعل ليشبه الواقع شيفرتي. »

ما يجب النظر إليه : يرفض Terraform، ويشرح. قرأ local_file، واستنتج منه أنه يحتاج إلى المزوّد registry.terraform.io/hashicorp/local، ويلاحظ أنه لا يملكه (no version is selected). السطر الأخير هو الحل : terraform init. هذا الخطأ الذي يصادفه كل مبتدئ مرة ؛ الآن تعرف قراءته.

الخطوة 4 — افتتاح ورشة البناء

terraform init

Initializing the backend...
Initializing provider plugins...
- Finding latest version of hashicorp/local...
- Installing hashicorp/local v2.9.1...
- Installed hashicorp/local v2.9.1 (signed by HashiCorp)
Terraform has created a lock file .terraform.lock.hcl to record the provider
selections it made above. Include this file in your version control repository
so that Terraform can guarantee to make the same selections by default when
you run "terraform init" in the future.

Terraform has been successfully initialized!

You may now begin working with Terraform. Try running "terraform plan" to see
any changes that are required for your infrastructure. All Terraform commands
should now work.
…

ما يطلبه الأمر : « نزّل المزوّدين الذين تطلبهم شيفرتي وحضّر هذا المجلد. »

ما يجب النظر إليه : Finding latest version of hashicorp/local... : بدون كتلة required_providers، يأخذ Terraform أحدث إصدار (v2.9.1 على جهاز الدورة ؛ عندك، ربما أحدث). في المشروع 01، كان السطر نفسه يقول Finding hashicorp/local versions matching "~> 2.5"... لأن الشيفرة كانت تثبّت قيدًا. ثم الجملة المنتظرة : Terraform has been successfully initialized!

اسرد المجلد، مع الملفات المخفية :

Windows (PowerShell) :

Get-ChildItem -Force

Linux وmacOS وWSL 2 وGit Bash :

ls -la

ثلاثة مدخلات : .terraform (مجلد، المزوّد المنزَّل)، و.terraform.lock.hcl (الإصدار المختار، مدوَّنًا) وmain.tf الخاص بك. لا bonjour.txt بعد، ولا terraform.tfstate بعد : لم يبنِ init شيئًا.

الخطوة 5 — قراءة الكشف

terraform plan

Terraform used the selected providers to generate the following execution
plan. Resource actions are indicated with the following symbols:
  + create

Terraform will perform the following actions:

  # local_file.bonjour will be created
  + resource "local_file" "bonjour" {
      + content              = "Bonjour Terraform"
      + content_base64sha256 = (known after apply)
      + content_base64sha512 = (known after apply)
      + content_md5          = (known after apply)
      + content_sha1         = (known after apply)
      + content_sha256       = (known after apply)
      + content_sha512       = (known after apply)
      + directory_permission = "0777"
      + file_permission      = "0777"
      + filename             = "./bonjour.txt"
      + id                   = (known after apply)
    }

Plan: 1 to add, 0 to change, 0 to destroy.

─────────────────────────────────────────────────────────────────────────────

Note: You didn't use the -out option to save this plan, so Terraform can't
guarantee to take exactly these actions if you run "terraform apply" now.

ما يطلبه الأمر : الطلب نفسه كما في الخطوة 3. هذه المرة يملك Terraform مزوّده، ويجيب.

ما يجب النظر إليه، سطرًا سطرًا، لأنها المخرجات التي ستقرأها أكثر من أي شيء آخر طوال حياتك مع Terraform :

لم يُنشأ شيء. تحقق : bonjour.txt ما زال غير موجود في المجلد.

الخطوة 6 — تنفيذ الكشف

terraform apply

Terraform used the selected providers to generate the following execution
plan. Resource actions are indicated with the following symbols:
  + create

Terraform will perform the following actions:

  # local_file.bonjour will be created
  + resource "local_file" "bonjour" {
      + content              = "Bonjour Terraform"
      …
      + filename             = "./bonjour.txt"
      + id                   = (known after apply)
    }

Plan: 1 to add, 0 to change, 0 to destroy.

Do you want to perform these actions?
  Terraform will perform the actions described above.
  Only 'yes' will be accepted to approve.

  Enter a value: yes

local_file.bonjour: Creating...
local_file.bonjour: Creation complete after 0s [id=fd9aee5556589b4d797e6d49f8ec894e29e57713]

Apply complete! Resources: 1 added, 0 changed, 0 destroyed.

ما يطلبه الأمر : « أعد حساب الكشف، أرِني إياه، انتظر موافقتي، ثم نفّذه. »

ما يجب النظر إليه : الخطة نفسها كما في الخطوة 5، ثم السؤال. اكتب yes، كاملة، ثم Enter. بعد ذلك Creating...، Creation complete after 0s [id=fd9aee55…] : الـ id الذي كان (known after apply) معروف الآن. والجملة المنتظرة : Apply complete! Resources: 1 added, 0 changed, 0 destroyed. الأعداد الثلاثة هي أعداد الخطة.

إذا كتبت y بدلًا من yes، يجيب Terraform بـ Apply cancelled. ولا يفعل شيئًا. جرّب مرة، لتكون قد رأيتها ؛ ثم أعد التشغيل بـ yes.

الخطوة 7 — قراءة الملف، سرد المجلد

Windows (PowerShell) :

Get-Content .\bonjour.txt
Get-ChildItem -Force

Linux وmacOS وWSL 2 وGit Bash :

cat bonjour.txt
ls -la

Bonjour Terraform

total 14
drwxr-xr-x 1 rehou 197609    0 sept. 15 14:55 .
drwxr-xr-x 1 rehou 197609    0 sept. 15 14:55 ..
drwxr-xr-x 1 rehou 197609    0 sept. 15 14:55 .terraform
-rw-r--r-- 1 rehou 197609 1228 sept. 15 14:55 .terraform.lock.hcl
-rw-r--r-- 1 rehou 197609   17 sept. 15 14:55 bonjour.txt
-rw-r--r-- 1 rehou 197609  111 sept. 15 14:55 main.tf
-rw-r--r-- 1 rehou 197609 1634 sept. 15 14:55 terraform.tfstate

(سرد ls -la من جهاز الدورة ؛ يعرض Get-ChildItem -Force الأسماء الخمسة نفسها، بأعمدة أخرى.)

ما تطلبه الأوامر : « أرِني محتوى bonjour.txt، ثم كل ما في المجلد، بما في ذلك الملفات المخفية. »

ما يجب النظر إليه : Bonjour Terraform، 17 بايتًا، بالضبط content الخاص بك، بلا سطر جديد في النهاية (تحت bash، قد يظهر موجّه الأوامر ملتصقًا بالنص : هذا طبيعي). وجديدان في المجلد منذ الخطوة 4 : bonjour.txt، المورد، وterraform.tfstate، state. apply هو من أنشأ الاثنين، في الوقت نفسه : الملف على القرص، والملاحظة « أنشأته » في السجل.

الخطوة 8 — قراءة السجل : القائمة

terraform state list

local_file.bonjour

ما يطلبه الأمر : « اسرد كل ما تديره في هذا المجلد. »

ما يجب النظر إليه : سطر واحد، مورد واحد، مُعيَّن بعنوانه local_file.bonjour، العنوان نفسه كما في الخطة. هذا دليل على أن Terraform ربط كتلتك بالملف الحقيقي. قبل الخطوة 6، كان الأمر نفسه سيجيب No state file was found! : لم يكن هناك سجل بعد.

الخطوة 9 — قراءة السجل : التفاصيل

terraform state show local_file.bonjour

# local_file.bonjour:
resource "local_file" "bonjour" {
    content              = "Bonjour Terraform"
    content_base64sha256 = "SvXkP5Iqo1rJKHgTVJnjanxfsNVGhb+r52mzUqZJYyg="
    content_base64sha512 = "r3+PevYNJRFsHMz4H4U1DK+lg89nhO9SLJZMAqqtzPKiIv3ilrmbx5sYh2JCW9o5EF0NXanYmuxMvI2QN4Z1Ag=="
    content_md5          = "ff3a967c227a58691a3d34a931d3eeb5"
    content_sha1         = "fd9aee5556589b4d797e6d49f8ec894e29e57713"
    content_sha256       = "4af5e43f922aa35ac92878135499e36a7c5fb0d54685bfabe769b352a6496328"
    content_sha512       = "af7f8f7af60d25116c1cccf81f85350cafa583cf6784ef522c964c02aaadccf2a222fde296b99bc79b188762425bda39105d0d5da9d89aec4cbc8d9037867502"
    directory_permission = "0777"
    file_permission      = "0777"
    filename             = "./bonjour.txt"
    id                   = "fd9aee5556589b4d797e6d49f8ec894e29e57713"
}

ما يطلبه الأمر : « أرِني كل ما تعرفه عن local_file.bonjour. »

ما يجب النظر إليه : الشكل نفسه كخطة الخطوة 5، لكن دون أي + ودون أي (known after apply) : كل شيء معروف، كل شيء مدوَّن. الـ id هو بصمة SHA-1 للمحتوى (fd9aee55…)، مطابقة لـ content_sha1 ولـ [id=…] الذي عرضه apply. وسيطاك (filename، content) موجودان، مع الخصائص التسع التي حسبها المزوّد. هذا هو مخرجك المطلوب : احتفظ به.

الخطوة 10 — طلب خطة مجددًا : لا شيء للعمل

terraform plan

local_file.bonjour: Refreshing state... [id=fd9aee5556589b4d797e6d49f8ec894e29e57713]

No changes. Your infrastructure matches the configuration.

Terraform has compared your real infrastructure against your configuration
and found no differences, so no changes are needed.

ما يطلبه الأمر : الطلب نفسه كما في الخطوتَين 3 و5.

ما يجب النظر إليه : جديدان مقارنة بالخطوة 5. Refreshing state... [id=…] : قبل المقارنة، ذهب Terraform ليعيد قراءة الملف الحقيقي للتحقق من أنه ما زال مطابقًا للسجل. ثم No changes. Your infrastructure matches the configuration. : الشيفرة والسجل والواقع تقول الشيء نفسه، والكشف فارغ. هذا هو التكافؤ الذاتي من الدرس 01، في الطرفية : إعادة التشغيل لا تفعل شيئًا إضافيًا.

لا تدمّر شيئًا. تنطلق الورشة الأساسية 2 بالضبط من هذا المجلد، بهذا الملف وهذا state. إذا لم تتابعها فورًا، فاترك المجلد كما هو : لا شيء يُفوتَر، لا شيء يتحرك. (إذا أردت فعلًا محو كل شيء الآن : terraform destroy، yes، وستعيد الورشة 1 قبل الورشة 2.)

التحقق النهائي

اصعد إلى جذر العُدّة وشغّل العدّاد :

Windows (PowerShell) :

cd ..\..
.\labo.ps1 etat

Linux وmacOS وWSL 2 وGit Bash :

cd ../..
./labo.sh etat

travail atelier-1 : 1 ressource dans le state
Ressources encore gérées : 1 (0 attendu à la fin d'une séance).

الإجابة المنتظرة : 1 ressource dans le state (مورد واحد في state). عبارة (0 attendu à la fin d'une séance) (0 متوقع في نهاية الجلسة) هي تذكير العُدّة ؛ هنا من الطبيعي أن تكون عند 1، لأن الورشة 2 ستدمّر هذا المورد.

• كتبت main.tf من كتلة واحدة، بلا terraform {} ولا provider {}، وكان ذلك كافيًا.
• رأيت Error: Inconsistent dependency lock file وتعرف أن الحل في السطر الأخير.
• أنشأ init المجلد .terraform/ والملف .terraform.lock.hcl، ولا شيء آخر.
• تعرف قراءة خطة : + create، will be created، (known after apply)، Plan: 1 to add, 0 to change, 0 to destroy.
• طلب apply كلمة yes، وأنشأ bonjour.txt وterraform.tfstate.
• يُرجع state list القيمة local_file.bonjour ؛ ويُرجع state show الكتلة الكاملة مع id من أربعين حرفًا.
• يُرجع plan ثانٍ No changes.
• احتفظت بمخرجات terraform state show local_file.bonjour (الخطوة 9) كمخرج مطلوب.

إذا تعطّل شيء