Pulumi を使用してデプロイを実行するように ADE を構成する

この記事では、Azure Deployment Environments (ADE) でのデプロイに Pulumi を利用する方法について説明します。 Pulumi によって提供される標準のイメージを使用する方法、または Pulumi のコードとしてのインフラストラクチャ (IaC) フレームワークを使用してインフラストラクチャをプロビジョニングするようにカスタム イメージを構成する方法について説明します。

ADE は、拡張性モデルを使って、ユーザーが環境定義で使用できるカスタム イメージを作成できるように支援します。 この拡張機能モデルを使用するには、独自のカスタム イメージを作成し、それをパブリック コンテナー レジストリに格納できます。 その後、環境定義でこれらのイメージを参照して、環境をデプロイできます。

環境定義は、少なくとも 2 つのファイルで構成されます。これらは、Pulumi プロジェクト ファイル (Pulumi.yaml) と、environment.yaml という名前のマニフェスト ファイルです。 また、好みのプログラミング言語 (C#、TypeScript、Python など) で記述されたユーザー プログラムが含まれる場合もあります。ADE では、コンテナーを使用して環境定義をデプロイします。

前提条件

• アクティブなサブスクリプションが含まれる Azure アカウント。 無料でアカウントを作成できます。
• Azure サブスクリプション内にセットアップされた Azure Deployment Environments。
  • ADE を設定するには、「クイックスタート: Azure Deployment Environments を構成する」に従います。

Pulumi によって提供される標準の Docker イメージを使用する

Pulumi チームは、作業を開始するための事前構築済みイメージを提供しています。これは、Runner-Image フォルダー内にあります。 このイメージは、Pulumi Docker Hub で pulumi/azure-deployment-environments として一般提供されているため、ADE 環境定義から直接使用できます。

事前構築済みイメージを利用するサンプルの environment.yaml ファイルを次に示します。

name: SampleDefinition
version: 1.0.0
summary: First Pulumi-Enabled Environment
description: Deploys a Storage Account with Pulumi
runner: pulumi/azure-deployment-environments:0.1.0
templatePath: Pulumi.yaml

Environments フォルダーには、いくつかのサンプル環境定義があります。

カスタム Docker イメージをビルドして利用する

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

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

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

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

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

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

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

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

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

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

Pulumi CLI を実行可能ファイルの場所にインストールすると、デプロイおよび削除シナリオで使用することができます。

このプロセスの例を次に示します。この例では、最新版の Pulumi CLI をインストールします。

RUN apk add curl
RUN curl -fsSL https://get.pulumi.com | sh
ENV PATH="${PATH}:/root/.pulumi/bin"

Pulumi プログラムに使用するプログラミング言語によっては、1 つ以上の対応するランタイムをインストールすることが必要な場合があります。 Python ランタイムは、基本イメージで既に使用できます。

Node.js と TypeScript をインストールする例を次に示します。

# install node.js, npm, and typescript
RUN apk add nodejs npm
RUN npm install typescript -g

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

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

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

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

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

Pulumi CLI を使用する操作シェル スクリプトを作成する

Pulumi を使用してインフラストラクチャをデプロイするには、次の 4 つのステップがあります。

1. pulumi login - ローカル ファイル システムまたは Pulumi Cloud 内の状態ストレージに接続する
2. pulumi stack select - 特定の環境に使用するスタックを作成または選択する
3. pulumi config set - デプロイ パラメーターを Pulumi 構成値として渡す
4. pulumi up - デプロイを実行して、Azure で新しいインフラストラクチャを作成するか、既存のインフラストラクチャを更新する

コア イメージのエントリポイントでは、既存のローカル状態ファイルが、コンテナーと、環境変数 $ADE_STORAGE に保存されているディレクトリにプルされます。 既存の状態ファイルにアクセスするには、次のコマンドを実行します。

mkdir -p $ADE_STORAGE
export PULUMI_CONFIG_PASSPHRASE=
pulumi login file://$ADE_STORAGE

代わりに Pulumi Cloud にログインするには、Pulumi アクセス トークンを環境変数として設定し、次のコマンドを実行します。

export PULUMI_ACCESS_TOKEN=YOUR_PULUMI_ACCESS_TOKEN
pulumi login

現在の環境に設定されているすべてのパラメーターは、変数 $ADE_OPERATION_PARAMETERS に格納されます。 さらに、選択した Azure リージョンとリソース グループ名がそれぞれ、ADE_ENVIRONMENT_LOCATION と ADE_RESOURCE_GROUP_NAME に渡されます。 Pulumi スタック構成を設定するには、次のコマンドを実行します。

# Create or select the stack for the current environment
pulumi stack select $ADE_ENVIRONMENT_NAME --create

# Store configuration values in durable storage
export PULUMI_CONFIG_FILE=$ADE_STORAGE/Pulumi.$ADE_ENVIRONMENT_NAME.yaml

# Set the Pulumi stack config
pulumi config set azure-native:location $ADE_ENVIRONMENT_LOCATION --config-file $PULUMI_CONFIG_FILE
pulumi config set resource-group-name $ADE_RESOURCE_GROUP_NAME --config-file $PULUMI_CONFIG_FILE
echo "$ADE_OPERATION_PARAMETERS" | jq -r 'to_entries|.[]|[.key, .value] | @tsv' |
  while IFS=$'\t' read -r key value; do
    pulumi config set $key $value --config-file $PULUMI_CONFIG_FILE
  done

さらに、ADE の特権を利用してサブスクリプション内にインフラストラクチャをデプロイするには、Pulumi Azure Native または Azure Classic プロバイダーを使用してインフラストラクチャをプロビジョニングするときに、スクリプトで ADE マネージド サービス ID (MSI) を使用する必要があります。 特定のロールなど、デプロイを完了するためにデプロイで特別なアクセス許可が必要な場合は、環境のデプロイに使われているプロジェクト環境の種類の ID に、それらのアクセス許可を割り当てます。 ADE により、コア イメージのエントリポイント内のクライアント、テナント、サブスクリプションの ID など、関連する環境変数が設定されるため、次のコマンドを実行して、プロバイダーで 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

これで、pulumi up コマンドを使用して、デプロイを実行できるようになりました。

pulumi up --refresh --yes --config-file $PULUMI_CONFIG_FILE

削除スクリプトでは、次の例に示すように、代わりに destroy コマンドを実行できます。

pulumi destroy --refresh --yes --config-file $PULUMI_CONFIG_FILE

最後に、デプロイの出力をアップロードして、Azure CLI で環境にアクセスするときにアクセスできるようにするには、JQ パッケージを使用して、出力オブジェクトを Pulumi から、ADE で指定されている形式に変換します。 次の例で示すように、$ADE_OUTPUTS 環境変数に値を設定します。

stackout=$(pulumi stack output --json | jq -r 'to_entries|.[]|{(.key): {type: "string", value: (.value)}}')
echo "{\"outputs\": ${stackout:-{\}}}" > $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 はコンテナー内のカスタム イメージにアクセスして実行できます。

Pulumi を使用して、Azure Container Registry を作成し、イメージを発行する

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

Pulumi を使用して、Azure Container Registry を作成し、それにイメージを発行できます。 必要なすべてのリソースを Azure アカウントに作成する自己完結型の Pulumi プロジェクトについては、Provisioning/custom-image の例を参照してください。

CLI を使用して、Azure Container Registry を作成し、イメージを手動で発行する

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

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

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 カスタム ランナー イメージ リファレンス
• Pulumi の azure-deployment-environments レジストリ