Cloud Foundation Toolkit 101

۱. مقدمه‌ای بر CFT 101

b1d2ab0f35bb62a8.png

آخرین به‌روزرسانی: 2022-02-11

جعبه ابزار بنیاد ابری چیست؟

در اصل، CFT الگوهای عملی برتر را برای شروع سریع در Google Cloud Platform ارائه می‌دهد. در این آموزش، نحوه مشارکت در جعبه ابزار بنیاد ابر را خواهید آموخت.

آنچه نیاز دارید

  • یک حساب کاربری گیت‌هاب.
  • داکر روی دستگاه شما نصب شده باشد یا از Cloud Shell استفاده کنید ( نصب مک ، نصب ویندوز )
  • ویرایشگر کد برای ویرایش کد (مثال: ویژوال استودیو کد )
  • آشنایی اولیه با گیت و گیت‌هاب
  • کمی تجربه با Terraform و زیرساخت به عنوان کد
  • اجازه اعطای نقش خالق پروژه به یک حساب سرویس
  • یک سازمان ابری گوگل، یک پوشه آزمایشی و یک حساب صورتحساب

آنچه خواهید ساخت

در این آزمایشگاه کد، شما یاد خواهید گرفت که چگونه در جعبه ابزار بنیاد ابری (CFT) مشارکت کنید.

شما:

  • راه‌اندازی یک محیط توسعه برای مشارکت در CFT
  • افزودن یک ویژگی به ماژول CFT
  • اضافه کردن تست برای ویژگی اضافه شده
  • اجرای تست‌های یکپارچه‌سازی در CFT
  • اجرای تست‌های Lint
  • کد را به GitHub ارسال کنید و یک درخواست Pull (PR) ارسال کنید

شما تمام مراحل فوق را با اضافه کردن یک ویژگی جدید به ماژول CFT ذخیره‌سازی ابری گوگل (Google Cloud Storage CFT) انجام خواهید داد. شما یک برچسب به نام "silly_label" اضافه خواهید کرد که به طور خودکار به تمام سطل‌های ایجاد شده از طریق ماژول CFT GCS اضافه می‌شود. همچنین می‌توانید تست‌هایی برای اعتبارسنجی ویژگی خود بنویسید و از ادغام سرتاسری اطمینان حاصل کنید.

۲. راه‌اندازی محیط توسعه

اگر بخواهید، می‌توانید از Cloud Shell برای اهداف توسعه خود استفاده کنید. اگر نمی‌خواهید از Cloud Shell برای مشارکت در CFT استفاده کنید، می‌توانید محیط توسعه خود را روی دستگاه خود تنظیم کنید.

گیت را راه‌اندازی کنید

گیت‌هاب بر اساس یک سیستم کنترل نسخه (VCS) متن‌باز به نام گیت (Git) ساخته شده است. گیت مسئول هر اتفاقی است که به صورت محلی روی دستگاه شما یا پوسته ابری شما و مرتبط با گیت‌هاب رخ می‌دهد.

  1. وقتی از Cloud Shell استفاده می‌کنید، نیازی به نصب git ندارید زیرا از قبل نصب شده است. 
$ git --version
# This will display the git version on the Cloud Shell.

اگر در حال راه‌اندازی محیط توسعه (dev environment) روی دستگاه خود هستید، باید گیت (Git) را نصب کنید.

تنظیم نام کاربری و ایمیل در گیت

گیت از یک نام کاربری برای مرتبط کردن کامیت‌ها با یک هویت استفاده می‌کند. نام کاربری گیت با نام کاربری گیت‌هاب شما یکسان نیست.

شما می‌توانید نامی را که با کامیت‌های گیت شما مرتبط است با استفاده از دستور git config تغییر دهید. تغییر نام مرتبط با کامیت‌های گیت شما با استفاده از git config فقط بر کامیت‌های آینده تأثیر می‌گذارد و نام مورد استفاده برای کامیت‌های گذشته را تغییر نمی‌دهد.

شما گیت را با موفقیت راه‌اندازی کرده‌اید و باید بتوانید شاخه‌ها را منشعب، ایجاد و کلون کنید. ما در این آزمایشگاه کد به طور گسترده از گیت استفاده خواهیم کرد.

۳. مخزن GCS فورک CFT

یک مخزن CFT ایجاد کنید

شما در مرحله قبل گیت را روی دستگاه محلی یا Cloud Shell خود راه‌اندازی کردید. اکنون برای شروع مشارکت، باید مخزن CFT ذخیره‌سازی ابری گوگل را فورک کنید.

یک انشعاب (fork) یک کپی از یک مخزن (repository) است. انشعاب یک مخزن به شما این امکان را می‌دهد که آزادانه تغییرات را بدون تأثیر بر پروژه اصلی آزمایش کنید.

معمولاً، از فورک‌ها برای پیشنهاد تغییرات در پروژه شخص دیگری یا استفاده از پروژه شخص دیگری به عنوان نقطه شروع برای ایده خودتان استفاده می‌شود.

