Azure CLI에서 ARM(Azure Resource Manager) 배포 템플릿을 사용하는 방법

아티클
03/18/2024

이 문서는 ARM 템플릿(Azure Resource Manager 템플릿)으로 Azure CLI를 사용하여 Azure에 리소스를 배포하는 방법을 설명합니다. Azure 솔루션 배포 및 관리 개념에 익숙하지 않은 경우 템플릿 배포 개요를 참조하세요.

배포 명령이 Azure CLI 버전 2.2.0에서 변경되었습니다. 이 문서의 예제에는 Azure CLI 버전 2.20.0 이상이 필요합니다.

이 샘플을 실행하려면 최신 버전의 Azure CLI를 설치합니다. 시작하려면 az login을 실행하여 Azure와 연결합니다.

Azure CLI 샘플은 bash 셸용으로 작성됩니다. Windows PowerShell 또는 명령 프롬프트에서 이 샘플을 실행하려면 스크립트의 요소를 변경해야 할 수도 있습니다.

Azure CLI가 설치되어 있지 않으면 Azure Cloud Shell을 사용할 수 있습니다. 자세한 내용은 Azure Cloud Shell에서 ARM 템플릿 배포를 참조하세요.

팁

ARM 템플릿과 동일한 기능을 제공하고 구문이 사용하기 더 쉽기 때문에 Bicep를 권장합니다. 자세한 내용은 Bicep 및 Azure CLI를 사용하여 리소스를 배포하는 방법을 참조하세요.

필요한 사용 권한

