리소스 관리자 템플릿과 Azure PowerShell로 리소스 배포Deploy resources with Resource Manager templates and Azure PowerShell

Resource Manager 템플릿으로 Azure PowerShell을 사용하여 Azure에 리소스를 배포하는 방법을 알아봅니다.Learn how to use Azure PowerShell with Resource Manager templates to deploy your resources to Azure. Azure 솔루션 배포 및 관리 개념에 대한 자세한 내용은 Azure Resource Manager 개요를 참조하세요.For more information about the concepts of deploying and managing your Azure solutions, see Azure Resource Manager overview.

참고

이 문서는 새 Azure PowerShell Az 모듈을 사용하도록 업데이트되었습니다.This article has been updated to use the new Azure PowerShell Az module. AzureRM 모듈은 적어도 2020년 12월까지 버그 수정을 수신할 예정이므로 계속 사용하셔도 됩니다.You can still use the AzureRM module, which will continue to receive bug fixes until at least December 2020. 새 Az 모듈 및 AzureRM 호환성에 대한 자세한 내용은 새 Azure PowerShell Az 모듈 소개를 참조하세요.To learn more about the new Az module and AzureRM compatibility, see Introducing the new Azure PowerShell Az module. Az 모듈 설치 지침은 Azure PowerShell 설치를 참조하세요.For Az module installation instructions, see Install Azure PowerShell.

배포 범위Deployment scope

Azure 구독 또는 구독 내에서 리소스 그룹 배포를 대상으로 지정할 수 있습니다.You can target your deployment to either an Azure subscription or a resource group within a subscription. 대부분의 경우에서 리소스 그룹 배포를 대상으로 수 있습니다.In most cases, you'll target deployment to a resource group. 구독 배포를 사용 하 여 정책 및 역할 할당은 구독에서 적용 하 합니다.Use subscription deployments to apply policies and role assignments across the subscription. 또한 리소스 그룹을 만들고 리소스를 배포할 구독 배포를 사용 합니다.You also use subscription deployments to create a resource group and deploy resources to it. 배포의 범위에 따라 다른 명령을 사용할 수 있습니다.Depending on the scope of the deployment, you use different commands.

배포 하는 리소스 그룹를 사용 하 여 새로 만들기-AzResourceGroupDeployment:To deploy to a resource group, use New-AzResourceGroupDeployment:

New-AzResourceGroupDeployment -ResourceGroupName <resource-group-name> -TemplateFile <path-to-template>

배포 하는 구독를 사용 하 여 새로 만들기-AzDeployment:To deploy to a subscription, use New-AzDeployment:

New-AzDeployment -Location <location> -TemplateFile <path-to-template>

현재 REST API를 통해 관리 그룹 배포만 지원 됩니다.Currently, management group deployments are only supported through the REST API. 참조 Resource Manager 템플릿과 Resource Manager REST API를 사용 하 여 리소스 배포합니다.See Deploy resources with Resource Manager templates and Resource Manager REST API.

이 문서의 예제에서는 리소스 그룹 배포를 사용합니다.The examples in this article use resource group deployments. 구독 배포에 대 한 자세한 내용은 참조 하세요. 구독 수준에서 리소스 그룹 및 리소스를 만드는합니다.For more information about subscription deployments, see Create resource groups and resources at the subscription level.

필수 조건Prerequisites

템플릿을 배포 해야 합니다.You need a template to deploy. 다운로드 하 고 저장 하면 이미 계정이 없는 경우는 예제 템플릿 Azure 빠른 시작 템플릿 리포지토리에서 합니다.If you don't already have one, download and save an example template from the Azure Quickstart templates repo. 이 문서에 사용된 로컬 파일 이름은 c:\MyTemplates\azuredeploy.json입니다.The local file name used in this article is c:\MyTemplates\azuredeploy.json.

