ARM şablonu en iyi uygulamaları

Bu makalede, Azure Resource Manager şablonunuzu (ARM şablonu) oluştururken önerilen yöntemlerin nasıl kullanılacağı gösterilmektedir. Bu öneriler, bir çözümü dağıtmak için ARM şablonu kullanırken sık karşılaşılan sorunlardan kaçınmanıza yardımcı olur.

Şablon sınırları

Şablonunuzun boyutunu 4 MB ve her kaynak tanımını 1 MB ile sınırlayın. Sınırlar, yinelemeli kaynak tanımları ve değişkenler ve parametreler için değerler ile genişletildikten sonra şablonun son durumuna uygulanır. Parametre dosyası da 4 MB ile sınırlıdır. İsteğin toplam boyutu fazla büyük olursa 4 MB'tan küçük bir şablon veya parametre dosyasıyla ilgili olarak hata alabilirsiniz. Şablonunuzu basitleştirerek büyük isteklerden kaçınmak hakkında daha fazla bilgi için bkz. Aşılan iş boyutuyla ilgili hataları düzeltme.

Ayrıca şöyle sınırlarınız vardır:

• 256 parametre
• 512 değişken
• 800 kaynak (kopyalama sayısı dahil)
• 64 çıkış değeri
• Abonelik/kiracı/yönetim grubu kapsamı başına 10 benzersiz konum
• Şablon ifadesinde 24.576 karakter

İç içe yerleştirilmiş bir şablon kullanarak bazı şablon sınırlarını aşabilirsiniz. Daha fazla bilgi için bkz. Azure kaynaklarını dağıtırken bağlı ve iç içe yerleştirilmiş şablonlar kullanma. Parametre, değişken veya çıkış sayısını azaltmak için birkaç değeri tek bir nesnede birleştirebilirsiniz. Daha fazla bilgi için bkz. Parametre olarak nesneler.

Kaynak grubu

Kaynakları bir kaynak grubuna dağıttığınızda, kaynak grubu kaynaklar hakkındaki meta verileri depolar. Meta veriler kaynak grubunun konumunda depolanır.

Kaynak grubunun bölgesi geçici olarak kullanılamaz durumdaysa, meta veriler kullanılamadığından kaynak grubundaki kaynakları güncelleştiremezsiniz. Diğer bölgelerdeki kaynaklar beklendiği gibi çalışmaya devam eder ama bunları güncelleştiremezsiniz. Riski en aza indirmek için kaynak grubunuzu ve kaynaklarınızı aynı bölgeye konumlandırın.

Parametreler

Parametrelerle çalışırken bu bölümdeki bilgiler yararlı olabilir.

Parametreler için genel öneriler

• Parametre kullanımınızı en aza indirin. Bunun yerine, dağıtım sırasında belirtilmesi gerekmeyen özellikler için değişkenleri veya değişmez değerleri kullanın.

• Parametre adları için camel case kullanın.

• Ortama göre değişen SKU, boyut veya kapasite gibi ayarlar için parametreleri kullanın.

• Kolay tanımlama için belirtmek istediğiniz kaynak adları için parametreleri kullanın.

• Meta verilerdeki her parametrenin açıklamasını sağlayın.

  "parameters": {
    "storageAccountType": {
      "type": "string",
      "metadata": {
        "description": "The type of the new storage account created to store the VM disks."
      }
    }
  }
  

• Hassas olmayan parametreler için varsayılan değerleri tanımlayın. Varsayılan bir değer belirterek, şablonu dağıtmak daha kolaydır ve şablonunuzun kullanıcıları uygun bir değer örneği görür. Bir parametrenin varsayılan değerleri, varsayılan dağıtım yapılandırmasındaki tüm kullanıcılar için geçerli olmalıdır.

  "parameters": {
    "storageAccountType": {
      "type": "string",
      "defaultValue": "Standard_GRS",
      "metadata": {
        "description": "The type of the new storage account created to store the VM disks."
      }
    }
  }
  

