ARM と Bicep を使用してデプロイを実行するようにコンテナー イメージを構成する

この記事では、Azure Resource Manager (ARM) と Bicep のカスタム コンテナー イメージを構築し、Azure Deployment Environments (ADE) に環境定義をデプロイする方法を説明します。

環境定義は、少なくとも 2 つのファイル、すなわち、テンプレート ファイル (例: azuredeploy.json または main.bicep) とマニフェスト ファイル (environment.yaml という名前) で構成されます。 ADE は、コンテナーを使用して環境定義をデプロイし、ARM と Bicep IaC のフレームワークをネイティブにサポートします。

ADE 機能拡張モデルにより、カスタム コンテナー イメージを作成して環境定義で使用することができます。 この機能拡張モデルを使用すると、独自のカスタム イメージを作成し、それらのイメージをコンテナー レジストリ (DockerHub など) に格納できます。 その後、環境定義でこれらのイメージを参照して、環境をデプロイできます。

ADE チームからは作業を始めるのに適したイメージが選択されて提供されており、それにはコア イメージや Azure Resource Manager (ARM)/Bicep イメージが含まれます。 これらのサンプル イメージには、Runner-Images フォルダーでアクセスできます。

ADE CLI は、ADE の基本イメージを使ってカスタム イメージを構築できるツールです。 ADE CLI を使い、ワークフローに合わせてデプロイと削除をカスタマイズできます。 サンプル イメージには、ADE CLI がプレインストールされています。 ADE CLI について詳しくは、CLI カスタム ランナー イメージ リファレンスに関する記事をご覧ください。

前提条件

• アクティブなサブスクリプションが含まれる Azure アカウント。 無料でアカウントを作成できます。
• Azure サブスクリプション内にセットアップされた Azure Deployment Environments。
  • ADE をセットアップするには、「クイック スタート: Azure Deployment Environments でデベロッパー センターを作成して構成する」の手順を実行します。

Docker イメージを作成してビルドする

この例では、ADE で作成されたイメージの 1 つを基にして、ADE のデプロイを利用して ADE CLI にアクセスする Docker イメージをビルドする方法について説明します。

ADE 用に構成されたイメージのビルドは、次の手順に従って行います。

1. ADE で作成されたサンプル イメージまたは FROM ステートメントを使って選んだ任意のイメージを基にして、イメージを作成します。
2. RUN ステートメントを使って、イメージに必要なパッケージをインストールします。
3. Dockerfile と同じレベルに scripts フォルダーを作成し、その中に deploy.sh と delete.sh ファイルを格納して、作成されたコンテナー内でそれらのスクリプトを検出して実行できるようにします。 デプロイが ADE コア イメージを使って動作するためには、このステップが必要です。
4. イメージをビルドしてコンテナー レジストリにプッシュし、ADE からアクセスできることを確認します。
5. 環境定義の runner プロパティでイメージを参照します。

FROM ステートメントを使用してサンプル コンテナー イメージを選択する

Microsoft アーティファクト レジストリでホストされているサンプル イメージを指す FROM ステートメントを、新しいイメージ用に作成される DockerFile に含めます。

サンプル コア イメージを参照する FROM ステートメントの例を次に示します。

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

このステートメントは、最も新しく公開されたコア イメージをプルして、それをカスタム イメージの基礎にします。

Dockerfile に Bicep をインストールする

次の例に示すように、RUN ステートメントを使って、Azure CLI で Bicep パッケージをインストールできます。

RUN az bicep install

ADE サンプル イメージは Azure CLI イメージに基づいており、ADE CLI と JQ のパッケージがプレインストールされています。 詳しくは、Azure CLI と JQ パッケージに関するページをご覧ください。

イメージ内で必要なパッケージをさらにインストールするには、RUN ステートメントを使います。

操作のシェル スクリプトを実行する

サンプル イメージ内では、操作名に基づいて操作が決定されて実行されます。 現在サポートされている 2 つの操作名は、deploy と delete です。

この構造を利用するようにカスタム イメージを設定するには、Dockerfile のレベルで scripts という名前のフォルダー指定し、2 つのファイル deploy.sh と delete.sh を指定します。deploy シェル スクリプトは環境の作成時または再デプロイ時に実行され、delete シェル スクリプトは環境の削除時に実行されます。 リポジトリ内のシェル スクリプトの例は、ARM-Bicep 用の Runner-Images フォルダーのイメージの下で確認できます。