템플릿을 배포 하는 Azure Cloud shell을 사용 하지 않는 한 Azure PowerShell을 설치 하 고 Azure에 연결 해야 합니다.Unless you use the Azure Cloud shell to deploy templates, you need to install Azure PowerShell and connect to Azure:

로컬 템플릿 배포Deploy local template

다음 예제에서는 리소스 그룹을 만들고 로컬 컴퓨터에서 템플릿을 배포 합니다.The following example creates a resource group, and deploys a template from your local machine. 리소스 그룹의 이름은 영숫자, 마침표, 밑줄, 하이픈 및 괄호만 포함할 수 있습니다.The name of the resource group can only include alphanumeric characters, periods, underscores, hyphens, and parenthesis. 최대 90자까지 가능합니다.It can be up to 90 characters. 마침표로 끝날 수 없습니다.It can't end in a period.

$resourceGroupName = Read-Host -Prompt "Enter the Resource Group name"
$location = Read-Host -Prompt "Enter the location (i.e. centralus)"

New-AzResourceGroup -Name $resourceGroupName -Location $location
New-AzResourceGroupDeployment -ResourceGroupName $resourceGroupName `
  -TemplateFile c:\MyTemplates\azuredeploy.json

배포가 완료될 때까지 몇 분 정도 걸릴 수 있습니다.The deployment can take a few minutes to complete.

원격 템플릿 배포Deploy remote template

로컬 컴퓨터에 Resource Manager 템플릿을 저장하는 대신, 외부 위치에 저장할 수 있습니다.Instead of storing Resource Manager templates on your local machine, you may prefer to store them in an external location. 원본 제어 리포지토리(예: GitHub)에 템플릿을 저장할 수 있습니다.You can store templates in a source control repository (such as GitHub). 또는 조직에서 공유 액세스에 대한 Azure Storage 계정에 저장할 수 있습니다.Or, you can store them in an Azure storage account for shared access in your organization.

외부 템플릿을 배포하려면 TemplateUri 매개 변수를 사용합니다.To deploy an external template, use the TemplateUri parameter. 예제의 URI를 사용하여 GitHub에서 샘플 템플릿을 배포합니다.Use the URI in the example to deploy the sample template from GitHub.

$resourceGroupName = Read-Host -Prompt "Enter the Resource Group name"
$location = Read-Host -Prompt "Enter the location (i.e. centralus)"

New-AzResourceGroup -Name $resourceGroupName -Location $location
New-AzResourceGroupDeployment -ResourceGroupName $resourceGroupName `
  -TemplateUri https://raw.githubusercontent.com/Azure/azure-quickstart-templates/master/101-storage-account-create/azuredeploy.json

앞의 예제에서는 템플릿에 중요한 데이터가 포함되어 있지 않으므로 대부분의 시나리오에 적합한 이 템플릿에 대해 공개적으로 액세스할 수 있는 URI가 필요합니다.The preceding example requires a publicly accessible URI for the template, which works for most scenarios because your template shouldn't include sensitive data. 중요한 데이터(예: 관리자 암호)를 지정해야 하는 경우 해당 값을 안전한 매개 변수로 전달합니다.If you need to specify sensitive data (like an admin password), pass that value as a secure parameter. 그러나 템플릿에 공개적으로 액세스할 수 있도록 하지 않으려면 프라이빗 스토리지 컨테이너에 저장하여 보호할 수 있습니다.However, if you don't want your template to be publicly accessible, you can protect it by storing it in a private storage container. SAS(공유 액세스 서명) 토큰이 필요한 템플릿을 배포하는 데 관한 내용은 SAS 토큰으로 프라이빗 템플릿 배포를 참조하세요.For information about deploying a template that requires a shared access signature (SAS) token, see Deploy private template with SAS token. 자습서를 진행하려면 자습서: Resource Manager 템플릿 배포에 Azure Key Vault 통합을 참조하세요.To go through a tutorial, see Tutorial: Integrate Azure Key Vault in Resource Manager Template deployment.