• İsteğe bağlı bir parametre belirtmek için, varsayılan değer olarak boş bir dize kullanmayın. Bunun yerine, değer oluşturmak için değişmez değer veya dil ifadesi kullanın.

  "storageAccountName": {
     "type": "string",
     "defaultValue": "[concat('storage', uniqueString(resourceGroup().id))]",
     "metadata": {
       "description": "Name of the storage account"
     }
  }
  

• allowedValues ögesini tedbirli kullanın. Yalnızca bazı değerlerin izin verilen seçeneklere dahil edilmediğinden emin olmanız gerektiğinde kullanın. Çok geniş bir şekilde kullanıyorsanız allowedValues , listenizi güncel tutmayarak geçerli dağıtımları engelleyebilirsiniz.

• Şablonunuzdaki bir parametre adı PowerShell dağıtım komutundaki bir parametreyle eşleştiğinde, Resource Manager şablon parametresine FromTemplate son ekini ekleyerek bu adlandırma çakışmasını çözer. Örneğin, şablonunuzda ResourceGroupName adlı bir parametre eklerseniz, bu parametre New-AzResourceGroupDeployment cmdlet'indeki ResourceGroupName parametresiyle çakılır. Dağıtım sırasında ResourceGroupNameFromTemplate için bir değer sağlamanız istenir.

Parametreler için güvenlik önerileri

• Kullanıcı adları ve parolalar (veya gizli diziler) için her zaman parametreleri kullanın.

• securestring ögesini tüm parolalar ve gizli diziler için kullanın. Hassas verileri bir JSON nesnesine geçirirseniz türünü kullanın secureObject . Güvenli dize veya güvenli nesne türlerine sahip şablon parametreleri kaynak dağıtımı sonrasında okunamaz.

  "parameters": {
    "secretValue": {
      "type": "securestring",
      "metadata": {
        "description": "The value of the secret to store in the vault."
      }
    }
  }
  

• Kullanıcı adları, parolalar veya tür gerektiren herhangi bir secureString değer için varsayılan değerler sağlamayın.

• Uygulamanın saldırı yüzeyi alanını artıran özellikler için varsayılan değerler sağlamayın.

Parametreler için konum önerileri

• Kaynakların konumunu belirtmek için bir parametre kullanın ve varsayılan değeri olarak resourceGroup().locationayarlayın. Konum parametresinin sağlanması, şablon kullanıcılarının kaynakları dağıtma iznine sahip oldukları bir konum belirtmesini sağlar.

  "parameters": {
     "location": {
       "type": "string",
       "defaultValue": "[resourceGroup().location]",
       "metadata": {
         "description": "The location in which the resources should be deployed."
       }
     }
  }
  

• Konum parametresini belirtmeyin allowedValues . Belirttiğiniz konumlar tüm bulutlarda kullanılamayabilir.

• Aynı konumda olma olasılığı olan kaynaklar için konum parametresi değerini kullanın. Bu yaklaşım, kullanıcıların konum bilgilerini sağlamalarının istenmesinin sayısını en aza indirir.

• Tüm konumlarda bulunmayan kaynaklar için ayrı bir parametre kullanın veya sabit bir konum değeri belirtin.

Değişkenler

Değişkenlerle çalışırken aşağıdaki bilgiler yararlı olabilir:

• Değişken adları için deve büyük/küçük harf kullanın.

• Şablonda birden çok kez kullanmanız gereken değerler için değişkenleri kullanın. Bir değer yalnızca bir kez kullanılıyorsa, sabit kodlanmış bir değer şablonunuzun daha kolay okunmasını sağlar.

• Şablon işlevlerinin karmaşık bir düzenlemesinden oluşturduğunuz değerler için değişkenleri kullanın. Karmaşık ifade yalnızca değişkenlerde göründüğünde şablonunuz daha kolay okunur.

