Mengonfigurasi gambar kontainer untuk menjalankan penyebaran dengan ARM dan Bicep

Artikel
05/31/2024

Dalam artikel ini, Anda mempelajari cara membuat gambar kontainer Azure Resource Manager (ARM) dan Bicep kustom untuk menyebarkan definisi lingkungan Anda di Azure Deployment Environments (ADE).

Definisi lingkungan terdiri dari setidaknya dua file: file templat, seperti azuredeploy.json atau main.bicep, dan file manifes bernama environment.yaml. ADE menggunakan kontainer untuk menyebarkan definisi lingkungan, dan secara asli mendukung kerangka kerja ARM dan Bicep IaC.

Model ekstensibilitas ADE memungkinkan Anda membuat gambar kontainer kustom untuk digunakan dengan definisi lingkungan Anda. Dengan menggunakan model ekstensibilitas, Anda dapat membuat gambar kontainer kustom Anda sendiri, dan menyimpannya dalam registri kontainer seperti DockerHub. Anda kemudian dapat mereferensikan gambar-gambar ini dalam definisi lingkungan Anda untuk menyebarkan lingkungan Anda.

Tim ADE menyediakan pilihan gambar untuk membantu Anda memulai, termasuk gambar inti, dan gambar Azure Resource Manager (ARM)/Bicep. Anda dapat mengakses gambar sampel ini di folder Runner-Images .

Prasyarat

Akun Azure dengan langganan aktif. Buat akun secara gratis.
Lingkungan Penyebaran Azure disiapkan di langganan Azure Anda.
- Untuk menyiapkan ADE, ikuti Mulai Cepat: Mengonfigurasi Lingkungan Penyebaran Azure.

Menggunakan gambar kontainer dengan ADE

Anda dapat mengambil salah satu pendekatan berikut untuk menggunakan gambar kontainer dengan ADE:

Gunakan gambar kontainer standar: Untuk skenario sederhana, gunakan gambar kontainer Bicep standar yang disediakan oleh ADE.
Membuat gambar kontainer kustom: Untuk skenario yang lebih kompleks, buat gambar kontainer kustom yang memenuhi persyaratan spesifik Anda.

Terlepas dari pendekatan mana yang Anda pilih, Anda harus menentukan gambar kontainer dalam definisi lingkungan Anda untuk menyebarkan sumber daya Azure Anda.

Menggunakan gambar kontainer Bicep standar

ADE mendukung Bicep secara asli, sehingga Anda dapat mengonfigurasi definisi lingkungan yang menyebarkan sumber daya Azure untuk lingkungan penyebaran dengan menambahkan file templat (azuredeploy.json dan environment.yaml) ke katalog Anda. ADE kemudian menggunakan gambar kontainer Bicep standar untuk membuat lingkungan penyebaran.

Dalam file environment.yaml, properti runner menentukan lokasi gambar kontainer yang ingin Anda gunakan. Untuk menggunakan gambar sampel yang diterbitkan di Registri Artefak Microsoft, gunakan masing-masing pengidentifikasi runner, seperti yang tercantum dalam tabel berikut.

Contoh berikut menunjukkan runner yang mereferensikan sampel gambar kontainer Bicep:

    name: WebApp
    version: 1.0.0
    summary: Azure Web App Environment
    description: Deploys a web app in Azure without a datastore
    runner: Bicep
    templatePath: azuredeploy.json

Anda dapat melihat gambar kontainer Bicep standar di repositori sampel ADE di bawah folder Runner-Images untuk gambar ARM-Bicep .

Untuk informasi selengkapnya tentang cara membuat definisi lingkungan yang menggunakan gambar kontainer ADE untuk menyebarkan sumber daya Azure Anda, lihat Menambahkan dan mengonfigurasi definisi lingkungan.

Membuat gambar kontainer Bicep kustom

Membuat gambar kontainer kustom memungkinkan Anda menyesuaikan penyebaran agar sesuai dengan kebutuhan Anda. Anda dapat membuat gambar kustom berdasarkan gambar kontainer standar ADE.

