パラメーターと名前を改善する

8 分

パラメーターは、同僚がテンプレートを操作するための最も一般的な方法です。彼らはテンプレートをデプロイするときに、パラメーターの値を指定する必要があります。 Azure 環境にアクセスするすべてのユーザーに対して、作成したリソースの名前は、その目的についての重要な情報を提供します。

このユニットでは、Bicep ファイルのパラメーターとリソースに付ける名前について計画するときに考慮すべきいくつかの重要な事項について学習します。

パラメーターのわかりやすさ

パラメーターを使用すると、Bicep ファイルが再利用可能で柔軟なものになります。各パラメーターの目的が、そのパラメーターを使用するすべてのユーザーにとって明確であることが重要です。同僚は、テンプレートを使用するときに、パラメーターを使ってデプロイの動作をカスタマイズします。

たとえば、Bicep ファイルを使用してストレージアカウントをデプロイする必要があるとします。ストレージアカウントの必須プロパティの 1 つは、データの冗長性レベルを定義する Stock Keeping Unit (SKU) です。 SKU には複数のプロパティがあり、最も重要なのが name です。ストレージアカウントの SKU の値を設定するパラメーターを作成するときは、storageAccountSkuName など、明確に定義された名前を使用します。 sku や skuName などの汎用的な名前の代わりにこの値を使用すると、他のユーザーがパラメーターの目的と、それの値を設定した場合の影響を理解するのに役立ちます。

既定値は、テンプレートを他のユーザーにとって便利なものにするための重要な方法です。妥当な既定値を使用することが重要です。それらは 2 つの面でテンプレートのユーザーに役立ちます。

既定値を使用すると、テンプレートのデプロイプロセスが簡略化されます。テンプレートのほとんどのユーザーにとって適切な既定値がパラメーターに設定されている場合、ユーザーはテンプレートをデプロイするたびにパラメーター値を指定するのではなく、パラメーター値を省略できます。
既定値は、想定されるパラメーター値がどのようなものかについての例を示します。テンプレートのユーザーが別の値を選択する必要がある場合、既定値によって、どのような値を使用すればよいかについてのヒントを得ることができます。

Bicep は、"パラメーターデコレーター" を通じてユーザーが入力を検証するのにも役立ちます。デコレーターを使用して、パラメーターの説明を入力したり、使用できる値の種類を指定したりできます。 Bicep には、いくつかの種類のパラメーターデコレーターが用意されています。

説明は、パラメーターの目的とその値を設定した場合の影響について、人が判読できる情報を提供するものです。
値の制約は、ユーザーがパラメーターの値として入力できる内容に制限を適用するものです。 @allowed() デコレーターを使って、使用できる特定の値の一覧を指定できます。 @minValue() および @maxValue() デコレーターを使うと数値パラメーターに最小値と最大値を適用でき、@minLength() および @maxLength() デコレーターを使うと文字列と配列パラメーターの長さを適用できます。

ヒント

@allowed() パラメーターデコレーターを使用して SKU を指定する場合は、注意が必要です。 Azure サービスには新しい SKU が頻繁に追加されます。テンプレートでそれらの使用を不必要に禁止することは望ましくありません。特定の SKU の使用を強制するには Azure Policy を使用することを検討し、SKU を指定した @allowed() デコレーターは、テンプレートのユーザーが特定の SKU を選択すべきでない機能上の理由がある場合にのみ使用してください。たとえば、テンプレートに必要な機能がその SKU では使用できないような場合です。これを説明するには、将来のすべてのユーザーに対して理由を明確にする @description() デコレーターまたはコメントを使用します。
メタデータは、一般的に使用されるものではありませんが、パラメーターに関する追加のカスタムメタデータを指定するために適用できます。

Bicep ファイルに必要な柔軟性の度合い

コードとしてのインフラストラクチャを定義する目標の 1 つは、テンプレートを再利用可能で柔軟性のあるものにすることです。ハードコードされた構成を持つ単一目的のテンプレートを作成することは望んでいません。一方、すべてのリソースプロパティをパラメーターとして公開しても意味がありません。すべての状況に対して機能することが求められる汎用テンプレートではなく、特定のビジネス上の問題またはソリューション用に機能するテンプレートを作成します。また、テンプレートをデプロイする前に値の入力に時間がかかるため、パラメーター数があまり多くならないようにしたいと考えています。これは、リソースの SKU とインスタンス数を構成する場合に特に重要です。