• Şablonun bölümünde başvuru işlevini variables kullanamazsınız. işlevi değerini reference kaynağın çalışma zamanı durumundan türetir. Ancak, değişkenler şablonun ilk ayrıştırılması sırasında çözümlenir. İşleve ihtiyaç duyan reference değerleri doğrudan şablonun resources veya outputs bölümünde oluşturma.

• Benzersiz olması gereken kaynak adları için değişkenleri ekleyin.

• Yinelenen JSON nesnelerinin desenini oluşturmak için değişkenlerde kopyalama döngüsü kullanın.

• Kullanılmayan değişkenleri kaldırın.

API sürümü

apiVersion özelliğini kaynak türü için sabit kodlanmış bir API sürümüne ayarlayın. Yeni şablon oluştururken, bir kaynak türü için en son API sürümünü kullanmanızı öneririz. Kullanılabilir değerleri belirlemek için bkz . şablon başvurusu.

Şablonunuz beklendiği gibi çalıştığında, aynı API sürümünü kullanmaya devam etmenizi öneririz. Aynı API sürümünü kullanarak, sonraki sürümlerde kullanıma sunulacak hataya neden olan değişiklikler konusunda endişelenmeniz gerekmez.

API sürümü için parametre kullanmayın. Kaynak özellikleri ve değerleri API sürümüne göre farklılık gösterebilir. Kod düzenleyicisindeki IntelliSense, API sürümü bir parametreye ayarlandığında doğru şemayı belirleyemez. Şablonunuzdaki özelliklerle eşleşmeyen bir API sürümü geçirirseniz dağıtım başarısız olur.

API sürümü için değişkenleri kullanmayın.

Kaynak bağımlılıkları

Hangi bağımlılıkların ayarlanacağına karar verirken aşağıdaki yönergeleri kullanın:

• reference işlevini kullanın ve bir özelliği paylaşması gereken kaynaklar arasında örtük bir bağımlılık ayarlamak için kaynak adını geçirin. Örtük bir bağımlılık tanımladıysanız açık dependsOn bir öğe eklemeyin. Bu yaklaşım gereksiz bağımlılıklara sahip olma riskini azaltır. Örtük bağımlılık ayarlama örneği için bkz . başvuru ve liste işlevleri.

• Alt kaynağı üst kaynağına bağımlı olarak ayarlayın.

• Koşul öğesinin ayarlandığı false kaynaklar bağımlılık sırasına göre otomatik olarak kaldırılır. Bağımlılıkları, kaynak her zaman dağıtılmış gibi ayarlayın.

• Bağımlılıkların açıkça ayarlanmadan art arda ayarlanmasına izin verin. Örneğin, sanal makineniz bir sanal ağ arabirimine, sanal ağ arabirimi ise bir sanal ağa ve genel IP adreslerine bağlıdır. Bu nedenle, sanal makine üç kaynağın tümünden sonra dağıtılır, ancak sanal makineyi üç kaynağa da bağımlı olarak açıkça ayarlamayın. Bu yaklaşım bağımlılık sırasını netleştirir ve şablonu daha sonra değiştirmeyi kolaylaştırır.

• Dağıtımdan önce bir değer belirlenebiliyorsa, kaynağı bağımlılık olmadan dağıtmayı deneyin. Örneğin, bir yapılandırma değeri başka bir kaynağın adına ihtiyaç duyuyorsa, bağımlılık gerekmeyebilir. Bazı kaynaklar diğer kaynağın varlığını doğruladığı için bu kılavuz her zaman çalışmaz. Hata alırsanız bir bağımlılık ekleyin.

Kaynaklar

Kaynaklarla çalışırken aşağıdaki bilgiler yararlı olabilir:

• Diğer katkıda bulunanların kaynağın amacını anlamasına yardımcı olmak için comments ögesini şablondaki her kaynak için belirtin.

  "resources": [
    {
      "name": "[variables('storageAccountName')]",
      "type": "Microsoft.Storage/storageAccounts",
      "apiVersion": "2019-06-01",
      "location": "[resourceGroup().location]",
      "comments": "This storage account is used to store the VM disks.",
        ...
    }
  ]
  

  ARM şablonunuz bir .jsonc dosyada depolanıyorsa, burada gösterildiği gibi söz dizimini // kullanan açıklamalar desteklenir.

  "resources": [
    {
      // This storage account is used to store the VM disks.
      "name": "[variables('storageAccountName')]",
      "type": "Microsoft.Storage/storageAccounts",
      "apiVersion": "2019-06-01",
      "location": "[resourceGroup().location]",
        ...
    }
  ]
  

  Açıklamalar ve meta veriler hakkında daha fazla ayrıntı için bkz . ARM şablonlarının yapısını ve söz dizimini anlama.

• Şablonunuzda genel uç nokta kullanıyorsanız (Azure Blob depolama genel uç noktası gibi), ad alanını sabit kodlamayın . ad alanını reference dinamik olarak almak için işlevini kullanın. Şablonu, şablondaki uç noktayı el ile değiştirmeden farklı genel ad alanı ortamlarına dağıtmak için bu yaklaşımı kullanabilirsiniz. API sürümünü, şablonunuzdaki depolama hesabı için kullandığınız sürüme ayarlayın.

  "diagnosticsProfile": {
    "bootDiagnostics": {
      "enabled": "true",
      "storageUri": "[reference(resourceId('Microsoft.Storage/storageAccounts', variables('storageAccountName')), '2019-06-01').primaryEndpoints.blob]"
    }
  }
  

  Depolama hesabı, oluşturduğunuz şablonda dağıtılıyorsa ve depolama hesabının adı şablondaki başka bir kaynakla paylaşılmıyorsa, sağlayıcı ad alanını veya apiVersion kaynağa başvururken belirtmeniz gerekmez. Aşağıdaki örnekte basitleştirilmiş söz dizimi gösterilmektedir.

  "diagnosticsProfile": {
    "bootDiagnostics": {
      "enabled": "true",
      "storageUri": "[reference(variables('storageAccountName')).primaryEndpoints.blob]"
    }
  }
  

  Ayrıca, farklı bir kaynak grubunda bulunan mevcut bir depolama hesabına da başvurabilirsiniz.

  "diagnosticsProfile": {
    "bootDiagnostics": {
      "enabled": "true",
      "storageUri": "[reference(resourceId(parameters('existingResourceGroup'), 'Microsoft.Storage/storageAccounts', parameters('existingStorageAccountName')), '2019-06-01').primaryEndpoints.blob]"
    }
  }
  

• Sanal makineye yalnızca bir uygulama gerektirdiğinde genel IP adresleri atayın. Yönetim amacıyla bir sanal makineye bağlanmak için gelen NAT kurallarını, sanal ağ geçidini veya sıçrama kutusunu kullanın.

  Sanal makinelere bağlanma hakkında daha fazla bilgi için bkz:

  • Azure Bastion nedir?
  • Windows çalıştıran bir Azure sanal makinesine bağlanma ve oturum açma
  • Azure Resource Manager'da Sanal Makineler için WinRM erişimini ayarlama
  • Linux VM'ye bağlanma

• domainNameLabel Genel IP adreslerinin özelliği benzersiz olmalıdır. Değer domainNameLabel 3 ile 63 karakter uzunluğunda olmalı ve şu normal ifade tarafından belirtilen kurallara uymalıdır: ^[a-z][a-z0-9-]{1,61}[a-z0-9]$. uniqueString İşlev 13 karakter uzunluğunda bir dize oluşturduğundandnsPrefixString, parametre 50 karakterle sınırlıdır.

  "parameters": {
    "dnsPrefixString": {
      "type": "string",
      "maxLength": 50,
      "metadata": {
        "description": "The DNS label for the public IP address. It must be lowercase. It should match the following regular expression, or it will raise an error: ^[a-z][a-z0-9-]{1,61}[a-z0-9]$"
      }
    }
  },
  "variables": {
    "dnsPrefix": "[concat(parameters('dnsPrefixString'),uniquestring(resourceGroup().id))]"
  }
  

