Jak używać szablonów wdrażania usługi Azure Resource Manager (ARM) przy użyciu interfejsu wiersza polecenia platformy Azure
W tym artykule wyjaśniono, jak używać interfejsu wiersza polecenia platformy Azure z szablonami usługi Azure Resource Manager (szablonami usługi ARM) do wdrażania zasobów na platformie Azure. Jeśli nie znasz pojęć związanych z wdrażaniem rozwiązań platformy Azure i zarządzaniem nimi, zobacz Omówienie wdrażania szablonów.
Polecenia wdrażania zmieniły się w interfejsie wiersza polecenia platformy Azure w wersji 2.2.0. Przykłady w tym artykule wymagają interfejsu wiersza polecenia platformy Azure w wersji 2.20.0 lub nowszej.
Aby uruchomić ten przykład, zainstaluj najnowszą wersję interfejsu wiersza polecenia platformy Azure. Aby rozpocząć, uruchom polecenie
az login w celu nawiązania połączenia z platformą Azure.
Przykłady dla interfejsu wiersza polecenia platformy Azure są napisane dla powłoki
bash . Aby uruchomić ten przykład w Windows PowerShell lub wierszu polecenia, może być konieczne zmianę elementów skryptu.
Jeśli nie masz zainstalowanego interfejsu wiersza polecenia platformy Azure, możesz użyć usługi Azure Cloud Shell. Aby uzyskać więcej informacji, zobacz Deploy ARM templates from Azure Cloud Shell (Wdrażanie szablonów usługi ARM z usługi Azure Cloud Shell).
Porada
Zalecamy Bicep , ponieważ oferuje te same możliwości co szablony usługi ARM, a składnia jest łatwiejsza w użyciu. Aby dowiedzieć się więcej, zobacz How to deploy resources with Bicep and Azure CLI (Jak wdrażać zasoby za pomocą interfejsu wiersza polecenia platformy Bicep i interfejsu wiersza polecenia platformy Azure).
Wymagane uprawnienia
Aby wdrożyć plik Bicep lub szablon usługi ARM, potrzebujesz dostępu do zapisu w zasobach wdrażanych i dostępu do wszystkich operacji w typie zasobu Microsoft.Resources/deployments. Na przykład w celu wdrożenia maszyny wirtualnej potrzebne są
Microsoft.Compute/virtualMachines/write uprawnienia i
Microsoft.Resources/deployments/* uprawnienia. Operacja warunkowa ma te same wymagania dotyczące uprawnień.
Aby uzyskać listę ról i uprawnień, zobacz Role wbudowane platformy Azure.
Zakres wdrożenia
Szablon wdrożenia platformy Azure można kierować do grupy zasobów, subskrypcji, grupy zarządzania lub dzierżawy. W zależności od zakresu wdrożenia należy użyć różnych poleceń.
Aby wdrożyć w grupie zasobów, użyj polecenia az deployment group create:
az deployment group create --resource-group <resource-group-name> --template-file <path-to-template>
Aby wdrożyć w subskrypcji, użyj polecenia az deployment sub create:
az deployment sub create --location <location> --template-file <path-to-template>
Aby uzyskać więcej informacji na temat wdrożeń na poziomie subskrypcji, zobacz Tworzenie grup zasobów i zasobów na poziomie subskrypcji.
Aby wdrożyć w grupie zarządzania, użyj polecenia az deployment mg create:
az deployment mg create --location <location> --template-file <path-to-template>
Aby uzyskać więcej informacji na temat wdrożeń na poziomie grupy zarządzania, zobacz Tworzenie zasobów na poziomie grupy zarządzania.
Aby wdrożyć w dzierżawie, użyj polecenia az deployment tenant create:
az deployment tenant create --location <location> --template-file <path-to-template>
Aby uzyskać więcej informacji na temat wdrożeń na poziomie dzierżawy, zobacz Tworzenie zasobów na poziomie dzierżawy.
Dla każdego zakresu użytkownik wdrażający szablon musi mieć wymagane uprawnienia do tworzenia zasobów.
Wdrażanie szablonu lokalnego
Szablon usługi ARM można wdrożyć na komputerze lokalnym lub na komputerze lokalnym, który jest przechowywany zewnętrznie. W tej sekcji opisano wdrażanie szablonu lokalnego.
Jeśli wdrażasz w grupie zasobów, która nie istnieje, utwórz grupę zasobów. Nazwa grupy zasobów może zawierać tylko znaki alfanumeryczne, kropki, podkreślenia, łączniki i nawiasy. Może to być maksymalnie 90 znaków. Nazwa nie może kończyć się kropką.
az group create --name ExampleGroup --location "Central US"
Aby wdrożyć szablon lokalny, użyj parametru
--template-file w poleceniu wdrażania. W poniższym przykładzie pokazano również, jak ustawić wartość parametru.
az deployment group create \ --name ExampleDeployment \ --resource-group ExampleGroup \ --template-file <path-to-template> \ --parameters storageAccountType=Standard_GRS
Wartość parametru
--template-file musi być plikiem Bicep lub plikiem
.json lub
.jsonc . Rozszerzenie
.jsonc pliku wskazuje, że plik może zawierać
// komentarze stylu. System ARM akceptuje komentarze w
.json plikach
//. Nie zależy to na rozszerzeniu pliku. Aby uzyskać więcej informacji na temat komentarzy i metadanych, zobacz Omówienie struktury i składni szablonów usługi ARM.
Ukończenie szablonu wdrażania platformy Azure może potrwać kilka minut. Po zakończeniu zostanie wyświetlony komunikat zawierający wynik:
"provisioningState": "Succeeded",
Wdrażanie szablonu zdalnego
Zamiast przechowywać szablony usługi ARM na komputerze lokalnym, możesz wolisz przechowywać je w lokalizacji zewnętrznej. Szablony można przechowywać w repozytorium kontroli źródła (na przykład GitHub). Można je również przechowywać na koncie usługi Azure Storage w celu uzyskania dostępu współdzielonego w organizacji.
Uwaga
Aby wdrożyć szablon lub odwołać się do połączonego szablonu przechowywanego w prywatnym repozytorium GitHub, zobacz niestandardowe rozwiązanie opisane w temacie Tworzenie niestandardowej i bezpiecznej oferty witryny Azure Portal. Możesz utworzyć funkcję platformy Azure, która ściąga token usługi GitHub z usługi Azure Key Vault.
Jeśli wdrażasz w grupie zasobów, która nie istnieje, utwórz grupę zasobów. Nazwa grupy zasobów może zawierać tylko znaki alfanumeryczne, kropki, podkreślenia, łączniki i nawiasy. Może to być maksymalnie 90 znaków. Nazwa nie może kończyć się kropką.
az group create --name ExampleGroup --location "Central US"
Aby wdrożyć szablon zewnętrzny, użyj parametru
template-uri.
az deployment group create \ --name ExampleDeployment \ --resource-group ExampleGroup \ --template-uri "https://raw.githubusercontent.com/Azure/azure-quickstart-templates/master/quickstarts/microsoft.storage/storage-account-create/azuredeploy.json" \ --parameters storageAccountType=Standard_GRS
Powyższy przykład wymaga publicznie dostępnego identyfikatora URI szablonu, który działa w większości scenariuszy, ponieważ szablon nie powinien zawierać poufnych danych. Jeśli musisz określić poufne dane (takie jak hasło administratora), przekaż wartość jako bezpieczny parametr. Jeśli jednak chcesz zarządzać dostępem do szablonu, rozważ użycie specyfikacji szablonu.
Aby wdrożyć zdalne połączone szablony ze ścieżką względną przechowywaną na koncie magazynu, użyj polecenia
query-string , aby określić token SAS:
az deployment group create \ --name linkedTemplateWithRelativePath \ --resource-group myResourceGroup \ --template-uri "https://stage20210126.blob.core.windows.net/template-staging/mainTemplate.json" \ --query-string $sasToken
Aby uzyskać więcej informacji, zobacz Używanie ścieżki względnej dla połączonych szablonów.
Nazwa szablonu wdrożenia platformy Azure
Podczas wdrażania szablonu usługi ARM możesz nadać szablonowi wdrożenia platformy Azure nazwę. Ta nazwa może pomóc w pobraniu wdrożenia z historii wdrożenia. Jeśli nie podasz nazwy wdrożenia, zostanie użyta nazwa pliku szablonu. Jeśli na przykład wdrożysz szablon o nazwie azuredeploy.json i nie określisz nazwy wdrożenia, wdrożenie ma nazwę
azuredeploy.
Za każdym razem, gdy uruchamiasz wdrożenie, do historii wdrożenia grupy zasobów zostanie dodany wpis o nazwie wdrożenia. Jeśli uruchomisz inne wdrożenie i nadasz mu taką samą nazwę, wcześniejszy wpis zostanie zastąpiony bieżącym wdrożeniem. Jeśli chcesz zachować unikatowe wpisy w historii wdrożenia, nadaj każdemu wdrożeniu unikatową nazwę.
Aby utworzyć unikatową nazwę, możesz przypisać liczbę losową.
deploymentName='ExampleDeployment'$RANDOM
Możesz też dodać wartość daty.
deploymentName='ExampleDeployment'$(date +"%d-%b-%Y")
Jeśli uruchamiasz współbieżne wdrożenia do tej samej grupy zasobów o tej samej nazwie wdrożenia, ukończono tylko ostatnie wdrożenie. Wszystkie wdrożenia o tej samej nazwie, które nie zostały zakończone, są zastępowane przez ostatnie wdrożenie. Jeśli na przykład uruchomisz wdrożenie o nazwie
newStorage , które wdraża konto magazynu o nazwie , a jednocześnie uruchomisz inne wdrożenie o nazwie , które wdraża konto magazynu o
newStorage nazwie
storage2
storage1, wdrożysz tylko jedno konto magazynu. Wynikowe konto magazynu nosi nazwę
storage2.
Jeśli jednak uruchomisz wdrożenie o nazwie
newStorage , które wdraża konto magazynu o nazwie , i natychmiast po jego zakończeniu uruchomisz inne wdrożenie o nazwie
newStorage , które wdraża konto magazynu o nazwie
storage1
storage2, masz dwa konta magazynu. Jeden ma nazwę , a drugi nosi nazwę
storage1
storage2. Jednak w historii wdrożenia masz tylko jeden wpis.
Po określeniu unikatowej nazwy dla każdego wdrożenia można uruchamiać je współbieżnie bez konfliktu. Jeśli uruchomisz wdrożenie o nazwie
newStorage1 , które wdraża konto magazynu o nazwie , a jednocześnie uruchomisz inne wdrożenie o nazwie
newStorage2 , które wdraża konto magazynu o nazwie
storage1
storage2, masz dwa konta magazynu i dwa wpisy w historii wdrożenia.
Aby uniknąć konfliktów z współbieżnymi wdrożeniami i zapewnić unikatowe wpisy w historii wdrożenia, nadaj każdemu wdrożeniu unikatową nazwę.
Wdrażanie specyfikacji szablonu
Zamiast wdrażać szablon lokalny lub zdalny, można utworzyć specyfikację szablonu. Specyfikacja szablonu to zasób w subskrypcji platformy Azure, który zawiera szablon usługi ARM. Ułatwia bezpieczne udostępnianie szablonu użytkownikom w organizacji. Aby udzielić dostępu do specyfikacji szablonu, należy użyć kontroli dostępu opartej na rolach (RBAC) platformy Azure. Ta funkcja jest obecnie dostępna w wersji zapoznawczej.
W poniższych przykładach pokazano, jak utworzyć i wdrożyć specyfikację szablonu.
Najpierw utwórz specyfikację szablonu, podając szablon usługi ARM.
az ts create \ --name storageSpec \ --version "1.0" \ --resource-group templateSpecRG \ --location "westus2" \ --template-file "./mainTemplate.json"
Następnie pobierz identyfikator specyfikacji szablonu i wdróż go.
id = $(az ts show --name storageSpec --resource-group templateSpecRG --version "1.0" --query "id") az deployment group create \ --resource-group demoRG \ --template-spec $id
Aby uzyskać więcej informacji, zobacz Azure Resource Manager specyfikacje szablonów.
Podgląd zmian
Przed wdrożeniem szablonu usługi ARM możesz wyświetlić podgląd zmian w środowisku. Użyj operacji analizy warunkowej , aby sprawdzić, czy szablon wprowadza oczekiwane zmiany. Co-jeśli weryfikuje również szablon pod kątem błędów.
Parametry
Aby przekazać wartości parametrów, możesz użyć parametrów wbudowanych lub pliku parametrów.
Parametry wbudowane
Aby przekazać parametry wbudowane, podaj wartości w pliku
parameters. Aby na przykład przekazać ciąg i tablicę do szablonu w powłoce Bash, użyj polecenia:
az deployment group create \ --resource-group testgroup \ --template-file <path-to-template> \ --parameters exampleString='inline string' exampleArray='("value1", "value2")'
Jeśli używasz interfejsu wiersza polecenia platformy Azure z wierszem polecenia systemu Windows (CMD) lub programem PowerShell, przekaż tablicę w formacie:
exampleArray="['value1','value2']".
Możesz również pobrać zawartość pliku i podać jej zawartość jako parametr wbudowany.
az deployment group create \ --resource-group testgroup \ --template-file <path-to-template> \ --parameters email@example.com firstname.lastname@example.org
Uzyskanie wartości parametru z pliku jest przydatne, gdy trzeba podać wartości konfiguracji. Można na przykład podać wartości cloud-init dla maszyny wirtualnej z systemem Linux.
Format arrayContent.json to:
[ "value1", "value2" ]
Aby przekazać obiekt, na przykład w celu ustawienia tagów, użyj kodu JSON. Na przykład szablon może zawierać parametr podobny do następującego:
"resourceTags": { "type": "object", "defaultValue": { "Cost Center": "IT Department" } }
W takim przypadku można przekazać ciąg JSON, aby ustawić parametr, jak pokazano w poniższym skry skry skryptzie powłoki Bash:
tags='{"Owner":"Contoso","Cost Center":"2345-324"}' az deployment group create --name addstorage --resource-group myResourceGroup \ --template-file $templateFile \ --parameters resourceName=abcdef4556 resourceTags="$tags"
Użyj podwójnych cudzysłowów wokół kodu JSON, które chcesz przekazać do obiektu.
Możesz użyć zmiennej , aby zawierać wartości parametrów. W powłoce Bash ustaw zmienną na wszystkie wartości parametrów i dodaj ją do polecenia wdrożenia.
params="prefix=start suffix=end" az deployment group create \ --resource-group testgroup \ --template-file <path-to-template> \ --parameters $params
Jeśli jednak używasz interfejsu wiersza polecenia platformy Azure z wierszem polecenia systemu Windows (CMD) lub programem PowerShell, ustaw zmienną na ciąg JSON. Ucieczka znaków cudzysłowu:
$params = '{ \"prefix\": {\"value\":\"start\"}, \"suffix\": {\"value\":\"end\"} }'.
Pliki parametrów
Zamiast przekazywania parametrów jako wartości śródwierszowych w skrypcie prostszym może się okazać użycie pliku JSON zawierającego wartości parametrów. Plik parametrów musi być plikiem lokalnym. Pliki parametrów zewnętrznych nie są obsługiwane w interfejsie wiersza polecenia platformy Azure.
Aby uzyskać więcej informacji na temat pliku parametrów, zobacz Tworzenie pliku parametrów usługi Resource Manager.
Aby przekazać plik parametrów lokalnych, użyj polecenia
@ , aby określić plik lokalny o nazwie storage.parameters.json.
az deployment group create \ --name ExampleDeployment \ --resource-group ExampleGroup \ --template-file storage.json \ --parameters '@storage.parameters.json'
Komentarze i rozszerzony format JSON
Komentarze stylu można uwzględnić
// w pliku parametrów, ale musisz nadać plikowi nazwę z
.jsonc rozszerzeniem.
az deployment group create \ --name ExampleDeployment \ --resource-group ExampleGroup \ --template-file storage.json \ --parameters '@storage.parameters.jsonc'
Aby uzyskać więcej informacji na temat komentarzy i metadanych, zobacz Omówienie struktury i składni szablonów usługi ARM.
Jeśli używasz interfejsu wiersza polecenia platformy Azure w wersji 2.3.0 lub starszej, możesz wdrożyć szablon z wielowierszowymi ciągami lub komentarzami przy użyciu przełącznika
--handle-extended-json-format . Przykład:
{ "type": "Microsoft.Compute/virtualMachines", "apiVersion": "2018-10-01", "name": "[variables('vmName')]", // to customize name, change it in variables "location": "[ parameters('location') ]", //defaults to resource group location /* storage account and network interface must be deployed first */ "dependsOn": [ "[resourceId('Microsoft.Storage/storageAccounts/', variables('storageAccountName'))]", "[resourceId('Microsoft.Network/networkInterfaces/', variables('nicName'))]" ],
Następne kroki
- Aby przywrócić pomyślne wdrożenie po wystąpieniu błędu, zobacz Wycofywanie po błędzie w celu pomyślnego wdrożenia.
- Aby określić sposób obsługi zasobów istniejących w grupie zasobów, ale nie są zdefiniowane w szablonie, zobacz Tryby wdrażania usługi Azure Resource Manager.
- Aby dowiedzieć się, jak definiować parametry w szablonie, zobacz Omówienie struktury i składni szablonów usługi ARM.
- Aby uzyskać porady dotyczące rozwiązywania typowych błędów wdrażania, zobacz Rozwiązywanie typowych błędów wdrażania platformy Azure w usłudze Azure Resource Manager.