Setelah menyelesaikan kustomisasi gambar, Anda harus membangun gambar dan mendorongnya ke registri kontainer Anda.

Membuat dan menyesuaikan gambar kontainer dengan Docker

Dalam contoh ini, Anda mempelajari cara membuat gambar Docker untuk menggunakan penyebaran ADE dan mengakses ADE CLI, mendasarkan gambar Anda dari salah satu gambar yang ditulis ADE.

ADE CLI adalah alat yang memungkinkan Anda membuat gambar kustom dengan menggunakan gambar dasar ADE. Anda dapat menggunakan ADE CLI untuk menyesuaikan penyebaran dan penghapusan agar sesuai dengan alur kerja Anda. ADE CLI telah diinstal sebelumnya pada gambar sampel. Untuk mempelajari selengkapnya tentang CLI ADE, lihat referensi Gambar Runner Kustom CLI.

Untuk membuat gambar yang dikonfigurasi untuk ADE, ikuti langkah-langkah berikut:

Dasarkan gambar Anda pada gambar sampel yang ditulis ADE atau gambar pilihan Anda dengan menggunakan pernyataan FROM.
Instal paket yang diperlukan untuk gambar Anda dengan menggunakan pernyataan RUN.
Buat folder skrip pada tingkat yang sama dengan Dockerfile Anda, simpan file deploy.sh dan delete.sh Anda di dalamnya, dan pastikan skrip tersebut dapat ditemukan dan dapat dieksekusi di dalam kontainer yang Anda buat. Langkah ini diperlukan agar penyebaran Anda berfungsi menggunakan gambar inti ADE.

Pilih gambar kontainer sampel dengan menggunakan pernyataan FROM

Sertakan pernyataan FROM dalam DockerFile yang dibuat untuk gambar baru Anda yang menunjuk ke gambar sampel yang dihosting di Registri Artefak Microsoft.

Berikut adalah contoh pernyataan FROM, yang merujuk gambar inti sampel:

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

Pernyataan ini menarik gambar inti yang terakhir diterbitkan, dan menjadikannya dasar untuk gambar kustom Anda.

Menginstal Bicep di Dockerfile

Anda dapat menginstal paket Bicep dengan Azure CLI dengan menggunakan pernyataan RUN, seperti yang ditunjukkan dalam contoh berikut:

RUN az bicep install

Gambar sampel ADE didasarkan pada gambar Azure CLI, dan memiliki paket ADE CLI dan JQ yang telah diinstal sebelumnya. Anda dapat mempelajari selengkapnya tentang Azure CLI, dan paket JQ.

Untuk menginstal paket lain yang Anda butuhkan dalam gambar Anda, gunakan pernyataan RUN.

Menjalankan skrip shell operasi

Dalam gambar sampel, operasi ditentukan dan dijalankan berdasarkan nama operasi. Saat ini, dua nama operasi yang didukung disebarkan dan dihapus.

Untuk menyiapkan gambar kustom Anda untuk menggunakan struktur ini, tentukan folder di tingkat skrip bernama Dockerfile Anda, dan tentukan dua file, deploy.sh, dan delete.sh. Skrip shell penyebaran berjalan saat lingkungan Anda dibuat atau disebarkan ulang, dan skrip shell penghapusan berjalan saat lingkungan Anda dihapus. Anda dapat melihat contoh skrip shell di repositori di bawah folder Runner-Images untuk gambar ARM-Bicep .

Untuk memastikan skrip shell ini dapat dieksekusi, tambahkan baris berikut ke Dockerfile Anda:

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

Menulis skrip shell operasi untuk menyebarkan templat ARM atau Bicep

Untuk memastikan Anda berhasil menyebarkan infrastruktur ARM atau Bicep melalui ADE, Anda harus:

Mengonversi parameter ADE ke parameter yang dapat diterima ARM
Mengatasi templat tertaut jika digunakan dalam penyebaran
Menggunakan identitas terkelola istimewa untuk melakukan penyebaran

