Bicep'te Azure Resource Manager şablonu belirtimleri

  • Makale

Şablon belirtimi, bir Azure Resource Manager şablonunu (ARM şablonu) daha sonra dağıtılmak üzere depolamaya yönelik bir kaynak türüdür. Bu kaynak türü, ARM şablonlarını kuruluşunuzdaki diğer kullanıcılarla paylaşmanızı sağlar. Diğer tüm Azure kaynaklarda olduğu gibi, şablon belirtimini paylaşmak için Azure rol tabanlı erişim denetimini (Azure RBAC) kullanabilirsiniz. Bicep dosyaları sağlayarak şablon belirtimleri oluşturmak için Azure CLI veya Azure PowerShell kullanabilirsiniz. Bicep dosyaları depolanmadan önce ARM JSON şablonlarına dönüştürülür. Şu anda şablon belirtimi kaynağı oluşturmak için Azure portaldan bicep dosyasını içeri aktaramazsınız.

Microsoft.Resources/templateSpecs, şablon belirtimleri için kaynak türüdür. Bir ana şablondan ve herhangi bir sayıda bağlantılı şablondan oluşur. Azure, şablon belirtimlerini kaynak gruplarında güvenli bir şekilde depolar. Hem ana şablon hem de bağlantılı şablonlar JSON'da olmalıdır. Şablon Özellikleri sürüm oluşturma desteği sağlar.

Şablon belirtimini dağıtmak için PowerShell, Azure CLI, Azure portalı, REST ve diğer desteklenen SDK'lar ve istemciler gibi standart Azure araçlarını kullanırsınız. Şablon veya Bicep dosyası için kullandığınız komutların aynısını kullanırsınız.

Not

Azure PowerShell ile Bicep'te şablon belirtimlerini kullanmak için 6.3.0 veya sonraki bir sürümü yüklemeniz gerekir. Azure CLI ile kullanmak için 2.27.0 veya sonraki bir sürümü kullanın.

Dağıtımınızı tasarlarken her zaman kaynakların yaşam döngüsünü göz önünde bulundurun ve benzer yaşam döngüsünü paylaşan kaynakları tek bir şablon belirtiminde gruplandırın. Örneğin dağıtımlarınız, her örneği kendi veritabanlarını ve kapsayıcılarını içeren birden çok Azure Cosmos DB örneğini içerir. Veritabanları ve kapsayıcılar çok fazla değişmediğinden, Cosmo DB örneğini ve temel veritabanlarını ve kapsayıcılarını içerecek bir şablon belirtimi oluşturmak istiyorsunuz. Daha sonra bu kaynakların birden çok örneğini oluşturmak için Bicep'inizde koşullu deyimleri ve kopyalama döngülerini kullanabilirsiniz.

İpucu

Modül kayıt defteri ve şablon özellikleri arasındaki seçim çoğunlukla tercih konusudur. İkisi arasında seçim yaparken göz önünde bulundurmanız gereken birkaç şey vardır:

  • Modül kayıt defteri yalnızca Bicep tarafından desteklenir. Henüz Bicep kullanmıyorsanız şablon belirtimlerini kullanın.
  • Bicep modülü kayıt defterindeki içerik yalnızca başka bir Bicep dosyasından dağıtılabilir. Şablon özellikleri doğrudan API, Azure PowerShell, Azure CLI ve Azure portalından dağıtılabilir. Portal dağıtım deneyimini özelleştirmek için bile kullanabilirsiniz UiFormDefinition .
  • Bicep, diğer proje yapıtlarını (Bicep olmayan ve ARM şablonu olmayan dosyalar dahil) eklemek için bazı sınırlı özelliklere sahiptir. Örneğin, ve loadFileAsBase64 işlevlerini kullanarak loadTextContent PowerShell betikleri, CLI betikleri ve diğer ikili dosyalar). Şablon özellikleri bu yapıtları paketleyemez.

Eğitim kaynakları

Şablon özellikleri hakkında daha fazla bilgi edinmek ve uygulamalı yönergeler için bkz . Şablon belirtimlerini kullanarak yeniden kullanılabilir altyapı kodu kitaplıklarını yayımlama.

Gerekli izinler

Şablon belirtimi için tanımlanan iki Azure yerleşik rolü vardır:

Ayrıca, bicep dosyasını dağıtmak için izinlere de ihtiyacınız vardır. Bkz . Dağıtma - CLI veya Dağıtım - PowerShell.

Şablon belirtimlerini neden kullanmalısınız?