Azure Cloud shell에서 배포Deploy from Azure Cloud shell

Azure Cloud Shell을 사용하여 템플릿을 배포할 수 있습니다.You can use the Azure Cloud Shell to deploy your template. 외부 템플릿을 배포하려면 템플릿의 URI를 제공합니다.To deploy an external template, provide the URI of the template. 로컬 템플릿을 배포하려면 먼저 Cloud Shell용 스토리지 계정에 템플릿을 로드해야 합니다.To deploy a local template, you must first load your template into the storage account for your Cloud Shell. 셸에 파일을 업로드하려면 셸 창에서 파일 업로드/다운로드 메뉴 아이콘을 선택합니다.To upload files to the shell, select the Upload/Download files menu icon from the shell window.

Cloud Shell을 열려면 https://shell.azure.com으로 이동하거나, 다음 코드 섹션에서 Try-It을 선택합니다.To open the Cloud shell, browse to https://shell.azure.com, or select Try-It from the following code section:

$resourceGroupName = Read-Host -Prompt "Enter the Resource Group name"
$location = Read-Host -Prompt "Enter the location (i.e. centralus)"

New-AzResourceGroup -Name $resourceGroupName -Location $location
New-AzResourceGroupDeployment -ResourceGroupName $resourceGroupName `
  -TemplateUri https://raw.githubusercontent.com/Azure/azure-quickstart-templates/master/101-storage-account-create/azuredeploy.json

셸에 코드를 붙여넣으려면 셸 내부를 마우스 오른쪽 단추로 클릭하고 붙여넣기를 선택합니다.To paste the code into the shell, right-click inside the shell and then select Paste.

배포 실패 시 다시 배포Redeploy when deployment fails

이 기능은 라고도 오류 발생 시 롤백합니다.This feature is also known as Rollback on error. 배포가 실패하면 배포 기록에서 이전에 성공한 배포를 자동으로 다시 배포할 수 있습니다.When a deployment fails, you can automatically redeploy an earlier, successful deployment from your deployment history. 재배포를 지정하려면 배포 명령에 -RollbackToLastDeployment 또는 -RollBackDeploymentName 매개 변수를 사용합니다.To specify redeployment, use either the -RollbackToLastDeployment or -RollBackDeploymentName parameter in the deployment command. 이 기능은 인프라 배포에 대 한 알려진된 좋은 상태로 했습니다를이 상태로 되돌리려는 경우에 유용 합니다.This functionality is useful if you've got a known good state for your infrastructure deployment and want to revert to this state. 주의 및 제한 사항이 있습니다.There are a number of caveats and restrictions:

  • 재배포는 동일한 매개 변수를 사용 하 여 이전에 실행 했던 대로 실행 됩니다.The redeployment is run exactly as it was run previously with the same parameters. 매개 변수를 변경할 수 없습니다.You can't change the parameters.
  • 이전 배포를 사용 하 여 실행 되는 전체 모드합니다.The previous deployment is run using the complete mode. 이전 배포에 포함 되지 모든 리소스가 삭제 되 고 모든 리소스 구성을 이전 상태로 설정 됩니다.Any resources not included in the previous deployment are deleted, and any resource configurations are set to their previous state. 완벽 하 게 이해 해야 합니다 배포 모드합니다.Make sure you fully understand the deployment modes.
  • 리소스에만 영향을 줍니다 재배포, 모든 데이터 변경 내용은 영향을 받지 않습니다.The redeployment only affects the resources, any data changes aren't affected.
  • 이 기능은 리소스 그룹 배포의 경우 구독 수준 배포에만 지원 됩니다.This feature is only supported on Resource Group deployments, not subscription level deployments. 구독 수준 배포에 대 한 자세한 내용은 참조 하세요. 구독 수준에서 리소스 그룹 및 리소스를 만드는합니다.For more information about subscription level deployment, see Create resource groups and resources at the subscription level.

이 옵션을 사용하려면 배포가 배포 기록에서 식별될 수 있도록 고유한 이름을 지정해야 합니다.To use this option, your deployments must have unique names so they can be identified in the history. 고유한 이름이 없으면 현재 실패한 배포가 기록에서 이전에 성공한 배포를 덮어쓸 수 있습니다.If you don't have unique names, the current failed deployment might overwrite the previously successful deployment in the history. 루트 수준 배포에만 이 옵션을 사용할 수 있습니다.You can only use this option with root level deployments. 중첩된 템플릿의 배포는 다시 배포할 수 없습니다.Deployments from a nested template aren't available for redeployment.

성공한 마지막 배포를 다시 배포하려면 -RollbackToLastDeployment 매개 변수를 플래그로 추가합니다.To redeploy the last successful deployment, add the -RollbackToLastDeployment parameter as a flag.

New-AzResourceGroupDeployment -Name ExampleDeployment02 `
  -ResourceGroupName $resourceGroupName `
  -TemplateFile c:\MyTemplates\azuredeploy.json `
  -RollbackToLastDeployment