Selama titik masuk gambar inti, parameter apa pun yang diatur untuk lingkungan saat ini disimpan di bawah variabel $ADE_OPERATION_PARAMETERS. Untuk mengonversinya ke parameter yang dapat diterima ARM, Anda dapat menjalankan perintah berikut menggunakan JQ:

# format the parameters as arm parameters
deploymentParameters=$(echo "$ADE_OPERATION_PARAMETERS" | jq --compact-output '{ "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#", "contentVersion": "1.0.0.0", "parameters": (to_entries | if length == 0 then {} else (map( { (.key): { "value": .value } } ) | add) end) }' )

Selanjutnya, untuk mengatasi templat tertaut apa pun yang digunakan dalam templat berbasis ARM JSON, Anda dapat mendekompilasi file templat utama, yang menyelesaikan semua file infrastruktur lokal yang digunakan ke dalam banyak modul Bicep. Kemudian, bangun kembali modul tersebut menjadi satu templat ARM dengan templat tertaut yang disematkan ke dalam templat ARM utama sebagai templat berlapis. Langkah ini hanya diperlukan selama operasi penyebaran. File templat utama dapat ditentukan menggunakan $ADE_TEMPLATE_FILE set selama titik masuk gambar inti, dan Anda harus mengatur ulang variabel ini dengan file templat yang dikompresi ulang. Lihat contoh berikut:

if [[ $ADE_TEMPLATE_FILE == *.json ]]; then

    hasRelativePath=$( cat $ADE_TEMPLATE_FILE | jq '[.. | objects | select(has("templateLink") and (.templateLink | has("relativePath")))] | any' )

    if [ "$hasRelativePath" = "true" ]; then
        echo "Resolving linked ARM templates"

        bicepTemplate="${ADE_TEMPLATE_FILE/.json/.bicep}"
        generatedTemplate="${ADE_TEMPLATE_FILE/.json/.generated.json}"

        az bicep decompile --file "$ADE_TEMPLATE_FILE"
        az bicep build --file "$bicepTemplate" --outfile "$generatedTemplate"

        # Correctly reassign ADE_TEMPLATE_FILE without the $ prefix during assignment
        ADE_TEMPLATE_FILE="$generatedTemplate"
    fi
fi

Untuk memberikan izin yang diperlukan penyebaran untuk menjalankan penyebaran dan penghapusan sumber daya dalam langganan, gunakan identitas terkelola istimewa yang terkait dengan jenis lingkungan proyek ADE. Jika penyebaran Anda memerlukan izin khusus untuk diselesaikan, seperti peran tertentu, tetapkan peran tersebut ke identitas jenis lingkungan proyek. Terkadang, identitas terkelola tidak segera tersedia saat memasukkan kontainer; Anda dapat mencoba kembali hingga proses masuk berhasil.

echo "Signing into Azure using MSI"
while true; do
    # managed identity isn't available immediately
    # we need to do retry after a short nap
    az login --identity --allow-no-subscriptions --only-show-errors --output none && {
        echo "Successfully signed into Azure"
        break
    } || sleep 5
done

Untuk memulai penyebaran templat ARM atau Bicep, jalankan az deployment group create perintah . Saat menjalankan perintah ini di dalam kontainer, pilih nama penyebaran yang tidak menimpa penyebaran sebelumnya, dan gunakan --no-prompt true bendera dan --only-show-errors untuk memastikan penyebaran tidak gagal pada peringatan atau kios apa pun saat menunggu input pengguna, seperti yang ditunjukkan dalam contoh berikut:

deploymentName=$(date +"%Y-%m-%d-%H%M%S")
az deployment group create --subscription $ADE_SUBSCRIPTION_ID \
    --resource-group "$ADE_RESOURCE_GROUP_NAME" \
    --name "$deploymentName" \
    --no-prompt true --no-wait \
    --template-file "$ADE_TEMPLATE_FILE" \
    --parameters "$deploymentParameters" \
    --only-show-errors