Şablon belirtimleri aşağıdaki avantajları sağlar:

  • Şablon belirtiminiz için standart ARM şablonları veya Bicep dosyaları kullanırsınız.
  • Erişimi SAS belirteçleri yerine Azure RBAC aracılığıyla yönetirsiniz.
  • Kullanıcılar, Bicep dosyasına yazma erişimi olmadan şablon belirtimini dağıtabilir.
  • Şablon belirtimini PowerShell betiği veya DevOps işlem hattı gibi mevcut dağıtım işlemiyle tümleştirebilirsiniz.

Şablon özellikleri kurallı şablonlar oluşturmanıza ve bunları kuruluşunuzdaki ekiplerle paylaşmanıza olanak tanır. Şablon belirtimleri, dağıtım için Azure Resource Manager'da kullanılabildiğinden, ancak doğru izinlere sahip olmayan kullanıcılar tarafından erişilemediğinden güvenlidir. Kullanıcıların yalnızca şablonu dağıtmak için şablon belirtimine okuma erişimine ihtiyacı vardır, böylece şablonu başkalarının değiştirmesine izin vermeden paylaşabilirsiniz.

Şablonlarınız şu anda bir GitHub deposunda veya depolama hesabındaysa, şablonları paylaşmaya ve kullanmaya çalışırken çeşitli zorluklarla karşılaşırsınız. Şablonu dağıtmak için şablonu herkese açık hale getirmeniz veya SAS belirteçleriyle erişimi yönetmeniz gerekir. Bu sınırlamayı aşabilmek için kullanıcılar yerel kopyalar oluşturabilir ve bu kopyaların sonunda özgün şablonunuzdan farklı olması gerekir. Şablon belirtimleri şablonların paylaşımını basitleştirir.

Şablon belirtimine eklediğiniz şablonlar, kuruluşunuzun gereksinimlerini ve yönergelerini izlemek için kuruluşunuzdaki yöneticiler tarafından doğrulanmalıdır.

Şablon belirtimi oluşturma

Aşağıdaki örnekte Azure'da depolama hesabı oluşturmaya yönelik basit bir Bicep dosyası gösterilmektedir.

@allowed([
  'Standard_LRS'
  'Standard_GRS'
  'Standard_ZRS'
  'Premium_LRS'
])
param storageAccountType string = 'Standard_LRS'

resource stg 'Microsoft.Storage/storageAccounts@2021-04-01' = {
  name:  'store${uniqueString(resourceGroup().id)}'
  location: resourceGroup().location
  sku: {
    name: storageAccountType
  }
  kind:'StorageV2'
}

Kullanarak bir şablon belirtimi oluşturun:

New-AzTemplateSpec -Name storageSpec -Version 1.0a -ResourceGroupName templateSpecsRg -Location westus2 -TemplateFile ./mainTemplate.bicep

Ayrıca, Bicep dosyalarını kullanarak şablon belirtimleri de oluşturabilirsiniz. Ancak içeriğinin mainTemplate JSON içinde olması gerekir. Aşağıdaki şablon, depolama hesabı dağıtmak için bir şablon belirtimi oluşturur:

param templateSpecName string = 'CreateStorageAccount'
param templateSpecVersionName string = '0.1'
param location string = resourceGroup().location

resource createTemplateSpec 'Microsoft.Resources/templateSpecs@2021-05-01' = {
  name: templateSpecName
  location: location
  properties: {
    description: 'A basic templateSpec - creates a storage account.'
    displayName: 'Storage account (Standard_LRS)'
  }
}

resource createTemplateSpecVersion 'Microsoft.Resources/templateSpecs/versions@2021-05-01' = {
  parent: createTemplateSpec
  name: templateSpecVersionName
  location: location
  properties: {
    mainTemplate: {
      '$schema': 'https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#'
      'contentVersion': '1.0.0.0'
      'parameters': {
        'storageAccountType': {
          'type': 'string'
          'defaultValue': 'Standard_LRS'
          'allowedValues': [
            'Standard_LRS'
            'Standard_GRS'
            'Standard_ZRS'
            'Premium_LRS'
          ]
        }
      }
      'resources': [
        {
          'type': 'Microsoft.Storage/storageAccounts'
          'apiVersion': '2019-06-01'
          'name': 'store$uniquestring(resourceGroup().id)'
          'location': resourceGroup().location
          'kind': 'StorageV2'
          'sku': {
            'name': '[parameters(\'storageAccountType\')]'
          }
        }
      ]
    }
  }
}