برای مثال، می‌توانید از فورک‌ها برای پیشنهاد تغییرات مربوط به رفع یک اشکال استفاده کنید. برای رفع یک اشکال، می‌توانید:

  • مخزن را فورک کنید.
  • رفع اشکال کنید.
  • درخواست pull را به صاحب پروژه ارسال کنید.

مراحل فورک کردن یک مخزن CFT:

  1. مرورگر وب خود را باز کنید و به مخزن terraform-google-modules/terraform-google-cloud-storage بروید. ما از این مخزن برای کل Codelab استفاده خواهیم کرد.
  2. در گوشه سمت راست بالای صفحه، روی «چنگال» کلیک کنید.

9dc18f15ca662b56.png

  1. به شما گزینه‌ای برای محل قرارگیری فورک ارائه می‌شود، پروفایل خود را انتخاب کنید و مخزن فورک خواهد شد.

چنگال خود را به صورت محلی کلون کنید

انشعابی که ایجاد کردید یک کپی از مخزن ماژول GCS است. اکنون این مخزن را در محیط محلی خود کلون خواهید کرد تا ویژگی جدید خود را اضافه کنید.

مراحل کلون کردن چنگال شما:

  1. مرورگر وب خود را باز کنید و به شاخه terraform-google-modules/terraform-google-cloud-storage بروید.
  2. در گوشه بالا سمت راست، دکمه «کد» را پیدا خواهید کرد، روی آن کلیک کنید.

۹۸f۸be۸df۳۱۹dcd۸.png

  1. پس از کلیک بر روی دکمه "کد"، روی نماد "کپی" کلیک کنید تا URL چنگال کپی شود. شما از این URL برای کلون کردن چنگال خود در محیط محلی خود استفاده خواهید کرد.

e61e1da6371f2a1d.png

  1. به ترمینال VSCode یا دستگاه خود بروید و fork را کلون کنید. 
$ git clone <url>
# This command will clone your fork locally.
# Paste the copied URL from the previous step.
  1. حالا که فورک خود را به صورت محلی کلون کرده‌اید، باید به مخزن خود بروید، یک شاخه جدید از فورک ایجاد کنید و تغییرات کد را در شاخه موقت اعمال کنید.

طبق قرارداد، می‌توانید شاخه خود را به صورت زیر نامگذاری کنید:

  • برای درخواست ویژگی: feature/feature-name
  • برای به‌روزرسانی‌های داخلی، internal/change-name
  • برای رفع اشکال: bugfix/issue-name

از آنجایی که در حال اضافه کردن یک ویژگی جدید هستید، می‌توانید شاخه موقت خود را feature/silly_label فراخوانی کنید.

$ cd terraform-google-cloud-storage
# This command takes you into the cloned directory on your local machine.

$ git branch
# This command tells your current branch
# When you run this for the first time after you have cloned, your 
# output should say "master", that is your fork.

$ git checkout -b feature/silly_label
# This command creates a new branch on your fork and switches your 
# branch to the newly created branch.

$ git branch
# This command will confirm your current branch to be "feature/silly_label"

اکنون همه چیز برای شروع کار روی جعبه ابزار بنیاد ابری آماده است!

۴. یک محیط آزمایشی ایجاد کنید

فرآیند توسعه استاندارد CFT مبتنی بر استفاده از یک پروژه آزمایشی مجزا برای آزمایش است. این مرحله شما را در ایجاد پروژه آزمایشی (بر اساس پیکربندی استاندارد) از طریق یک حساب کاربری سرویس راهنمایی می‌کند.

0. نصب موتور داکر

اگر از دستگاه خود برای اهداف توسعه استفاده می‌کنید، باید Docker Engine را نصب کنید.

۱. نصب SDK گوگل کلود

اگر از GCP Cloud Shell استفاده می‌کنید، نیازی به نصب Google Cloud SDK ندارید.

به Google Cloud SDK بروید و نصب‌کننده تعاملی را برای پلتفرم خود دانلود کنید.

۲. پیکربندی را تنظیم کنید

برای ایجاد یک محیط آزمایشی، به یک سازمان ابری گوگل، یک پوشه آزمایشی و یک حساب صورتحساب نیاز دارید. این مقادیر باید از طریق متغیرهای محیطی تنظیم شوند:

export TF_VAR_org_id="your_org_id"
export TF_VAR_folder_id="your_folder_id"
export TF_VAR_billing_account="your_billing_account_id"

۳. حساب کاربری سرویس خود را تنظیم کنید

قبل از ایجاد یک محیط آزمایشی، باید یک کلید حساب سرویس برای محیط آزمایشی خود دانلود کنید. این حساب سرویس به نقش‌های سازنده پروژه، کاربر حساب صورتحساب و بیننده سازمان نیاز دارد. این مراحل به شما کمک می‌کند تا یک حساب سرویس جدید ایجاد کنید، اما می‌توانید از یک حساب موجود نیز دوباره استفاده کنید.