Untuk menghapus lingkungan, lakukan penyebaran Mode lengkap dan berikan templat ARM kosong, yang menghapus semua sumber daya dalam grup sumber daya ADE yang ditentukan, seperti yang ditunjukkan dalam contoh berikut:

deploymentName=$(date +"%Y-%m-%d-%H%M%S")
az deployment group create --resource-group "$ADE_RESOURCE_GROUP_NAME" \
    --name "$deploymentName" \
    --no-prompt true --no-wait --mode Complete \
    --only-show-errors \
    --template-file "$DIR/empty.json"

Anda dapat memeriksa status provisi dan detail dengan menjalankan perintah di bawah ini. ADE menggunakan beberapa fungsi khusus untuk membaca dan memberikan lebih banyak konteks berdasarkan detail provisi, yang dapat Anda temukan di folder Runner-Images . Implementasi sederhana bisa sebagai berikut:

if [ $? -eq 0 ]; then # deployment successfully created
    while true; do

        sleep 1

        ProvisioningState=$(az deployment group show --resource-group "$ADE_RESOURCE_GROUP_NAME" --name "$deploymentName" --query "properties.provisioningState" -o tsv)
        ProvisioningDetails=$(az deployment operation group list --resource-group "$ADE_RESOURCE_GROUP_NAME" --name "$deploymentName")

        echo "$ProvisioningDetails"

        if [[ "CANCELED|FAILED|SUCCEEDED" == *"${ProvisioningState^^}"* ]]; then

            echo -e "\nDeployment $deploymentName: $ProvisioningState"

            if [[ "CANCELED|FAILED" == *"${ProvisioningState^^}"* ]]; then
                exit 11
            else
                break
            fi
        fi
    done
fi

Terakhir, untuk melihat output penyebaran Anda dan meneruskannya ke ADE untuk membuatnya dapat diakses melalui Azure CLI, Anda dapat menjalankan perintah berikut:

deploymentOutput=$(az deployment group show -g "$ADE_RESOURCE_GROUP_NAME" -n "$deploymentName" --query properties.outputs)
if [ -z "$deploymentOutput" ]; then
    deploymentOutput="{}"
fi
echo "{\"outputs\": $deploymentOutput}" > $ADE_OUTPUTS

Membuat gambar kustom dapat diakses oleh ADE

Anda harus membangun gambar Docker dan mendorongnya ke registri kontainer Anda untuk membuatnya tersedia untuk digunakan dalam ADE. Anda dapat membuat gambar menggunakan Docker CLI, atau dengan menggunakan skrip yang disediakan oleh ADE.

Pilih tab yang sesuai untuk mempelajari selengkapnya tentang setiap pendekatan.

Membangun gambar dengan Docker CLI
Membuat gambar kontainer dengan skrip

Sebelum Anda membuat gambar untuk didorong ke registri Anda, pastikan Mesin Docker diinstal di komputer Anda. Kemudian, navigasikan ke direktori Dockerfile Anda, dan jalankan perintah berikut:

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

Misalnya, jika Anda ingin menyimpan gambar Anda di bawah repositori dalam registri Anda bernama customImage, dan unggah dengan versi 1.0.0tag , Anda akan menjalankan:

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

Mendorong gambar Docker ke registri

Untuk menggunakan gambar kustom, Anda perlu menyiapkan registri gambar yang dapat diakses publik dengan penarikan gambar anonim diaktifkan. Dengan cara ini, Lingkungan Penyebaran Azure dapat mengakses gambar kustom Anda untuk dijalankan dalam kontainer kami.

Azure Container Registry adalah penawaran Azure yang menyimpan gambar kontainer dan artefak serupa.

Untuk membuat registri, yang dapat dilakukan melalui Azure CLI, perintah portal Azure, PowerShell, dan lainnya, ikuti salah satu mulai cepat.

Untuk menyiapkan registri Anda agar penarikan gambar anonim diaktifkan, jalankan perintah berikut di 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

Saat Anda siap untuk mendorong gambar ke registri, jalankan perintah berikut:

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