Bicep dosyasına eklenmiş JSON şablonunun şu değişiklikleri yapması gerekir:

  • Satırların sonundaki virgülleri kaldırın.
  • Çift tırnakları tek tırnakla değiştirin.
  • İfadelerin içindeki tek tırnak işaretinden kaçış. Örneğin, 'name': '[parameters(\'storageAccountType\')]'.
  • Bicep dosyasında tanımlanan parametrelere ve değişkenlere erişmek için parametre adlarını ve değişken adlarını doğrudan kullanabilirsiniz. içinde mainTemplatetanımlanan parametrelere ve değişkenlere erişmek için ARM JSON şablonu söz dizimini kullanmanız gerekir. Örneğin, 'name': '[parameters(\'storageAccountType\')]'.
  • Bicep işlevlerini çağırmak için Bicep söz dizimini kullanın. Örneğin, 'location': resourceGroup().location.

Şablon belirtiminin boyutu yaklaşık 2 MB ile sınırlıdır. Şablon belirtim boyutu sınırı aşarsa TemplateSpecTooLarge hata kodunu alırsınız. Hata iletisinde şöyle yazıyor:

The size of the template spec content exceeds the maximum limit. For large template specs with many artifacts, the recommended course of action is to split it into multiple template specs and reference them modularly via TemplateLinks.

Aboneliğinizdeki tüm şablon belirtimlerini şu şekilde görüntüleyebilirsiniz:

Get-AzTemplateSpec

Bir şablon belirtiminin, sürümleri de dahil olmak üzere ayrıntılarını şu şekilde görüntüleyebilirsiniz:

Get-AzTemplateSpec -ResourceGroupName templateSpecsRG -Name storageSpec

Şablon belirtimlerini dağıtma

Şablon belirtimini oluşturduktan sonra, Şablon Belirtimleri Okuyucusu rolüne sahip kullanıcılar bunu dağıtabilir. Buna ek olarak, ARM şablonunu dağıtmak için izinlere de ihtiyacınız vardır. Bkz . Dağıtma - CLI veya Dağıtım - PowerShell.

Şablon özellikleri portal, PowerShell, Azure CLI veya daha büyük bir şablon dağıtımında Bicep modülü olarak dağıtılabilir. Bir kuruluştaki kullanıcılar Azure'daki herhangi bir kapsama (kaynak grubu, abonelik, yönetim grubu veya kiracı) bir şablon belirtimi dağıtabilir.

Bicep dosyası için bir yol veya URI geçirmek yerine, kaynak kimliğini sağlayarak bir şablon belirtimi dağıtırsınız. Kaynak kimliği aşağıdaki biçime sahiptir:

/subscriptions/{subscription-id}/resourceGroups/{resource-group}/providers/Microsoft.Resources/templateSpecs/{template-spec-name}/versions/{template-spec-version}

Kaynak kimliğinin şablon belirtimi için bir sürüm adı içerdiğine dikkat edin.

Örneğin, aşağıdaki komutla bir şablon belirtimi dağıtırsınız.

$id = "/subscriptions/11111111-1111-1111-1111-111111111111/resourceGroups/templateSpecsRG/providers/Microsoft.Resources/templateSpecs/storageSpec/versions/1.0a"

New-AzResourceGroupDeployment `
  -TemplateSpecId $id `
  -ResourceGroupName demoRG

Uygulamada, genellikle dağıtmak istediğiniz şablon belirtiminin kimliğini almak için veya az ts show komutunu çalıştırırsınızGet-AzTemplateSpec.

$id = (Get-AzTemplateSpec -Name storageSpec -ResourceGroupName templateSpecsRg -Version 1.0a).Versions.Id

New-AzResourceGroupDeployment `
  -ResourceGroupName demoRG `
  -TemplateSpecId $id

Şablon belirtimini dağıtmak için url'yi aşağıdaki biçimde de açabilirsiniz:

https://portal.azure.com/#create/Microsoft.Template/templateSpecVersionId/%2fsubscriptions%2f{subscription-id}%2fresourceGroups%2f{resource-group-name}%2fproviders%2fMicrosoft.Resources%2ftemplateSpecs%2f{template-spec-name}%2fversions%2f{template-spec-version}

Parametreler

Parametreleri şablon belirtimine geçirmek, parametreleri bir Bicep dosyasına geçirmeye benzer. Parametre değerlerini satır içi veya parametre dosyasına ekleyin.

Satır içi parametreler