۳.۱ ایجاد یا انتخاب پروژه GCP اولیه

قبل از ایجاد حساب کاربری سرویس خود، باید یک پروژه برای میزبانی آن انتخاب کنید. همچنین می‌توانید یک پروژه جدید ایجاد کنید.

gcloud config set core/project YOUR_PROJECT_ID

۳.۲ فعال کردن APIهای گوگل کلود

API های Google Cloud زیر را در پروژه اصلی خود فعال کنید:

gcloud services enable cloudresourcemanager.googleapis.com
gcloud services enable iam.googleapis.com
gcloud services enable cloudbilling.googleapis.com

۳.۳ ایجاد حساب کاربری سرویس

برای مدیریت محیط تست، یک حساب کاربری سرویس جدید ایجاد کنید:

# Creating a service account for CFT.
gcloud iam service-accounts create cft-onboarding \
  --description="CFT Onboarding Terraform Service Account" \
  --display-name="CFT Onboarding"

# Assign SERVICE_ACCOUNT environment variable for later steps
export SERVICE_ACCOUNT=cft-onboarding@$(gcloud config get-value core/project).iam.gserviceaccount.com

تأیید کنید که حساب سرویس شما ایجاد شده است:

gcloud iam service-accounts list --filter="EMAIL=${SERVICE_ACCOUNT}"

۳.۴ اعطای نقش‌های ایجادکننده پروژه، کاربر حساب صورتحساب و مشاهده‌گر سازمان به حساب سرویس:

gcloud resource-manager folders add-iam-policy-binding ${TF_VAR_folder_id} \
  --member="serviceAccount:${SERVICE_ACCOUNT}" \
  --role="roles/resourcemanager.projectCreator"
gcloud organizations add-iam-policy-binding ${TF_VAR_org_id} \
  --member="serviceAccount:${SERVICE_ACCOUNT}" \
  --role="roles/billing.user"
gcloud beta billing accounts add-iam-policy-binding ${TF_VAR_billing_account} \
  --member="serviceAccount:${SERVICE_ACCOUNT}" \
  --role="roles/billing.user"
gcloud organizations add-iam-policy-binding ${TF_VAR_org_id} \
  --member="serviceAccount:${SERVICE_ACCOUNT}" \
  --role="roles/resourcemanager.organizationViewer"

اکنون شما یک حساب کاربری سرویس دارید که می‌تواند برای مدیریت محیط تست استفاده شود.

۴. اعتبارنامه Terraform را آماده کنید

برای ایجاد محیط آزمایشی، باید کلید حساب سرویس را در پوسته خود دانلود کنید.

۴.۱ کلید حساب سرویس

یک کلید حساب کاربری سرویس برای Terraform ایجاد و دانلود کنید 

gcloud iam service-accounts keys create cft.json --iam-account=${SERVICE_ACCOUNT}

۴.۲ راه‌اندازی اعتبارنامه Terraform

با استفاده از متغیر محیطی SERVICE_ACCOUNT_JSON ، کلید را به Terraform ارائه دهید و مقدار آن را برابر با محتوای کلید حساب سرویس خود تنظیم کنید. 

export SERVICE_ACCOUNT_JSON=$(< cft.json)

پس از ذخیره اطلاعات اعتبارنامه در متغیر محیطی، فایل کلیدی را حذف کنید. در صورت نیاز می‌توانید بعداً با استفاده از همان دستور بالا، یک کلید را دوباره ایجاد کنید. 

rm -rf cft.json

۵. ایجاد پروژه آزمایشی برای استقرار Terraform

حالا که همه چیز آماده شده است، می‌توانید پروژه آزمایشی را با یک دستور واحد ایجاد کنید. این دستور را از دایرکتوری ریشه terraform-google-cloud-storage اجرا کنید: 

make docker_test_prepare

هنگام اجرای دستور make docker_test_prepare ، خروجی زیر را مشاهده خواهید کرد. در پایان، test project_id ایجاد شده را دریافت خواهید کرد که در آن ماژول Cloud Storage خود را با ویژگی جدید خود مستقر و آزمایش خواهید کرد. اگر در اتصال حساب صورتحساب با مشکل مواجه شدید، به مراحل عیب‌یابی مراجعه کنید. 

macbookpro3:terraform-google-cloud-storage user$ make docker_test_prepare
docker run --rm -it \
                -e SERVICE_ACCOUNT_JSON \
                -e TF_VAR_org_id \
                -e TF_VAR_folder_id \
                -e TF_VAR_billing_account \
                -v /Users/cft/terraform-google-cloud-storage:/workspace \
                gcr.io/cloud-foundation-cicd/cft/developer-tools:0.8.0 \
                /usr/local/bin/execute_with_credentials.sh prepare_environment
Activated service account credentials for: [cft-onboarding@<project_id>.iam.gserviceaccount.com]
Activated service account credentials for: [cft-onboarding@<project_id>.iam.gserviceaccount.com]
Initializing modules...

