Windows용 사용자 지정 스크립트 확장Custom Script Extension for Windows

사용자 지정 스크립트 확장은 Azure 가상 머신에서 스크립트를 다운로드하고 실행합니다.The Custom Script Extension downloads and executes scripts on Azure virtual machines. 이 확장은 배포 후 구성, 소프트웨어 설치 또는 기타 구성/관리 작업에 유용합니다.This extension is useful for post deployment configuration, software installation, or any other configuration / management task. 스크립트를 Azure Storage 또는 GitHub에서 다운로드하거나 확장 런타임에서 Azure Portal에 제공할 수 있습니다.Scripts can be downloaded from Azure storage or GitHub, or provided to the Azure portal at extension run time. 사용자 지정 스크립트 확장은 Azure Resource Manager 템플릿과 통합되고, Azure CLI, PowerShell, Azure Portal 또는 Azure Virtual Machine REST API를 사용하여 실행할 수도 있습니다.The Custom Script extension integrates with Azure Resource Manager templates, and can also be run using the Azure CLI, PowerShell, Azure portal, or the Azure Virtual Machine REST API.

이 문서에서는 Azure PowerShell 모듈, Azure Resource Manager 템플릿을 사용하는 사용자 지정 스크립트 확장을 사용하는 방법과 Windows 시스템에서 문제 해결 단계를 자세히 설명하고 있습니다.This document details how to use the Custom Script Extension using the Azure PowerShell module, Azure Resource Manager templates, and details troubleshooting steps on Windows systems.

필수 구성 요소Prerequisites

참고

해당 매개 변수와 동일한 VM을 사용하여 Update-AzureRmVM을 실행하려는 경우에는 사용자 지정 스크립트 확장을 사용하지 마세요. 대기 시간이 길어집니다.Do not use Custom Script Extension to run Update-AzureRmVM with the same VM as its parameter, since it will wait on itself.

운영 체제Operating System

Windows용 사용자 지정 스크립트 확장은 Windows 10 Client, Windows Server 2008 R2, 2012, 2012 R2 및 2016 릴리스에 대해 실행할 수 있습니다.The Custom Script Extension for Windows can be run against Windows 10 Client, Windows Server 2008 R2, 2012, 2012 R2, and 2016 releases.

스크립트 위치Script Location

이 스크립트는 Azure Blob Storage 또는 유효한 URL을 통해 액세스 가능한 기타 위치에 보관해야 합니다.The script needs to be stored in Azure Blob storage, or any other location accessible through a valid URL.

인터넷 연결Internet Connectivity

Windows용 사용자 지정 스크립트 확장은 대상 가상 머신이 인터넷에 연결되어 있어야 합니다.The Custom Script Extension for Windows requires that the target virtual machine is connected to the internet.

확장 스키마Extension schema

다음 JSON은 사용자 지정 스크립트 확장에 대한 스키마를 보여줍니다.The following JSON shows the schema for the Custom Script Extension. 이 확장은 스크립트 위치(Azure Storage 또는 유효한 URL이 있는 기타 위치)와 실행할 명령이 필요합니다.The extension requires a script location (Azure Storage or other location with valid URL), and a command to execute. 스크립트 원본으로 Azure Storage를 사용하는 경우 Azure Storage 계정 이름 및 계정 키가 필요합니다.If using Azure Storage as the script source, an Azure storage account name and account key is required. 이러한 항목은 중요한 데이터로 처리하고 확장으로 보호되는 설정 구성에 지정되어야 합니다.These items should be treated as sensitive data and specified in the extensions protected setting configuration. Azure VM 확장으로 보호되는 설정 데이터는 암호화되어 대상 가상 머신에서만 해독됩니다.Azure VM extension protected setting data is encrypted, and only decrypted on the target virtual machine.

{
    "apiVersion": "2015-06-15",
    "type": "Microsoft.Compute/virtualMachines/extensions",
    "name": "config-app",
    "location": "[resourceGroup().location]",
    "dependsOn": [
        "[concat('Microsoft.Compute/virtualMachines/', variables('vmName'),copyindex())]",
        "[variables('musicstoresqlName')]"
    ],
    "tags": {
        "displayName": "config-app"
    },
    "properties": {
        "publisher": "Microsoft.Compute",
        "type": "CustomScriptExtension",
        "typeHandlerVersion": "1.9",
        "autoUpgradeMinorVersion": true,
        "settings": {
            "fileUris": [
                "script location"
            ]
        },
        "protectedSettings": {
            "commandToExecute": "myExecutionCommand",
            "storageAccountName": "myStorageAccountName",
            "storageAccountKey": "myStorageAccountKey"
        }
    }
}

