Tworzenie i publikowanie specyfikacji szablonu

Ukończone

Przyjrzyjmy się sposobom tworzenia i publikowania specyfikacji szablonu.

Tworzenie szablonu

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ć szablonów powiązanych z , 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ą właściwości allowedValues, maxValuei description, aby wyjaśnić, jakie są parametry i jaki jest efekt ustawiania ich wartości. Szablon zawiera również typ secureString wskazujący, że parametr key 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ą @allowed, @maxValuei dekoratorów @description, aby wyjaśnić, jakie są parametry i jaki jest efekt ustawiania ich wartości. Szablon zawiera również dekorator secure wskazujący, że parametr key zawiera dane tajne.

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

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

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

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żny

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 polecenia cmdlet New-AzTemplateSpec. W poniższym przykładzie pokazano, jak utworzyć specyfikację szablonu dla szablonu konta przechowywania:

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 jest nazwą 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 jest wersją specyfikacji szablonu. Zapoznasz się z wersjami w dalszej części tego modułu.
• -TemplateFile to ścieżka do szablonu ARM do utworzenia specyfikacji szablonu.

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

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 jest nazwą 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 jest wersją specyfikacji szablonu. Zapoznasz się z wersjami w dalszej części tego modułu.
• --template-file to ścieżka do szablonu ARM do utworzenia specyfikacji szablonu.

Napiwek

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