ARMテンプレートの新機能とノウハウ

この記事はAzure AdventCalendar2019 の記事です。

去年も同様のARMテンプレートノウハウ記事を書いてますので合わせてご参考ください。
https://qiita.com/tenn25/items/7921a9f1a36fcb6218d9

１．最近の新機能

先月のMSIgniteでARMテンプレートに関する新機能がいくつか発表されました。

セッション動画がYoutubeで公開されています（ありがたや）
https://www.youtube.com/watch?v=3D-JIKShrws&feature=youtu.be

①コメントアウトできるようになった

ARMテンプレートは現状JSONファイルですが、//や/**/でコメントが入れられるようになり、
CLIやPowershellからのデプロイに対応しました。
以下で紹介する公式の拡張機能を入れる前提ですが、VSCode上でもエラーになりません。

②コードスニペット機能

こちらも後述のVSCodeの拡張機能ですが、
今までは、公式のリファレンスを見るか、ポータルから既存リソースをコードに出力してプロパティを確認するしかありませんでした。
armと入力することでコードスニペットの候補が出てきます。

選択すると、自動でひな形が作られます。
まだ大まかなリソースしか出てこず、第2,3階層の細かいリソースは出てきませんが、今後に期待したいです。

"type": ""と打てば細かいリソースも候補に出てきそうです。

apiVersionもそのリソースタイプが定義されているAPIバージョンの候補が出てきます。これは便利。

""と入れれば他の項目も候補に出てきます。

MSIgniteのデモだと、以下のように中のプロパティも候補が確認できてるのですが、
自分の手元では出し方が分かりませんでした…（できた方教えてください）

③デプロイ前に差分が確認できるようになった(What If機能)

待望の機能がついに出ました…！！！
AWSのCloudformationやTerraformなどはデプロイ前に差分が確認できますが、
ARMテンプレートは長らくこれができず、IaCツールとしては遅れをとっていました。

こちらもMSIgniteのデモから抜粋します。
デモではaddressPrefixを変更し、subnetを１つコメントアウトして、PowerhsellのNew-AzDeploymentWhatIfコマンドを実行しています。

右側のターミナルに差分が表示されています。
素晴らしいです…涙で前が見えません。
まだプレビュー段階ですが、これで実運用でも安心してデプロイできそうです。

利用申請はこちら
http://aka.ms/ARMTemplatePreviews

公式ドキュメントはこちら
https://docs.microsoft.com/en-us/azure/azure-resource-manager/template-deploy-what-if

２．VSCodeのおすすめプラグイン

①ARMテンプレート公式拡張機能

この拡張が優秀なので、宗教上の理由がない限りはVSCodeを使いましょう。

機能は上記に書いたような機能やインテリセンス、文字の色付けです。

②JSONの括弧を見やすくする拡張機能

ついでにJSONの括弧に色を付けてくれる拡張も入れましょう。
https://marketplace.visualstudio.com/items?itemName=CoenraadS.bracket-pair-colorizer-2

①②の拡張インストール前

インストール後

圧倒的見やすさ…！！
生のJSONは人間が読むものじゃないと思っていますが、だいぶマシになりました。

③ARMテンプレート関数の出力値チェックに使える拡張機能

Azure ARM Template Helper
https://marketplace.visualstudio.com/items?itemName=ed-elliott.azure-arm-template-helper

使うためには準備が必要で、ARMテンプレートのリポジトリのルートディレクトリに
.vscode/armd.jsonを作成しましょう。
以下のように、テンプレートファイルからの相対パス でParamaters.jsonへのパスを指定します。

{
    "parameterFile": "***/***/parameters.json"
}

その後、VS Code再起動すると、
コマンドパレット(Ctrl+Shif+P)から以下の操作が可能になります。

ARM:TestExtentionを選択して、関数を入力すると、その出力を確認することができます。

例）[concat('hoge-', parameters('environment'), '-webapps')] evaluated to: hoge-staging-webapps

関数周りは、ARMテンプレートで最もエラー原因になりやすいです。
parameters,variabels,concat,reference,list**あたりの関数を多用すると複雑になるので、結構重宝します。

３．Variablesのうまい使い方