속성 값Property values

이름Name 값/예제Value / Example
apiVersionapiVersion 2015-06-152015-06-15
publisherpublisher Microsoft.ComputeMicrosoft.Compute
형식type 확장extensions
typeHandlerVersiontypeHandlerVersion 1.91.9
fileUris(예)fileUris (e.g) https://raw.githubusercontent.com/Microsoft/dotnet-core-sample-templates/master/dotnet-core-music-windows/scripts/configure-music-app.ps1https://raw.githubusercontent.com/Microsoft/dotnet-core-sample-templates/master/dotnet-core-music-windows/scripts/configure-music-app.ps1
commandToExecute(예)commandToExecute (e.g) powershell -ExecutionPolicy Unrestricted -File configure-music-app.ps1powershell -ExecutionPolicy Unrestricted -File configure-music-app.ps1
storageAccountName(예)storageAccountName (e.g) examplestorageacctexamplestorageacct
storageAccountKey(예)storageAccountKey (e.g) TmJK/1N3AbAZ3q/+hOXoi/l73zOqsaxXDhqa9Y83/v5UpXQp2DQIBuv2Tifp60cE/OaHsJZmQZ7teQfczQj8hg==TmJK/1N3AbAZ3q/+hOXoi/l73zOqsaxXDhqa9Y83/v5UpXQp2DQIBuv2Tifp60cE/OaHsJZmQZ7teQfczQj8hg==

참고 - 이러한 속성 이름은 대/소문자를 구분합니다.Note - these property names are case sensitive. 배포 문제를 방지하려면 위와 같이 이름을 사용합니다.Use the names as seen above to avoid deployment issues.

템플릿 배포Template deployment

Azure Resource Manager 템플릿을 사용하여 Azure VM 확장을 배포할 수 있습니다.Azure VM extensions can be deployed with Azure Resource Manager templates. 이전 섹션에서 자세히 설명되어 있는 JSON 스키마는 Azure Resource Manager 템플릿에서 사용하여 Azure Resource Manager 템플릿 배포 중 사용자 지정 스크립트 확장을 실행할 수 있습니다.The JSON schema detailed in the previous section can be used in an Azure Resource Manager template to run the Custom Script Extension during an Azure Resource Manager template deployment. 사용자 지정 스크립트 확장이 포함된 샘플 템플릿은 여기 GitHub에서 확인할 수 있습니다.A sample template that includes the Custom Script Extension can be found here, GitHub.

PowerShell 배포PowerShell deployment

Set-AzureRmVMCustomScriptExtension 명령을 사용하여 사용자 지정 스크립트 확장을 기존 가상 머신에 추가할 수 있습니다.The Set-AzureRmVMCustomScriptExtension command can be used to add the Custom Script extension to an existing virtual machine. 자세한 내용은 Set-AzureRmVMCustomScriptExtension을 참조하세요.For more information, see Set-AzureRmVMCustomScriptExtension .

