Bicep ファイルをリファクタリングする

5 分

テンプレートを Bicep に変換するための変換と移行のフェーズ後、ファイルを改善する必要があります。このプロセスは、"リファクタリング" と呼ばれます。 JSON ARM テンプレートと Azure リソースを Bicep に移行するために推奨されるワークフローの 3 番目のフェーズは、リファクタリングフェーズです。

Diagram that shows the refactor phase of the recommended workflow for migrating Azure resources to Bicep.

"リファクタリング" フェーズの主な焦点は、Bicep コードの品質を向上させることです。機能強化には、テンプレートをテンプレート標準に合わせるための、コードコメントの追加などの変更が含まれることがあります。

リファクタリングフェーズは 8 つのステップで構成され、任意の順序で実行できます。

リソース API のバージョンをレビューする。
新しい Bicep ファイルでリンターの修正候補をレビューする。
パラメーター、変数、およびシンボリック名を変更する。
式を簡略化する。
子および拡張リソースをレビューする。
モジュール化する。
コメントを追加する。
Bicep のベストプラクティスに従う。

次の例は、App Service プランを作成する JSON テンプレートの Bicep decompile コマンドからの出力を示しています。

@description('Location for resources.')
param location string = resourceGroup().location

@allowed([
  'prod'
  'dev'
  'test'
])
@description('The list of allowed environment names.')
param environment string = 'prod'

@allowed([
  'P1v3'
  'P2v3'
  'P3v3'
])
@description('The list of allowed App Service Plan SKUs.')
param appServicePlanSku string = 'P1v3'

@minValue(1)
@maxValue(10)
@description('The number of allowed App Service Plan instances.')
param appServicePlanInstanceCount int = 1

var appServicePlanName_var = 'plan-${environment}-001'

resource appServicePlanName 'Microsoft.Web/serverfarms@2020-12-01' = {
  name: appServicePlanName_var
  location: location
  sku: {
    name: appServicePlanSku
    capacity: appServicePlanInstanceCount
  }
  kind: 'app'
  properties: {}
}

output appServicePlanId string = appServicePlanName.id

この Bicep テンプレートをこのままデプロイしてもデプロイは成功しますが、テンプレート標準に合うようにテンプレートを改善することもできます。

リソース API のバージョンを確認する

Bicep を使用して Azure リソースを操作する場合は、使用する "API バージョン" を指定します。 Azure の製品が変更および改善されると、より新しい API バージョンがリリースされ、それによって新しい機能にアクセスできます。 Azure リソースをエクスポートするとき、エクスポートされたテンプレートに、リソースの種類に応じた最新の API バージョンが使用されていない場合があります。将来のデプロイに特定のプロパティが必要な場合は、API を適切なバージョンに更新します。エクスポートされた各リソースの API バージョンを確認することをお勧めします。

Azure ARM テンプレートリファレンスは、テンプレートに適した API バージョンとリソースプロパティを確認するのに役立ちます。

新しい Bicep ファイルでリンターの修正候補をレビューする

Visual Studio Code 用の Bicep 拡張機能を使って Bicep ファイルを作成すると、リンターが自動的に実行され、コードのエラーが強調表示され、修正候補が表示されます。修正候補やエラーの多くには、問題にクイック修正を適用するオプションが含まれます。これらの推奨事項を確認し、Bicep ファイルを調整します。

パラメーター、変数、およびシンボリック名を変更する

運用環境や開発環境など、複数の環境がインフラストラクチャでサポートされている場合は、これらの環境をサポートするパラメーターを作成します。適切なパラメーターの名前付け規則を使うと、環境ごとにデプロイを簡単にカスタマイズできます。

デコンパイラによって生成されるパラメーター、変数、シンボリック名の名前が、標準の名前付け規則と一致しない可能性があります。生成された名前を確認し、必要に応じて調整を行います。

次の例では、appServicePlanName_var という名前の変数があり、元の変数名の末尾に _var が追加されています。

@minValue(1)
@maxValue(10)
@description('The number of allowed App Service Plan instances.')
param appServicePlanInstanceCount int = 1

var appServicePlanName_var = 'plan-${environment}-001'