テンプレートについて計画する場合は、柔軟性とシンプルさのバランスをどう取るかを検討してください。テンプレートでパラメーターを指定するには、2 つの一般的な方法があります。

自由形式の構成オプションを指定する
定義済みの構成セットを使用する

ストレージアカウントと Azure App Service プランをデプロイする Bicep ファイルの例を使用して、両方の方法を検討しましょう。

自由形式の構成オプションを指定する

App Service プランとストレージアカウントの両方に SKU を指定する必要があります。リソースの各 SKU とインスタンス数を制御するパラメーターのセットを作成することもできます。

App Service プランとストレージアカウントを制御するパラメーターの図。

これは Bicep で次のようになります。

param appServicePlanSkuName string
param appServicePlanSkuCapacity int
param storageAccountSkuName string

resource appServicePlan 'Microsoft.Web/serverfarms@2023-12-01' = {
  name: appServicePlanName
  location: location
  sku: {
    name: appServicePlanSkuName
    capacity: appServicePlanSkuCapacity
  }
}

resource storageAccount 'Microsoft.Storage/storageAccounts@2023-05-01' = {
  name: storageAccountSkuName
  location: location
  sku: {
    name: storageAccountSkuName
  }
}

これは、テンプレートを使用するユーザーがパラメーター値の任意の組み合わせを指定できるので、最も柔軟性が高い形式です。ただし、リソースを追加する場合は、追加のパラメーターが必要になります。その結果、テンプレートは複雑になります。また、パラメーターの特定の組み合わせを制限することや、特定のリソースをある 1 つの SKU を使ってデプロイし、別のリソースを別の SKU を使ってデプロイする必要があることを確実に示す必要が生じる場合があります。指定する個別のパラメーター数が多すぎると、これらの規則を適用するのは難しくなります。

ヒント

テンプレートを使用するユーザーについて考えてみてください。パラメーターが何十個も表示されることに圧倒され、テンプレートを使用することをあきらめてしまうかもしれません。

次のように、関連するパラメーターをパラメーターオブジェクトの形式にグループ化することで、パラメーターの数を減らせる場合があります。

param appServicePlanSku object = {
  name: 'S1'
  capacity: 2
}

ただし、この方法を使用すると、パラメーター値を検証する機能が低下するおそれがあります。また、テンプレートのユーザーがオブジェクトの定義方法を必ずしも簡単に理解できなくなります。

定義済みの構成セットを使用する

または、"構成セット" を指定することもできます。これは 1 個のパラメーターであり、その値は、環境の種類の一覧のように、使用できる値を制限したリストです。ユーザーがテンプレートをデプロイするときは、この 1 つのパラメーターの値を選択するだけで済みます。パラメーターの値を選択すると、デプロイに構成のセットが自動的に継承されます。

App Service プランとストレージアカウントを制御する構成セットの図。

パラメーター定義はこのようになります。

@allowed([
  'Production'
  'Test'
])
param environmentType string = 'Test'

構成セットを使うと、テンプレートをデプロイするユーザーが個々のリソースのサイズを指定できないので、柔軟性は低くなりますが、構成の各セットを検証し、要件に適合することを確認できます。構成セットを使用すると、テンプレートのユーザーが各リソースで使用できるさまざまなオプションを理解する必要性が減少し、テンプレートのサポート、テスト、トラブルシューティングが容易になります。

構成セットを使用する場合は、さまざまなリソースに設定する特定のプロパティをパラメーター値に基づいて定義する、"マップ" 変数を作成します。

var environmentConfigurationMap = {
  Production: {
    appServicePlan: {
      sku: {
        name: 'P2V3'
        capacity: 3
      }
    }
    storageAccount: {
      sku: {
        name: 'ZRS'
      }
    }
  }
  Test: {
    appServicePlan: {
      sku: {
        name: 'S2'
        capacity: 1
      }
    }
    storageAccount: {
      sku: {
        name: 'LRS'
      }
    }
  }
}

その後、リソース定義で構成マップを使用してリソースのプロパティを定義します。

resource appServicePlan 'Microsoft.Web/serverfarms@2023-12-01' = {
  name: appServicePlanName
  location: location
  sku: environmentConfigurationMap[environmentType].appServicePlan.sku
}

構成セットを使用すると、複雑なテンプレートをもっと簡単に利用できるものにすることができます。また、独自のルールを適用し、事前検証済みの構成値の使用を促進するのにも役立ちます。

注意