Set-AzureRmVMCustomScriptExtension -ResourceGroupName myResourceGroup `
    -VMName myVM `
    -Location myLocation `
    -FileUri myURL `
    -Run 'myScript.ps1' `
    -Name DemoScriptExtension

문제 해결 및 지원Troubleshoot and support

문제 해결Troubleshoot

확장 배포 상태에 대한 데이터는 Azure PowerShell 모듈을 사용하여 Azure Portal에서 검색할 수 있습니다.Data about the state of extension deployments can be retrieved from the Azure portal, and by using the Azure PowerShell module. 지정된 VM에 대한 확장의 배포 상태를 보려면 다음 명령을 실행합니다.To see the deployment state of extensions for a given VM, run the following command.

Get-AzureRmVMExtension -ResourceGroupName myResourceGroup -VMName myVM -Name myExtensionName

확장 실행 출력은 대상 가상 머신의 다음 디렉터리 아래에 기록됩니다.Extension execution output is logged to files found under the following directory on the target virtual machine.

C:\WindowsAzure\Logs\Plugins\Microsoft.Compute.CustomScriptExtension

지정된 파일은 대상 가상 머신의 다음 디렉터리에 다운로드됩니다.The specified files are downloaded into the following directory on the target virtual machine.

C:\Packages\Plugins\Microsoft.Compute.CustomScriptExtension\1.*\Downloads\<n>

여기서 <n>은 확장의 실행 간에 변경될 수 있는 10진수 정수입니다.where <n> is a decimal integer which may change between executions of the extension. 1.* 값은 확장의 현재 실제 typeHandlerVersion 값과 일치합니다.The 1.* value matches the actual, current typeHandlerVersion value of the extension. 예를 들어, 실제 디렉터리는 C:\Packages\Plugins\Microsoft.Compute.CustomScriptExtension\1.8\Downloads\2일 수 있습니다.For example, the actual directory could be C:\Packages\Plugins\Microsoft.Compute.CustomScriptExtension\1.8\Downloads\2.

commandToExecute 명령을 실행할 경우 확장은 현재 작업 디렉터리처럼 이 디렉터리를 설정합니다(예: ...\Downloads\2).When executing the commandToExecute command, the extension will have set this directory (e.g., ...\Downloads\2) as the current working directory. 그러면 fileURIs 속성을 통해 다운로드된 파일을 배치하는 상대 경로를 사용할 수 있습니다.This enables the use of relative paths to locate the files downloaded via the fileURIs property. 예제는 아래 테이블을 참조하세요.See the table below for examples.

시간이 지남에 따라 절대 다운로드 경로가 달라질 수 있으므로 가능한 경우 commandToExecute 문자열에서 상대 스크립트/파일 경로를 옵트인하는 것이 좋습니다.Since the absolute download path may vary over time, it is better to opt for relative script/file paths in the commandToExecute string, whenever possible. 예: For example:

    "commandToExecute": "powershell.exe . . . -File './scripts/myscript.ps1'"

첫 번째 URI 세그먼트 뒤의 경로 정보는 fileUris 속성 목록을 통해 다운로드된 파일에 유지됩니다.Path information after the first URI segment is retained for files downloaded via the fileUris property list. 아래 테이블에 표시된 대로 다운로드된 파일은 다운로드 하위 디렉터리에 매핑되어 fileUris 값의 구조를 반영합니다.As shown in the table below, downloaded files are mapped into download subdirectories to reflect the structure of the fileUris values.

다운로드된 파일의 예Examples of Downloaded Files

fileUris의 URIURI in fileUris 다운로드된 상대 위치Relative downloaded location 다운로드된 절대 위치*Absolute downloaded location *
https://someAcct.blob.core.windows.net/aContainer/scripts/myscript.ps1 ./scripts/myscript.ps1 C:\Packages\Plugins\Microsoft.Compute.CustomScriptExtension\1.8\Downloads\2\scripts\myscript.ps1
https://someAcct.blob.core.windows.net/aContainer/topLevel.ps1 ./topLevel.ps1 C:\Packages\Plugins\Microsoft.Compute.CustomScriptExtension\1.8\Downloads\2\topLevel.ps1

\* 위와 같이 CustomScript 확장의 단일 실행 이내가 아닌 VM의 수명 동안 절대 디렉터리 경로가 변경됩니다.\* As above, the absolute directory paths will change over the lifetime of the VM, but not within a single execution of the CustomScript extension.

지원Support

이 문서의 어디에서든 도움이 필요한 경우 MSDN Azure 및 Stack Overflow 포럼에서 Azure 전문가에게 문의할 수 있습니다.If you need more help at any point in this article, you can contact the Azure experts on the MSDN Azure and Stack Overflow forums. 또는 Azure 기술 지원 인시던트를 제출할 수 있습니다.Alternatively, you can file an Azure support incident. Azure 지원 사이트로 가서 지원 받기를 선택합니다.Go to the Azure support site and select Get support. Azure 지원을 사용하는 방법에 대한 자세한 내용은 Microsoft Azure 지원 FAQ를 참조하세요.For information about using Azure Support, read the Microsoft Azure support FAQ.