Bicep 파일 또는 ARM 템플릿을 배포하려면 배포하는 리소스에 대한 쓰기 액세스 및 Microsoft.Resources/deployments 리소스 형식의 모든 작업에 대한 액세스가 필요합니다. 예를 들어 가상 머신을 배포하려면 Microsoft.Compute/virtualMachines/write 및 Microsoft.Resources/deployments/* 권한이 필요합니다. 가상 작업에는 동일한 사용 권한 요구 사항이 있습니다.

역할 및 사용 권한 목록은 Azure 기본 제공 역할을 참조하세요.

배포 범위

Azure 배포 템플릿을 리소스 그룹, 구독, 관리 그룹 또는 테넌트로 지정할 수 있습니다. 배포의 범위에 따라 다른 명령을 사용합니다.

리소스 그룹에 배포하려면 az deployment group create를 사용합니다.

az deployment group create --resource-group <resource-group-name> --template-file <path-to-template>

구독에 배포하려면 az deployment sub create를 사용합니다.
```
az deployment sub create --location <location> --template-file <path-to-template>
```
구독 수준 배포에 대한 자세한 내용은 구독 수준에서 리소스 그룹 및 리소스 만들기를 참조하세요.
관리 그룹에 배포하려면 az deployment mg create를 사용합니다.
```
az deployment mg create --location <location> --template-file <path-to-template>
```
관리 그룹 수준 배포에 대한 자세한 내용은 관리 그룹 수준에서 리소스 만들기를 참조하세요.
테넌트에 배포하려면 az deployment tenant create를 사용합니다.
```
az deployment tenant create --location <location> --template-file <path-to-template>
```
테넌트 수준 배포에 대한 자세한 내용은 테넌트 수준에서 리소스 만들기를 참조하세요.

모든 범위에서 템플릿을 배포하는 사용자는 리소스를 만드는 데 필요한 권한이 있어야 합니다.

로컬 템플릿 배포

로컬 컴퓨터이나 외부에 저장된 컴퓨터에서 ARM 템플릿을 배포할 수 있습니다. 이 섹션에서는 로컬 템플릿 배포에 대해 설명합니다.

존재하지 않는 리소스 그룹에 배포하는 경우 리소스 그룹을 만듭니다. 리소스 그룹의 이름은 영숫자, 마침표, 밑줄, 하이픈 및 괄호만 포함할 수 있습니다. 최대 90자까지 가능합니다. 이름은 마침표로 끝날 수 없습니다.

az group create --name ExampleGroup --location "Central US"

로컬 템플릿을 배포하려면 배포 명령에 --template-file 매개 변수를 사용합니다. 다음 예제에서는 매개 변수 값을 설정하는 방법을 보여 줍니다.

az deployment group create \
  --name ExampleDeployment \
  --resource-group ExampleGroup \
  --template-file <path-to-template> \
  --parameters storageAccountType=Standard_GRS

--template-file 매개 변수의 값은 Bicep 파일 또는 .json 또는 .jsonc 파일이어야 합니다. .jsonc 파일 확장명은 파일에 // 스타일 주석이 포함될 수 있음을 나타냅니다. ARM 시스템은 .json 파일의 // 주석을 허용합니다. 파일 확장명은 신경 쓰지 않습니다. 주석 및 메타데이터에 대한 자세한 내용은 ARM 템플릿의 구조 및 구문 이해를 참조하세요.

Azure 배포 템플릿을 완료하는 데 몇 분 정도 걸릴 수 있습니다. 완료되면 결과가 포함된 메시지가 표시됩니다.

"provisioningState": "Succeeded",

원격 템플릿 배포

로컬 컴퓨터에 ARM 템플릿을 저장하는 대신, 외부 위치에 저장할 수 있습니다. 원본 제어 리포지토리(예: GitHub)에 템플릿을 저장할 수 있습니다. 또는 조직에서 공유 액세스에 대한 Azure Storage 계정에 저장할 수 있습니다.

참고 항목

템플릿을 배포하거나 프라이빗 GitHub 리포지토리에 저장된 연결된 템플릿을 참조하려면 사용자 지정 및 보안 Azure Portal 제품 만들기에 설명된 사용자 지정 솔루션을 참조하세요. Azure Key Vault에서 GitHub 토큰을 가져오는 Azure 함수를 만들 수 있습니다.

az group create --name ExampleGroup --location "Central US"

외부 템플릿을 배포하려면 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

앞의 예제에서는 템플릿에 중요한 데이터가 포함되어 있지 않으므로 대부분의 시나리오에 적합한 이 템플릿에 대해 공개적으로 액세스할 수 있는 URI가 필요합니다. 중요한 데이터(예: 관리자 암호)를 지정해야 하는 경우 해당 값을 안전한 매개 변수로 전달합니다. 그러나 템플릿에 대한 액세스를 관리하려는 경우 템플릿 사양을 사용하는 것이 좋습니다.

스토리지 계정에 저장된 상대 경로를 사용하여 원격 연결된 템플릿을 배포하려면 query-string을 사용하여 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

자세한 내용은 연결된 템플릿에 상대 경로 사용을 참조하세요.

Azure 배포 템플릿 이름

ARM 템플릿을 배포할 때 Azure 배포 템플릿에 이름을 지정할 수 있습니다. 해당 이름은 배포 기록에서 배포를 검색하는 데 도움이 될 수 있습니다. 배포에 이름을 제공하지 않으면 템플릿 파일의 이름이 사용됩니다. 예를 들어 azuredeploy.json이라는 템플릿을 배포하고 배포 이름을 지정하지 않으면 배포 이름은 azuredeploy가 됩니다.

배포를 실행할 때마다 리소스 그룹의 배포 기록에 항목이 배포 이름과 함께 추가됩니다. 다른 배포를 실행하고 동일한 이름을 지정하는 경우 이전 항목이 현재 배포로 바뀝니다. 배포 기록에서 고유한 항목을 유지하려면 각 배포에 고유한 이름을 지정합니다.

고유한 이름을 만들려면 임의의 번호를 할당하면 됩니다.

deploymentName='ExampleDeployment'$RANDOM

또는 날짜 값을 추가할 수 있습니다.

deploymentName='ExampleDeployment'$(date +"%d-%b-%Y")

같은 배포 이름의 동일한 리소스 그룹에 동시 배포를 실행하는 경우 마지막 배포만 완료됩니다. 완료되지 않은 동일한 이름의 배포는 마지막 배포로 대체됩니다. 예를 들어 storage1이라는 스토리지 계정을 배포하는 newStorage라는 배포를 실행하는 동시에 storage2라는 스토리지 계정을 배포하는 newStorage라는 다른 배포를 실행하는 경우 스토리지 계정을 하나만 배포합니다. 결과 스토리지 계정의 이름은 storage2입니다.

그러나 storage1이라는 스토리지 계정을 배포하는 newStorage라는 배포를 실행하고 배포가 완료된 직후에 storage2라는 스토리지 계정을 배포하는 newStorage라는 다른 배포를 실행하면 두 개의 스토리지 계정이 배포됩니다. 하나는 storage1이고 다른 하나는 storage2입니다. 그러나 배포 기록에는 하나의 항목만 기록됩니다.

각 배포에 고유한 이름을 지정하는 경우 충돌 없이 동시에 실행할 수 있습니다. storage1이라는 스토리지 계정을 배포하는 newStorage1이라는 배포를 실행하는 동시에 storage2라는 스토리지 계정을 배포하는 newStorage2라는 다른 배포를 실행하면 두 개의 스토리지 계정이 배포되고 배포 기록에 두 개의 항목이 기록됩니다.

동시 배포와의 충돌을 방지하고 배포 기록에서 고유한 항목이 기록되게 하려면 각 배포에 고유한 이름을 지정합니다.

템플릿 사양 배포

로컬 또는 원격 템플릿을 배포하는 대신 템플릿 사양을 만들 수 있습니다. 템플릿 사양은 ARM 템플릿이 포함된 Azure 구독의 리소스입니다. 이를 통해 조직의 사용자와 템플릿을 쉽고 안전하게 공유할 수 있습니다. Azure RBAC(역할 기반 액세스 제어)를 사용하여 템플릿 사양에 대한 액세스 권한을 부여합니다. 이 기능은 현재 미리 보기로 제공됩니다.

다음 예제에서는 템플릿 사양을 만들고 배포하는 방법을 보여 줍니다.

먼저 ARM 템플릿을 제공하여 템플릿 사양을 만듭니다.

az ts create \
  --name storageSpec \
  --version "1.0" \
  --resource-group templateSpecRG \
  --location "westus2" \
  --template-file "./mainTemplate.json"

그런 다음 템플릿 사양의 ID를 가져와서 배포합니다.

id = $(az ts show --name storageSpec --resource-group templateSpecRG --version "1.0" --query "id")

az deployment group create \
  --resource-group demoRG \
  --template-spec $id

자세한 내용은 Azure Resource Manager 템플릿 사양을 참조하세요.

변경 미리 보기

ARM 템플릿을 배포하기 전에 템플릿이 환경에 적용할 변경 내용을 미리 볼 수 있습니다. 가상 작업을 사용하여 템플릿이 예상대로 변경사항을 적용하는지 확인합니다. 가상 작업은 템플릿의 오류도 확인합니다.

매개 변수

매개 변수 값을 전달하려면 인라인 매개 변수 또는 매개 변수 파일을 사용할 수 있습니다. 매개 변수 파일은 Bicep 매개 변수 파일 또는 JSON 매개 변수 파일일 수 있습니다.

인라인 매개 변수입니다.

인라인 매개 변수를 전달하려면 parameters에 값을 제공합니다. 예를 들어 Bash 셸에서 문자열 및 배열을 템플릿에 전달하려면 다음을 사용합니다.

az deployment group create \
  --resource-group testgroup \
  --template-file <path-to-template> \
  --parameters exampleString='inline string' exampleArray='("value1", "value2")'

Windows 명령 프롬프트(CMD) 또는 PowerShell을 사용하여 Azure CLI를 사용하는 경우 배열을 exampleArray="['value1','value2']" 형식으로 전달합니다.

파일의 콘텐츠를 가져와서 해당 콘텐츠를 인라인 매개 변수로 제공할 수도 있습니다.

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

파일에서 매개 변수 값을 가져오면 구성 값을 제공해야 하는 경우에 유용합니다. 예를 들어, Linux 가상 머신에 대한 Cloud-Init 값을 제공할 수 있습니다.

arrayContent.json 형식은 다음과 같습니다.

[
  "value1",
  "value2"
]

예를 들어 태그를 설정하기 위해 개체를 전달하려면 JSON을 사용합니다. 예를 들어 템플릿에 다음과 같은 매개 변수가 포함될 수 있습니다.

"resourceTags": {
  "type": "object",
  "defaultValue": {
    "Cost Center": "IT Department"
  }
}

이 경우 다음 Bash 스크립트와 같이 JSON 문자열을 전달하여 매개 변수를 설정할 수 있습니다.

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

개체에 전달하려는 JSON 주위에 큰따옴표를 사용합니다.

변수를 사용하여 매개 변수 값을 포함할 수 있습니다. Bash에서 변수를 모든 매개 변수 값으로 설정하고 배포 명령에 추가합니다.

params="prefix=start suffix=end"

az deployment group create \
  --resource-group testgroup \
  --template-file <path-to-template> \
  --parameters $params

그러나 Windows 명령 프롬프트(CMD) 또는 PowerShell에서 Azure CLI를 사용하는 경우에는 변수를 JSON 문자열로 설정합니다. 따옴표를 이스케이프합니다(예: $params = '{ \"prefix\": {\"value\":\"start\"}, \"suffix\": {\"value\":\"end\"} }').

JSON 매개 변수 파일

스크립트에서 매개 변수를 인라인 값으로 전달하는 대신 .bicepparam 파일이나 매개 변수 값이 포함된 JSON 매개 변수 파일에 해당하는 매개 변수 파일을 사용하는 것이 더 편리할 수 있습니다. 매개 변수 파일은 로컬 파일이어야 합니다. 외부 매개 변수 파일은 Azure CLI에서 지원되지 않습니다.

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

매개 변수 파일에 대한 자세한 내용은 Resource Manager 매개 변수 파일 만들기를 참조하세요.

Bicep 매개 변수 파일

Azure CLI 버전 2.53.0 이상 및 Bicep CLI 버전 0.22.6 이상에서는 Bicep 매개 변수 파일을 활용하여 Bicep 파일을 배포할 수 있습니다. Bicep 매개 변수 파일 내의 using 문을 사용하면 --parameters 스위치에 대한 Bicep 매개 변수 파일을 지정할 때 --template-file 스위치를 제공할 필요가 없습니다. --template-file 스위치를 포함하면 ".bicep 템플릿만 .bicepparam 파일로 허용됩니다." 오류가 발생합니다.

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

매개 변수 파일은 로컬 파일이어야 합니다. 외부 매개 변수 파일은 Azure CLI에서 지원되지 않습니다. 매개 변수 파일에 대한 자세한 내용은 Resource Manager 매개 변수 파일 만들기를 참조하세요.

주석 및 확장된 JSON 형식

매개 변수 파일에 // 스타일 주석을 포함할 수 있지만 파일 이름을 .jsonc 확장명으로 지정해야 합니다.

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

주석 및 메타데이터에 대한 자세한 내용은 ARM 템플릿의 구조 및 구문 이해를 참조하세요.

버전이 2.3.0 이하인 Azure CLI를 사용하는 경우 --handle-extended-json-format 스위치를 사용하여 다중 선 줄 문자열이나 주석이 있는 템플릿을 배포할 수 있습니다. 예시:

{
  "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'))]"
  ],

다음 단계

오류 발생 시 성공적인 배포로 롤백하려면 오류 발생 시 성공적인 배포로 롤백을 참조하세요.
리소스 그룹에 있지만 템플릿에 정의되지 않은 리소스를 처리하는 방법을 지정하려면 Azure Resource Manager 배포 모드를 참조하세요.
템플릿에서 매개 변수를 정의하는 방법을 이해하려면 ARM 템플릿의 구조 및 구문 이해를 참조하세요.
일반적인 배포 오류를 해결하는 방법은 Azure Resource Manager를 사용한 일반적인 Azure 배포 오류 해결을 참조하세요.