Tworzenie i publikowanie specyfikacji szablonu

  • 3 min

Przyjrzyjmy się sposobom tworzenia i publikowania specyfikacji szablonu.

Utwórz szablon

Aby utworzyć szablon do użycia jako specyfikację szablonu, należy napisać szablon usługi Azure Resource Manager (szablon usługi ARM), tak jak zwykle. Możesz uwzględnić parametry, zmienne, zasoby i dane wyjściowe.

Możesz użyć połączonych szablonów, które umożliwiają definiowanie części wdrożenia w osobnych plikach. Podczas pracy ze specyfikacjami szablonów połączone szablony można osadzać w specyfikacji szablonu i odwoływać się do szablonu głównego.

Ważne jest, aby szablon był łatwy dla każdego użytkownika w organizacji do zrozumienia i użycia, zwłaszcza jego parametrów. Upewnij się, że używasz przejrzystych i zrozumiałych nazw parametrów. Użyj właściwości parametru i metadanych szablonu, aby podać informacje o wartościach, które mają zawierać parametry, jak w tym przykładzie:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "environmentType": {
      "type": "string",
      "allowedValues": [
        "Production",
        "NonProduction"
      ],
      "metadata": {
        "description": "The type of the environment to deploy. This will determine the SKUs and cost of the resources."
      }
    },
    "key": {
      "type": "secureString",
      "metadata": {
        "description": "The secret key to use."
      }
    },
    "location": {
      "type": "string",
      "metadata": {
        "description": "The Azure region into which the resources should be deployed."
      }
    },
    "sqlServerCount": {
      "type": "int",
      "maxValue": 5,
      "metadata": {
        "description": "The number of Azure SQL logical servers to create."
      }
    }
  },
  "resources": []
}

W tym przykładzie parametry szablonu używają allowedValueswłaściwości , maxValuei description , aby wyjaśnić, jakie są parametry i jaki jest efekt ustawiania ich wartości. Szablon zawiera secureString również typ wskazujący key , że parametr zawiera dane tajne.

Ważne jest, aby szablon był łatwy dla każdej osoby w organizacji do zrozumienia i użycia, zwłaszcza parametrów. Upewnij się, że używasz przejrzystych i zrozumiałych nazw parametrów. Użyj dekoratorów parametrów, aby podać informacje o wartościach, które powinny zawierać parametry, tak jak w tym przykładzie:

@description('The type of the environment to deploy. This will determine the SKUs and cost of the resources.')
@allowed([
  'Production'
  'NonProduction'
])
param environmentType string

@secure()
@description('The secret key to use.')
param key string

@description('The Azure region into which the resources should be deployed.')
param location string

@description('The number of Azure SQL logical servers to create.')
@maxValue(5)
param sqlServerCount int

W tym przykładzie parametry szablonu używają @allowedelementów , @maxValuei @description dekoratorów, aby wyjaśnić, jakie są parametry i jaki jest efekt ustawiania ich wartości. Szablon zawiera secure również dekorator wskazujący key , że parametr zawiera tajne dane.

Gdy ktoś wdroży specyfikację szablonu przy użyciu witryny Azure Portal, portal:

  • Wyświetla nazwę parametru i opis.
  • Ukrywa wpis tekstowy dla bezpiecznych parametrów.
  • Wymusza zdefiniowane wartości dozwolone, limity długości i limity wartości.

Ten zrzut ekranu ilustruje wpis wartości parametrów:

Screenshot that shows the Azure portal interface for entering parameter values for a template spec deployment.

Ważne jest, aby zastanowić się, jak użytkownicy korzystają ze specyfikacji szablonu, i upewnić się, że parametry są jasne i zrozumiałe.

Publikowanie specyfikacji szablonu na platformie Azure

Po napisaniu szablonu zamiast przesyłania szablonu na platformę Azure do wdrożenia należy opublikować specyfikację szablonu.

Ważne

Podczas publikowania pliku Bicep jako specyfikacji szablonu kod Bicep jest konwertowany na szablon JSON. Proces konwertowania kodu Bicep na kod JSON usuwa niektóre informacje w pliku Bicep. Na przykład komentarze, nazwy symboliczne zasobów i kolejność definiowania zasobów mogą być brakujące lub inne w formacie JSON. Oznacza to, że nie można łatwo opublikować pliku Bicep jako specyfikacji szablonu, a następnie uzyskać oryginalny plik Bicep z powrotem (nazywany również roundtripping). Dobrym pomysłem jest przechowywanie kopii oryginalnego kodu Bicep w repozytorium kodu, takiego jak Git, szczególnie w przypadku pracy ze specyfikacjami szablonu.

Aby utworzyć specyfikację szablonu, użyj New-AzTemplateSpec polecenia cmdlet . W poniższym przykładzie pokazano, jak utworzyć specyfikację szablonu dla szablonu konta magazynu:

New-AzTemplateSpec `
  -Name StorageWithoutSAS `
  -Location westus `
  -DisplayName 'Storage account with SAS disabled' `
  -Description 'This template spec creates a storage account, which is preconfigured to disable SAS authentication.' `
  -Version '1.0' `
  -TemplateFile main.bicep

New-AzTemplateSpec `
  -Name StorageWithoutSAS `
  -Location westus `
  -DisplayName 'Storage account with SAS disabled' `
  -Description 'This template spec creates a storage account, which is preconfigured to disable SAS authentication.' `
  -Version '1.0' `
  -TemplateFile azuredeploy.json

Przyjrzyjmy się każdemu z parametrów:

  • -Name to nazwa zasobu specyfikacji szablonu, która nie może zawierać spacji.
  • -Location to lokalizacja, w której powinny zostać utworzone metadane specyfikacji szablonu. Specyfikację szablonu można jednak wdrożyć w dowolnym regionie.
  • -DisplayName to czytelna dla człowieka nazwa, która może zawierać spacje.
  • -Description to czytelny dla człowieka opis, którego można użyć, aby podać szczegółowe informacje o zawartości specyfikacji szablonu i o tym, kiedy ktoś może go użyć.
  • -Version to wersja specyfikacji szablonu. Zapoznasz się z wersjami w dalszej części tego modułu.
  • -TemplateFile to ścieżka do szablonu usługi ARM w celu utworzenia specyfikacji szablonu.

Aby utworzyć specyfikację szablonu, użyj az ts create polecenia . W poniższym przykładzie pokazano, jak utworzyć specyfikację szablonu dla szablonu konta magazynu:

az ts create \
  --name StorageWithoutSAS \
  --location westus \
  --display-name "Storage account with SAS disabled" \
  --description "This template spec creates a storage account, which is preconfigured to disable SAS authentication." \
  --version 1.0 \
  --template-file main.bicep

az ts create \
  --name StorageWithoutSAS \
  --location westus \
  --display-name "Storage account with SAS disabled" \
  --description "This template spec creates a storage account, which is preconfigured to disable SAS authentication." \
  --version 1.0 \
  --template-file azuredeploy.json

Przyjrzyjmy się każdemu z argumentów:

  • --name to nazwa zasobu specyfikacji szablonu, która nie może zawierać spacji.
  • --location to lokalizacja, w której powinny zostać utworzone metadane specyfikacji szablonu. Specyfikację szablonu można jednak wdrożyć w dowolnym regionie.
  • --display-name to czytelna dla człowieka nazwa, która może zawierać spacje.
  • --description to czytelny dla człowieka opis, którego można użyć, aby podać szczegółowe informacje o zawartości specyfikacji szablonu i o tym, kiedy ktoś może go użyć.
  • --version to wersja specyfikacji szablonu. Zapoznasz się z wersjami w dalszej części tego modułu.
  • --template-file to ścieżka do szablonu usługi ARM w celu utworzenia specyfikacji szablonu.

Napiwek

Możesz również zdefiniować specyfikację szablonu w szablonie usługi ARM! Ponieważ specyfikacja szablonu jest samym zasobem platformy Azure, można wdrożyć szablon definiujący zasób o typie Microsoft.Deployments/templateSpecs.