특정 배포를 다시 배포하려면 -RollBackDeploymentName 매개 변수를 사용하고 배포의 이름을 제공합니다.To redeploy a specific deployment, use the -RollBackDeploymentName parameter and provide the name of the deployment.

New-AzResourceGroupDeployment -Name ExampleDeployment02 `
  -ResourceGroupName $resourceGroupName `
  -TemplateFile c:\MyTemplates\azuredeploy.json `
  -RollBackDeploymentName ExampleDeployment01

지정된 배포는 분명히 성공했을 것입니다.The specified deployment must have succeeded.

매개 변수 값 전달Pass parameter values

매개 변수 값을 전달하려면 인라인 매개 변수 또는 매개 변수 파일을 사용할 수 있습니다.To pass parameter values, you can use either inline parameters or a parameter file. 이 문서의 이전 예제에서는 인라인 매개 변수를 보여 줍니다.The preceding examples in this article show inline parameters.

인라인 매개 변수Inline parameters

인라인 매개 변수를 전달하려면 New-AzResourceGroupDeployment 명령을 사용하여 매개 변수 이름을 제공합니다.To pass inline parameters, provide the names of the parameter with the New-AzResourceGroupDeployment command. 예를 들어, 문자열 및 배열을 템플릿에 전달하려면 다음을 사용합니다.For example, to pass a string and array to a template, use:

$arrayParam = "value1", "value2"
New-AzResourceGroupDeployment -ResourceGroupName testgroup `
  -TemplateFile c:\MyTemplates\demotemplate.json `
  -exampleString "inline string" `
  -exampleArray $arrayParam

파일의 콘텐츠를 가져와서 해당 콘텐츠를 인라인 매개 변수로 제공할 수도 있습니다.You can also get the contents of file and provide that content as an inline parameter.