インフラコードのツールにはよくあるものですが、
ARMテンプレートにも"variables":{}という変数を定義・加工できるスコープがあります。

Azureポータルから既存のリソースをARMテンプレートとして出力した場合は、
variablesが使われることはなく冗長な書き方で出力されます。

分かりやすいテンプレートを書くためには、変数を上手くまとめる必要がありますが、
関連する変数（同じリソースのもの）を階層でグルーピングしてあげると分かりやすいです。

階層化された変数は、以下のように上の階層から"."で繋げることで参照できます。

こうすることで変数名も短くなりますし、
Resource側の設定を見た時も直感的で分かり易いと思います。

４．リファレンスやポータルを参考にしてlistKeys関数を使う

参照系の関数は、ARMテンプレートを使っていて一番つまづくところだと思います。
ややこしくて嫌になりますが、避けて通れないところでもあります。

listKeys関数は、すでに存在するリソースのプロパティなどを取得する関数です。
よくあるユースケースとしては、リソースの接続文字列を取得してKeyVaultやAppServiceの環境変数に埋め込むときに使います。

ここではNoritficationHub/Namespaceの接続文字列を取得して、
AzureFunctionのアプリケーション設定(環境変数)に設定するまでの流れを説明します。

①ポータルで取得したい値を確認

まずは今回取得したい値をポータル上で確認します。

このConnectionStringのPrimaryキーをAppFunctionで使いたいです。

②ポータル上でARMテンプレートに出力して、対象のリソース名を確認

ポータル画面から既存のリソースをテンプレートとして出力します。
超分かりづらいですが、NotificationHubを構成するリソースは以下の通りだということが確認できます。

• Microsoft.NotificationHubs/namespaces
  • Microsoft.NotificationHubs/namespaces/AuthorizationRules (RootManageSharedAccessKey)
  • Microsoft.NotificationHubs/namespaces/notificationHubs
    • Microsoft.NotificationHubs/namespaces/notificationHubs/authorizationRules (★DefaultFullSharedAccessSignature)
    • Microsoft.NotificationHubs/namespaces/notificationHubs/authorizationRules (DefaultListenSharedAccessSignature)

今回はこの★マークのリソースが発行する接続文字列をlistKeys関数で取得します。

③listKeysに関するリファレンスを確認

listKeysに対応しているリソースの一覧にNotificationHubがあるので、問題なく使えそうです。

primaryKeyConnectionという値で取れそうなことが分かります

④テンプレートの実装

listKeysは以下のような引数を指定します。

listKeys(resourceName or resourceIdentifier, apiVersion, functionValues)

Parametersを直接参照して、文字連結などしても良いですが、
私の場合は以下のようにResourceIdやApiVersionをVariablesに定義してしまいます。
後々他のリソースで同様の値を使うこともあり得ますし、何よりlistKeys内のネストが深くなることを避けています。

これでもかなり長ったらしいですが、パッと見て理解しやすいと思います。

５．デバッグ方法

ARMテンプレートを実行する方法は大きく分けて3つほどあります。

• ローカルのCLIまたはCLoudShellからコマンド実行
• Azureポータル上のデプロイ画面にテンプレートとパラメータを貼り付けて実行
• AzureDevOpsのReleaseパイプラインによる実行

ARMテンプレートで運用していてキツいのが、エラー発生時です。
エラーが発生している行数などが分からないこともあり、原因が特定ができないときがあります。

上記3つはエラーの出方や詳細度が結構違うので、
ローカルから実行したけどエラーが全然分からん！という時は、ポータルから実行してみたりするとヒントが得られることもあるので試してみると良いと思います。

最近はエラーに関する公式ドキュメントも揃ってきたので、こちらも参考すると良いでしょう。
https://docs.microsoft.com/ja-jp/azure/azure-resource-manager/resource-manager-common-deployment-errors

まとめ

なるべく公式ドキュメントに載っていないことを書いたつもりですが、参考になれば嬉しいです。
ARMテンプレートは2年ほど使ってますが、正直アップデートが少ない印象があったので今回の新機能発表はかなりテンション上がりました。

あとはYAML対応するか、AWS CDKのようなラッパーツールが登場してくれれば、他のIaCツールに負けない強力なものになると思います。