تكوين صورة حاوية لتنفيذ عمليات التوزيع باستخدام Terraform

في هذه المقالة، ستتعلم كيفية إنشاء صور حاوية Terraform مخصصة لنشر تعريفات البيئة الخاصة بك في بيئات نشر Azure (ADE). يمكنك التعرف على كيفية تكوين صورة مخصصة لتوفير البنية الأساسية باستخدام إطار عمل Terraform Infrastructure-as-Code (IaC).

يتكون تعريف البيئة من ملفين على الأقل: ملف قالب، مثل main.tf، وملف بيان باسم environment.yaml. يمكنك استخدام حاوية لنشر تعريف البيئة الذي يستخدم Terraform.

يتيح لك نموذج قابلية توسعة ADE إنشاء صور حاوية مخصصة لاستخدامها مع تعريفات البيئة الخاصة بك. باستخدام نموذج القابلية للتوسعة، يمكنك إنشاء صور الحاوية المخصصة الخاصة بك وتخزينها في سجل حاوية مثل DockerHub. يمكنك بعد ذلك الرجوع إلى هذه الصور في تعريفات البيئة الخاصة بك لنشر بيئاتك.

المتطلبات الأساسية

• حساب Azure مع اشتراك نشط. أنشئ حساباً مجاناً.
• تم إعداد Azure Deployment Environments في اشتراك Azure الخاص بك.
  • لإعداد ADE، اتبع التشغيل السريع: تكوين بيئات نشر Azure.

إنشاء صورة حاوية Terraform مخصصة

يتيح لك إنشاء صورة حاوية مخصصة تخصيص عمليات النشر الخاصة بك لتناسب متطلباتك.

بعد إكمال تخصيص الصورة، يجب إنشاء الصورة ودفعها إلى سجل الحاوية.

إنشاء صورة حاوية وتخصيصها باستخدام Docker

في هذا المثال، ستتعلم كيفية إنشاء صورة Docker للاستفادة من عمليات نشر ADE والوصول إلى CLI ADE، استنادا إلى صورك على إحدى الصور التي ألفتها ADE.

ADE CLI هي أداة تسمح لك بإنشاء صور مخصصة باستخدام صور ADE الأساسية. يمكنك استخدام ADE CLI لتخصيص عمليات النشر والحذف لتناسب سير العمل الخاص بك. تم تثبيت ADE CLI مسبقا على عينات الصور. لمعرفة المزيد حول CLI ADE، راجع مرجع صورة مشغل CLI المخصص.

لإنشاء صورة تم تكوينها ل ADE، اتبع الخطوات التالية:

1. قم بإسناد صورتك إلى صورة عينة مؤلفة من ADE أو الصورة التي تختارها باستخدام عبارة FROM.
2. قم بتثبيت أي حزم ضرورية لصورتك باستخدام عبارة RUN.
3. أنشئ مجلد البرامج النصية في نفس مستوى Dockerfile الخاص بك، وقم بتخزين deploy.sh وملفات delete.sh داخله، وتأكد من أن هذه البرامج النصية قابلة للاكتشاف والتنفيذ داخل الحاوية التي تم إنشاؤها. هذه الخطوة ضرورية للنشر الخاص بك للعمل باستخدام الصورة الأساسية ADE.

حدد نموذج صورة حاوية باستخدام عبارة FROM

قم بتضمين عبارة FROM داخل DockerFile تم إنشاؤه لصورتك الجديدة التي تشير إلى نموذج صورة مستضاف على Microsoft Artifact Registry.

فيما يلي مثال على عبارة FROM، التي تشير إلى نموذج الصورة الأساسية:

FROM mcr.microsoft.com/deployment-environments/runners/core:latest

تسحب هذه العبارة أحدث صورة أساسية منشورة، وتجعلها أساسا لصورتك المخصصة.

تثبيت Terraform في Dockerfile

يمكنك تثبيت Terraform CLI إلى موقع قابل للتنفيذ بحيث يمكن استخدامه في البرامج النصية للتوزيع والحذف.

فيما يلي مثال على هذه العملية، تثبيت الإصدار 1.7.5 من Terraform CLI:

RUN wget -O terraform.zip https://releases.hashicorp.com/terraform/1.7.5/terraform_1.7.5_linux_amd64.zip
RUN unzip terraform.zip && rm terraform.zip
RUN mv terraform /usr/bin/terraform

تلميح