$arrayParam = "value1", "value2"
New-AzResourceGroupDeployment -ResourceGroupName testgroup `
  -TemplateFile c:\MyTemplates\demotemplate.json `
  -exampleString $(Get-Content -Path c:\MyTemplates\stringcontent.txt -Raw) `
  -exampleArray $arrayParam

파일에서 매개 변수 값을 가져오면 구성 값을 제공해야 하는 경우에 유용합니다.Getting a parameter value from a file is helpful when you need to provide configuration values. 예를 들어, Linux 가상 머신에 대한 Cloud-Init 값을 제공할 수 있습니다.For example, you can provide cloud-init values for a Linux virtual machine.

개체의 배열을 전달 해야 할 경우 PowerShell에서 해시 테이블을 만들기 및 배열에 추가 합니다.If you need to pass in an array of objects, create hash tables in PowerShell and add them to an array. 배포 중 매개 변수로 해당 배열에 전달 합니다.Pass that array as a parameter during deployment.

$hash1 = @{ Name = "firstSubnet"; AddressPrefix = "10.0.0.0/24"}
$hash2 = @{ Name = "secondSubnet"; AddressPrefix = "10.0.1.0/24"}
$subnetArray = $hash1, $hash2
New-AzResourceGroupDeployment -ResourceGroupName testgroup `
  -TemplateFile c:\MyTemplates\demotemplate.json `
  -exampleArray $subnetArray

매개 변수 파일Parameter files

매개 변수를 스크립트에 인라인 값으로 전달하는 것보다는, 매개 변수 값이 포함된 JSON 파일을 사용하는 것이 더 쉬울 수 있습니다.Rather than passing parameters as inline values in your script, you may find it easier to use a JSON file that contains the parameter values. 매개 변수 파일은 로컬 파일이거나 액세스 가능한 URI가 있는 외부 파일일 수 있습니다.The parameter file can be a local file or an external file with an accessible URI.

매개 변수 파일은 다음과 같은 형식이어야 합니다.The parameter file must be in the following format:

{
  "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
     "storageAccountType": {
         "value": "Standard_GRS"
     }
  }
}

매개 변수 섹션에는 템플릿에 정의된 매개 변수(storageAccountType)와 일치하는 매개 변수 이름이 포함되어 있습니다.Notice that the parameters section includes a parameter name that matches the parameter defined in your template (storageAccountType). 매개 변수 파일에는 매개 변수의 값이 포함됩니다.The parameter file contains a value for the parameter. 이 값은 배포 동안 템플릿에 자동으로 전달됩니다.This value is automatically passed to the template during deployment. 둘 이상의 매개 변수 파일을 만든 후 시나리오에 적합한 매개 변수 파일을 전달할 수 있습니다.You can create more than one parameter file, and then pass in the appropriate parameter file for the scenario.

앞의 예제를 복사하고 storage.parameters.json이라는 파일로 저장합니다.Copy the preceding example and save it as a file named storage.parameters.json.

로컬 매개 변수 파일을 전달하려면 TemplateParameterFile 매개 변수를 사용합니다.To pass a local parameter file, use the TemplateParameterFile parameter:

New-AzResourceGroupDeployment -Name ExampleDeployment -ResourceGroupName ExampleResourceGroup `
  -TemplateFile c:\MyTemplates\azuredeploy.json `
  -TemplateParameterFile c:\MyTemplates\storage.parameters.json

외부 매개 변수 파일을 전달하려면 TemplateParameterUri 매개 변수를 사용합니다.To pass an external parameter file, use the TemplateParameterUri parameter:

New-AzResourceGroupDeployment -Name ExampleDeployment -ResourceGroupName ExampleResourceGroup `
  -TemplateUri https://raw.githubusercontent.com/Azure/azure-quickstart-templates/master/101-storage-account-create/azuredeploy.json `
  -TemplateParameterUri https://raw.githubusercontent.com/Azure/azure-quickstart-templates/master/101-storage-account-create/azuredeploy.parameters.json

매개 변수 우선 순위Parameter precedence

동일한 배포 작업에서 인라인 매개 변수 및 로컬 매개 변수 파일을 사용할 수 있습니다.You can use inline parameters and a local parameter file in the same deployment operation. 예를 들어 로컬 매개 변수 파일에서 일부 값을 지정하고 배포하는 동안 인라인으로 다른 값을 추가할 수 있습니다.For example, you can specify some values in the local parameter file and add other values inline during deployment. 로컬 매개 변수 파일 및 인라인에서 매개 변수에 대한 값을 제공하는 경우 인라인 값이 우선합니다.If you provide values for a parameter in both the local parameter file and inline, the inline value takes precedence.