• Özel betik uzantısına parola eklediğinizde özelliğindeki protectedSettings özelliğini kullanıncommandToExecute.

  "properties": {
    "publisher": "Microsoft.Azure.Extensions",
    "type": "CustomScript",
    "typeHandlerVersion": "2.0",
    "autoUpgradeMinorVersion": true,
    "settings": {
      "fileUris": [
        "[concat(variables('template').assets, '/lamp-app/install_lamp.sh')]"
      ]
    },
    "protectedSettings": {
      "commandToExecute": "[concat('sh install_lamp.sh ', parameters('mySqlPassword'))]"
    }
  }
  

  Not

  Gizli dizilerin VM'lere ve uzantılara parametre olarak geçirildiğinde şifrelendiğinden protectedSettings emin olmak için ilgili uzantıların özelliğini kullanın.

• Zaman içinde değişebilecek varsayılan değerlere sahip özellikler için açık değerler belirtin. Örneğin, aks kümesi dağıtıyorsanız özelliğini belirtebilir veya atlayabilirsiniz kubernetesVersion . Belirtmezseniz, küme varsayılan olarak N-1 ikincil sürümüne ve en son düzeltme ekine ayarlanır. Bir ARM şablonu kullanarak kümeyi dağıttığınızda, bu varsayılan davranış beklediğiniz gibi olmayabilir. Şablonunuzun yeniden dağıtılması, kümenin beklenmedik şekilde yeni bir Kubernetes sürümüne yükseltilmesine neden olabilir. Bunun yerine, açık bir sürüm numarası belirtmeyi ve kümenizi yükseltmeye hazır olduğunuzda bunu el ile değiştirmeyi göz önünde bulundurun.

Açıklamalar

özelliğine comments ek olarak, söz dizimini // kullanan açıklamalar da desteklenir. Açıklamalar ve meta veriler hakkında daha fazla ayrıntı için bkz . ARM şablonlarının yapısını ve söz dizimini anlama. JSON dosyasının açıklamalar içerdiğini belirtmek için dosya uzantısını .jsonc kullanarak açıklama içeren // JSON dosyalarını kaydetmeyi seçebilirsiniz. ARM hizmeti ayrıca parametre dosyaları da dahil olmak üzere tüm JSON dosyalarındaki açıklamaları kabul eder.

Visual Studio Code ARM Araçları

Visual Studio Code için Azure Resource Manager (ARM) Araçları ile ARM şablonlarıyla çalışmak daha kolaydır. Bu uzantı, Azure Resource Manager şablonları oluşturmanıza ve doğrulamanıza yardımcı olmak için dil desteği, kaynak parçacıkları ve kaynak otomatik tamamlama sağlar. Daha fazla bilgi edinmek ve uzantıyı yüklemek için bkz . Azure Resource Manager (ARM) Araçları.

Test araç setini kullanma

ARM şablonu test araç seti, şablonunuzun önerilen yöntemleri kullanıp kullanmadığını denetleen bir betiktir. Şablonunuz önerilen uygulamalarla uyumlu olmadığında, önerilen değişikliklerin yer aldığı uyarıların listesini döndürür. Test araç seti, şablonunuzda en iyi yöntemleri uygulamayı öğrenmenize yardımcı olabilir.

Şablonunuzu tamamladıktan sonra test araç setini çalıştırarak uygulamayı geliştirmenin yolları olup olmadığını öğrenin. Daha fazla bilgi için bkz . ARM şablonu test araç setini kullanma.

Sonraki adımlar

• Şablon dosyasının yapısı hakkında bilgi için bkz . ARM şablonlarının yapısını ve söz dizimini anlama.
• Tüm Azure bulut ortamlarında çalışan şablonlar oluşturma hakkında öneriler için bkz . Bulut tutarlılığı için ARM şablonları geliştirme.