Bir parametreyi satır içinde geçirmek için şunu kullanın:

New-AzResourceGroupDeployment `
  -TemplateSpecId $id `
  -ResourceGroupName demoRG `
  -StorageAccountType Standard_GRS

Parametre dosyaları

  • Bicep parametre dosyasını kullanma

    Bicep parametre dosyası oluşturmak için deyimini using belirtmeniz gerekir. Örnek aşağıda verilmiştir:

    using 'using 'ts:<subscription-id>/<resource-group-name>/<template-spec-name>:<tag>'

param StorageAccountType = 'Standard_GRS'

    Daha fazla bilgi için bkz . Bicep parametre dosyası.

    Parametre dosyasını şu şekilde geçirmek için:

    Şu anda Azure PowerShell kullanarak .bicepparam dosyasıyla şablon belirtimleri dağıtamazsınız.

  • JSON parametre dosyasını kullanma

    Aşağıdaki JSON örnek bir JSON parametre dosyasıdır:

    {
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "StorageAccountType": {
      "value": "Standard_GRS"
    }
  }
}

    Ve bu parametre dosyasını şu şekilde geçirin:

    New-AzResourceGroupDeployment `
  -TemplateSpecId $id `
  -ResourceGroupName demoRG `
  -TemplateParameterFile ./mainTemplate.parameters.json

Sürüm oluşturma

Şablon belirtimi oluşturduğunuzda, bunun için bir sürüm adı sağlarsınız. Şablon kodunu yinelerken, var olan bir sürümü güncelleştirebilir (düzeltmeler için) veya yeni bir sürüm yayımlayabilirsiniz. Sürüm bir metin dizesidir. Anlamsal sürüm oluşturma dahil olmak üzere herhangi bir sürüm oluşturma sistemini izlemeyi seçebilirsiniz. Şablon belirtiminin kullanıcıları, dağıtırken kullanmak istedikleri sürüm adını sağlayabilir. Aralıksız sayıda sürüme sahip olabilirsiniz.

Etiketleri kullanma

Etiketler , kaynaklarınızı mantıksal olarak düzenlemenize yardımcı olur. Azure PowerShell ve Azure CLI kullanarak şablon özelliklerine etiket ekleyebilirsiniz. Aşağıdaki örnek, şablon belirtimini oluştururken etiketlerin nasıl belirtileceğini gösterir:

New-AzTemplateSpec `
  -Name storageSpec `
  -Version 1.0a `
  -ResourceGroupName templateSpecsRg `
  -Location westus2 `
  -TemplateFile ./mainTemplate.bicep `
  -Tag @{Dept="Finance";Environment="Production"}

Sonraki örnekte, mevcut şablon belirtimini güncelleştirirken etiketlerin nasıl uygulanacağı gösterilmektedir:

Set-AzTemplateSpec `
  -Name storageSpec `
  -Version 1.0a `
  -ResourceGroupName templateSpecsRg `
  -Location westus2 `
  -TemplateFile ./mainTemplate.bicep `
  -Tag @{Dept="Finance";Environment="Production"}

Hem şablonun hem de sürümlerinin etiketleri olabilir. Etiketler, belirttiğiniz parametrelere bağlı olarak uygulanır veya devralınır.

Şablon belirtimi Sürüm Sürüm parametresi Etiket parametresi Etiket değerleri
Exists Yok Belirtilmemiş Belirtilen şablon belirtimine uygulandı
Exists Yeni Belirtilen Belirtilmemiş şablon belirtiminden sürüme devralındı
Yeni Yeni Belirtilen Belirtilen hem şablon belirtimine hem de sürüme uygulandı
Exists Yeni Belirtilen Belirtilen sürüme uygulandı
Exists Exists Belirtilen Belirtilen sürüme uygulandı

Bir şablon belirtimi oluşturduktan sonra, bir Bicep modülünde bu şablon belirtimine bağlanabilirsiniz. Bu modülü içeren Bicep dosyasını dağıttığınızda şablon belirtimi dağıtılır. Daha fazla bilgi için bkz . Şablonda dosya belirtimi.

Modül bağlamaya yönelik şablon belirtimlerine yönelik diğer adlar oluşturmak için bkz . Modüller için diğer adlar.

Sonraki adımlar

Şablon özellikleri hakkında daha fazla bilgi edinmek ve uygulamalı yönergeler için bkz . Şablon belirtimlerini kullanarak yeniden kullanılabilir altyapı kodu kitaplıklarını yayımlama.