Microsoft menyediakan skrip mulai cepat untuk membantu Anda memulai. Skrip membangun gambar Anda dan mendorongnya ke Azure Container Registry (ACR) tertentu di bawah repositori ade dan tag latest.

Untuk menggunakan skrip, Anda harus:

Buat folder Dockerfile dan skrip untuk mendukung model ekstensibilitas ADE.
Berikan nama dan direktori registri untuk gambar kustom Anda.
Pasang Azure CLI dan Docker Desktop dan di variabel PATH Anda.
Memiliki izin untuk mendorong ke registri yang ditentukan.

Anda dapat melihat skrip di sini.

Anda dapat memanggil skrip menggunakan perintah berikut di PowerShell:

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

Selain itu, jika Anda ingin mendorong ke repositori dan nama tag tertentu, Anda dapat menjalankan:

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

Menyambungkan gambar ke definisi lingkungan Anda

Saat menulis definisi lingkungan untuk menggunakan gambar kustom Anda dalam penyebarannya, edit runner properti pada file manifes (environment.yaml atau manifest.yaml).

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

Untuk mempelajari selengkapnya tentang cara membuat definisi lingkungan yang menggunakan gambar kontainer ADE untuk menyebarkan sumber daya Azure Anda, lihat Menambahkan dan mengonfigurasi definisi lingkungan.

Mengakses log operasi dan detail kesalahan

ADE menyimpan detail kesalahan untuk penyebaran yang gagal dalam file $ADE_ERROR_LOG dalam kontainer.

Untuk memecahkan masalah penyebaran yang gagal:

Masuk ke Portal Pengembang.
Identifikasi lingkungan yang gagal disebarkan, dan pilih Lihat detail.
Tinjau detail kesalahan di bagian Detail Kesalahan.

Selain itu, Anda dapat menggunakan Azure CLI untuk melihat detail kesalahan lingkungan menggunakan perintah berikut:

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

Untuk melihat log operasi untuk penyebaran atau penghapusan lingkungan, gunakan Azure CLI untuk mengambil operasi terbaru untuk lingkungan Anda, lalu lihat log untuk ID operasi tersebut.

# 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}

Bagikan melalui

Mengonfigurasi gambar kontainer untuk menjalankan penyebaran dengan ARM dan Bicep

Prasyarat

Menggunakan gambar kontainer dengan ADE

Menggunakan gambar kontainer Bicep standar

Membuat gambar kontainer Bicep kustom

Membuat dan menyesuaikan gambar kontainer dengan Docker

Pilih gambar kontainer sampel dengan menggunakan pernyataan FROM

Menginstal Bicep di Dockerfile

Menjalankan skrip shell operasi

Menulis skrip shell operasi untuk menyebarkan templat ARM atau Bicep

Membuat gambar kustom dapat diakses oleh ADE

Mendorong gambar Docker ke registri

Menyambungkan gambar ke definisi lingkungan Anda

Mengakses log operasi dan detail kesalahan

Saran dan Komentar

Saran dan Komentar

Sumber Daya Tambahan:

Bagikan melalui

Mengonfigurasi gambar kontainer untuk menjalankan penyebaran dengan ARM dan Bicep

Prasyarat

Menggunakan gambar kontainer dengan ADE

Menggunakan gambar kontainer Bicep standar

Membuat gambar kontainer Bicep kustom

Membuat dan menyesuaikan gambar kontainer dengan Docker

Pilih gambar kontainer sampel dengan menggunakan pernyataan FROM

Menginstal Bicep di Dockerfile

Menjalankan skrip shell operasi

Menulis skrip shell operasi untuk menyebarkan templat ARM atau Bicep

Membuat gambar kustom dapat diakses oleh ADE

Mendorong gambar Docker ke registri

Menyambungkan gambar ke definisi lingkungan Anda

Mengakses log operasi dan detail kesalahan

Konten terkait

Saran dan Komentar

Saran dan Komentar

Sumber Daya Tambahan: