Jak wdrażać zasoby za pomocą języka Bicep i interfejsu wiersza polecenia platformy Azure

Artykuł
03/22/2024

W tym artykule wyjaśniono, jak używać interfejsu wiersza polecenia platformy Azure z plikami Bicep w celu wdrożenia 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 Bicep.

Wymagania wstępne

Do wdrożenia potrzebny jest plik Bicep. Plik musi być lokalny.

Potrzebny jest interfejs wiersza polecenia platformy Azure i połączenie z platformą Azure:

Zainstaluj polecenia interfejsu wiersza polecenia platformy Azure na komputerze lokalnym. Aby wdrożyć pliki Bicep, potrzebujesz interfejsu wiersza polecenia platformy Azure w wersji 2.20.0 lub nowszej.
Połączenie na platformę Azure przy użyciu polecenia az login. Jeśli masz wiele subskrypcji platformy Azure, może być również konieczne uruchomienie polecenia az account set.

Przykłady dla interfejsu wiersza polecenia platformy Azure są napisane dla powłoki bash . Aby uruchomić ten przykład w programie 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 Bicep files from Azure Cloud Shell (Wdrażanie plików Bicep z usługi Azure Cloud Shell).

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 Microsoft.Compute/virtualMachines/write są uprawnienia i Microsoft.Resources/deployments/* uprawnienia. Operacja analizy co-jeżeli ma te same wymagania dotyczące uprawnień.

Aby uzyskać listę ról i uprawnień, zobacz Role wbudowane platformy Azure.

Zakres wdrożenia

Wdrożenie 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-bicep>

Aby wdrożyć w subskrypcji, użyj polecenia az deployment sub create:
```
az deployment sub create --location <location> --template-file <path-to-bicep>
```
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-bicep>
```
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-bicep>
```
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 plik Bicep musi mieć wymagane uprawnienia do tworzenia zasobów.

Wdrażanie lokalnego pliku Bicep

Możesz wdrożyć plik Bicep z komputera lokalnego lub pliku przechowywanego zewnętrznie. W tej sekcji opisano wdrażanie lokalnego pliku Bicep.

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ć lokalny plik Bicep, użyj przełącznika --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-bicep> \
  --parameters storageAccountType=Standard_GRS

Wdrożenie może potrwać kilka minut. Po zakończeniu zostanie wyświetlony komunikat zawierający wynik:

"provisioningState": "Succeeded",

Wdrażanie zdalnego pliku Bicep

Obecnie interfejs wiersza polecenia platformy Azure nie obsługuje wdrażania zdalnych plików Bicep. Interfejs wiersza polecenia Bicep umożliwia skompilowanie pliku Bicep do szablonu JSON, a następnie załadowanie pliku JSON do lokalizacji zdalnej. Aby uzyskać więcej informacji, zobacz Wdrażanie zdalnych szablonów JSON usługi ARM.

Parametry

Aby przekazać wartości parametrów, możesz użyć parametrów wbudowanych lub pliku parametrów. Plik parametrów może być plikiem parametrów Bicep lub plikiem parametrów JSON.

Parametry wbudowane

Aby przekazać parametry wbudowane, podaj wartości w pliku parameters. Aby na przykład przekazać ciąg i tablicę do pliku Bicep w powłoce powłoki Bash, użyj polecenia:

az deployment group create \
  --resource-group testgroup \
  --template-file <path-to-bicep> \
  --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 wbudowany parametr. Poprzedzaj nazwę pliku ciągiem @.

az deployment group create \
  --resource-group testgroup \
  --template-file <path-to-bicep> \
  --parameters exampleString=@stringContent.txt exampleArray=@arrayContent.json

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 formatu JSON. Na przykład plik Bicep 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 skrywcie powłoki Bash:

tags='{"Owner":"Contoso","Cost Center":"2345-324"}'
az deployment group create --name addstorage  --resource-group myResourceGroup \
--template-file $bicepFile \
--parameters resourceName=abcdef4556 resourceTags="$tags"

Użyj podwójnych cudzysłowów wokół kodu JSON, który chcesz przekazać do obiektu.

Jeśli używasz interfejsu wiersza polecenia platformy Azure z wierszem polecenia systemu Windows (CMD) lub programem PowerShell, przekaż obiekt w następującym formacie:

$tags="{'Owner':'Contoso','Cost Center':'2345-324'}"
az deployment group create --name addstorage  --resource-group myResourceGroup \
--template-file $bicepFile \
--parameters resourceName=abcdef4556 resourceTags=$tags

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-bicep> \
  --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. Uniknie cudzysłowu: $params = '{ \"prefix\": {\"value\":\"start\"}, \"suffix\": {\"value\":\"end\"} }'.

Ocena parametrów jest zgodna z kolejnością sekwencyjną, co oznacza, że jeśli wartość jest przypisana wiele razy, zostanie użyta tylko ostatnia przypisana wartość. Aby zapewnić prawidłowe przypisanie parametrów, zaleca się wstępne podanie pliku parametrów i selektywne zastąpienie określonych parametrów przy użyciu składni KEY=VALUE . Należy pamiętać, że jeśli podasz bicepparam plik parametrów, możesz użyć tego argumentu tylko raz.

Pliki parametrów Bicep

Zamiast przekazywać parametry jako wartości wbudowane w skrypcie, można łatwiej użyć pliku parametrów, pliku parametrów Bicep lub pliku parametrów 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 Create Resource Manager parameters file (Tworzenie pliku parametrów usługi Resource Manager).

Za pomocą interfejsu wiersza polecenia platformy Azure w wersji 2.53.0 lub nowszej oraz interfejsu wiersza polecenia Bicep w wersji 0.22.X lub nowszej można wdrożyć plik Bicep, korzystając z pliku parametrów Bicep. W pliku using parametrów Bicep instrukcji nie ma potrzeby podawania --template-file przełącznika podczas określania pliku parametrów Bicep dla przełącznika --parameters . Dołączenie przełącznika --template-file spowoduje wystąpienie błędu "Tylko szablon bicep jest dozwolony z plikiem bicepparam".

W poniższym przykładzie przedstawiono plik parametrów o nazwie storage.bicepparam. Plik znajduje się w tym samym katalogu, w którym jest uruchamiane polecenie.

az deployment group create \
  --name ExampleDeployment \
  --resource-group ExampleGroup \
  --parameters storage.bicepparam

Pliki parametrów JSON

W poniższym przykładzie przedstawiono plik parametrów o nazwie storage.parameters.json. Plik znajduje się w tym samym katalogu, w którym jest uruchamiane polecenie.

az deployment group create \
  --name ExampleDeployment \
  --resource-group ExampleGroup \
  --template-file storage.bicep \
  --parameters '@storage.parameters.json'

Aby uzyskać więcej informacji na temat pliku parametrów, zobacz Create Resource Manager parameters file (Tworzenie pliku parametrów usługi Resource Manager).

Możesz użyć wbudowanych parametrów i pliku parametrów lokalizacji w tej samej operacji wdrażania. Aby uzyskać więcej informacji, zobacz Pierwszeństwo parametrów.

Podgląd zmian

Przed wdrożeniem pliku Bicep możesz wyświetlić podgląd zmian, które plik Bicep wprowadzi w środowisku. Użyj operacji analizy co-jeżeli, aby sprawdzić, czy plik Bicep wprowadza oczekiwane zmiany. Co-jeżeli weryfikuje również plik Bicep pod kątem błędów.

Wdrażanie specyfikacji szablonu

Obecnie interfejs wiersza polecenia platformy Azure nie obsługuje tworzenia specyfikacji szablonu, udostępniając pliki Bicep. Można jednak utworzyć plik Bicep za pomocą zasobu Microsoft.Resources/templateSpecs w celu wdrożenia specyfikacji szablonu. Przykład tworzenia specyfikacji szablonu pokazuje, jak utworzyć specyfikację szablonu w pliku Bicep. Możesz również skompilować plik Bicep w formacie JSON przy użyciu interfejsu wiersza polecenia Bicep, a następnie utworzyć specyfikację szablonu przy użyciu szablonu JSON.

Nazwa wdrożenia

Podczas wdrażania pliku Bicep można nadać wdrożeniu 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 Bicep. Jeśli na przykład wdrożysz plik Bicep o nazwie main.bicep i nie określisz nazwy wdrożenia, wdrożenie ma nazwę main.

Za każdym razem, gdy uruchamiasz wdrożenie, wpis jest dodawany do historii wdrożenia grupy zasobów 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 wdrażania, nadaj każdemu wdrożeniu unikatową nazwę.

Aby utworzyć unikatową nazwę, można 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, zostanie ukończone tylko ostatnie wdrożenie. Wszystkie wdrożenia o tej samej nazwie, które nie zostały zakończone, są zastępowane ostatnim wdrożeniem. Jeśli na przykład uruchomisz wdrożenie o nazwie newStorage , które wdraża konto magazynu o nazwie , a jednocześnie uruchom inne wdrożenie o nazwie newStorage , które wdraża konto magazynu o nazwie storage1storage2, wdrażasz 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 zakończeniu uruchamiania innego wdrożenia o nazwie newStorage , które wdraża konto magazynu o nazwie storage1storage2, masz dwa konta magazynu. Jeden ma nazwę storage1, a drugi ma nazwę storage2. Jednak w historii wdrażania 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 uruchom kolejne wdrożenie o nazwie newStorage2 , które wdraża konto magazynu o nazwie storage1storage2, wówczas masz dwa konta magazynu i dwa wpisy w historii wdrożenia.

Aby uniknąć konfliktów z wdrożeniami współbieżnymi i zapewnić unikatowe wpisy w historii wdrożenia, nadaj każdemu wdrożeniu unikatową nazwę.

Następne kroki

Aby dowiedzieć się, jak definiować parametry w pliku, zobacz Omówienie struktury i składni plików Bicep.