このアプローチは、t-shirt sizing と呼ばれる場合があります。 T シャツを購入するとき、長さ、幅、袖などについて多くの選択肢はありません。それらの寸法は S、M、L のサイズごとに T シャツのデザイナーによって事前に定義されているので、その中から選択するだけです。

リソースの名前の付け方

Bicep では、リソースにわかりやすい名前を付けることが重要です。 Bicep のリソースには 2 つの名前があります。

シンボリック名は Bicep ファイル内でのみ使用され、Azure リソースには表示されません。シンボリック名は、テンプレートを読むまたは変更するユーザーがパラメーター、変数、またはリソース定義の目的を理解するに役立ちます。また、テンプレートを変更するかどうかについてユーザーが情報に基づいた意思決定を行うのに役立ちます。
リソース名は、Azure で作成されるリソースの名前です。多くのリソースには名前に制約があり、多くは名前を一意にする必要があります。

シンボリック名

リソースに適用するシンボリック名について考えることが重要です。テンプレートを変更する必要がある同僚がいるとします。彼らに各リソースの目的がわかるでしょうか。

たとえば、ユーザーが Web サイトからダウンロードする製品マニュアルを含むストレージアカウントを定義するとします。リソースには、たとえば storageAccount のようなシンボリック名を付けることができますが、Bicep ファイルに他のリソースが多く含まれ、さらには他のストレージアカウントも含まれる可能性がある場合、そのような名前では十分わかりやすくありません。そのようなときは代わりに、productManualStorageAccount のように、目的に関する情報を含むシンボリック名を付けることができます。

Bicep では通常、パラメーター、変数、リソースのシンボリック名である名前に camelCase の大文字スタイルを使用します。つまり、最初の単語の先頭文字に小文字を使用し、他の単語の先頭文字を大文字にします (上記の productManualStorageAccount の例のように)。必ずしも camelCase を使用する必要はありません。別のスタイルを使用する場合は、チーム内で 1 つの標準に合意し、それを一貫して使用することが重要です。

リソース名

すべての Azure リソースに名前があります。名前は、リソースの識別子の一部を構成します。リソースは、多くの場合、リソースへのアクセスに使用するホスト名としても表されます。たとえば、myapp という名前の App Service アプリを作成した場合、そのアプリにアクセスするために使用するホスト名は、myapp.azurewebsites.net となります。リソースをデプロイした後でその名前を変更することはできません。

Azure リソースの名前の付け方を考慮することが重要です。多くの組織では、リソースの名前付け規則が独自に定義されています。 Azure 向けクラウド導入フレームワークの具体的なガイダンスがあり、ご自分のものを定義するときに参考にすることができます。リソースの名前付け規則の目的は、組織内のすべてのユーザーが各リソースの目的を理解する助けになることです。

さらに、すべての Azure リソースには、特定の名前付け規則と制限があります。たとえば、名前の長さ、含めることができる文字、名前がグローバルに一意である必要があるか、リソースグループ内だけで一意であればよいかに関する制限があります。

Azure の名前付け要件だけでなく組織のすべての名前付け規則に従うことは複雑になる場合があります。適切に記述された Bicep テンプレートは、この複雑さをユーザーから隠し、リソースの名前を自動的に決定するものである必要があります。従うアプローチの一例を次に示します。

"一意性サフィックス" を作成するために使用されるパラメーターを追加します。これは、リソースに確実に一意の名前を付けるのに役立ちます。 uniqueString() 関数を使用して既定値を生成することをお勧めします。テンプレートをデプロイするユーザーは、わかりやすい名前を付けしたい場合は、これを特定の値でオーバーライドできます。リソース名が最大長を超えないように、@maxLength() デコレーターを使用してこのサフィックスの長さを制限してください。

ヒント

プレフィックスではなく、一意性サフィックスを使用することをお勧めします。この方法を使用すると、リソース名を簡単に並べ替え、すばやくスキャンできます。また、一部の Azure リソースには名前の先頭文字に関する制限があり、場合によっては、ランダムに生成された名前がこれらの制限に違反するおそれがあります。
変数を使用してリソース名を動的に構築します。 Bicep コードにより、生成される名前が、Azure の要件だけでなく組織の名前付け規則にも従っていることが保証されます。リソース名の一部として一意性サフィックスを含めます。

注意

すべてのリソースがグローバルに一意な名前を必要とするとは限りません。一意にするためのサフィックスを、すべてのリソースの名前に含めるか、必要なものだけにするかを検討してください。