يمكنك الحصول على عنوان URL للتنزيل للإصدار المفضل لديك من Terraform CLI من إصدارات Hashicorp.

تستند صور عينة ADE إلى صورة Azure CLI، ويتم تثبيت حزم ADE CLI وJQ مسبقا. يمكنك معرفة المزيد حول Azure CLI وحزمة JQ.

لتثبيت أي حزم أخرى تحتاج إليها داخل صورتك، استخدم عبارة RUN.

تنفيذ البرامج النصية ل shell العملية

داخل نماذج الصور، يتم تحديد العمليات وتنفيذها استنادا إلى اسم العملية. حاليا، يتم نشر اسمي العملية المدعومين وحذفهما.

لإعداد صورتك المخصصة لاستخدام هذه البنية، حدد مجلدا على مستوى Dockerfile المسمى البرامج النصية، وحدد ملفين، deploy.sh، delete.sh. يتم تشغيل البرنامج النصي deploy shell عند إنشاء بيئتك أو إعادة توزيعها، ويتم تشغيل البرنامج النصي delete shell عند حذف البيئة الخاصة بك. يمكنك مشاهدة أمثلة على البرامج النصية shell في المستودع ضمن مجلد Runner-Images لصورة ARM-Bicep .

للتأكد من أن هذه البرامج النصية shell قابلة للتنفيذ، أضف الأسطر التالية إلى Dockerfile الخاص بك:

COPY scripts/* /scripts/
RUN find /scripts/ -type f -iname "*.sh" -exec dos2unix '{}' '+'
RUN find /scripts/ -type f -iname "*.sh" -exec chmod +x {} \;

تأليف البرامج النصية shell لاستخدام Terraform CLI

هناك ثلاث خطوات لنشر البنية الأساسية عبر Terraform:

1. terraform init - تهيئة Terraform CLI لتنفيذ الإجراءات داخل دليل العمل
2. terraform plan- تطوير خطة تستند إلى ملفات البنية الأساسية Terraform الواردة والمتغيرات، وأي ملفات حالة موجودة، وتطوير الخطوات اللازمة لإنشاء أو تحديث البنية الأساسية المحددة في ملفات .tf
3. terraform apply - يطبق الخطة لإنشاء بنية أساسية جديدة أو تحديث البنية الأساسية الموجودة في Azure

أثناء نقطة إدخال الصورة الأساسية، يتم سحب أي ملفات حالة موجودة إلى الحاوية والدليل المحفوظ ضمن متغير $ADE_STORAGEالبيئة . بالإضافة إلى ذلك، أي معلمات تم تعيينها للبيئة الحالية المخزنة ضمن المتغير $ADE_OPERATION_PARAMETERS. للوصول إلى ملف الحالة الموجود، وتعيين المتغيرات داخل ملف .tfvars.json ، قم بتشغيل الأوامر التالية:

EnvironmentState="$ADE_STORAGE/environment.tfstate"
EnvironmentPlan="/environment.tfplan"
EnvironmentVars="/environment.tfvars.json"

echo "$ADE_OPERATION_PARAMETERS" > $EnvironmentVars

بالإضافة إلى ذلك، لاستخدام امتيازات ADE لنشر البنية الأساسية داخل اشتراكك، يحتاج البرنامج النصي إلى استخدام هوية الخدمة المدارة (MSI) عند توفير البنية الأساسية باستخدام موفر Terraform AzureRM. إذا كان التوزيع يحتاج إلى أذونات خاصة لإكمال النشر، مثل أدوار معينة، فعين هذه الأذونات إلى هوية نوع بيئة المشروع التي يتم استخدامها لنشر البيئة الخاصة بك. يعين ADE متغيرات البيئة ذات الصلة، مثل معرفات العميل والمستأجر والاشتراك داخل نقطة إدخال الصورة الأساسية، لذا قم بتشغيل الأوامر التالية للتأكد من أن الموفر يستخدم ADE MSI:

export ARM_USE_MSI=true
export ARM_CLIENT_ID=$ADE_CLIENT_ID
export ARM_TENANT_ID=$ADE_TENANT_ID
export ARM_SUBSCRIPTION_ID=$ADE_SUBSCRIPTION_ID

إذا كان لديك متغيرات أخرى للإشارة إليها داخل القالب لم يتم تحديدها في معلمات البيئة الخاصة بك، فقم بتعيين متغيرات البيئة باستخدام البادئة TF_VAR. يتم توفير قائمة بمتغيرات بيئة ADE المتوفرة مرجع متغيرات Azure Deployment Environment CLI. ومن الأمثلة على هذه الأوامر ما يلي:

export TF_VAR_resource_group_name=$ADE_RESOURCE_GROUP_NAME
export TF_VAR_ade_env_name=$ADE_ENVIRONMENT_NAME
export TF_VAR_env_name=$ADE_ENVIRONMENT_NAME
export TF_VAR_ade_subscription=$ADE_SUBSCRIPTION_ID
export TF_VAR_ade_location=$ADE_ENVIRONMENT_LOCATION
export TF_VAR_ade_environment_type=$ADE_ENVIRONMENT_TYPE

الآن، يمكنك تشغيل الخطوات المذكورة سابقا لتهيئة Terraform CLI، وإنشاء خطة لتوفير البنية الأساسية، وتطبيق خطة أثناء البرنامج النصي للتوزيع:

terraform init
terraform plan -no-color -compact-warnings -refresh=true -lock=true -state=$EnvironmentState -out=$EnvironmentPlan -var-file="$EnvironmentVars"
terraform apply -no-color -compact-warnings -auto-approve -lock=true -state=$EnvironmentState $EnvironmentPlan

أثناء البرنامج النصي للحذف، يمكنك إضافة العلامة destroy إلى إنشاء خطتك لحذف الموارد الموجودة، كما هو موضح في المثال التالي:

terraform init
terraform plan -no-color -compact-warnings -destroy -refresh=true -lock=true -state=$EnvironmentState -out=$EnvironmentPlan -var-file="$EnvironmentVars"
terraform apply -no-color -compact-warnings -auto-approve -lock=true -state=$EnvironmentState $EnvironmentPlan

وأخيرا، لجعل مخرجات النشر الخاصة بك محملة ويمكن الوصول إليها عند الوصول إلى بيئتك عبر Azure CLI، قم بتحويل كائن الإخراج من Terraform إلى التنسيق المحدد من قبل ADE من خلال حزمة JQ. تعيين القيمة إلى متغير البيئة $ADE_OUTPUTS، كما هو موضح في المثال التالي:

tfOutputs=$(terraform output -state=$EnvironmentState -json)
# Convert Terraform output format to ADE format.
tfOutputs=$(jq 'walk(if type == "object" then 
            if .type == "bool" then .type = "boolean" 
            elif .type == "list" then .type = "array" 
            elif .type == "map" then .type = "object" 
            elif .type == "set" then .type = "array" 
            elif (.type | type) == "array" then 
                if .type[0] == "tuple" then .type = "array" 
                elif .type[0] == "object" then .type = "object" 
                elif .type[0] == "set" then .type = "array" 
                else . 
                end 
            else . 
            end 
        else . 
        end)' <<< "$tfOutputs")

echo "{\"outputs\": $tfOutputs}" > $ADE_OUTPUTS

جعل الصورة المخصصة قابلة للوصول إلى ADE

يجب إنشاء صورة Docker ودفعها إلى سجل الحاوية لجعلها متاحة للاستخدام في ADE. يمكنك إنشاء صورتك باستخدام Docker CLI، أو باستخدام برنامج نصي يوفره ADE.

حدد علامة التبويب المناسبة لمعرفة المزيد حول كل نهج.

إنشاء الصورة باستخدام Docker CLI

قبل إنشاء الصورة التي سيتم دفعها إلى السجل الخاص بك، تأكد من تثبيت Docker Engine على جهاز الكمبيوتر الخاص بك. ثم انتقل إلى دليل Dockerfile الخاص بك، ثم قم بتشغيل الأمر التالي:

docker build . -t {YOUR_REGISTRY}.azurecr.io/{YOUR_REPOSITORY}:{YOUR_TAG}

على سبيل المثال، إذا كنت تريد حفظ صورتك ضمن مستودع داخل السجل الخاص بك المسمى customImage، وتحميلها باستخدام إصدار العلامة من 1.0.0، يمكنك تشغيل:

docker build . -t {YOUR_REGISTRY}.azurecr.io/customImage:1.0.0

دفع صورة Docker إلى سجل

لاستخدام الصور المخصصة، تحتاج إلى إعداد سجل صور يمكن الوصول إليه بشكل عام مع تمكين سحب الصور المجهولة. بهذه الطريقة، يمكن لبيئات نشر Azure الوصول إلى صورتك المخصصة لتنفيذها في حاويتنا.

Azure Container Registry هو عرض Azure يخزن صور الحاوية والبيانات الاصطناعية المماثلة.

لإنشاء سجل، والذي يمكن القيام به من خلال Azure CLI ومدخل Azure والأوامر PowerShell والمزيد، اتبع إحدى عمليات التشغيل السريع.

لإعداد السجل الخاص بك لتمكين سحب الصور المجهولة، قم بتشغيل الأوامر التالية في Azure CLI:

az login
az acr login -n {YOUR_REGISTRY}
az acr update -n {YOUR_REGISTRY} --public-network-enabled true
az acr update -n {YOUR_REGISTRY} --anonymous-pull-enabled true

عندما تكون مستعدا لدفع صورتك إلى السجل الخاص بك، قم بتشغيل الأمر التالي:

docker push {YOUR_REGISTRY}.azurecr.io/{YOUR_IMAGE_LOCATION}:{YOUR_TAG}

إنشاء صورة حاوية باستخدام برنامج نصي

توفر Microsoft برنامج نصي للتشغيل السريع لمساعدتك على البدء. يقوم البرنامج النصي بإنشاء صورتك ودفعها إلى Azure Container Registry (ACR) محدد ضمن المستودع ade والعلامة latest.

لاستخدام البرنامج النصي، يجب عليك:

1. إنشاء مجلد Dockerfile والبرامج النصية لدعم نموذج قابلية توسعة ADE.
2. قم بتوفير اسم سجل ودليل لصورتك المخصصة.
3. تثبيت Azure CLI وDocker Desktop وفي متغيرات PATH.
4. لديك أذونات للدفع إلى السجل المحدد.

يمكنك عرض البرنامج النصي هنا.

يمكنك استدعاء البرنامج النصي باستخدام الأمر التالي في PowerShell:

.\quickstart-image-build.ps1 -Registry '{YOUR_REGISTRY}' -Directory '{DIRECTORY_TO_YOUR_IMAGE}'

بالإضافة إلى ذلك، إذا كنت ترغب في الدفع إلى مستودع معين واسم العلامة، يمكنك تشغيل:

.\quickstart-image.build.ps1 -Registry '{YOUR_REGISTRY}' -Directory '{DIRECTORY_TO_YOUR_IMAGE}' -Repository '{YOUR_REPOSITORY}' -Tag '{YOUR_TAG}'

الاتصال الصورة إلى تعريف البيئة الخاصة بك

عند تأليف تعريفات البيئة لاستخدام صورتك المخصصة في توزيعها، قم بتحرير runner الخاصية على ملف البيان (environment.yaml أو manifest.yaml).

runner: "{YOUR_REGISTRY}.azurecr.io/{YOUR_REPOSITORY}:{YOUR_TAG}"

الوصول إلى سجلات العمليات وتفاصيل الخطأ

يخزن ADE تفاصيل الخطأ لتوزيع فاشل في ملف $ADE_ERROR_LOG داخل الحاوية.

لاستكشاف أخطاء التوزيع الفاشلة وإصلاحها:

1. سجل الدخول إلى مدخل المطور.

2. حدد البيئة التي فشلت في النشر، وحدد عرض التفاصيل.

   

3. راجع تفاصيل الخطأ في قسم تفاصيل الخطأ.

   

بالإضافة إلى ذلك، يمكنك استخدام Azure CLI لعرض تفاصيل خطأ البيئة باستخدام الأمر التالي:

az devcenter dev environment show --environment-name {YOUR_ENVIRONMENT_NAME} --project {YOUR_PROJECT_NAME}

لعرض سجلات العملية لنشر بيئة أو حذفها، استخدم Azure CLI لاسترداد أحدث عملية بيئة، ثم اعرض سجلات معرف العملية هذا.

# Get list of operations on the environment, choose the latest operation
az devcenter dev environment list-operation --environment-name {YOUR_ENVIRONMENT_NAME} --project {YOUR_PROJECT_NAME}
# Using the latest operation ID, view the operation logs
az devcenter dev environment show-logs-by-operation --environment-name {YOUR_ENVIRONMENT_NAME} --project {YOUR_PROJECT_NAME} --operation-id {LATEST_OPERATION_ID}

المحتوى ذو الصلة

• مرجع صورة مشغل مخصص ل ADE CLI
• مرجع متغيرات ADE CLI