하지만 외부 매개 변수 파일을 사용하면 인라인 또는 로컬 파일에서 다른 값을 전달할 수 없습니다.However, when you use an external parameter file, you can't pass other values either inline or from a local file. TemplateParameterUri 매개 변수에서 매개 변수 파일을 지정하는 경우 모든 인라인 매개 변수는 무시됩니다.When you specify a parameter file in the TemplateParameterUri parameter, all inline parameters are ignored. 외부 파일에서 모든 매개 변수 값을 제공해야 합니다.Provide all parameter values in the external file. 템플릿이 매개 변수 파일에 포함할 수 없는 중요한 값을 포함하는 경우 해당 값을 키 자격 증명 모음에 추가하고 동적으로 모든 매개 변수 값을 인라인으로 제공합니다.If your template includes a sensitive value that you can't include in the parameter file, either add that value to a key vault, or dynamically provide all parameter values inline.

매개 변수 이름 충돌Parameter name conflicts

템플릿에 PowerShell 명령의 매개 변수 중 하나와 이름이 같은 매개 변수가 포함되어 있으면 PowerShell에서 접미사가 FromTemplate인 템플릿에서 매개 변수를 제공합니다.If your template includes a parameter with the same name as one of the parameters in the PowerShell command, PowerShell presents the parameter from your template with the postfix FromTemplate. 예를 들어 템플릿의 ResourceGroupName 매개 변수는 New-AzResourceGroupDeployment cmdlet의 ResourceGroupName 매개 변수와 충돌합니다.For example, a parameter named ResourceGroupName in your template conflicts with the ResourceGroupName parameter in the New-AzResourceGroupDeployment cmdlet. ResourceGroupNameFromTemplate에 대한 값을 제공하라는 메시지가 표시됩니다.You're prompted to provide a value for ResourceGroupNameFromTemplate. 일반적으로 배포 작업에 사용되는 매개 변수와 동일한 이름을 가진 매개 변수를 명명하지 않음으로써 이러한 혼동이 발생하지 않도록 해야 합니다.In general, you should avoid this confusion by not naming parameters with the same name as parameters used for deployment operations.

템플릿 배포 테스트Test template deployments

리소스를 실제로 배포하지 않고 템플릿과 매개 변수 값을 테스트하려면 Test-AzureRmResourceGroupDeployment를 사용합니다.To test your template and parameter values without actually deploying any resources, use Test-AzureRmResourceGroupDeployment.

Test-AzResourceGroupDeployment -ResourceGroupName ExampleResourceGroup `
  -TemplateFile c:\MyTemplates\azuredeploy.json -storageAccountType Standard_GRS

오류가 감지되지 않으면 명령은 응답 없이 완료됩니다.If no errors are detected, the command finishes without a response. 오류가 감지되면 명령은 오류 메시지를 반환합니다.If an error is detected, the command returns an error message. 예를 들어, 저장소 계정 SKU에 대해 잘못된 값을 전달하면 다음 오류가 반환됩니다.For example, passing an incorrect value for the storage account SKU, returns the following error:

Test-AzResourceGroupDeployment -ResourceGroupName testgroup `
  -TemplateFile c:\MyTemplates\azuredeploy.json -storageAccountType badSku

Code    : InvalidTemplate
Message : Deployment template validation failed: 'The provided value 'badSku' for the template parameter 'storageAccountType'
          at line '15' and column '24' is not valid. The parameter value is not part of the allowed value(s):
          'Standard_LRS,Standard_ZRS,Standard_GRS,Standard_RAGRS,Premium_LRS'.'.
Details :

템플릿에 구문 오류가 있는 경우 명령은 템플릿을 구문 분석할 수 없다는 오류를 반환합니다.If your template has a syntax error, the command returns an error indicating it couldn't parse the template. 메시지는 줄 번호 및 구문 분석 오류의 위치를 나타냅니다.The message indicates the line number and position of the parsing error.

Test-AzResourceGroupDeployment : After parsing a value an unexpected character was encountered: 
  ". Path 'variables', line 31, position 3.

다음 단계Next steps