아티팩트는 Azure DevTest Labs VM에 추가할 수 있는 도구, 작업 또는 소프트웨어입니다. 예를 들어 아티팩트가 스크립트를 실행하거나, 도구를 설치하거나, 도메인 가입과 같은 작업을 수행할 수 있습니다. DevTest Labs 사용자는 VM에 아티팩트를 추가할 수 있으며 랩 관리자는 모든 랩 VM에 추가할 필수 아티팩트를 지정할 수 있습니다.
이 문서에서는 랩 VM을 프로비전하는 아티팩트 만들기 방법을 설명합니다. 아티팩트는 Git 리포지토리 폴더에 저장된 아티팩트 정의 JSON 파일 및 기타 스크립트 파일로 구성됩니다. 아티팩트를 프라이빗 또는 퍼블릭 Git 리포지토리에 저장할 수 있습니다. 랩 관리자는 모든 랩 사용자가 액세스할 수 있도록 랩에 아티팩트 리포지토리를 추가할 수 있습니다.
필수 조건
- 아티팩트 정의 파일을 만들고 사용하려면 JSON 편집기가 필요합니다. Visual Studio Code 는 Windows, Linux 및 macOS에서 사용할 수 있습니다.
- 아티팩트 정의 및 스크립트 파일을 저장하려면 GitHub 계정이 필요합니다.
아티팩트 정의 파일 이해
아티팩트 정의 파일은 VM에서 수행할 작업을 지정하는 JSON 식으로 구성됩니다. 이 파일은 아티팩트 이름, 실행할 명령 및 명령에 사용할 수 있는 매개 변수를 정의합니다. 아티팩트에서 다른 스크립트 파일이 포함된 경우 아티팩트 정의 파일에서 이름으로 파일을 참조할 수 있습니다.
다음 예제에서는 artifactfile.json 아티팩트 정의 파일의 기본 구조를 보여줍니다.
{
"$schema": "https://raw.githubusercontent.com/Azure/azure-devtestlab/master/schemas/2016-11-28/dtlArtifacts.json",
"title": "<title>",
"description": "<description>",
"iconUri": "",
"targetOsType": "<os>",
"parameters": {
"<paramName>": {
"type": "<type>",
"displayName": "<display name>",
"description": "<description>"
}
},
"runCommand": {
"commandToExecute": "<command>"
}
}
정의에는 다음과 같은 필수 요소와 선택적 요소가 있습니다.
| 요소 이름 | Description |
|---|---|
$schema |
정의 파일의 유효성을 테스트하는 데 도움이 되는 JSON 스키마 파일의 위치입니다. |
title |
표시할 아티팩트 이름이 필요합니다. |
description |
필수 아티팩트 설명입니다. |
iconUri |
표시할 아티팩트 아이콘 URI입니다. |
targetOsType |
설치할 운영 체제가 필요합니다. 지원되는 값은 Windows 또는 Linux입니다. |
parameters |
설치하는 동안 사용 가능한 아티팩트 사용자 지정 |
runCommand |
VM에 아티팩트 설치에 필요한 명령입니다. |
아티팩트 매개 변수
정의 파일의 섹션에서는 parameters 아티팩트 설치 시 사용자가 지정할 수 있는 옵션과 값을 정의합니다. 에서 이러한 매개 변수 runCommand를 참조할 수 있습니다.
다음 구조체는 매개 변수를 정의합니다.
"parameters": {
"<name>": {
"type": "<type>",
"displayName": "<display name>",
"description": "<description>"
}
}
각 매개 변수에는 이름이 필요하며 매개 변수 정의에는 다음 요소가 필요합니다.
| 요소 이름 | Description |
|---|---|
type |
필수 매개 변수 값 형식입니다. 형식은 유효한 모든 JSON string, 정수형 int, 부울 bool, 또는 array일 수 있습니다. |
displayName |
사용자에게 표시할 매개 변수 이름이 필요합니다. |
description |
필수 매개 변수 설명입니다. |
보안 문자열 매개 변수
아티팩트 정의에 비밀을 포함하려면 정의 파일 섹션의 구문을 secureStringParam 사용하여 parameters 비밀을 보안 문자열로 선언합니다. 요소는 description 공백을 비롯한 모든 텍스트 문자열을 허용하고 UI의 문자열을 마스킹된 문자로 표시합니다.
"securestringParam": {
"type": "securestring",
"displayName": "Secure String Parameter",
"description": "<any text string>",
"allowEmpty": false
},
다음 runCommand는 ConvertTo-SecureString 명령을 사용하여 생성된 보안 문자열을 가져오는 PowerShell 스크립트를 사용합니다. 스크립트는 디버깅을 위해 출력을 캡처하므로 보안을 위해 출력을 콘솔에 기록하지 않습니다.
"runCommand": {
"commandToExecute": "[concat('powershell.exe -ExecutionPolicy bypass \"& ./artifact.ps1 -StringParam ''', parameters('stringParam'), ''' -SecureStringParam (ConvertTo-SecureString ''', parameters('securestringParam'), ''' -AsPlainText -Force) -IntParam ', parameters('intParam'), ' -BoolParam:$', parameters('boolParam'), ' -FileContentsParam ''', parameters('fileContentsParam'), ''' -ExtraLogLines ', parameters('extraLogLines'), ' -ForceFail:$', parameters('forceFail'), '\"')]"
}
아티팩트 식 및 함수
식 및 함수를 사용하여 아티팩트 설치 명령을 생성할 수 있습니다. 식은 아티팩트가 설치될 때 평가됩니다.
식은 JSON 문자열 값에서 어느 위치에나 나타날 수 있으며 항상 다른 JSON 값을 반환합니다. 식을 대괄호로 묶습니다. [ ] 대괄호로 시작하는 리터럴 문자열을 사용해야 하는 경우 두 개의 대괄호를 [[사용합니다.
일반적으로 함수와 함께 식을 사용하여 값을 생성합니다. 함수 호출의 형식은 다음과 같습니다 functionName(arg1, arg2, arg3).
일반적인 함수는 다음과 같습니다.
| 기능 | Description |
|---|---|
parameters(parameterName) |
아티팩트 명령이 실행되면 사용할 매개 변수 값을 반환합니다. |
concat(arg1, arg2, arg3, ...) |
여러 문자열 값을 결합하고 다양한 인수를 사용할 수 있습니다. |
다음 예제에서는 함수와 함께 concat 식을 사용하여 값을 생성합니다.
runCommand": {
"commandToExecute": "[concat('powershell.exe -ExecutionPolicy bypass \"& ./startChocolatey.ps1'
, ' -RawPackagesList ', parameters('packages')
, ' -Username ', parameters('installUsername')
, ' -Password ', parameters('installPassword'))]"
}
사용자 지정 아티팩트 만들기
샘플 artifactfile.json 정의 파일에서 시작하여 사용자 지정 아티팩트를 만들 수 있습니다. 공용 DevTest Labs 아티팩트 리포지토리 에는 아티팩트 라이브러리가 있습니다. 아티팩트 정의 파일을 다운로드하고 사용자 지정하여 고유한 아티팩트를 만들 수 있습니다.
artifactfile.json 정의 파일 및 artifact.ps1 PowerShell 스크립트를 https://github.com/Azure/azure-devtestlab/tree/master/Artifacts/windows-test-paramtypes에서 다운로드합니다.
아티팩트 정의 파일을 편집하여 요소와 값에 몇 가지 유효한 변경을 가합니다. Visual Studio Code에서 IntelliSense를 사용하여 유효한 요소 및 값 옵션을 볼 수 있습니다. 예를 들어 요소
targetOsType를 편집할 때 IntelliSense는 사용자에게Windows또는Linux옵션을 표시합니다.공용 또는 프라이빗 Git 아티팩트 리포지토리에 아티팩트를 저장합니다.
- 각 artifactfile.json 아티팩트 정의 파일을 아티팩트 이름과 동일한 별도의 디렉터리에 저장합니다.
- 설치 명령이 참조하는 스크립트를 아티팩트 정의 파일과 동일한 디렉터리에 저장합니다.
다음 스크린샷은 아티팩트 폴더 예제를 보여줍니다.
비고
공용 DevTest Labs 아티팩트 리포지토리에 사용자 지정 아티팩트를 추가하려면 리포지토리에 대한 끌어오기 요청을 엽니다.