resource appServicePlanName 'Microsoft.Web/serverfarms@2020-12-01' = {

わかりやすくするため、変数名から _var を削除することをお勧めします。しかし、変数の名前を変更すると、その新しい名前が App Service プランリソースのシンボリック名と競合します。そのため、まずリソースの名前を変更してから、その定義で使われている変数の名前を変更することをお勧めします。

ヒント

識別子の名前を変更するときは、テンプレートのすべての部分で一貫して名前を変更してください。これは、テンプレート全体で参照するパラメーター、変数、およびリソースの場合に特に重要です。

Visual Studio Code には、シンボルの名前を変更する便利な方法が用意されています。名前を変更する識別子を選択し、F2 キーを押して新しい名前を入力したら、Enter キーを押します。

Screenshot from Visual Studio Code that shows how to rename a symbol.

これらのステップで、識別子の名前が変更され、それに対するすべての参照が自動的に更新されます。

式を簡略化する

逆コンパイルプロセスでは、Bicep の一部の機能を常に利用できるとは限りません。変換で生成された式をすべて確認し、それらを簡略化します。たとえば、逆コンパイルテンプレートには、文字列補間を使用して簡略化できる concat() または format() 関数が含まれる場合があります。リンターからの修正候補を確認し、必要に応じて調整を行います。

子および拡張リソースをレビューする

Bicep には、リソースの名前を連結したり、parent プロパティを使ったり、入れ子になったリソースを使ったりするなど、子および拡張リソースを宣言する方法が複数あります。

逆コンパイル後にこれらのリソースを確認し、構造が標準に合っていることを確認することを検討してください。たとえば、子リソース名の作成に文字列の連結を使用しないようにする必要があります。代わりに、parent プロパティまたは入れ子になったリソースを使用します。同様に、仮想ネットワークのプロパティまたは別のリソースとして、サブネットを参照できます。

モジュール化する

多くのリソースを含むテンプレートを変換する場合は、わかりやすくするために個々のリソースの種類をモジュールに分割することを検討してください。 Bicep でモジュールを使用すると、テンプレートのデプロイの複雑さを軽減するのに役立ちます。

Note

Bicep デプロイでは、JSON テンプレートをモジュールとして使用することができます。 Bicep では、JSON モジュールを認識し、Bicep モジュールを使う場合と同じように参照することができます。

コメントと説明を追加する

優れた Bicep コードは、"自己文書化" されています。 Bicep では、ご自分のコードにコメントと説明を追加して、自分のインフラストラクチャを文書化できます。チームメイトはコードをコメントと説明により理解し、変更された場合により確信を持つことができます。コメントと説明は、Visual Studio Code で Bicep ファイルを操作するときに表示されます。たとえば、モジュールのパラメーター値を指定する必要がある場合などです。ただし、Bicep ファイルを Azure にデプロイする場合、コメントは無視されます。

// 文字シーケンスを使って、単一行コメントを追加できます。複数行コメントの場合は、/* で始まり */ で終わります。コメントを追加して、コード内の特定の行またはコードのセクションに適用することができます。

ファイルの先頭には複数行コメントを追加できます。

/*
  This Bicep file was developed by the web team.
  It deploys the resources we need for our toy company's website.
*/

単一行コメントは、コードのセクションのヘッダーとして、またはコードを記述する個々の行に追加できます。

// Resource - App Service plan
@description('The App Service plan resource name.')
resource appServicePlan 'Microsoft.Web/serverfarms@2022-03-01' = {
  name: appServicePlanName
  location: location
  sku: {
    name: appServicePlanSku // Specifies the SKU of the App Service plan.
    capacity: appServicePlanInstanceCount
  }
  kind: 'app' // Specifies a Windows App Service plan.
}

// Outputs
@description('The resource ID of the App Service plan.')
output appServicePlanId string = appServicePlan.id // Resource ID of the App Service plan.

Bicep には、お使いのパラメーター、変数、リソース、モジュール、出力の目的を文書化できる @description デコレーターがあります。説明は、説明する項目の上の行に追加できます。

@description('The name of the App Service plan.')
var appServicePlanName = 'plan-${environment}-001'

Bicep のベストプラクティスに従う

Bicep ファイルが標準的な推奨事項に従っていることを確認します。 Bicep のベストプラクティスを参照し、見逃した可能性があるものがないかどうかを確認してください。

変換されたテンプレート

適切な改善を行った後、デプロイする前に最終的なテンプレートを確認します。更新されたテンプレートには、変更された名前、API のバージョン、説明、追加されたコメントが含まれています。

/*
  This Bicep file was developed by the web team.
  It deploys the resources we need for our toy company's website.
*/

// Parameters
@description('Location for all resources.')
param location string = resourceGroup().location

@allowed([
  'prod' // Production environment
  'dev' // Development environment
  'test' // Test environment
])
@description('The list of allowed environment names.')
param environment string = 'prod'

@allowed([
  'P1v3'
  'P2v3'
  'P3v3'
])
@description('The list of allowed App Service plan SKUs.')
param appServicePlanSku string = 'P1v3'

@minValue(1)
@maxValue(10)
@description('The number of allowed App Service plan instances.')
param appServicePlanInstanceCount int = 1

// Variables
@description('The name of the App Service plan.')
var appServicePlanName = 'plan-${environment}-001'

// Resource - App Service plan
@description('The App Service plan resource name.')
resource appServicePlan 'Microsoft.Web/serverfarms@2022-03-01' = {
  name: appServicePlanName
  location: location
  sku: {
    name: appServicePlanSku // Specifies the SKU of the App Service plan.
    capacity: appServicePlanInstanceCount
  }
  kind: 'app' // Specifies a Windows App Service plan.
}

// Outputs
@description('The resource ID of the App Service plan.')
output appServicePlanId string = appServicePlan.id // Resource ID of the App Service plan.