これらのシェル スクリプトを確実に実行できるようにするには、Dockerfile に次の行を追加します。

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

ARM テンプレートまたは Bicep テンプレートをデプロイするための操作シェル スクリプトを作成する

ADE を介して ARM または Bicep インフラストラクチャを正常にデプロイできるようにするには、次の操作を行う必要があります。

• ADE パラメーターを ARM 許容パラメーターに変換する
• リンクされたテンプレートがデプロイで使用されている場合は解決する
• 特権マネージド ID を使用してデプロイを実行する

コア イメージのエントリポイント中に、現在の環境に設定されているすべてのパラメーターが変数 $ADE_OPERATION_PARAMETERS の下に格納されます。 それらを ARM 許容パラメーターに変換するには、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) }' )

次に、ARM JSON ベースのテンプレート内で使用されるリンクされたテンプレートを解決するには、メイン テンプレート ファイルを逆コンパイルします。これによって、多くの Bicep モジュールに使用されているすべてのローカル インフラストラクチャ ファイルが解決されます。 次に、メイン ARM テンプレートに入れ子になったテンプレートとして埋め込まれたリンク済みテンプレートを使用して、これらのモジュールを 1 つの ARM テンプレートにリビルドします。 この手順は、デプロイ操作中にのみ必要です。 メイン テンプレート ファイルは、コア イメージのエントリ ポイント中に $ADE_TEMPLATE_FILE セットを使用して指定できます。この変数は、再コンパイルされたテンプレート ファイルで設定し直す必要があります。 次の例を参照してください。

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

デプロイにおいて、サブスクリプション内のリソースのデプロイと削除を実行するために必要なアクセス許可を付与するには、ADE プロジェクト環境の種類に関連付けられている特権マネージド ID を使用します。 特定のロールなど、デプロイを完了するために特別なアクセス許可が必要な場合は、それらのロールをプロジェクト環境の種類の ID に割り当てます。 場合によっては、コンテナーに入る時点で直ちにマネージド ID を使用できないこともあるため、サインインは成功するまで再試行できます。

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

ARM テンプレートまたは Bicep テンプレートのデプロイを開始するには、az deployment group create コマンドを実行します。 コンテナー内でこのコマンドを実行する場合は、過去のデプロイをオーバーライドしないデプロイ名を選択し、--no-prompt true フラグと --only-show-errors フラグを使用して、次の例に示すように、警告やユーザー入力の待機中にデプロイが失敗したり、止まってしまったりしないようにします。

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

環境を削除するには、完全モードのデプロイを実行し、空の ARM テンプレートを指定します。これにより、次の例に示すように、指定した ADE リソース グループ内のすべてのリソースが削除されます。

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"

次のコマンドを実行して、プロビジョニングの状態と詳細を確認できます。 プロビジョニングの詳細に基づいて追加のコンテキストを読み取り、提供するために、ADE ではいくつかの特殊な関数を使用します。それらは Runner-Images フォルダーにあります。 単純な実装は次のようになります。

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

最後に、デプロイの出力を表示し、それらを ADE に渡して Azure CLI 経由でアクセスできるようにするには、次のコマンドを実行します。

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

イメージをビルドする

レジストリにプッシュされるイメージをビルドする前に、コンピューターに Docker エンジンがインストールされていることを確認します。 その後、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 Deployment Environments はコンテナー内のカスタム イメージにアクセスして実行できます。

Azure Container Registry は、コンテナー イメージおよび同様の成果物を格納する Azure オファリングです。

Azure CLI、Azure portal、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}

環境定義にイメージを接続する

デプロイ内のカスタム イメージを使用する環境定義を作成するときは、マニフェスト ファイル (environment.yaml または manifest.yaml) で runner プロパティを編集します。

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

スクリプトを使用してコンテナー イメージをビルドする

Microsoft から、作業を始めるのに役立つクイックスタート スクリプトが提供されています。 このスクリプトは、イメージをビルドし、リポジトリ ade とタグ latest を使用して指定された Azure Container Registry (ACR) にプッシュします。

スクリプトを使うには、次のことが必要です。

1. ADE 拡張性モデルをサポートするように Dockerfile と scripts フォルダーを構成します。
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}'

操作ログとエラーの詳細にアクセスする

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 を使って環境の最新の操作を取得し、その操作 ID のログを表示します。

# 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 カスタム ランナー イメージ リファレンス