Initializing the backend...

Initializing provider plugins...

The following providers do not have any version constraints in configuration,
so the latest version was installed.

To prevent automatic upgrades to new major versions that may contain breaking
changes, it is recommended to add version = "..." constraints to the
corresponding provider blocks in configuration, with the constraint strings
suggested below.

* provider.google-beta: version = "~> 3.9"
* provider.null: version = "~> 2.1"
* provider.random: version = "~> 2.2"

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.

If you ever set or change modules or backend configuration for Terraform,
rerun this command to reinitialize your working directory. If you forget, other
commands will detect it and remind you to do so if necessary.
module.project.module.project-factory.null_resource.preconditions: Refreshing state... [id=8723188031607443970]
module.project.module.project-factory.null_resource.shared_vpc_subnet_invalid_name[0]: Refreshing state... [id=5109975723938185892]
module.project.module.gsuite_group.data.google_organization.org[0]: Refreshing state...
module.project.module.project-factory.random_id.random_project_id_suffix: Refreshing state... [id=rnk]
module.project.module.project-factory.google_project.main: Refreshing state... [id=<project-id>]
module.project.module.project-factory.google_project_service.project_services[0]: Refreshing state... [id=<project-id>/storage-api.googleapis.com]
module.project.module.project-factory.google_project_service.project_services[1]: Refreshing state... [id=<project-id>/cloudresourcemanager.googleapis.com]
module.project.module.project-factory.google_project_service.project_services[2]: Refreshing state... [id=<project-id>/compute.googleapis.com]
module.project.module.project-factory.data.null_data_source.default_service_account: Refreshing state...
module.project.module.project-factory.google_service_account.default_service_account: Refreshing state... [id=projects/ci-cloud-storage-ae79/serviceAccounts/project-service-account@<project-id>.iam.gserv
iceaccount.com]
module.project.module.project-factory.google_project_service.project_services[3]: Refreshing state... [id=<project-id>/serviceusage.googleapis.com]
module.project.module.project-factory.null_resource.delete_default_compute_service_account[0]: Refreshing state... [id=3576396874950891283]
google_service_account.int_test: Refreshing state... [id=projects/<project-id>/serviceAccounts/cft-onboarding@<project-id>.iam.gserviceaccount.com]
google_service_account_key.int_test: Refreshing state... [id=projects/<project-id>/serviceAccounts/cft-onboarding@<project-id>.iam.gserviceaccount.com/keys/351009a1e011e88049ab2097994d1c627a61
6961]
google_project_iam_member.int_test[1]: Refreshing state... [id=<project-id>/roles/iam.serviceAccountUser/serviceaccount:cft-onboarding@<project-id>.iam.gserviceaccount.com]
google_project_iam_member.int_test[0]: Refreshing state... [id=<project-id>/roles/storage.admin/serviceaccount:cft-onboarding@<project-id>.iam.gserviceaccount.com]

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

Outputs:

project_id = <test-project-id>
sa_key = <sensitive>
Found test/setup/make_source.sh. Using it for additional explicit environment configuration.

اکنون یک پروژه آزمایشی ایجاد کرده‌اید که همانطور که در خروجی کنسول مشاهده می‌کنید، توسط project_id ارجاع داده شده است. محیط توسعه و آزمایش شما راه‌اندازی شده است.

۵. اضافه کردن یک ویژگی جدید به ماژول CFT

اکنون محیط توسعه و آزمایش شما راه‌اندازی شده است، بیایید ویژگی "silly_label" خود را به ماژول CFT google-cloud-storage اضافه کنیم.

مطمئن شوید که در پوشه‌ی terraform-google-cloud-storage هستید و فایل main.tf را همانطور که در زیر می‌بینید، در ساختار پوشه باز کنید.

ac1dba25408abd09.png

از آنجایی که "silly_label" یک برچسب است، شما این ویژگی را در خط ۲۷ در متغیر "labels" در main.tf اضافه خواهید کرد، همانطور که در زیر می‌بینید:

Terraform-google-cloud-storage/main.tf 

resource "google_storage_bucket" "buckets" {
 <...>
 storage_class = var.storage_class
 // CODELAB:Add silly label in labels variable
 labels        = merge(var.labels, { name = replace("${local.prefix}${lower(each.value)}", ".", "-") }, { "silly" = var.silly_label })
 force_destroy = lookup(
 <...>
}

حالا، متغیر stupid_label را در فایل variables.tf که در ساختار پوشه بالا می‌بینید، اضافه خواهید کرد.

کد زیر را کپی و در خط ۳۱ در variables.tf اضافه کنید و مطمئن شوید که یک کاراکتر خط جدید در بالا و پایین بلوک متغیری که اضافه می‌کنید، قرار داده‌اید.

فایل terraform-google-cloud-storage/variables.tf 

variable "names" {
 description = "Bucket name suffixes."
 type        = list(string)
}

// CODELAB: Add "silly_label" variable to variables.tf between "names" and "location"
variable "silly_label" {
 description = "Sample label for bucket."
 type        = string
}

variable "location" {
 description = "Bucket location."
 default     = "EU"
}

۶. اضافه کردن یک ویژگی جدید به نمونه‌ی سطل ذخیره‌سازی

شما ویژگی مورد نظر خود را به فایل main.tf ماژول اضافه کرده‌اید و اکنون می‌توانید ویژگی اضافه شده را از طریق یک مثال آزمایش کنید.

"silly_label" باید به فایل examples/multiple-buckets/main.tf اضافه شود.

این مثال در مرحله بعدی برای انجام تست‌های یکپارچه‌سازی استفاده خواهد شد.

متغیر stupid_label زیر را در خط ۲۷ در main.tf در terraform-google-cloud-storage/examples/multiple-buckets/ کپی و پیست کنید، همانطور که در ساختار پوشه مشاهده می‌شود:

5224fefbbcc61d89.png

terraform-google-cloud-storage/examples/multiple-buckets/main.tf 

module "cloud_storage" {
 <...>
 // CODELAB: Add "silly_label" as an example to main.tf.
 silly_label        = "awesome"

 <..>
}

۷. تست طرح اولیه را برای بررسی ویژگی‌ها به‌روزرسانی کنید

شما ویژگی خود را به main.tf ماژول اضافه کرده‌اید و سپس آن ویژگی را به مثال multiple_buckets اضافه کرده‌اید. اکنون، باید ویژگی خود را از طریق یک تست ادغام طرح کلی که با زبان Golang نوشته شده است، آزمایش کنید.

شما تست‌های جدید خود را در فایل multiple_buckets_test.go که در ساختار پوشه زیر قرار دارد، اضافه خواهید کرد:

72ea272d4792405.png

شما "silly_label" را به تمام سطل‌هایی که از طریق ماژول multiple_buckets ایجاد می‌شوند اضافه کرده‌اید و اکنون باید تست‌هایی برای آزمایش ویژگی جدید بنویسید.

در کد زیر، شما برچسب هر سطل را از طریق دستور gcloud alpha storage دریافت می‌کنید و سپس خروجی برگشتی از دستور را بررسی می‌کنید.

تست/یکپارچه‌سازی/multiple_buckets/multiple_buckets_test.go 

func TestMultipleBuckets(t *testing.T) {
 <..>
op := gcloud.Run(t, fmt.Sprintf("alpha storage ls --buckets gs://%s", bucketName), gcloudArgs).Array()[0]

// verify silly label on each bucket
assert.Equal("awesome", op.Get("metadata.labels.silly").String(), "should have silly label set to awesome")

// verify lifecycle rules
...
}

۸. اجرای تست‌های یکپارچه‌سازی در CFT

تست یکپارچه‌سازی

تست‌های یکپارچه‌سازی برای تأیید رفتار ماژول ریشه، زیرماژول‌ها و مثال‌ها استفاده می‌شوند. اضافات، تغییرات و اصلاحات باید با تست‌ها همراه باشند.

تست‌های یکپارچه‌سازی با استفاده از چارچوب تست طرح نوشته شده و با استفاده از CFT CLI اجرا می‌شوند. این ابزارها برای راحتی در یک تصویر داکر بسته‌بندی شده‌اند.

استراتژی کلی برای این تست‌ها، تأیید رفتار ماژول‌های نمونه است، به این ترتیب اطمینان حاصل می‌شود که ماژول ریشه، زیرماژول‌ها و ماژول‌های نمونه همگی از نظر عملکردی صحیح هستند.

در اجرای تعاملی، شما هر مرحله را از طریق چندین دستور اجرا می‌کنید.

  1. برای شروع آزمایش کانتینر داکر در حالت تعاملی، make docker_run را اجرا کنید.

Make یک ابزار اتوماسیون ساخت است که به طور خودکار برنامه‌ها و کتابخانه‌های اجرایی را از کد منبع با خواندن فایل‌هایی به نام Makefiles می‌سازد که نحوه استخراج برنامه هدف را مشخص می‌کنند. هنگامی که تغییرات فایل را ایجاد می‌کنید، کانتینر داکر باید به طور خودکار به‌روزرسانی شود.

وقتی دستور make docker_run اجرا می‌کنید، یک فضای کاری در کانتینر داکر خود ایجاد می‌کنید و اعتبارنامه‌ها را برای حساب سرویس خود فعال می‌کنید. این فضای کاری در مراحل بعدی برای اجرای تست‌ها استفاده خواهد شد.

خروجی زیر را در ترمینال خود مشاهده خواهید کرد: 

Activated service account credentials for: [cft@<PROJECT_ID>.iam.gserviceaccount.com]
  1. برای تنظیم فایل‌های main.tf نمونه جهت وارد کردن ماژول‌ها از فایل‌های محلی شما به جای ماژول‌های منتشر شده، module-swapper -registry-prefix=terraform-google-modules را اجرا کنید.

باید خروجی مانند زیر را در ترمینال خود ببینید: 

[root@<CONTAINER_ID> workspace]# module-swapper -registry-prefix=terraform-google-modules
2025/08/04 19:26:29 Module name set from remote to cloud-storage
2025/08/04 19:26:29 Modifications made to file /workspace/examples/multiple_buckets/main.tf
2025/08/04 19:26:29 --- Original
+++ Modified
@@ -21,7 +21,7 @@
 }
 
 module "cloud_storage" {
-  source = "terraform-google-modules/cloud-storage/google"
+  source = "../.."
   # [restore-marker]   version = "~> 10.0"
 
   project_id = var.project_id
  1. دستور cft test list اجرا کنید تا تمام تست‌های طرح اولیه (blueprints) در فضای کاری شما فهرست شوند.

خروجی زیر را در ترمینال خود مشاهده خواهید کرد: 

[root@CONTAINER_ID workspace]# cft test list
 NAME                           | CONFIG                    | LOCATION                                                   
--------------------------------+---------------------------+------------------------------------------------------------
 TestAll/examples/simple_bucket | examples/simple_bucket    | test/integration/discover_test.go                          
 TestMultipleBuckets            | examples/multiple_buckets | test/integration/multiple_buckets/multiple_buckets_test.go
  1. برای مقداردهی اولیه مثال cft test run <EXAMPLE_NAME> --stage init اجرا کنید. در این حالت، برای مقداردهی اولیه اجرای تست TestMultipleBuckets ، cft test run TestMultipleBuckets --stage init . همچنین می‌توانید از پرچم --verbose برای دریافت اطلاعات بیشتر هنگام اجرای تست‌ها استفاده کنید.

این مرحله‌ی آغازین، نمونه‌ی Terraform را مقداردهی اولیه می‌کند.

خروجی زیر را در ترمینال خود مشاهده خواهید کرد. 

[root@<CONTAINER_ID> workspace]# cft test run TestMultipleBuckets --stage init --verbose
INFO[02-09|08:24:31] using test-dir: test/integration 
...
TestMultipleBuckets 2022-02-09T08:24:35Z command.go:179: Terraform has been successfully initialized!
...
TestMultipleBuckets 2022-02-09T08:24:35Z command.go:100: Running command terraform with args [validate]
TestMultipleBuckets 2022-02-09T08:24:36Z command.go:179: Success! The configuration is valid.
...
--- PASS: TestMultipleBuckets (4.05s)
  1. برای اعمال ماژول مثال، cft test run <EXAMPLE_NAME> --stage apply اجرا کنید.

این مرحله، مثال مقداردهی اولیه شده در مرحله قبل را روی پروژه GCP که قبلاً در Codelab ایجاد شده است، اعمال می‌کند.

خروجی زیر را در ترمینال خود مشاهده خواهید کرد. 

[root@<CONTAINER_ID> workspace]# cft test run TestMultipleBuckets --stage apply --verbose
INFO[02-09|08:28:11] using test-dir: test/integration
...
TestMultipleBuckets 2022-02-09T08:28:19Z command.go:179: Apply complete! Resources: 6 added, 0 changed, 0 destroyed.
TestMultipleBuckets 2022-02-09T08:28:19Z command.go:179: 
TestMultipleBuckets 2022-02-09T08:28:19Z command.go:179: Outputs:
TestMultipleBuckets 2022-02-09T08:28:19Z command.go:179: 
TestMultipleBuckets 2022-02-09T08:28:19Z command.go:179: names = {
TestMultipleBuckets 2022-02-09T08:28:19Z command.go:179:   "one" = "multiple-buckets-erp1-eu-one"
...
--- PASS: TestMultipleBuckets (6.51s)
PASS
ok      github.com/terraform-google-modules/terraform-google-cloud-storage/test/integration/multiple_buckets    6.548s
  1. دستور cft test run <EXAMPLE_NAME> --stage verify اجرا کنید تا تأیید شود که مثال، زیرساخت مورد انتظار را ایجاد کرده است.

این مرحله تابع تأیید را در TestMultipleBuckets اجرا می‌کند. معمولاً تأیید از طریق اجرای یک دستور gcloud برای بازیابی خروجی JSON برای وضعیت فعلی یک منبع و تأیید اینکه وضعیت فعلی مطابق با مثال اعلام شده است، انجام می‌شود.

اگر خطایی دریافت کردید، خواهید دید که چه چیزی مورد انتظار بوده و چه چیزی توسط دستور برای تست دریافت شده است.

خروجی زیر را در ترمینال خود مشاهده خواهید کرد. 

[root@<CONTAINER_ID> workspace]# cft test run TestMultipleBuckets --stage verify --verbose
INFO[02-09|08:30:19] using test-dir: test/integration
...
TestMultipleBuckets 2022-02-09T08:30:27Z command.go:100: Running command terraform with args [output -no-color -json names_list]
TestMultipleBuckets 2022-02-09T08:30:27Z command.go:179: ["multiple-buckets-erp1-eu-one","multiple-buckets-erp1-eu-two"]
TestMultipleBuckets 2022-02-09T08:30:27Z command.go:100: Running command gcloud with args [alpha storage ls --buckets gs://multiple-buckets-erp1-eu-one --project ci-cloud-storage-8ce9 --json]
TestMultipleBuckets 2022-02-09T08:30:28Z command.go:179: [
TestMultipleBuckets 2022-02-09T08:30:28Z command.go:179: {
TestMultipleBuckets 2022-02-09T08:30:28Z command.go:179:   "url": "gs://multiple-buckets-erp1-eu-one/",
...
TestMultipleBuckets 2022-02-09T08:30:33Z command.go:179: ]
2022/02/09 08:30:33 RUN_STAGE env var set to verify
2022/02/09 08:30:33 Skipping stage teardown
--- PASS: TestMultipleBuckets (12.32s)
PASS
ok      github.com/terraform-google-modules/terraform-google-cloud-storage/test/integration/multiple_buckets    12.359s
  1. برای تجزیه و تحلیل مثال cft test run <EXAMPLE_NAME> --stage teardown اجرا کنید.

این مرحله زیرساختی را که در مراحل بالا ایجاد کرده‌اید، از بین می‌برد. این مرحله همچنین سطل‌های GCS ایجاد شده در پروژه را به همراه برچسبی که به ماژول GCS اضافه کرده‌اید، از بین خواهد برد.

می‌توانید خروجی زیر را در ترمینال خود مشاهده کنید. 

[root@<CONTAINER_ID> workspace]# cft test run TestMultipleBuckets --stage teardown --verbose
INFO[02-09|08:36:02] using test-dir: test/integration
...
TestMultipleBuckets 2022-02-09T08:36:06Z command.go:100: Running command terraform with args [destroy -auto-approve -input=false -lock=false]
TestMultipleBuckets 2022-02-09T08:36:07Z command.go:179: module.cloud_storage.random_id.bucket_suffix: Refreshing state... [id=mNA]
TestMultipleBuckets 2022-02-09T08:36:07Z command.go:179: random_string.prefix: Refreshing state... [id=erp1]
TestMultipleBuckets 2022-02-09T08:36:08Z command.go:179: module.cloud_storage.google_storage_bucket.buckets["two"]: Refreshing state... [id=multiple-buckets-erp1-eu-two]
...
TestMultipleBuckets 2022-02-09T08:36:10Z command.go:179: Destroy complete! Resources: 6 destroyed.
TestMultipleBuckets 2022-02-09T08:36:10Z command.go:179: 
--- PASS: TestMultipleBuckets (6.62s)
PASS
ok      github.com/terraform-google-modules/terraform-google-cloud-storage/test/integration/multiple_buckets    6.654s
  1. برای لغو تنظیمات فایل‌های main.tf نمونه از آخرین باری که module-swapper را اجرا کردید module-swapper -registry-prefix=terraform-google-modules -restore اجرا کنید. 
[root@<CONTAINER_ID> workspace]# module-swapper -registry-prefix=terraform-google-modules -restore
2025/08/04 19:30:41 Module name set from remote to cloud-storage
2025/08/04 19:36:32 Modifications made to file /workspace/examples/multiple_buckets/main.tf
2025/08/04 19:36:32 --- Original
+++ Modified
@@ -21,8 +21,8 @@
 }
 
 module "cloud_storage" {
-  source = "../.."
-   version = "~> 10.0"
+  source  = "terraform-google-modules/cloud-storage/google"
+  version = "~> 10.0"
 
   project_id = var.project_id
  1. برای خروج از محفظه آزمایش، exit را اجرا کنید.

۹. تولید مستندات برای ورودی‌ها و خروجی‌ها

جداول ورودی‌ها و خروجی‌ها در README های ماژول ریشه، زیرماژول‌ها و ماژول‌های نمونه به طور خودکار بر اساس variables و outputs ماژول‌های مربوطه تولید می‌شوند. در صورت تغییر رابط‌های ماژول، این جداول باید به‌روزرسانی شوند.

اجرا: 

make generate_docs
# This will generate new Inputs and Outputs tables

۱۰. تست‌های lint را در CFT اجرا کنید

لینتر ابزاری است که کد منبع را تجزیه و تحلیل می‌کند تا خطاهای برنامه‌نویسی، اشکالات، خطاهای سبکی و ساختارهای مشکوک را علامت‌گذاری کند.

بسیاری از فایل‌های موجود در مخزن را می‌توان برای حفظ استاندارد کیفیت، lint یا قالب‌بندی کرد. برای اطمینان از کیفیت در CFT، از تست lint استفاده خواهید کرد.

اجرا: 

make docker_test_lint
# This will run all lint tests on your repo

۱۱. ارسال درخواست Pull در گیت‌هاب

حالا که کد خود را به صورت محلی تغییر داده‌اید و آن را از طریق تست‌های یکپارچه‌سازی آزمایش کرده‌اید، می‌خواهید این کد را در مخزن اصلی منتشر کنید.

برای اینکه کد شما در مخزن اصلی (master repo) در دسترس قرار گیرد، باید تغییرات کد را در شاخه خود ثبت (commit) کرده و آن را به مخزن اصلی (master repository) ارسال (push) کنید. برای اینکه کد شما به مخزن اصلی که در ابتدای Codelab آن را فورک کرده‌اید اضافه شود، پس از ثبت کد در مخزن خود، یک درخواست Pull (PR) در مخزن اصلی ایجاد خواهید کرد.

وقتی PR را افزایش می‌دهید، به مدیر مخزن اطلاع داده می‌شود تا تغییرات کد پیشنهادی را بررسی کند. علاوه بر این، می‌توانید کاربران دیگری را نیز به عنوان داور اضافه کنید تا در مورد تغییرات کد خود بازخورد دریافت کنید. PR باعث ایجاد یک Cloud Build می‌شود که آزمایش‌هایی را روی مخزن اجرا می‌کند.

بر اساس تغییرات کد شما، بررسی‌کنندگان کد، نظرات خود را در مورد کد شما ارائه می‌دهند و در صورت نیاز به تغییر، بر اساس بهترین شیوه‌ها و مستندات، درخواست اصلاح می‌کنند. مدیر، تغییرات کد شما را بررسی می‌کند، اطمینان حاصل می‌کند که کد شما با مخزن اصلی مطابقت دارد و ممکن است دوباره از شما بخواهد قبل از ادغام کد خود در مخزن اصلی، تغییراتی ایجاد کنید.

مراحل زیر را برای ارسال کد به شاخه‌ی انشعاب یافته و ارسال کد به شاخه‌ی انشعاب یافته انجام دهید:

  1. اولین قدم اضافه کردن فایل‌های تغییر یافته به مخزن محلی است. 
$ git add main.tf
$ git add README.md
$ git add variables.tf
$ git add examples/multiple-buckets/main.tf
$ git add test/integration/multiple_buckets/multiple_buckets_test.go
# The ‘git add' command adds the file in the local repository and 
# stages the file for commit. To unstage a file, use git reset HEAD YOUR-FILE
  1. فایل‌های شما اکنون مرحله‌بندی شده‌اند، در مرحله بعد باید تغییرات را اعمال کنید. 
$ git commit -m "First CFT commit"
# This will commit the staged changes and prepares them to be pushed 
# to a remote repository. To remove this commit and modify the file, 
# use 'git reset --soft HEAD~1' and commit and add the file again.
  1. تغییرات اعمال‌شده در مخزن محلی خود را برای ایجاد یک درخواست Pull (PR) به GitHub ارسال کنید. 
$ git push -u origin feature/silly_label
# Pushes the changes in your local repository up to the remote
# repository you specified as the origin

تغییرات کد شما اکنون برای درخواست Pull آماده است!

مراحل زیر را برای ایجاد یک PR در مخزن terraform-google-modules/terraform-google-cloud-storage انجام دهید :

  1. در مرورگر وب خود، به صفحه اصلی مخزن بروید.
  2. شما از طریق بنر پیشنهادی برای باز کردن PR از فورک خود مشاهده خواهید کرد. روی "مقایسه و درخواست pull" کلیک کنید.

60e7ae0cbc11588e.png

  1. یک عنوان و توضیح برای درخواست pull خود وارد کنید تا تغییرات کد شما را توصیف کند. تا حد امکان دقیق و در عین حال مختصر باشید.

f4302385e9e1776a.png

  1. برای ایجاد یک درخواست pull که آماده بررسی باشد، روی «ایجاد درخواست pull» کلیک کنید.
  2. خواهید دید که Cloud Build Triggers در حال اجرا هستند که به دلیل PR فعال می‌شوند.
  3. در صورت بروز هرگونه مشکل، برای باز کردن درخواست‌های pull از فورک‌ها به مستندات رسمی گیت‌هاب مراجعه کنید.

شما با موفقیت اولین تغییر کد خود را به شاخه‌ی انشعاب‌یافته‌تان پوش کردید و اولین CFT PR خود را در برابر شاخه‌ی اصلی افزایش دادید!

۱۲. تبریک

تبریک می‌گویم، شما با موفقیت یک ویژگی را به ماژول CFT اضافه کردید و یک PR برای بررسی ارسال کردید!

شما یک ویژگی را به یک ماژول CFT اضافه کردید، آن را به صورت محلی از طریق یک مثال آزمایش کردید و قبل از ارسال کد خود به GitHub، تست‌هایی را انجام دادید. در نهایت، یک PR برای بررسی و ادغام نهایی در CFT ایجاد کردید.

اکنون مراحل مهم برای شروع کار با جعبه ابزار بنیاد ابری را می‌دانید.